*** UNIX MANUAL PAGE BROWSER ***

poll(2) System Calls Manual poll(2) NAME poll - Monitors conditions on multiple file descriptors SYNOPSIS #include <poll.h> int poll( struct pollfd filedes[ ], nfds_t nfds, int timeout ); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: poll(): XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Points to an array of pollfd structures, one for each file descriptor of interest. Each pollfd structure includes the following members: The file descriptor The requested conditions The reported conditions Speci- fies the number of pollfd structures in the filedes array. Specifies the maximum length of time (in milliseconds) to wait for at least one of the specified events to occur. 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 ap- plication 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 flags. The following condition flags are defined: An error has occurred on the file descriptor. This flag 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. The device has been dis- connected. 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 flag is only valid in the revents bit- mask; it is ignored in the events member. Data other than high- priority data may be read without blocking. This flag is set in revents even if the message is of zero length. In revents, this flag is mutually exclusive with POLLPRI. [Digital] Data may be read without blocking. The value specified for fd is invalid. This flag is only valid in the revents member; it is ignored in the events member. Normal (priority band equals 0) data may be written without blocking. High-priority data may be received without blocking. This flag is set in revents even if the mes- sage is of zero length. In revents, this flag is mutually ex- clusive with POLLIN. Data from a non-zero priority band may be read without blocking. This flag is set in revents even if the message is of zero length. Normal data (priority band equals 0) may be read without blocking. This flag is set in revents even if the message is of zero length. Priority data (priority band greater than 0) may be written. 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 spec- ify to return zero in order to indicate end-of-file. The condition flags 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 flags 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 flags are set in events. If any reportable condition is true for any file descrip- tor, the poll() function will return with flags 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 con- dition to become true. If, in that time interval, a reportable condi- tion becomes true for any of the file descriptors, poll() reports the condition in the file descriptor's associated revents member and re- turns. 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 af- fected by whether the O_NONBLOCK flag is set on any of the specified file descriptors. NOTES [Digital] For compatibility with BSD systems, the select() function is also supported. [Digital] This function supports up to 64K open file descriptors per process if that capability is enabled. RETURN VALUES Upon successful completion, the poll() function returns a nonnegative value. If the call returns 0 (zero), poll() has timed out and has not set any of the revents bitmasks. A positive value indicates the number of file descriptors for which poll() has set the revents bitmask. If the poll() function fails, -1 is returned and errno is set to indicate the error. ERRORS If the poll() function fails, errno may be set to one of the following values: Allocation of internal data structures failed. A later call to the poll() function may complete successfully. A signal was caught during the poll() function and the signal handler was installed with an indication that functions are not to be restarted. [Digital] The timeout parameter is a negative number other than -1. [Digital] The nfds parameter is greater than the process's soft file descriptor limit. [XPG4-UNIX] 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. [Digital] The filedes parameter in conjunction with the nfds parameter addresses a location outside of the allocated address space of the process. RELATED INFORMATION Functions: getmsg(2), putmsg(2), read(2), write(2), setsysinfo(2), streamio(7) Standards: standards(5) delim off poll(2)