poll(7) poll(7)
NAME [Toc] [Back]
poll - monitor I/O conditions on multiple file descriptors
SYNOPSIS [Toc] [Back]
#include <sys/devpoll.h> #include <fcntl.h>
int open("/dev/poll", O_RDWR);
int write(int filedes, const struct pollfd *buf, size_t nbyte);
int ioctl(int filedes, DP_POLL, struct dvpoll *arg);
int ioctl(int filedes, DP_ISPOLLED, struct pollfd *arg);
DESCRIPTION [Toc] [Back]
/dev/poll provides an interface to the event port driver allowing a
user to synchronously monitor a specific set of conditions associated
with a registered set of file descriptors. Poll conditions include
the ability to read or write data without blocking and certain
exceptional conditions.
Access to /dev/poll is provided through the open(), write(), and
ioctl() system calls.
The /dev/poll event port provides functionality comparable to the
select(2) and poll(2) system calls and supports the following types of
file descriptors: network (AF_INET) and Unix Domain (AF_UNIX) sockets,
named FIFO files and pipes, XTI endpoints, and STREAMS devices.
General operations supported by the event port driver are:
-- Opening an event port.
-- Registering and deregistering file descriptors on an event port.
-- Polling registered file descriptors on an event port.
-- Retrieving registered poll conditions for a file descriptor.
-- Closing an event port.
Opening An Event Port [Toc] [Back]
Each open of the /dev/poll device enables an event port from which a
different set of file descriptors can be polled. The file descriptor
returned by the open() system call represents the event port. Users
wishing to monitor multiple sets of file descriptors should open the
/dev/poll device multiple times. For example:
int evpfd;
evpfd = open("/dev/poll", O_RDWR);
Only the process that performed the open() on /dev/poll can perform
general event port operations. Specifically, any event port file
descriptor inherited by a child from its parent or that is received
from another process using the Unix Domain Sockets access rights can
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
poll(7) poll(7)
only be closed. (See sendmsg in the send(2) man page or the STREAMS
I_FDINSERT ioctl request in the streamio(7) man page.)
Registering and Deregistering File Descriptors [Toc] [Back]
An interest set of file descriptors and poll conditions is registered
with an event port by using the write() system call. By writing an
array of pollfd structures to an event port the user can register
multiple file descriptors in one write() service call. The pollfd
structure and related poll conditions are defined in <poll.h>,
(included by <sys/devpoll.h>). Other flags are defined in the
<sys/devpoll.h> file. See the poll(2) man page for the definition of
the poll conditions.
To register a file descriptor, the fd field is set to the file
descriptor to be registered, and the events field is set to one or
more poll conditions, such as POLLIN. Multiple poll conditions can be
ORed together. A given file descriptor can be registered with
multiple event ports. Re-registering a file descriptor with the same
event port will cause the the specified poll conditions to join the
previous conditions for the given file descriptor.
To deregister, fd is set to the file descriptor to be deregistered,
and events is set to POLLREMOVE. POLLREMOVE is defined in
<sys/devpoll.h>. POLLREMOVE must not be ORed together with any other
poll conditions.
When a polled file descriptor is closed, it is automatically
deregistered.
Continuing our example, the following registers two file descriptors
on the opened event port, fd1 and fd2:
struct pollfd pfd[2];
int err;
pfd[0].fd = fd1;
pfd[0].events = POLLIN;
pfd[1].fd = fd2;
pfd[1].events = (POLLIN | POLLRDBAND);
err = write(evpfd, pfd, sizeof(pfd));
Polling File Descriptors [Toc] [Back]
Polling an event port's interest set is initiated by calling ioctl()
specifying the DP_POLL request.
The ioctl arg parameter is a pointer to a dvpoll structure, defined in
<sys/devpoll.h>. It contains the following members:
struct dvpoll {
pollfd_t *dp_fds; /* pollfd[] to be used */
nfds_t dp_nfds; /* number of pollfd entries */
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
poll(7) poll(7)
int dp_timeout; /* milliseconds or -1 */
}
dp_fds is a pointer to an array of pollfd structures. dp_nfds is the
maximum number of pollfd structures to be returned in that array.
dp_timeout is the maximum time, in milliseconds, to wait for at least
one of the registered poll conditions to be met in the event port.
When one or more registered poll conditions are met for any of the
registered file descriptors, ioctl() stores the valid poll conditions
in the revents of each pollfd structure in the array, one array
element for each active file descriptor. The return value of ioctl()
is the number of valid pollfd structures.
If no poll conditions are met and if dp_timeout is -1, ioctl() sleeps
until a poll condition is met on any of the registered file
descriptors. If dp_timeout is non-negative, ioctl() returns after
dp_timeout milliseconds expires or when a poll condition is met. If
the time limit expires, the ioctl() return value is 0.
Retrieving Registered Poll Conditions for a File Descriptor [Toc] [Back]
The registered poll conditions for a given file descriptor in an
interest set can be determined by calling ioctl() with the DP_ISPOLLED
request. For example, for file descriptor fd1:
struct pollfd pfd;
int ispolled;
pfd.fd = fd1;
ispolled = ioctl(evpfd, DP_ISPOLLED, &pfd);
If the file descriptor is registered with the event port, the ioctl()
return value is 1, and the registered poll conditions are returned in
the events member of the pollfd structure.
The ioctl() return value is 0 if the file descriptor is not registered
or is not open.
Closing an Event Port [Toc] [Back]
An event port is closed with the close() system call specifying the
event port file descriptor. All file descriptors registered with that
event port are automatically deregistered from that event port.
RETURN VALUES [Toc] [Back]
open() returns the event port file descriptor. If the open() system
call fails, it returns -1, and errno is set to the error condition.
write() returns the number of bytes in the array of the pollfd
structure that was passed in buf. If the write() returns -1, errno is
set to the error condition.
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
poll(7) poll(7)
ioctl(DP_POLL) returns the number of file descriptors for which one or
more poll conditions are met. ioctl(DP_POLL) returns 0 if a timeout
occurred before any poll conditions were satisfied for any of the
registered file descriptors.
ioctl(DP_ISPOLLED) returns 1 if the file descriptor specified in the
pollfd structure is registered. ioctl(DP_ISPOLLED) returns 0 if the
file descriptor is not registered or is closed.
If ioctl() returns -1, errno is set to the error condition.
ERRORS [Toc] [Back]
The following errors are returned by the event port driver.
If open() fails, errno is set to one of the following values.
[EACCES] The minor number of the device file name passed to
open() is not 0.
[EAGAIN] Allocation of internal data structures failed due
to a temporary condition. Calling open() again
might succeed.
[EMFILE] The maximum number of file descriptors allowed for
the process is already open.
[ENFILE] The maximum number of files allowed for the system
is already open.
[ENXIO] Some of the requisite file types are not supported
by the /dev/poll driver. See the WARNINGS section
below.
If write() or ioctl() fails, errno is set to one of the following
values.
[EACCES] The calling process did not open the event port.
[EBADF] The filedes argument passed to write() is not an
open file descriptor.
[EFAULT] An attempt was made to access a pollfd structure
whose location is outside the process address
space.
[EINTR] A signal interrupted the ioctl(DP_POLL) system
call.
[EINVAL] The nbyte argument passed to write() is less than
0.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
poll(7) poll(7)
[ENODEV] The filedes argument passed to write() is not an
event port file descriptor.
EXAMPLES [Toc] [Back]
The following examples show how to use the /dev/poll driver to poll
for events on network socket file descriptors.
To register a TCP socket file descriptor (sd) so that ioctl(DP_POLL)
will notify the application when a new connection is established or
when input data is available:
struct pollfd regpfd;
int err;
regpfd.fd = sd;
regpfd.events = POLLIN;
err = write(evpfd, ®pfd, sizeof(regpfd));
POLLRDBAND should be ORed with POLLIN if the application needs to
distinguish the arrival of out-of-band data.
To wait for events on one or more registered sockets, up to 100
connections:
struct pollfd pollpfd[100];
struct dvpoll dvp;
int npoll;
dvp.dp_fds = pollpfd;
dvp.dp_nfds = 100;
dvp.dp_timeout = -1;
npoll = ioctl(evpfd, DP_POLL, &dvp);
If a non-blocking write to a socket is incomplete, the following can
be used to register the socket so that ioctl(DP_POLL) will notify the
application when the socket is writable again later. Typically, the
socket is already registered to receive input notifications. The
following will add the POLLOUT notification.
struct pollfd regpfd;
int err;
regpfd.fd = sd;
regpfd.events = POLLOUT;
err = write(evpfd, ®pfd, sizeof(regpfd));
After the last non-blocking write succeeds, the following should be
used to deregister for POLLOUT, but continue to be registered for
input notifications. Note that POLLREMOVE must be used in order to
remove the POLLOUT registration.
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
poll(7) poll(7)
struct pollfd regpfd[2];
int err;
regpfd[0].fd = sd;
regpfd[0].events = POLLREMOVE;
regpfd[1].fd = sd;
regpfd[1].events = POLLIN;
err = write(evpfd, regpfd, sizeof(regpfd));
The following uses ioctl(DP_ISPOLLED) to demonstrate how to accomplish
the same thing in the more general case, for example, when an
application library might not know how the file descriptor is normally
registered.
struct pollfd regpfd[2];
int err;
regpfd[0].fd = sd;
regpfd[0].events = POLLREMOVE;
regpfd[1].fd = sd;
err = ioctl(evpfd, DP_ISPOLLED, ®pfd[1]);
regpfd[1].events &= ~POLLOUT; /* clear POLLOUT */
err = write(evpfd, regpfd, sizeof(regpfd));
WARNINGS [Toc] [Back]
/dev/poll usually performs better than select() and poll() especially
when the application has registered a very large number of file
descriptors. However, in cases where specified conditions are likely
to occur simultaneously on a large number of registered file
descriptors, performance levels will be diminished.
If open() returns -1 and errno is set to [ENXIO], this indicates that
some of the necessary system patches have not been installed, and the
system administrator must install the File System, Transport, and
STREAMS patches that support /dev/poll (event ports).
The write() system call does not return any error indication if one or
more of the file descriptors in the pollfd structure could not be
registered or deregistered.
If POLLREMOVE is ORed with other poll conditions in a pollfd structure
passed to write(), POLLREMOVE is ignored. The other poll conditions
will be ORed with any existing poll conditions for the registered file
descriptor.
The ioctl(DP_POLL) system call returns only the first dp_nfds active
file descriptors. There is no indication if there are additional
active file descriptors.
The ioctl(DP_ISPOLLED) system call also returns its result in the
revents member of the pollfd structure, in order to be compatible with
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
poll(7) poll(7)
the implementation of the /dev/poll driver by some other vendors.
The ioctl(DP_ISPOLLED) system call does not return any error
indication if the file descriptor in the pollfd structure is not open.
When an event port is closed, the close() system call might take a
noticeable amount of time to complete if a very large number of file
descriptors is still registered.
AUTHOR [Toc] [Back]
The event port driver was developed independently by HP.
FILES [Toc] [Back]
/dev/poll driver device file
/sbin/init.d/devpoll start-up script that creates /dev/poll
/etc/rc.config.d/devpoll configuration parameters for start-up
script
SEE ALSO [Toc] [Back]
ioctl(2), mknod(2), open(2), pipe(2), poll(2), select(2), send(2),
socket(2), socketpair(2), write(2), t_open(3).
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003 [ Back ] |
