unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

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

poll(2)                          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 multi-
       plexing input/output over a set of file descriptors.  For  each  member
       of the array pointed to by fds, poll() examines the given file descrip-
       tor for the event(s) specified in events. The number of  pollfd  struc-
       tures  in the fds array is specified by nfds. The poll() function iden-
       tifies 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 examined 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 mem-
       bers:

       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 with-
                       out 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.



       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  speci-
       fied  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 descriptors. On a computer where mil-
       lisecond 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.

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

       The poll() function supports sockets.

       A  file  descriptor for a socket that is listening for connections will
       indicate that it is ready for reading, once connections 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 posi-
       tive 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.



ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:


       tab()    allbox;    cw(2.750000i)|     cw(2.750000i)     lw(2.750000i)|
       lw(2.750000i).   ATTRIBUTE TYPEATTRIBUTE VALUE Interface StabilityStan-
       dard


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

       STREAMS Programming Guide

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



SunOS 5.10                        23 Aug 2001                          poll(2)