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.