unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (HP-UX-11.11)
Page:
Section:
Apropos / Subsearch:
optional field



 poll(2)							     poll(2)




 NAME
      poll - monitor I/O conditions on multiple file descriptors

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

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

 DESCRIPTION
      poll() provides a general mechanism for reporting I/O conditions
      associated with a set of file descriptors and for waiting until one or
      more specified conditions becomes true.  Specified conditions include
      the ability to read or write data without blocking, and error
      conditions.

    Arguments
	   fds		  Points to an array of pollfd structures, one for
			  each file descriptor of interest.

	   nfds		  Specifies the number of pollfd structures in the
			  fds array.

	   timeout	  Specifies the maximum length of time (in
			  milliseconds) to wait for at least one of the
			  specified conditions to occur.

      Each pollfd structure includes the following members:

	   int fd	       File descriptor
	   short events	       Requested conditions
	   short revents       Reported conditions

      The fd member of each pollfd structure specifies an open file
      descriptor.  The poll() function uses the events member to determine
      what conditions to report for this file descriptor.  If one or more of
      these conditions is true, poll() sets the associated revents member.

      poll() ignores any pollfd structure whose fd member is negative.	If
      the fd member of all pollfd structures is negative, poll() returns 0
      and has no other results.

      The events and revents members of the pollfd structure are bit masks.
      The calling process sets the events bit mask, and poll() sets the
      revents bit masks.  These bit masks contain ORed combinations of
      condition flags.	The following condition flags are defined:





 Hewlett-Packard Company	    - 1 -   HP-UX Release 11i: November 2000






 poll(2)							     poll(2)




	   POLLIN	       Data can be read without blocking.  For
			       streams, this flag means that a message that
			       is not high priority is at the front of the
			       stream head read queue.	This message can be
			       of zero length.
	   POLLNORM	       Synonym for POLLIN
	   POLLPRI	       A high priority message is available.  For
			       streams, this message can be of zero length.
	   POLLOUT	       Data can be written without blocking.  For
			       streams, this flag specifies that normal data
			       (not high priority or priority band > 0) can
			       be written without being blocked by flow
			       control.	 This flag is not used for high
			       priority data, because it can be written even
			       if the stream is flow controlled.
	   POLLERR	       An error has occurred on the file descriptor.
	   POLLHUP	       The device has been disconnected.  For
			       streams, this flag in revents is mutually
			       exclusive with POLLOUT, since a stream cannot
			       be written to after a hangup occurs.  This
			       flag and POLLIN, POLLPRI, POLLRDNORM,
			       POLLRDBAND, and POLLMSG are not mutually
			       exclusive.
	   POLLNVAL	       fd is not a valid file descriptor.
	   POLLRDNORM	       A non-priority message is available.  For
			       streams, this flag means that a normal
			       message (not high priority or priority band >
			       0) is at the front of the stream head read
			       queue.  This message can be of zero length.
	   POLLRDBAND	       A priority message (priority band > 0) is at
			       the front of the stream head read queue.
			       This message can be read without blocking.
			       The message can be of zero length.
	   POLLWRNORM	       Same as POLLOUT
	   POLLWRBAND	       Priority data (priority band > 0) can be
			       written without being blocked by flow
			       control.	 Only previously written bands are
			       checked.
	   POLLMSG	       A M_SIG or M_PCSIG message specifying SIGPOLL
			       has reached the front of the stream head read
			       queue.

      The conditions indicated by POLLNORM and POLLOUT are true if and only
      if at least one byte of data can be read or written without blocking.
      The exception is regular files, which always poll true for POLLNORM
      and POLLOUT.  Also, streams return POLLNORM in revents even if the
      available message is of zero length.

      The condition flags POLLERR, POLLHUP, and POLLNVAL are always set in
      revents if the conditions they indicate are true for the specified
      file descriptor, whether or not these flags are set in events.



 Hewlett-Packard Company	    - 2 -   HP-UX Release 11i: November 2000






 poll(2)							     poll(2)




      For each call to poll(), the set of reportable conditions for each
      file descriptor consists of those conditions that are always reported,
      together with any further conditions for which flags are set in
      events.  If any reportable condition is true for any file descriptor,
      poll() returns with flags set in revents for each true condition for
      that file descriptor.

      If no reportable condition is true for any of the file descriptors,
      poll() waits up to timeout milliseconds for a reportable condition to
      become true.  If, in that time interval, a reportable condition
      becomes true for any of the file descriptors, poll() reports the
      condition in the file descriptor's associated revents member and
      returns.	If no reportable condition becomes true, poll() returns
      without setting any revents bit masks.

      If the timeout parameter is a value of -1, poll() does not return
      until at least one specified event has occurred.	If the value of the
      timeout parameter is 0, poll() does not wait for an event to occur but
      returns immediately, even if no specified event has occurred.  The
      behavior of poll() is not affected by whether the O_NONBLOCK flag is
      set on any of the specified file descriptors.

 RETURN VALUES
      Upon successful completion, poll() returns a nonnegative value.  If
      the call returns 0, poll() has timed out and has not set any of the
      revents bit masks.  A positive value indicates the number of file
      descriptors for which poll() has set the revents bit mask.  If poll()
      fails, it returns -1 and sets errno to indicate the error.

 ERRORS
      poll() fails if any of the following conditions are encountered:

	   [EAGAIN]	  Allocation of internal data structures failed.  A
			  later call to poll() may complete successfully.

	   [EINTR]	  A signal was delivered before any of the selected
			  for conditions occurred or before the time limit
			  expired.

	   [EINVAL]	  timeout is a negative number other than -1.

	   [EFAULT]	  The fds parameter in conjunction with the nfds
			  parameter addresses a location outside of the
			  allocated address space of the process.  Reliable
			  detection of this error is implementation-
			  dependent.

 EXAMPLES
      Wait for input on file descriptor 0:





 Hewlett-Packard Company	    - 3 -   HP-UX Release 11i: November 2000






 poll(2)							     poll(2)




	   #include <&lt&lt&lt;poll.h>&gt&gt&gt;
	   struct pollfd fds;

	   fds.fd = 0;
	   fds.events = POLLNORM;
	   poll(&&amp&amp&amp;fds, 1, -1);

      Wait for input on ifd1 and ifd2, output on ofd, giving up after 10
      seconds:

	   #include <&lt&lt&lt;poll.h>&gt&gt&gt;
	   struct pollfd fds[3];
	   int ifd1, ifd2, ofd, count;

	   fds[0].fd = ifd1;
	   fds[0].events = POLLNORM;
	   fds[1].fd = ifd2;
	   fds[1].events = POLLNORM;
	   fds[2].fd = ofd;
	   fds[2].events = POLLOUT;
	   count = poll(fds, 3, 10000);
	   if (count == -1) {
		   perror("poll failed");
		   exit(1);
	   }
	   if (count==0)
		   printf("No data for reading or writing\n");
	   if (fds[0].revents &&amp&amp&amp; POLLNORM)
		   printf("There is data for reading fd %d\n", fds[0].fd);
	   if (fds[1].revents &&amp&amp&amp; POLLNORM)
		   printf("There is data for reading fd %d\n", fds[1].fd);
	   if (fds[2].revents &&amp&amp&amp; POLLOUT)
		   printf("There is room to write on fd %d\n", fds[2].fd);

      Check for input or output on file descriptor 5 without waiting:

	   #include <&lt&lt&lt;poll.h>&gt&gt&gt;
	   struct pollfd fds;

	   fds.fd = 5;
	   fds.events = POLLNORM|POLLOUT;
	   poll(&&amp&amp&amp;fds, 1, 0);
	   if (fds.revents &&amp&amp&amp; POLLNORM)
		   printf("There is data available on fd %d\n", fds.fd);
	   if (fds.revents &&amp&amp&amp; POLLOUT)
		   printf("There is room to write on fd %d\n", fds.fd);

      Wait 3.5 seconds:

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



 Hewlett-Packard Company	    - 4 -   HP-UX Release 11i: November 2000






 poll(2)							     poll(2)




	   poll((struct pollfd *) NULL, 0, 3500);

      Wait for a high priority, priority, or normal message on streams file
      descriptor 0:

	   #include <&lt&lt&lt;poll.h>&gt&gt&gt;
	   struct pollfd fds;

	   fds.fd = 0;
	   fds.events = POLLIN|POLLPRI;
	   poll(&&amp&amp&amp;fds, 1, -1);

 SEE ALSO
      read(2), write(2), select(2), getmsg(2), putmsg(2), streamio(7).

 STANDARDS CONFORMANCE
      poll(): AES, SVID2, SVID3





































 Hewlett-Packard Company	    - 5 -   HP-UX Release 11i: November 2000