Provides users with a mechanism for multiplexing input/output over a set of file descriptors that reference open streams. This function is supported on OpenVMS Integrity servers and Alpha only. Format #include <poll.h> int poll (struct pollfd filedes [], nfds_t nfds, int timeout);
1 – Argument
filedes Points to an array of pollfd structures, one for each file descriptor of interest. Each pollfd structure includes the following members: int fd - The file descriptor int events - The requested conditions int revents - The reported conditions nfds The number of pollfd structures in the filedes array. timeout The maximum length of time (in milliseconds) to wait for at least one of the specified events to occur.
2 – Description
The poll function provides users with a mechanism for multiplexing input/output over a set of file descriptors that reference open streams. For each member of the array pointed to by filedes, poll examines the given file descriptor for the event(s) specified in events. The poll function identifies those streams on which an application can send or receive messages, or on which certain events have occurred. The filedes parameter specifies the file descriptor to be examined and the events of interest for each file descriptor. It is a pointer to an array of pollfd structures. The fd member of each pollfd structure specifies an open file descriptor. The poll function uses the events member to determine what conditions to report for this file descriptor. If one or more of these conditions is true, the poll function sets the associated revents member. The events and revents members of each pollfd structure are bitmasks. The calling process sets the events bitmask, and poll sets the revents bitmasks. These bitmasks contain inclusive ORed combinations of condition options. The following condition options are defined: POLLERR - An error has occurred on the file descriptor. This option is only valid in the revents bitmask; it is not used in the events member. For STREAMS devices, if an error occurs on the file descriptor and the device is also disconnected, poll returns POLLERR; POLLERR takes precedence over POLLHUP. POLLHUP - The device has been disconnected. This event is mutually exclusive with POLLOUT; a stream can never be writable if a hangup occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND or POLLPRI are not mutually exclusive. This option is only valid in the revents bitmask; it is ignored in the events member. POLLIN - Data other than high-priority data may be read without blocking. This option is set in revents even if the message is of zero length. In revents, this option is mutually exclusive with POLLPRI. POLLNVAL - The value specified for fd is invalid. This option is only valid in the revents member; it is ignored in the events member. POLLOUT - Normal (priority band equals 0) data may be written without blocking. POLLPRI - High-priority data may be received without blocking. This option is set in revents even if the message is of zero length. In revents, this option is mutually exclusive with POLLIN. POLLRDBAND - Data from a nonzero priority band may be read without blocking. This option is set in revents even if the message is of zero length. POLLRDNORM - Normal data (priority band equals 0) may be read without blocking. This option is set in revents even if the message is of zero length. POLLWRBAND - Priority data (priority band greater than 0) may be written. This event only examines bands that have been written to at least once. POLLWRNORM - Same as POLLOUT. The poll function ignores any pollfd structure whose fd member is less than 0 (zero). If the fd member of all pollfd structures is less than 0, the poll function will return 0 and have no other results. The conditions indicated by POLLNORM and POLLOUT are true if and only if at least one byte of data can be read or written without blocking. There are two exceptions: regular files, which always poll true for POLLNORM and POLLOUT, and pipes, when the rules for the operation specify to return zero in order to indicate end-of-file. The condition options POLLERR, POLLHUP, and POLLNVAL are always set in revents if the conditions they indicate are true for the specified file descriptor, whether or not these options are set in events. For each call to the poll function, the set of reportable conditions for each file descriptor consists of those conditions that are always reported, together with any further conditions for which options are set in events. If any reportable condition is true for any file descriptor, the poll function will return with options set in revents for each true condition for that file descriptor. If no reportable condition is true for any of the file descriptors, the poll function waits up to timeout milliseconds for a reportable condition to become true. If, in that time interval, a reportable condition becomes true for any of the file descriptors, poll reports the condition in the file descriptor's associated revents member and returns. If no reportable condition becomes true, poll returns without setting any revents bitmasks. If the timeout parameter is a value of -1, the poll function does not return until at least one specified event has occurred. If the value of the timeout parameter is 0 (zero), the poll function does not wait for an event to occur but returns immediately, even if no specified event has occurred. The behavior of the poll function is not affected by whether the O_NONBLOCK option is set on any of the specified file descriptors. The poll function supports regular files, terminal and pseudo- terminal devices, STREAMS-based files, FIFOs, and pipes. The behavior of poll on elements of file descriptors that refer to other types of files is unspecified. For sockets, a file descriptor for a socket that is listening for connections indicates it is ready for reading after connections are available. A file descriptor for a socket that is connecting asynchronously indicates it is ready for writing after a connection is established.
3 – Return Values
n Upon successful completion, a nonnegative value is returned, indicating the number of file descriptors for which poll has set the revents bitmask. 0 poll has timed out and has not set any of the revents bitmasks. -1 An error occurred. errno is set to indicate the error: o EAGAIN - Allocation of internal data structures failed. A later call to the poll function might complete successfully. o EINTR - A signal was intercepted during the poll function, and the signal handler was installed with an indication that functions are not to be restarted. o EINVAL - The nfds parameter is greater than OPEN_MAX, or one of the fd members refers to a stream or multiplexer that is linked (directly or indirectly) downstream from a multiplexer.