poll() — Monitor activity on file descriptors and message queues

Standards

Standards / Extensions C or C++ Dependencies
XPG4.2
Single UNIX Specification, Version 3
 both  

Format

Sockets: 
#define _XOPEN_SOURCE_EXTENDED 1
#include <poll.h>

int poll(struct pollfd fds[], nfds_t nmsgsfds, int timeout);
Message queues and sockets: 
#define _XOPEN_SOURCE_EXTENDED 1
#define _OPEN_MSGQ_EXT
#include <sys/types.h>
#include <sys/time.h>
#include <sys/msg.h>
#include <poll.h>

int poll(void *listptr, nmsgsfds_t nmsgsfds, int timeout);

_OPEN_MSGQ_EXT must be defined if message queues are to be monitored.

General description

The poll() function provides applications with a mechanism for multiplexing input/output over the following set of file descriptors:
  • regular files
  • terminal and pseudoterminal devices
  • STREAMS-based files
  • sockets
  • message queues.
  • FIFOs
  • pipes
For each member of the array(s) pointed to by listptr, poll() examines the given file descriptor or message queue for the event(s) specified in the member. The number of pollmsg structures and the number of pollfd structures in the arrays are specified by nmsgsfds. The poll() function identifies those file descriptors on which an application can read or write data, or on which an error event has occurred.
listptr
A pointer to an array of pollfd structures, pollmsg structures, or to a pollist structure. Each structure specifies a file descriptor or message queue identifier and the events of interest for this file or message queue. The type of parameter to pass depends on whether you want to monitor file and socket descriptors, message queue identifiers, or both. To monitor socket descriptors only, set the high-order halfword of nmsgsfds to 0, the low-order halfword to the number of pollfd structures to be provided, and pass a pointer to an array of pollfd structures. To monitor message queues only, set the low-order halfword of nmsgsfds to 0, the high-order halfword to the number of pollmsg structures to be provided, and pass a pointer to an array of pollmsg structures. To monitor both, set nmsgsfds as described below, and pass a pointer to a pollist structure. If a pollist structure is to be used, a structure similar to the following should be defined in a user program. The pollfd structure must precede the pollmsg structure. 
struct pollist {
   struct pollfd fds[3];
   struct pollmsg msgids[2];
   } list;
nmsgsfds
The number of pollmsg structures and the number of pollfd structures pointed to by listptr.

This parameter is divided into two parts. The first half (the high-order 16 bits) gives the number of pollmsg structures containing message queue identifiers. This number must not exceed the value 32767. The second half (the low-order 16 bits) gives the number of pollfd structures containing file descriptors to check. If either half of the nmsgsfds parameter is equal to a value of 0, the corresponding pollmsg structures or pollfd structures is assumed not to be present.

timeout
The amount of time, in milliseconds, to wait for an event to occur.

If none of the defined events have occurred on any selected descriptor, poll() waits at least timeout milliseconds for an event to occur on any of the selected descriptors. If the value of 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 above processing also applies to message queues.

Each pollfd or pollmsg structure contains the following fields:
  • fd/msgid - open file descriptor or message queue identifier
  • events - requested events
  • revents - returned events
The events and revents fields are bitmasks constructed by OR-ing a combination of the following event flags:
POLLERR
An error or exceptional condition has occurred. This flag is only valid in the revents bitmask; it is ignored in the events bitmask.
POLLHUP
The device has been disconnected. This event and POLLOUT are mutually exclusive, a stream can never be writable if a hang-up 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 ignored in the events member.
POLLIN
Same as POLLRDNORM
POLLNVAL
The specified fd/msgid value is invalid. This flag is only valid in the revents bitmask; it is ignored in the events bitmask.
POLLOUT
Same as POLLWRNORM
POLLPRI
Out-of-band data may be received without blocking.
POLLRDBAND
Data from a nonzero priority band may be read without blocking. For STREAMS, this flag is set in revents even if the message is of zero length.
POLLRDNORM
Normal data may be read without blocking.
POLLWRBAND
Priority data (priority band greater than 0) may be written.
POLLWRNORM
Normal data may be written without blocking.
Note: Poll bits are supported as follows.
Regular Files
Always poll() true for reading and writing. This means that all poll() read and write bits are supported. They will never return with POLLERR or POLLHUP.
FIFOs / PIPEs
Do not have the concept of out-of-band data or priority band data. They support POLLIN, POLLRDNORM, POLLOUT, and POLLWRNORM. They ignore POLLPRI, POLLRDBAND, and POLLWRBAND. They never return POLLERR.
TTYs / OCS
Same support as FIFOs and PIPEs, except that TTYs may return POLLERR.
Sockets
Have the concept of out-of-band data. They support POLLIN, POLLRDNORM, POLLOUT, POLLWRNORM, and POLLPRI for out-of-band data. They ignore POLLRDBAND and POLLWRBAND. They may return POLLERR, and never return POLLHUP.

If the value of fd/msgid is less than 0, events is ignored and revents is set to 0 in that entry on return from poll().

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

The poll() function is not affected by the O_NONBLOCK flag.

A file descriptor for a socket that is listening for connections will indicate that it is ready for reading, once connections are available. A file descriptor for a socket that is connecting asynchronously will indicate that it is ready for writing, once a connection has been established.

The following macros are provided to manipulate the nmsgsfds parameter and the return value from poll():
Macro
Description
_SET_FDS_MSGS(nmsgsfds, nmsgs, nfds)
Sets the high-order halfword of nmsgsfds to nmsgs, and sets the low-order halfword of nmsgsfds to nfds.
_NFDS(n)
If the return value n from poll() is nonnegative, returns the number of socket descriptors that meet the read, write, and exception criteria. A descriptor may be counted multiple times if it meets more than one given criterion.
_NMSGS(n)
If the return value n from poll() is nonnegative, returns the number of message queues that meet the read, write, and exception criteria. A message queue may be counted multiple times if it meets more than one given criterion.

Returned value

If successful, poll() returns a nonnegative value.

A positive value indicates the total number of events that were found to be ready among the message queues and the total number of events that were found to be ready among the file descriptors. The return value is similar to nmsgsfds in that the high-order 16 bits of the return value give the number associated with message queues, and the low-order 16 bits give the number associated with file descriptors. Should the number associated with message queues be greater than 32767, only 32767 will be reported. This is to ensure that the return value does not appear to be negative. Should the number associated with file descriptors be greater than 65535, only 65535 will be reported.

If the call timed out and no file descriptors have been selected, poll() returns 0.

If unsuccessful, poll() returns -1 and sets errno to one of the following values:
Error Code
Description
EAGAIN
The allocation of internal data structures failed, but a subsequent request may succeed.
EINTR
A signal was caught during poll().
EINVAL
One of the parameters specified a value that was not correct. Consult the reason code to determine the exact reason the error occurred. The following reason codes can accompany this return code.
  • JRWAITFOREVER
  • JRINVALIDNFDS
  • JRNOFDSTOOMANYQIDS
EIO
One of the descriptors in the select mask has become inoperative and it is being repeatedly included in a select even though other operations against this descriptor have been failing with EIO. A socket descriptor, for example, can become inoperative if TCP/IP is shut down. A failure from select can not tell you which descriptor has failed so generally select will succeed and these descriptors will be reported to you as being ready for whatever event they were being selected for. Subsequently when the descriptor is used on a receive or other operation you will receive the EIO failure and can react to the problem with the individual descriptor. In general you would close() the descriptor and remove it from the next select mask. If the individual descriptor's failing return code is ignored though and an inoperative descriptor is repeatedly selected on and used, even though each time it is used that call fails with EIO, eventually the select call itself will fail with EIO.

Related information