System Calls poll(2)
NAME
poll, ppoll - input/output multiplexing
SYNOPSIS
#include
int poll(struct pollfd * fds, nfds_t nfds, int timeout);
int ppoll(struct pollfd *restrict fds, nfds_t nfds,
const struct timespec *restrict timeout,const sigset_t *restrict sigmask);
DESCRIPTION
The poll() function provides applications with a mechanism
for multiplexing input/output over a set of file descrip-
tors. 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 structures in the
fds array is specified by nfds. The poll() function identi-
fies 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 exam-
ined and the events of interest for each file descriptor. It is a pointer to an array with one member for each openfile 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 message 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.SunOS 5.11 Last change: 11 Oct 2010 1
System Calls poll(2)
POLLRDBAND Data from a non-zero priority band may be read
without blocking. For streams, this flag is set in revents even if the message 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 writ-
ten. 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 bit-
mask; 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 andrevents 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.SunOS 5.11 Last change: 11 Oct 2010 2
System Calls poll(2)
If none are true, none of the specified bits are set inrevents 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 selectedfile descriptor, poll() waits at least timeout milliseconds
for an event to occur on any of the selected file descrip-
tors. On a computer where millisecond timing accuracy is not available, timeout is rounded up to the nearest legal valueavailable 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 isinterrupted. 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 connec-
tions will indicate that it is ready for reading, once con-
nections 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.Regular files always poll() TRUE for reading and writing.
The relationship between poll() and ppoll() is analogous to
the relationship between select(3C) and pselect(3C): likepselect(), ppoll() allows an application to safely wait
until either a file descriptor becomes ready or until a sig-
nal is caught.Other than the difference in the timeout argument, the fol-
lowing ppoll() call:
ready = ppoll(&fds, nfds, timeout, &sigmask);
SunOS 5.11 Last change: 11 Oct 2010 3
System Calls poll(2)
is equivalent to atomically executing the following calls:sigset_t origmask;
sigprocmask(SIG_SETMASK, &sigmask, &origmask);
ready = ppoll(&fds, nfds, timeout);
sigprocmask(SIG_SETMASK, &origmask, NULL);
If sigmask is not a null pointer, then the pselect() func-
tion replaces the signal mask of the process by the set ofsignals pointed to by sigmask before examining the descrip-
tors, and restores the signal mask of the process before returning. The timeout argument specifies an upper limit on the amountof time that ppoll() will block. This argument is a pointer
to a structure of the following form: struct timespec {long tv_sec; /* seconds */
long tv_nsec; /* nanoseconds */
};If timeout is specified as NULL, ppoll() can block indefin-
itely.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, filedescriptors for which the revents member is non-zero). A
value of 0 indicates that the call timed out and no filedescriptors have been selected. Upon failure, -1 is returned
and errno is set to indicate the error.ERRORS
The poll() and ppoll() functions 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.
SunOS 5.11 Last change: 11 Oct 2010 4
System Calls poll(2)
EINVAL The argument nfds is greater than {OPEN_MAX}, or
one of the fd members refers to a stream or multi-
plexer that is linked (directly or indirectly) downstream from a multiplexer.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
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 NOTESNon-STREAMS drivers use chpoll(9E) to implement poll() on
these devices.SunOS 5.11 Last change: 11 Oct 2010 5