unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

POLL(2)                     BSD System Calls Manual                    POLL(2)

NAME
     poll, ppoll -- synchronous I/O multiplexing

SYNOPSIS
     #include <&lt;poll.h>&gt;

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

     int
     ppoll(struct pollfd *fds, nfds_t nfds, const struct timespec *timeout,
         const sigset_t *mask);

DESCRIPTION
     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 effi-
     cient 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 millisec-
              onds.  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 block-
                 ing.

     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 mutually-
                 exclusive.  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.  For example, on OpenBSD, the POLLPRI and
     POLLRDBAND flags may be used to detect when out-of-band socket data may
     be read without blocking.

     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.

     The ppoll() function is similar to poll() except that it specifies the
     timeout using a timespec structure, and a null pointer is used to specify
     an indefinite timeout instead of INFTIM.  Also, if mask is a non-null
     pointer, ppoll() atomically sets the calling thread's signal mask to the
     signal set pointed to by mask for the duration of the function call.  In
     this case, the original signal mask will be restored before ppoll()
     returns.

RETURN VALUES
     Upon error, poll() and ppoll() return -1 and set the global variable
     errno to indicate the error.  If the timeout interval was reached before
     any events occurred, they return 0.  Otherwise, they return the number of
     pollfd structures for which revents is non-zero.

IDIOMS
     Care must be taken when converting code from select(2) to poll() as they
     have slightly different semantics.  The first semantic difference is
     that, unlike select(2), poll() has a way of indicating that one or more
     file descriptors is invalid by setting a flag in the revents field of
     corresponding entry of fds, whereas select(2) returns an error (-1) if
     any of the descriptors with bits set in the fd_set are invalid.  The sec-
     ond difference is that on EOF there is no guarantee that POLLIN will be
     set in revents, the caller must also check for POLLHUP.  This differs
     from select(2) where EOF is considered as a read event.

     Consider the following usage of select(2) that implements a read from the
     standard input with a 60 second time out:

           struct timeval timeout;
           fd_set readfds;
           char buf[BUFSIZ];
           int nready;

           timeout.tv_sec = 60;
           timeout.tv_usec = 0;
           FD_ZERO(&readfds);
           FD_SET(STDIN_FILENO);
           nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout);
           if (nready == -1)
                   err(1, "select");
           if (nready == 0)
                   errx(1, "time out");
           if (FD_ISSET(STDIN_FILENO, &readfds)) {
                   if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
                           err(1, "read");
           }

     This can be converted to poll() as follows:

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

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

ERRORS
     poll() and ppoll() will fail if:

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

     [EINTR]            A signal was caught before any polled events occurred
                        and before the timeout elapsed.

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

     [EINVAL]           The timeout passed was invalid.

SEE ALSO
     clock_gettime(2), getrlimit(2), read(2), select(2), write(2)

STANDARDS
     The poll() function is compliant with the IEEE Std 1003.1-2008
     (``POSIX.1'') specification.  The ppoll() function is a Linux extension.

HISTORY
     A poll() system call appeared in AT&T System V Release 3 UNIX.  The
     ppoll() function appeared in OpenBSD 5.4.

BUGS
     The POLLWRBAND flag is 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.  Simi-
     larly, the POLLPRI and POLLRDBAND flags are also equivalent.

     Internally to the kernel, poll() and ppoll() work poorly if multiple pro-
     cesses wait on the same file descriptor.

BSD                              March 3, 2015                             BSD