poll(7) Miscellaneous Information Manual poll(7)
NAME
poll - monitor I/O conditions on multiple file descriptors
SYNOPSIS
DESCRIPTION
provides an interface to the event port driver allowing a user to synchronously monitor a specific set of conditions associated with a reg-
istered set of file descriptors. Poll conditions include the ability to read or write data without blocking and certain exceptional condi-
tions.
Access to is provided through the and system calls.
The event port provides functionality comparable to the and system calls and supports the following types of file descriptors: network and
Unix Domain 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 device enables an event port from which a different set of file descriptors can be polled. The file descriptor returned
by the system call represents the event port. Users wishing to monitor multiple sets of file descriptors should open the device multiple
times. For example:
Only the process that performed the on 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 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 system call. By writing an array of
structures to an event port the user can register multiple file descriptors in one service call. The structure and related poll conditions
are defined in (included by Other flags are defined in the file. See the poll(2) man page for the definition of the poll conditions.
To register a file descriptor, the field is set to the file descriptor to be registered, and the field is set to one or more poll condi-
tions, such as Multiple poll conditions can be together. A given file descriptor can be registered with multiple event ports. Re-regis-
tering 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, is set to the file descriptor to be deregistered, and is set to is defined in must not be together with any other poll con-
ditions.
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, and
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 specifying the request.
The ioctl arg parameter is a pointer to a structure, defined in 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 */
}
is a pointer to an array of structures. is the maximum number of structures to be returned in that array. is the maximum time, in mil-
liseconds, 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, stores the valid poll conditions in the of
each structure in the array, one array element for each active file descriptor. The return value of is the number of valid structures.
If no poll conditions are met and if is sleeps until a poll condition is met on any of the registered file descriptors. If is non-nega-
tive, returns after dp_timeout milliseconds expires or when a poll condition is met. If the time limit expires, the return value is
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 with the request. For example,
for file descriptor
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 return value is and the registered poll conditions are returned in the member
of the structure.
The return value is if the file descriptor is not registered or is not open.
Closing an Event Port
An event port is closed with the 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
returns the event port file descriptor. If the system call fails, it returns and is set to the error condition.
returns the number of bytes in the array of the structure that was passed in buf. If the returns is set to the error condition.
returns the number of file descriptors for which one or more poll conditions are met. returns if a timeout occurred before any poll condi-
tions were satisfied for any of the registered file descriptors.
returns if the file descriptor specified in the structure is registered. returns if the file descriptor is not registered or is closed.
If returns is set to the error condition.
ERRORS
The following errors are returned by the event port driver.
If fails, is set to one of the following values.
The minor number of the device file name passed to
is not
Allocation of internal data structures failed due to
a temporary condition. Calling again might succeed.
The maximum number of file descriptors allowed for
the process is already open.
The maximum number of files allowed for the system
is already open.
Some of the requisite file types are not supported by the
driver. See the section below.
If or fails, is set to one of the following values.
The calling process did not open the event port.
The filedes argument passed to is not an open file descriptor.
An attempt was made to access a
structure whose location is outside the process address space.
A signal interrupted the
system call.
The nbyte argument passed to is less than
The filedes argument passed to is not an event port file descriptor.
EXAMPLES
The following examples show how to use the driver to poll for events on network socket file descriptors.
To register a TCP socket file descriptor so that 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));
should be with 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 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 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 but continue to be registered for input notifi-
cations. Note that must be used in order to remove the 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 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
usually performs better than and 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 returns and is set to 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 (event ports).
The system call does not return any error indication if one or more of the file descriptors in the structure could not be registered or
deregistered.
If is with other poll conditions in a structure passed to is ignored. The other poll conditions will be with any existing poll conditions
for the registered file descriptor.
The system call returns only the first dp_nfds active file descriptors. There is no indication if there are additional active file
descriptors.
The system call also returns its result in the member of the structure, in order to be compatible with the implementation of the driver by
some other vendors.
The system call does not return any error indication if the file descriptor in the structure is not open.
When an event port is closed, the 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
driver device file
start-up script that creates
configuration parameters for start-up script
SEE ALSO
ioctl(2), mknod(2), open(2), pipe(2), poll(2), select(2), send(2), socket(2), socketpair(2), write(2), t_open(3).
poll(7)