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

FreeBSD Manual Pages

  
 
  

home | help
POLL(2)			  FreeBSD System Calls Manual		       POLL(2)

NAME
     poll, ppoll -- synchronous	I/O multiplexing

SYNOPSIS
     #include <poll.h>

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

     int
     ppoll(struct pollfd *fds, nfds_t nfds, const struct timespec *timeout,
	 const sigset_t	*mask);

DESCRIPTION
     poll() provides a mechanism for multiplexing I/O across a set of file de-
     scriptors.	 It is similar in function to select(2).  Unlike select(2),
     however, it is possible to	only pass in data corresponding	to the file
     descriptors for which events are wanted.  This makes poll() more effi-
     cient than	select(2) in most cases.

     The arguments are as follows:

     fds      Points to	an array of pollfd structures, which are defined as:

		    struct pollfd {
			    int	fd;
			    short events;
			    short revents;
		    };

	      The fd member is an open file descriptor.	 If fd is -1, the
	      pollfd structure is considered unused, and revents will be
	      cleared.

	      The events and revents members are bitmasks of conditions	to
	      monitor and conditions found, respectively.

     nfds     An unsigned integer specifying the number	of pollfd structures
	      in the array.

     timeout  Maximum interval to wait for the poll to complete, in millisec-
	      onds.  If	this value is 0, poll()	will return immediately.  If
	      this value is INFTIM (-1), poll()	will block indefinitely	until
	      a	condition is found.

     The calling process sets the events bitmask and poll() sets the revents
     bitmask.  Each call to poll() resets the revents bitmask for accuracy.
     The condition flags in the	bitmasks are defined as:

     POLLIN	 Data other than high-priority data may	be read	without	block-
		 ing.

     POLLRDNORM	 Normal	data may be read without blocking.

     POLLRDBAND	 Priority data may be read without blocking.

     POLLNORM	 Same as POLLRDNORM.  This flag	is provided for	source code
		 compatibility with older programs and should not be used in
		 new code.

     POLLPRI	 High-priority data may	be read	without	blocking.

     POLLOUT	 Normal	data may be written without blocking.

     POLLWRNORM	 Same as POLLOUT.

     POLLWRBAND	 Priority data may be written.

     POLLERR	 An error has occurred on the device or	socket.	 This flag is
		 only valid in the revents bitmask; it is ignored in the
		 events	member.

     POLLHUP	 The device or socket has been disconnected.  This event and
		 POLLOUT are mutually-exclusive; a descriptor 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 ignored in the events member.

     POLLNVAL	 The corresponding file	descriptor is invalid.	This flag is
		 only valid in the revents bitmask; it is ignored in the
		 events	member.

     The significance and semantics of normal, priority, and high-priority
     data are device-specific.	For example, on	OpenBSD, the POLLPRI and
     POLLRDBAND	flags may be used to detect when out-of-band socket data may
     be	read without blocking.

     The ppoll() function is similar to	poll() except that it specifies	the
     timeout using a timespec structure, and a null pointer is used to specify
     an	indefinite timeout instead of INFTIM.  Also, if	mask is	a non-null
     pointer, ppoll() atomically sets the calling thread's signal mask to the
     signal set	pointed	to by mask for the duration of the function call.  In
     this case,	the original signal mask will be restored before ppoll() re-
     turns.

RETURN VALUES
     Upon error, poll()	and ppoll() return -1 and set the global variable
     errno to indicate the error.  If the timeout interval was reached before
     any events	occurred, they return 0.  Otherwise, they return the number of
     pollfd structures for which revents is non-zero.

IDIOMS
     Care must be taken	when converting	code from select(2) to poll() as they
     have slightly different semantics.	 The first semantic difference is
     that, unlike select(2), poll() has	a way of indicating that one or	more
     file descriptors is invalid by setting a flag in the revents field	of
     corresponding entry of fds, whereas select(2) returns an error (-1) if
     any of the	descriptors with bits set in the fd_set	are invalid.  The sec-
     ond difference is that on EOF there is no guarantee that POLLIN will be
     set in revents, the caller	must also check	for POLLHUP.  This differs
     from select(2) where EOF is considered as a read event.

     Consider the following usage of select(2) that implements a read from the
     standard input with a 60 second time out:

	   struct timeval timeout;
	   fd_set readfds;
	   char	buf[BUFSIZ];
	   int nready;

	   timeout.tv_sec = 60;
	   timeout.tv_usec = 0;
	   FD_ZERO(&readfds);
	   FD_SET(STDIN_FILENO,	&readfds);
	   nready = select(STDIN_FILENO	+ 1, &readfds, NULL, NULL, &timeout);
	   if (nready == -1)
		   err(1, "select");
	   if (nready == 0)
		   errx(1, "time out");
	   if (FD_ISSET(STDIN_FILENO, &readfds)) {
		   if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
			   err(1, "read");
	   }

     This can be converted to poll() as	follows:

	   struct pollfd pfd[1];
	   char	buf[BUFSIZ];
	   int nready;

	   pfd[0].fd = STDIN_FILENO;
	   pfd[0].events = POLLIN;
	   nready = poll(pfd, 1, 60 * 1000);
	   if (nready == -1)
		   err(1, "poll");
	   if (nready == 0)
		   errx(1, "time out");
	   if ((pfd[0].revents & (POLLERR|POLLNVAL)))
		   errx(1, "bad	fd %d",	pfd[0].fd);
	   if ((pfd[0].revents & (POLLIN|POLLHUP))) {
		   if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
			   err(1, "read");
	   }

ERRORS
     poll() and	ppoll()	will fail if:

     [EFAULT]		fds points outside the process's allocated address
			space.

     [EINTR]		A signal was caught before any polled events occurred
			and before the timeout elapsed.

     [EINVAL]		nfds was greater than the number of available file de-
			scriptors.

     [EINVAL]		The timeout passed was invalid.

SEE ALSO
     clock_gettime(2), getrlimit(2), read(2), select(2), write(2)

STANDARDS
     The poll()	function is compliant with the IEEE Std	1003.1-2008
     ("POSIX.1") specification.	 The ppoll() function is a Linux extension.

HISTORY
     A poll() system call appeared in AT&T System V Release 3 UNIX.  The
     ppoll() function appeared in OpenBSD 5.4.

BUGS
     The POLLWRBAND flag is accepted but ignored by the	kernel.

     Because OpenBSD does not implement	STREAMS, there is no distinction be-
     tween some	of the fields in the events and	revents	bitmasks.  As a	re-
     sult, the POLLIN, POLLNORM, and POLLRDNORM	flags are equivalent.  Simi-
     larly, the	POLLPRI	and POLLRDBAND flags are also equivalent.

     Internally	to the kernel, poll() and ppoll() work poorly if multiple pro-
     cesses wait on the	same file descriptor.

FreeBSD	13.0			August 18, 2018			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | IDIOMS | ERRORS | SEE ALSO | STANDARDS | HISTORY | BUGS

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

home | help