unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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



System Calls                                              poll(2)



NAME
     poll - input/output multiplexing

SYNOPSIS
     #include <poll.h>

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

DESCRIPTION
     The poll() function provides applications with  a  mechanism
     for  multiplexing  input/output  over a set of file descrip-
     tors.  For each member of  the  array  pointed  to  by  fds,
     poll()  examines  the given file descriptor for the event(s)
     specified in events. The number of pollfd structures in  the
     fds array is specified by nfds.  The poll() function identi-
     fies those file descriptors on which an application can read
     or write data, or on which certain events have occurred.

     The fds argument specifies the file descriptors to be  exam-
     ined  and  the  events of interest for each file descriptor.
     It is a pointer to an array with one member  for  each  open
     file descriptor of interest.  The array's members are pollfd
     structures, which contain the following members:

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

     The fd member specifies an  open  file  descriptor  and  the
     events  and  revents  members  are bitmasks constructed by a
     logical OR operation of any  combination  of  the  following
     event flags:

     POLLIN
           Data other than high priority data may be read without
           blocking.  For  STREAMS,  this  flag is set in revents
           even if the message is of zero length.

     POLLRDNORM
           Normal data (priority  band  equals  0)  may  be  read
           without  blocking.  For  STREAMS,  this flag is set in
           revents even if the message is of zero length.

     POLLRDBAND
           Data from a non-zero priority band may be read without
           blocking.  For  STREAMS,  this  flag is set in revents
           even if the message is of zero length.

     POLLPRI
           High priority data may be received  without  blocking.
           For  STREAMS,  this flag is set in revents even if the
           message is of zero length.



SunOS 5.9           Last change: 23 Aug 2001                    1






System Calls                                              poll(2)



     POLLOUT
           Normal data (priority band equals 0)  may  be  written
           without blocking.

     POLLWRNORM
           The same as  POLLOUT.

     POLLWRBAND
           Priority data (priority band  >  0)  may  be  written.
           This  event only examines bands that have been written
           to at least once.

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

     POLLHUP
           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,  POLLRDNORM, POLLRDBAND, or  POLLPRI are
           not mutually exclusive. This flag is only valid in the
           revents bitmask; it is not used in the events member.

     POLLNVAL
           The specified fd value does  not  belong  to  an  open
           file.  This  flag is only valid in the revents member;
           it is not used in the events member.

     If the value fd is  less  than  0,  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
     member  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 are 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  descrip-
     tors. 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.  The poll() function is  not  affected  by  the
     O_NDELAY and  O_NONBLOCK flags.



SunOS 5.9           Last change: 23 Aug 2001                    2






System Calls                                              poll(2)



     The poll() function supports  regular  files,  terminal  and
     pseudo-terminal  devices,  STREAMS-based  files,  FIFOs  and
     pipes.  The behavior of poll() on elements of fds that refer
     to other types of file is unspecified.

     The poll() function supports sockets.

     A file descriptor for a socket that is listening for connec-
     tions  will indicate that it is ready for reading, once con-
     nections are available.  A file descriptor for a socket that
     is  connecting asynchronously will indicate that it is ready
     for writing, once a connection has been established.

     Regular files always poll() TRUE for reading and writing.

RETURN VALUES
     Upon  successful  completion,  a   non-negative   value   is
     returned.  A  positive  value  indicates the total number of
     file descriptors that  has  been  selected  (that  is,  file
     descriptors  for  which  the  revents member is non-zero). A
     value of 0 indicates that the call timed  out  and  no  file
     descriptors have been selected. Upon failure, -1 is returned
     and errno is set to indicate the error.

ERRORS
     The poll() function will fail if:

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

     EFAULT
           Some argument points to an illegal address.

     EINTR A signal was caught during the poll() function.

     EINVAL
           The argument nfds is greater than {OPEN_MAX},  or  one
           of  the  fd  members refers to a STREAM or multiplexer
           that is linked  (directly  or  indirectly)  downstream
           from a multiplexer.

SEE ALSO
     intro(2),  getmsg(2),  getrlimit(2),   putmsg(2),   read(2),
     write(2), select(3C), chpoll(9E)

     STREAMS Programming Guide

NOTES
     Non-STREAMS drivers use  chpoll(9E) to implement  poll()  on
     these devices.




SunOS 5.9           Last change: 23 Aug 2001                    3