unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

POLL(2)                       System Calls Manual                      POLL(2)



NAME
       poll - I/O multiplexing

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

       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-prior-
                      ity 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 read-
                      able.   In revents, this flag is mutually exclusive with
                      POLLPRI.

       POLLPRI        If the file descriptor is a stream, a  priority  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 exceptional condition
                      has occurred.  In revents, this flag is mutually  exclu-
                      sive with POLLIN.

       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 exclusive.  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) specified 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  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 positive value indi-
       cates  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() system 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                        POLL(2)