| POLL(2) | System Calls Manual | POLL(2) | 
poll, pollts, ppoll —
#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);
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.
<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 interval 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 structure 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 blocking.
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:
There are three more conditions that are always checked for regardless of events and thus may always be reported in revents:
The following additional flags are defined:
No file descriptor will ever produce POLLHUP at the same time as POLLWRNORM.
Sockets produce POLLIN rather than POLLHUP when the remote end is closed.
poll() returns the number of descriptors that are ready
  for I/O, or -1 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.
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.
poll() indicates:
EFAULT]EINTR]EINVAL]poll() function appeared in
  AT&T System V Release 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.
The detailed behavior of specific flags is not very portable from one OS to another.
| February 8, 2021 | NetBSD 10.0 |