poll(7)

NAME

poll — monitor I/O conditions on multiple file descriptors

SYNOPSIS

#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

/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

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 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

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

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 */
   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

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

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

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.

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

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.
ENODEV: The filedes argument passed to write() is not an event port file descriptor.

EXAMPLES

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, &regpfd, 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, &regpfd, 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.

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, &regpfd[1]);
regpfd[1].events &= ~POLLOUT;    /* clear POLLOUT */
err = write(evpfd, regpfd, sizeof(regpfd));

WARNINGS

/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 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

The event port driver was developed independently by HP.

FILES

/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