poll(2) [osx man page]
POLL(2) BSD System Calls Manual POLL(2) NAME
poll -- synchronous I/O multiplexing SYNOPSIS
#include <poll.h> int poll(struct pollfd fds[], nfds_t nfds, int timeout); DESCRIPTION
Poll() examines a set of file descriptors to see if some of them are ready for I/O or if certain events have occurred on them. The fds argu- ment is a pointer to an array of pollfd structures, as defined in <poll.h> (shown below). The nfds argument specifies the size of the fds array. struct pollfd { int fd; /* file descriptor */ short events; /* events to look for */ short revents; /* events returned */ }; The fields of struct pollfd are as follows: fd File descriptor to poll. events Events to poll for. (See below.) revents Events which may occur or have occurred. (See below.) The event bitmasks in events and revents have the following bits: POLLERR An exceptional condition has occurred on the device or socket. This flag is output only, and ignored if present in the input events bitmask. POLLHUP The device or socket has been disconnected. This flag is output only, and ignored if present in the input events bitmask. Note that POLLHUP and POLLOUT are mutually exclusive and should never be present in the revents bitmask at the same time. POLLIN Data other than high priority data may be read without blocking. This is equivalent to ( POLLRDNORM | POLLRDBAND ). POLLNVAL The file descriptor is not open. This flag is output only, and ignored if present in the input events bitmask. POLLOUT Normal data may be written without blocking. This is equivalent to POLLWRNORM. POLLPRI High priority data may be read without blocking. POLLRDBAND Priority data may be read without blocking. POLLRDNORM Normal data may be read without blocking. POLLWRBAND Priority data may be written without blocking. POLLWRNORM Normal data may be written without blocking. The distinction between normal, priority, and high-priority data is specific to particular file types or devices. If timeout is greater than zero, it specifies a maximum interval (in milliseconds) to wait for any file descriptor to become ready. If timeout is zero, then poll() will return without blocking. If the value of timeout is -1, the poll blocks indefinitely. RETURN VALUES
Poll() returns the number of descriptors that are ready for I/O, or -1 if an error occurred. If the time limit expires, poll() returns 0. If poll() returns with an error, including one due to an interrupted call, the fds array will be unmodified and the global variable errno will be set to indicate the error. ERRORS
Poll() will fail if: [EAGAIN] Allocation of internal data structures fails. A subsequent request may succeed. [EFAULT] Fds points outside the process's allocated address space. [EINTR] A signal is delivered before the time limit expires and before any of the selected events occurs. [EINVAL] The nfds argument is greater than OPEN_MAX or the timeout argument is less than -1. BUGS
The poll() system call currently does not support devices. SEE ALSO
accept(2), connect(2), kevent(2), read(2), recv(2), select(2), send(2), write(2) HISTORY
The poll() function call appeared in AT&T System V UNIX. BSD
February 27, 2005 BSD
Check Out this Related Man Page
poll(2) System Calls poll(2) NAME
poll - input/output multiplexing SYNOPSIS
#include <poll.h> int poll(struct pollfd fds[], nfds_t nfds, int timeout); DESCRIPTION
The poll() function provides applications with a mechanism for multiplexing input/output over a set of file descriptors. For each member of the array pointed to by fds, poll() examines the given file descriptor for the event(s) specified in events. The number of pollfd struc- tures in the fds array is specified by nfds. The poll() function identifies those file descriptors on which an application can read or write data, or on which certain events have occurred. The fds argument specifies the file descriptors to be examined and the events of interest for each file descriptor. It is a pointer to an array with one member for each open file descriptor of interest. The array's members are pollfd structures, which contain the following members: int fd; /* file descriptor */ short events; /* requested events */ short revents; /* returned events */ The fd member specifies an open file descriptor and the events and revents members are bitmasks constructed by a logical OR operation of any combination of the following event flags: POLLIN Data other than high priority data may be read without blocking. For STREAMS, this flag is set in revents even if the mes- sage is of zero length. POLLRDNORM Normal data (priority band equals 0) may be read without blocking. For STREAMS, this flag is set in revents even if the message is of zero length. POLLRDBAND Data from a non-zero priority band may be read without blocking. For STREAMS, this flag is set in revents even if the mes- sage is of zero length. POLLPRI High priority data may be received without blocking. For STREAMS, this flag is set in revents even if the message is of zero length. POLLOUT Normal data (priority band equals 0) may be written without blocking. POLLWRNORM The same as POLLOUT. POLLWRBAND Priority data (priority band > 0) may be written. This event only examines bands that have been written to at least once. POLLERR An error has occurred on the device or stream. This flag is only valid in the revents bitmask; it is not used in the events member. POLLHUP A hangup has occurred on the stream. This event and POLLOUT are mutually exclusive; a stream can never be writable if a hangup has occurred. However, this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not mutually exclusive. This flag is only valid in the revents bitmask; it is not used in the events member. POLLNVAL The specified fd value does not belong to an open file. This flag is only valid in the revents member; it is not used in the events member. If the value fd is less than 0, events is ignored and revents is set to 0 in that entry on return from poll(). The results of the poll() query are stored in the revents member in the pollfd structure. Bits are set in the revents bitmask to indicate which of the requested events are true. If none are true, none of the specified bits are set in revents when the poll() call returns. The event flags POLLHUP, POLLERR, and POLLNVAL are always set in revents if the conditions they indicate are true; this occurs even though these flags were not present in events. If none of the defined events have occurred on any selected file descriptor, poll() waits at least timeout milliseconds for an event to occur on any of the selected file descriptors. On a computer where millisecond timing accuracy is not available, timeout is rounded up to the nearest legal value available on that system. If the value timeout is 0, poll() returns immediately. If the value of timeout is -1, poll() blocks until a requested event occurs or until the call is interrupted. The poll() function is not affected by the O_NDELAY and O_NONBLOCK flags. The poll() function supports regular files, terminal and pseudo-terminal devices, STREAMS-based files, FIFOs and pipes. The behavior of poll() on elements of fds that refer to other types of file is unspecified. The poll() function supports sockets. A file descriptor for a socket that is listening for connections will indicate that it is ready for reading, once connections are avail- able. A file descriptor for a socket that is connecting asynchronously will indicate that it is ready for writing, once a connection has been established. Regular files always poll() TRUE for reading and writing. RETURN VALUES
Upon successful completion, a non-negative value is returned. A positive value indicates the total number of file descriptors that has been selected (that is, file descriptors for which the revents member is non-zero). A value of 0 indicates that the call timed out and no file descriptors have been selected. Upon failure, -1 is returned and errno is set to indicate the error. ERRORS
The poll() function will fail if: EAGAIN Allocation of internal data structures failed, but the request may be attempted again. EFAULT Some argument points to an illegal address. EINTR A signal was caught during the poll() function. EINVAL The argument nfds 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. ATTRIBUTES
See attributes(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Interface Stability |Standard | +-----------------------------+-----------------------------+ SEE ALSO
intro(2), getmsg(2), getrlimit(2), putmsg(2), read(2), write(2), select(3C), attributes(5), standards(5), chpoll(9E) STREAMS Programming Guide NOTES
Non-STREAMS drivers use chpoll(9E) to implement poll() on these devices. SunOS 5.10 23 Aug 2001 poll(2)