poll(7)poll(7)NAMEpoll - monitor I/O conditions on multiple file descriptors
SYNOPSISDESCRIPTION
provides an interface to the event port driver allowing a user to syn‐
chronously 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 condi‐
tions 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 conditions,
such as Multiple poll conditions can be 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, is set to the file descriptor to be deregistered, and is
set to is defined in must not be together with any other poll condi‐
tions.
When a polled file descriptor is closed, it is automatically deregis‐
tered.
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 con‐
tains 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 reg‐
istered 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-negative,
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 inter‐
est 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 con‐
ditions 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 regis‐
tered. 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 suc‐
ceed.
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 appli‐
cation 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 connec‐
tions:
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 sys‐
tem 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 dereg‐
istered.
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 ALSOioctl(2), mknod(2), open(2), pipe(2), poll(2), select(2), send(2),
socket(2), socketpair(2), write(2), t_open(3).
poll(7)
