Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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	multi-
       plexing input/output over a set of file descriptors.  For  each	member
       of the array pointed to by fds, poll() examines the given file descrip-
       tor for the event(s) specified in events. The number of	pollfd	struc-
       tures in	the fds	array is specified by nfds.  The poll()	function iden-
       tifies 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 ar-
       ray with	one member for each open file descriptor of interest.  The ar-
       ray's members are pollfd	structures, which contain the  following  mem-
       bers:

       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  message  is
	     of	zero length.

       POLLRDNORM
	     Normal  data  (priority band equals 0) may	be read	without	block-
	     ing. 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  message  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  mem-
	     ber.

       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, POLL-
	     RDBAND, or	 POLLPRI are not mutually exclusive. This flag is only
	     valid  in	the revents bitmask; it	is not used in the events mem-
	     ber.

       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	speci-
       fied 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 de-
       scriptor, poll()	waits at least timeout milliseconds for	 an  event  to
       occur on	any of the selected file descriptors. On a computer where mil-
       lisecond	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-termi-
       nal devices, STREAMS-based files, FIFOs and  pipes.   The  behavior  of
       poll() on elements of fds that refer to other types of file is unspeci-
       fied.

       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 available.
       A file descriptor for a socket that is connecting  asynchronously  will
       indicate	 that  it is ready for writing,	once a connection has been es-
       tablished.

       Regular files always poll() TRUE	for reading and	writing.

RETURN VALUES
       Upon successful completion, a non-negative value	is returned.  A	 posi-
       tive 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 (di-
	     rectly or indirectly) downstream from a multiplexer.

SEE ALSO
       intro(2), getmsg(2), getrlimit(2), putmsg(2),  read(2),	write(2),  se-
       lect(3C), chpoll(9E)

       STREAMS Programming Guide

NOTES
       Non-STREAMS  drivers  use  chpoll(9E) to	implement  poll() on these de-
       vices.

SunOS 5.9			  23 Aug 2001			       poll(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=poll&sektion=2&manpath=SunOS+5.9>

home | help