*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> standard/poll (2)              


POLL(2)								       POLL(2)

NAME    [Toc]    [Back]

     poll - input/output multiplexing

SYNOPSIS    [Toc]    [Back]

     #include <stropts.h>
     #include <poll.h>

     int poll(struct pollfd *fds, unsigned long	nfds, int timeout);

DESCRIPTION    [Toc]    [Back]

     The IRIX version of poll provides users with a mechanism for multiplexing
     input and output over a set of any	type of	file descriptors, rather than
     the traditional limitation	to only	descriptors of STREAMS devices [see
     select(2)].  Poll identifies those	descriptors on which a user can	send
     or	receive	messages, or on	which certain events have occurred.

     Fds 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
     element for each open file	descriptor of interest.	 The array's elements
     are pollfd	structures which contain the following members:

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

     where fd specifies	an open	file descriptor	and events and revents are
     bitmasks constructed by or-ing any	combination of the following event

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

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

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

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

     POLLOUT	    Normal data	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.

									Page 1

POLL(2)								       POLL(2)

     POLLERR	    An error message has arrived at the	stream head.  This
		    flag is only valid in the revents bitmask; it is not used
		    in the events field.

     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
		    mutually exclusive.	 This flag is only valid in the
		    revents bitmask; it	is not used in the events field.

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

     For each element of the array pointed to by fds, poll examines the	given
     file descriptor for the event(s) specified	in events.  The	number of file
     descriptors to be examined	is specified by	nfds.  If nfds exceeds
     NOFILES, the system limit of open files [see ulimit(2)], poll will	fail.

     If	the value fd is	less than zero,	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 field 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 is 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 msec 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.  poll is not
     affected by the O_NDELAY and O_NONBLOCK flag.

     poll fails	if one or more of the following	are true:

     [EAGAIN]	  Allocation of	internal data structures failed	but request
		  should be attempted again.

     [EFAULT]	  Some argument	points outside the allocated address space.

     [EINTR]	  A signal was caught during the poll system call.

     [EINVAL]	  The argument nfds is less than zero, or nfds is greater than

									Page 2

POLL(2)								       POLL(2)

SEE ALSO    [Toc]    [Back]

     intro(2), select(2), read(2), write(2), getmsg(2),	putmsg(2), streamio(7)

DIAGNOSTICS    [Toc]    [Back]

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

NOTES    [Toc]    [Back]

     Some devices do not support polling via the select(2) and poll(2) system
     calls.  Doing a select or poll on a file descriptor associated with an
     "un-pollable" device will cause the select	or poll	to return immediately
     with a success value of 0 and the with the	corresponding file descriptor
     events of queried set true.  For instance,	if a select or poll is
     performed on a read file descriptor associated with an un-pollable
     device, the call would return immediately,	even though there may be
     nothing to	read on	the device.  A subsequent read(2) in this situation
     might return with a "bytes-read" count of 0 or might block	if the device
     supports read blocking.  Devices which exhibit this behavior (especially
     those from	third-party vendors) should be suspected as not	supporting

									PPPPaaaaggggeeee 3333
[ Back ]
 Similar pages
Name OS Title
ios IRIX input/output formatting
fread IRIX binary input/output
fread OpenBSD binary stream input/output
ioperm Linux set port input/output permissions
fwrite_unlocked Tru64 Perform input/output operations
fread Linux binary stream input/output
getw Linux input and output of words (ints)
gpio OpenBSD General Purpose Input/Output
fread FreeBSD binary stream input/output
log Tru64 Records input and output from a program
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service