Short: Use poll() instead of select()
Date: 980816
From: Lynx
Type: Feature
State: Acknowledged

poll() scales better for a large number of users, but is not implemented
everywhere.

Implementation maybe by simulation poll() through select() where not
supported.


POLL(2)                                                   POLL(2)


NAME
       poll - I/O multiplexing

SYNOPSIS
       #include <poll.h>

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

DESCRIPTION
       poll()  provides  users  with a mechanism for multiplexing
       input/output  over  a  set  of   file   descriptors   (see
       intro(2)).   poll()  identifies  those file descriptors on
       which a user can send or receive  messages,  or  on  which
       certain events have occurred.  A user can receive messages
       using read(2V) or getmsg(2) and can  send  messages  using
       write(2V)  and putmsg(2).  Certain ioctl(2) calls, such as
       I_RECVFD and I_SENDFD (see streamio(4)), can also be  used
       to receive and send messages on streams.

       fds  specifies the file descriptors to be examined and the
       events of interest for each  file  descriptor.   It  is  a
       pointer  to  an  array with one element for each open file
       descriptor of interest.  The array's elements  are  pollfd
       structures which contain the following members:

              int fd;                  /* file descriptor */
              short events;            /* requested events */
              short revents;           /* returned events */

       where  fd specifies an open file descriptor and events and
       revents are bitmasks constructed by ORing any  combination
       of the following event flags:

       POLLIN         If  the file descriptor refers to a stream,
                      a non-priority or file  descriptor  passing
                      message  (see  I_RECVFD)  is present on the
                      stream head read queue.  This flag  is  set
                      even  if the message is of zero length.  If
                      the file descriptor is not  a  stream,  the
                      file  descriptor  is readable.  In revents,
                      this flag is mutually exclusive with  POLL
                      PRI.

       POLLPRI        If  the file descriptor is a stream, a pri
                      ority message is present on the stream head
                      read  queue.   This flag is set even if the
                      message is of zero  length.   If  the  file
                      descriptor  is  not  a  stream, some excep
                      tional condition has occurred.  In revents,
                      this   flag   is  mutually  exclusive  with
                      POLLIN.



                         21 January 1990                        1





POLL(2)                                                   POLL(2)


       POLLOUT        If the file descriptor  is  a  stream,  the
                      first  downstream write queue in the stream
                      is not full.  Priority control messages can
                      be  sent  (see  putmsg(2)) at any time.  If
                      the file descriptor is not a stream, it  is
                      writable.

       POLLERR        If  the  file  descriptor  is  a stream, an
                      error message has  arrived  at  the  stream
                      head.   This  flag  is  only  valid  in the
                      revents bitmask; it  is  not  used  in  the
                      events field.

       POLLHUP        If  the  file  descriptor  is  a  stream, 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 or POLLPRI are not  mutually  exclu
                      sive.   This  flag  is  only  valid  in the
                      revents bitmask; it  is  not  used  in  the
                      events field.

       POLLNVAL       The  specified fd value does not specify an
                      open file descriptor.  This  flag  is  only
                      valid  in the revents field; it is not used
                      in the events field.

       For each element of the array pointed to  by  fds,  poll()
       examines the given file descriptor for the event(s) speci
       fied in events.  The number  of  file  descriptors  to  be
       examined is specified by nfds.  If nfds exceeds the system
       limit of open files (see  getdtablesize(2)),  poll()  will
       fail.

       If  the  value fd is less than zero, events is ignored and
       revents is set to 0 in that entry on return from poll().

       The results of the poll() query are stored in the  revents
       field  in  the  pollfd  structure.   Bits  are  set in the
       revents bitmask to indicate which of the requested  events
       are true.  If none are true, none of the specified bits is
       set in revents 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
       selected  file  descriptor,  poll() waits at least timeout
       milliseconds for an event to occur on any of the  selected
       file  descriptors.  On a computer where millisecond timing
       accuracy is not available, timeout is rounded  up  to  the
       nearest  legal  value  available  on  that system.  If the
       value timeout is 0, poll() returns  immediately.   If  the



                         21 January 1990                        2





POLL(2)                                                   POLL(2)


       value  of  timeout  is -1, poll() blocks until a requested
       event occurs or until the call is interrupted.  poll()  is
       not affected by the O_NDELAY flag.

RETURN VALUES
       poll()  returns  a non-negative value on success.  A posi
       tive value indicates the total number of file  descriptors
       that has been selected (for instance, file descriptors for
       which the revents field is  non-zero).   0  indicates  the
       call timed out and no file descriptors have been selected.
       On failure, poll() returns -1 and sets errno  to  indicate
       the error.

ERRORS
       EAGAIN         Allocation   of  internal  data  structures
                      failed, but the request should be attempted
                      again.

       EFAULT         Some  argument points outside the allocated
                      address space.

       EINTR          A signal was caught during the poll()  sys
                      tem call.

       EINVAL         The argument nfds is less than zero.

                      nfds  is  greater  than the system limit of
                      open files.

SEE ALSO
       getdtablesize(2),    getmsg(2),    intro(2),     ioctl(2),
       putmsg(2), read(2V), select(2), write(2V), streamio(4)

























                         21 January 1990                        3


