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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
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
       array  with  one	member for each	open file descriptor of	interest.  The
       array'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 with-
		       out blocking. 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 member.

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

       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
       descriptor,  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
       established.

       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  (directly  or indirectly) downstream	from a
		       multiplexer.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Standard			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       intro(2),  getmsg(2),  getrlimit(2),  putmsg(2),	  read(2),   write(2),
       select(3C), attributes(5), standards(5),	chpoll(9E)

       STREAMS Programming Guide

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

SunOS 5.10			  23 Aug 2001			       poll(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | 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.10>

home | help