unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



poll(2)								      poll(2)



NAME

  poll - Monitors conditions on	multiple file descriptors

SYNOPSIS

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

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

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  poll():  XSH5.0, XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  filedes   Points to an array of pollfd structures, one for each file
	    descriptor of interest.  Each pollfd structure includes the	fol-
	    lowing members:

	    int	fd    The file descriptor

	    int	events
		      The requested conditions

	    int	revents
		      The reported conditions

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

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

DESCRIPTION

  The poll() function provides users with a mechanism for multiplexing
  input/output over a set of file descriptors that reference open streams.
  For each member of the array pointed to by filedes, poll() examines the
  given	file descriptor	for the	event(s) specified in events.  The poll()
  function identifies those streams on which an	application can	send or
  receive messages, or on which	certain	events have occurred.

  The filedes parameter	specifies the file descriptor to be examined and the
  events of interest for each file descriptor.	It is a	pointer	to an array
  of pollfd structures.	The fd member of each pollfd structure specifies an
  open file descriptor.	 The poll() function uses the events member to deter-
  mine what conditions to report for this file descriptor.  If one or more of
  these	conditions is true, the	poll() function	sets the associated revents
  member.

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

  POLLERR   An error has occurred on the file descriptor.  This	flag is	only
	    valid in the revents bitmask; it is	not used in the	events
	    member.

	    For	STREAMS	devices, if an error occurs on the file	descriptor
	    and	the device is also disconnected, poll()	returns	POLLERR;
	    POLLERR takes precedence over POLLHUP.

  POLLHUP   The	device has been	disconnected.  This event is mutually
	    exclusive with POLLOUT; a stream can never be writable if a
	    hangup 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 ignored in	the events
	    member.

  POLLIN    Data other than high-priority data may be read without blocking.
	    This flag is set in	revents	even if	the message is of zero
	    length.  In	revents, this flag is mutually exclusive with
	    POLLPRI.

  POLLNORM  [Tru64 UNIX]  Data may be read without blocking.

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

  POLLOUT   Normal (priority band equals 0) data may be	written	without
	    blocking.

  POLLPRI   High-priority data may be received without blocking.  This flag
	    is set in revents even if the message is of	zero length.  In
	    revents, this flag is mutually exclusive with POLLIN.

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

  POLLRDNORM
	    Normal data	(priority band equals 0) may be	read without block-
	    ing.  This flag is set in revents even if the message is of	zero
	    length.

  POLLWRBAND
	    Priority data (priority band greater than 0) may be	written.
	    This event only examines bands that	have been written to at	least
	    once.

  POLLWRNORM
	    Same as POLLOUT.

  The poll() function ignores any pollfd structure whose fd member is less
  than 0 (zero).  If the fd member of all pollfd structures is less than 0,
  the poll() function will return 0 and	have no	other results.


  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.  There are
  two exceptions:  regular files, which	always poll true for POLLNORM and
  POLLOUT, and pipes, when the rules for the operation specify to return zero
  in order to indicate end-of-file.

  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.

  For each call	to the poll() function,	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, the	poll() func-
  tion will return 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, the
  poll() function 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, the poll()	function does not
  return until at least	one specified event has	occurred.  If the value	of
  the timeout parameter	is 0 (zero), the poll()	function does not wait for an
  event	to occur but returns immediately, even if no specified event has
  occurred.

  The behavior of the poll() function is not affected by whether the
  O_NONBLOCK flag is set on any	of the specified file descriptors.

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

  For sockets, a file descriptor for a socket that is listening	for connec-
  tions	indicates it is	ready for reading after	connections are	available.  A
  file descriptor for a	socket that is connecting asynchronously indicates it
  is ready for writing after a connection is established.

NOTES

  [Tru64 UNIX]	For compatibility with BSD systems, the	select() function is
  also supported.

  [Tru64 UNIX]	This function supports up to 64K open file descriptors per
  process if that capability is	enabled.

RETURN VALUES

  Upon successful completion, the poll() function returns a nonnegative
  value.  If the call returns 0	(zero),	poll() has timed out and has not set
  any of the revents bitmasks.	A positive value indicates the number of file
  descriptors for which	poll() has set the revents bitmask.  If	the poll()
  function fails, -1 is	returned and errno is set to indicate the error.

ERRORS

  If the poll()	function fails,	errno may be set to one	of the following
  values:

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

  [EINTR]   A signal was caught	during the poll() function and the signal
	    handler was	installed with an indication that functions are	not
	    to be restarted.

  [EINVAL]  [Tru64 UNIX]  The timeout parameter	is a negative number other
	    than -1.

	    [Tru64 UNIX]  The  nfds parameter is greater than the process's
	    soft file descriptor limit.

	    The	nfds parameter 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.

  [EFAULT]  [Tru64 UNIX]  The filedes parameter	in conjunction with the	nfds
	    parameter addresses	a location outside of the allocated address
	    space of the process.

RELATED	INFORMATION

  Functions: getmsg(2),	putmsg(2), read(2), write(2), setsysinfo(2),
  streamio(7)

  Standards: standards(5)