poll()--Wait for Events on Multiple Descriptors

 #include <sys/poll.h>

 int poll(struct pollfd fds[],
          nfds_t nfds,
          int timeout)

The poll() function is used to enable an application to multiplex I/O over a set of descriptors. For each member of the array pointed to by fds, poll() will examine the given descriptor for the event(s) specified. nfds is the number of pollfd structures in the fds array. The poll() function will determine which descriptors can read or write data, or whether certain events have occured on the descriptors within the timeout period.

Parameters

fds

(Input) Specifies an array of descriptors to be examined and the events of interest for each descriptor.

      struct pollfd {
         int    fd;         /* Descriptor        */
         short  events;     /* Requested events  */
         short  revents;    /* Returned events   */
      };

The array's members are pollfd structures within which fd specifies an open descriptor. The events and revents are bitmasks constructed by OR'ing a combination of the following event flags.

The following events can be specified in the events field:

POLLIN	Data may be read without blocking.
POLLPRI	High-priority(OOB) data may be read without blocking.
POLLOUT	Data may be written without blocking.
POLLWRNORM	Equivalent to POLLOUT.
POLLRDNORM	Equivalent to POLLIN.
POLLNORM	Equivalent to POLLIN.

Each of the events listed above may be returned in the revents field when the poll() API completes if that requested condition is valid for the specified descriptor. In addition to these events, the following event may also be returned in the revents field:

POLLNVAL

The specified fd value is invalid. This flag is ignored if it is specified in the events field.

The following events will never be returned in the revents field on a System i^® platform:

POLLRDBAND	Priority message ready to read.
POLLWRBAND	Writable priority band exists.
POLLERR	An error occurred.
POLLHUP	Connection disconnected.

In each pollfd structure, poll() will clear the revents member, except that where the application requested a report on a condition by setting one of the bits of events, poll() will set the corresponding bit in revents if the requested condition is true. In addition, poll() shall set the POLLNVAL flag in revents if the condition is true, even if the application did not set the corresponding bit in events.

nfds

(Input) nfds is the number of pollfd structures in the fds array.

timeout

(Input) The timeout argument specifies how long poll() is to wait before returning. If none of the requested events have occurred on any of the descriptors, poll() will wait at least timeout milliseconds for an event to occur on any of the descriptors. If the value of timeout is 0, poll() will return immediately. If the value of timeout is -1, poll() will block until a requested event occurs or until the call is interrupted.

Authorities

No authorization is required.

Return Value

poll() returns an integer. Possible values are:

• -1 (unsuccessful)
  
  
• 0 (the timeout expired before any of the requested events were satisfied)
  
  
• n (total number of descriptors that met poll criteria)

Error Conditions

When poll() fails, errno can be set to one of the following:

Error Messages

Usage Notes

1. When specifying the POLLIN flag for events, the following can be indicated:
   • Data is available to be read
     
     
   • An error event exists on the descriptor.
     
     
   • A socket descriptor that is listening for connections will indicate that it is ready for reading, once connections are available.
     
     
   • No data can be read from the underlying instance represented by the descriptor. For example, a socket descriptor for which a shutdown() call has been done to disable the reception of data.
     
     
   
   
   
2. When specifying the POLLOUT flag for events, the following can be indicated:
   • When a write() can be successfully issued without blocking (or, for nonblocking, so it does not return [EWOULDBLOCK]).
     
     
   • Completion of a non-blocking connect() call on a socket descriptor. This allows an application to set a socket descriptor to nonblocking (with fcntl() or ioctl()), issue a connect() and receive [EINPROGRESS], and then use poll() to verify that the connection has completed.
     
     
   • No data can be written to the underlying instance represented by the descriptor (for example, a socket descriptor for which a shutdown() has been done to disable the sending of data).
     
     
   
   
   
3. If the revents field is set to POLLPRI when the poll() API completes, this indicates that out-of-band data has arrived on the descriptor specified by the fd field. This is only supported for connection-oriented sockets with an address family of AF_INET or AF_INET6.
   
   
4. The poll() API will not be affected by the O_NONBLOCK flag.
   
   
5. The poll() API is more efficient than the select() API and therefore poll() is always recommended over select().
   
   
6. The timeout mechanism is different between poll() and select(). The poll() API uses an integer with the unit of measure as milliseconds. The select() API uses a timeval structure.
   
   
7. Unpredictable results will appear if this function or any of its associated type and macro definitions are used in a thread executing one of the scan-related exit programs (or any of its' created threads). See Integrated File System Scan on Open Exit Programs and Integrated File System Scan on Close Exit Programs for more information.
   
   
   

Related Information

• select()--Wait for events on Multiple Sockets

[ Back to top | UNIX-Type APIs | APIs by category ]