👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for poll (linux section 3posix)

POLL(P) 			    POSIX Programmer's Manual				  POLL(P)

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()
       shall  examine  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  shall
       identify  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 within which  fd  speci-
       fies  an  open file descriptor and events and revents are bitmasks constructed by OR'ing a
       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. This  flag
       shall be equivalent to POLLRDNORM | POLLRDBAND.

       POLLRDNORM
	      Normal data may be read without blocking.

       For  STREAMS,  data  on priority band 0 may be read without blocking.  This flag is set in
       revents even if the message is of zero length.

       POLLRDBAND
	      Priority data may be read without blocking.

       For STREAMS, data on priority bands greater than 0 may be read without blocking. This flag
       is set in revents even if the message is of zero length.

       POLLPRI
	      High-priority data may be read without blocking.

       For STREAMS, this flag is set in revents even if the message is of zero length.

       POLLOUT
	      Normal data may be written without blocking.

       For STREAMS, data on priority band 0 may be written without blocking.

       POLLWRNORM
	      Equivalent to POLLOUT.

       POLLWRBAND
	      Priority data may be written.

       For STREAMS, data on priority bands greater than 0 may be written without blocking. If any
       priority band has been written to on this STREAM, 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 shall be ignored in the events member.

       POLLHUP
	      The device has been disconnected. 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 shall be ignored in the events member.

       POLLNVAL
	      The  specified  fd value is invalid. This flag is only valid in the revents member;
	      it shall ignored in the events member.

       The significance and semantics of normal, priority, and high-priority data  are	file  and
       device-specific.

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

       In each pollfd structure, poll() shall clear the revents member,  except  that  where  the
       application  requested a report on a condition by setting one of the bits of events listed
       above, poll() shall set the corresponding bit in revents if  the  requested  condition  is
       true.  In addition, poll() shall set the POLLHUP, POLLERR, and POLLNVAL flag in revents if
       the condition is true, even if the application  did  not  set  the  corresponding  bit  in
       events.

       If  none of the defined events have occurred on any selected file descriptor, poll() shall
       wait at least timeout milliseconds for an event to occur  on  any  of  the  selected  file
       descriptors.   If the value of timeout is 0, poll() shall return immediately. If the value
       of timeout is -1, poll() shall block until a requested event occurs or until the  call  is
       interrupted.

       Implementations	may  place  limitations  on  the granularity of timeout intervals. If the
       requested timeout interval requires a finer granularity than the implementation	supports,
       the actual timeout interval shall be rounded up to the next supported value.

       The poll() function shall not be affected by the O_NONBLOCK flag.

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

       Regular files shall always poll TRUE for reading and writing.

       A file descriptor for a socket that is listening for connections shall indicate that it is
       ready for reading, once connections are available. A file descriptor for a socket that  is
       connecting  asynchronously  shall indicate that it is ready for writing, once a connection
       has been established.

RETURN VALUE
       Upon successful completion, poll() shall return a non-negative  value.  A  positive  value
       indicates  the  total  number  of  file descriptors that have 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, poll() shall
       return -1 and set errno to indicate the error.

ERRORS
       The poll() function shall fail if:

       EAGAIN The allocation of internal data structures failed but a subsequent request may suc-
	      ceed.

       EINTR  A signal was caught during poll().

       EINVAL The nfds argument 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.

       The following sections are informative.

EXAMPLES
   Checking for Events on a Stream
       The  following  example	opens  a pair of STREAMS devices and then waits for either one to
       become writable. This example proceeds as follows:

	1. Sets the timeout parameter to 500 milliseconds.

	2. Opens the STREAMS devices /dev/dev0 and /dev/dev1, and  then  polls	them,  specifying
	   POLLOUT and POLLWRBAND as the events of interest.

       The  STREAMS device names /dev/dev0 and /dev/dev1 are only examples of how STREAMS devices
       can be named; STREAMS  naming  conventions  may	vary  among  systems  conforming  to  the
       IEEE Std 1003.1-2001.

	3. Uses  the ret variable to determine whether an event has occurred on either of the two
	   STREAMS. The poll() function is given 500 milliseconds to wait for an event	to  occur
	   (if it has not occurred prior to the poll() call).

	4. Checks  the returned value of ret. If a positive value is returned, one of the follow-
	   ing can be done:

	    a. Priority data can be written to the open STREAM on priority bands greater than  0,
	       because the POLLWRBAND event occurred on the open STREAM ( fds[0] or fds[1]).

	    b. Data  can  be  written  to the open STREAM on priority-band 0, because the POLLOUT
	       event occurred on the open STREAM ( fds[0] or fds[1]).

	5. If the returned value is not a positive value, permission to write data  to	the  open
	   STREAM (on any priority band) is denied.

	6. If  the POLLHUP event occurs on the open STREAM ( fds[0] or fds[1]), the device on the
	   open STREAM has disconnected.

	      #include <stropts.h>
	      #include <poll.h>
	      ...
	      struct pollfd fds[2];
	      int timeout_msecs = 500;
	      int ret;
		  int i;

	      /* Open STREAMS device. */
	      fds[0].fd = open("/dev/dev0", ...);
	      fds[1].fd = open("/dev/dev1", ...);
		  fds[0].events = POLLOUT | POLLWRBAND;
		  fds[1].events = POLLOUT | POLLWRBAND;

	      ret = poll(fds, 2, timeout_msecs);

	      if (ret > 0) {
		  /* An event on one of the fds has occurred. */
		  for (i=0; i<2; i++) {
		      if (fds[i].revents & POLLWRBAND) {
		      /* Priority data may be written on device number i. */
	      ...
		      }
		      if (fds[i].revents & POLLOUT) {
		      /* Data may be written on device number i. */
	      ...
		      }
		      if (fds[i].revents & POLLHUP) {
		      /* A hangup has occurred on device number i. */
	      ...
		      }
		  }
	      }

APPLICATION USAGE
       None.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       STREAMS , getmsg() , putmsg() , read() , select() , write() , the Base Definitions  volume
       of IEEE Std 1003.1-2001, <poll.h>, <stropts.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					  POLL(P)


All times are GMT -4. The time now is 12:33 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password