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 multiplexing input/output over a set of file descriptors.  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 struc-
       tures  in  the  fds  array  is specified by nfds. The poll() function identifies 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
       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 mes-
		       sage 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 mes-
		       sage 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 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 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.  The poll() function is not affected by the O_NDELAY and
       O_NONBLOCK flags.

       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 connections will indicate that it is ready for reading, once connections are avail-
       able.  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.

ATTRIBUTES

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

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)