NAME    [Toc]    [Back]

     poll - synchronous I/O multiplexing

SYNOPSIS    [Toc]    [Back]

     #include <poll.h>

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

DESCRIPTION    [Toc]    [Back]

     poll() provides a mechanism for multiplexing  I/O  across  a
set of file descriptors.
   It is similar in function to select(2).  Unlike
select(2),
     however, it is possible to only pass in  data  corresponding
to the file
     descriptors  for which events are wanted.  This makes poll()
more efficient
 than select(2) in most cases.

     The arguments are as follows:

     fds      Points to an array of pollfd structures, which  are
defined as:

                    struct pollfd {
                            int fd;
                            short events;
                            short revents;
                    };

              The fd member is an open file descriptor.  If fd is
-1, the
              pollfd structure is considered unused, and  revents
will be
              cleared.

              The events and revents members are bitmasks of conditions to
              monitor and conditions found, respectively.

     nfds     An unsigned integer specifying the number of pollfd
structures
              in the array.

     timeout   Maximum interval to wait for the poll to complete,
in milliseconds.
  If this value is 0, poll() will return immediately.  If
              this value is INFTIM (-1), poll() will block indefinitely until
              a condition is found.

     The calling process sets the events bitmask and poll()  sets
the revents
     bitmask.  Each call to poll() resets the revents bitmask for
accuracy.
     The condition flags in the bitmasks are defined as:

     POLLIN      Data other than high-priority data may  be  read
without blocking.


     POLLRDNORM  Normal data may be read without blocking.

     POLLRDBAND  Priority data may be read without blocking.

     POLLNORM     Same  as POLLRDNORM.  This flag is provided for
source code
                 compatibility with older programs and should not
be used in
                 new code.

     POLLPRI     High-priority data may be read without blocking.

     POLLOUT     Normal data may be written without blocking.

     POLLWRNORM  Same as POLLOUT.

     POLLWRBAND  Priority data may be written.

     POLLERR     An error has occurred on the device  or  socket.
This flag is
                 only valid in the revents bitmask; it is ignored
in the
                 events member.

     POLLHUP     The device  or  socket  has  been  disconnected.
This event and
                 POLLOUT are mutually-exclusive; a descriptor can
never be
                 writable if a  hangup  has  occurred.   However,
this event and
                 POLLIN,  POLLRDNORM,  POLLRDBAND, or POLLPRI are
not mutuallyexclusive.
  This  flag  is  only  valid  in  the
revents bitmask;
                 it is ignored in the events member.

     POLLNVAL     The  corresponding  file descriptor is invalid.
This flag is
                 only valid in the revents bitmask; it is ignored
in the
                 events member.

     The  significance  and  semantics  of  normal, priority, and
high-priority data
 are device-specific.

     In addition to I/O multiplexing, poll() can be used to  generate simple
     timeouts.   This  functionality may be achieved by passing a
null pointer
     for fds.

RETURN VALUES    [Toc]    [Back]

     Upon error, poll() returns -1 and sets the  global  variable
errno to indicate
  the error.  If the timeout interval was reached before
any events
     occurred, poll() returns 0.  Otherwise, poll()  returns  the
number of file
     descriptors for which revents is non-zero.

EXAMPLES    [Toc]    [Back]

     The  following  example  implements a read from the standard
input that
     times out after 60 seconds:

           #include <err.h>
           #include <poll.h>
           #include <stdio.h>
           #include <unistd.h>

           struct pollfd pfd[1];
           char buf[BUFSIZ];
           int nfds;

           pfd[0].fd = STDIN_FILENO;
           pfd[0].events = POLLIN;
           nfds = poll(pfd, 1, 60 * 1000);
           if (nfds == -1  ||  (pfd[0].revents  &  (POLLERR|POLLHUP|POLLNVAL)))
                   errx(1, "poll error");
           if (nfds == 0)
                   errx(1, "time out");
           if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
                   errx(1, "read");

ERRORS    [Toc]    [Back]

     poll() will fail if:

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

     [EINTR]    poll() caught a signal during  the  polling  process.

     [EINVAL]    nfds  was  greater  than the number of available
file descriptors.


     [EINVAL]   The timeout passed to poll() was too large.

SEE ALSO    [Toc]    [Back]

     getrlimit(2), read(2), select(2), write(2)

HISTORY    [Toc]    [Back]

     A poll() system call appeared in AT&T System V.3 UNIX.

BUGS    [Toc]    [Back]

     The POLLERR and POLLWRBAND flags are accepted but ignored by
the kernel.

     Because OpenBSD does not implement STREAMS, there is no distinction between
 some of the fields in the events and revents bitmasks.
As a result,
 the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent.

     Internally to the kernel, poll() works  poorly  if  multiple
processes wait
     on the same file descriptor.

OpenBSD      3.6                        December     13,     1994