poll(2) - NetBSD Manual Pages

POLL(2)                   NetBSD System Calls Manual                   POLL(2)


NAME

     poll, pollts, ppoll -- synchronous I/O multiplexing


LIBRARY

     Standard C Library (libc, -lc)


SYNOPSIS

     #include <poll.h>

     int
     poll(struct pollfd *fds, nfds_t nfds, int timeout);

     #include <poll.h>
     #include <signal.h>
     #include <time.h>

     int
     pollts(struct pollfd * restrict fds, nfds_t nfds,
         const struct timespec * restrict ts,
         const sigset_t * restrict sigmask);

     #include <poll.h>
     #include <signal.h>
     #include <time.h>

     int
     ppoll(struct pollfd * restrict fds, nfds_t nfds,
         const struct timespec * restrict ts,
         const sigset_t * restrict sigmask);


DESCRIPTION

     poll(), pollts() and ppoll() examine a set of file descriptors to see if
     some of them are ready for I/O.  For each object inspected, the caller
     provides a list of conditions (called ``events'') to check for, and the
     kernel returns a list of conditions that are true.  The intent, as with
     select(2), is to check for whether I/O is possible before performing any,
     so as to permit a top-level event loop to process input from many sources
     (and output to many destinations) without blocking on any of them and
     thus becoming stuck.

   Arguments
     The fds argument is a pointer to an array of pollfd structures, one per
     file to inspect, as defined in <poll.h> (shown below).  The nfds argument
     gives the size of the fds array.

     If timeout is neither zero nor INFTIM (-1), it specifies a maximum inter-
     val to wait for any file descriptor to become ready, in milliseconds.  If
     timeout is INFTIM (-1), then poll() blocks indefinitely.  If timeout is
     zero, then poll() will return without blocking.

     Similarly, if ts is not a null pointer, it references a timespec struc-
     ture which specifies a maximum interval to wait for any file descriptor
     to become ready.  If ts is a null pointer, pollts() and ppoll() block
     indefinitely.  If ts is not a null pointer, referencing a zero-valued
     timespec structure, then pollts() and ppoll() will return without block-
     ing.

     If sigmask is not a null pointer, then the pollts() and ppoll() functions
     replace the signal mask of the caller by the set of signals pointed to by
     sigmask while the call is in progress, and restore the caller's original
     signal mask before returning.

     The pollfd structure:

     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.  (Input)
     events      Conditions to poll for.  (Input)
     revents     Conditions that are true.  (Output)

   Conditions
     There are four conditions that can be placed in events and reported in
     revents:

     POLLRDNORM     Normal data may be read without blocking.
     POLLRDBAND     Urgent/out-of-band data may be read without blocking.
     POLLWRNORM     Normal data may be written without blocking.
     POLLWRBAND     Urgent/out-of-band data may be written without blocking.

     There are three more conditions that are always checked for regardless of
     events and thus may always be reported in revents:

     POLLERR        An exceptional condition has occurred on the object.
     POLLHUP        The object has been disconnected.
     POLLNVAL       The file descriptor is not open.

     The following additional flags are defined:

     POLLIN         Synonym for POLLRDNORM.
     POLLOUT        Synonym for POLLWRNORM.
     POLLPRI        Synonym for POLLRDBAND.

   Notes
     If the value passed in fd is negative, the entry is ignored and revents
     is set to 0.  (POLLNVAL is not set.)

     No file descriptor will ever produce POLLHUP at the same time as POLL-
     WRNORM.

     Sockets produce POLLIN rather than POLLHUP when the remote end is closed.


RETURN VALUES

     poll() returns the number of descriptors that are ready for I/O, or
     returns -1 and sets errno 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.


COMPATIBILITY

     This implementation differs from the historical one in that no individual
     file descriptor may cause poll() to return with an error.  In cases where
     this would have happened in the historical implementation (e.g. trying to
     poll a revoke(2)d descriptor), this implementation instead copies the
     events bitmask to the revents bitmask.  Attempting to perform I/O on this
     descriptor will then return an error.  This behavior is believed to be
     more useful.

     The ppoll() function is a wrapper for pollts() to provide compatibility
     with the Linux implementation.


ERRORS

     An error return from poll() indicates:

     [EFAULT]           fds points outside the process's allocated address
                        space.

     [EINTR]            A signal was delivered before the time limit expired
                        and before any of the selected events occurred.

     [EINVAL]           The specified time limit is negative or the number of
                        pollfd structures specified is larger than the current
                        file descriptor resource limit.


SEE ALSO

     accept(2), connect(2), read(2), recv(2), select(2), send(2), write(2)


HISTORY

     The poll() function appeared in AT&T System V.3 UNIX, and was added to
     NetBSD in NetBSD 1.3.  The pollts() function first appeared in
     NetBSD 3.0.  The ppoll() function first appeared in NetBSD 10.0.


BUGS

     As of this writing, in the underlying implementation, POLLIN and POLLPRI
     are distinct flags from POLLRDNORM and POLLRDBAND (respectively) and the
     behavior is not always exactly identical.

     The detailed behavior of specific flags is not very portable from one OS
     to another.

NetBSD 10.99                   February 8, 2021                   NetBSD 10.99