poll man page on OpenBSD

Man page or keyword search:  
man Server   11362 pages
apropos Keyword Search (all sections)
Output format
OpenBSD logo
[printable version]

POLL(2)			  OpenBSD Programmer's Manual		       POLL(2)

NAME
     poll - synchronous I/O multiplexing

SYNOPSIS
     #include <poll.h>

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

DESCRIPTION
     poll() provides a mechanism for multiplexing I/O across a set of file
     descriptors.  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
     efficient 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
	      milliseconds.  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
		 blocking.

     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.

     In addition to I/O multiplexing, poll() can be used to generate simple
     timeouts.	This functionality may be achieved by passing a null pointer
     for fds.

RETURN VALUES
     Upon error, poll() returns -1 and sets the global variable errno to
     indicate the error.  If the timeout interval was reached before any
     events occurred, poll() returns 0.	 Otherwise, poll() returns the number
     of file descriptors for which revents is non-zero.

EXAMPLES
     The following example implements a read from the standard input that
     times out after 60 seconds:

	   #include <err.h>
	   #include <poll.h>
	   #include <stdio.h>
	   #include <unistd.h>

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

	   pfd[0].fd = STDIN_FILENO;
	   pfd[0].events = POLLIN;
	   nfds = poll(pfd, 1, 60 * 1000);
	   if (nfds == -1 || (pfd[0].revents & (POLLERR|POLLHUP|POLLNVAL)))
		   errx(1, "poll error");
	   if (nfds == 0)
		   errx(1, "time out");
	   if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
		   errx(1, "read");

ERRORS
     poll() will fail if:

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

     [EINTR]	poll() caught a signal during the polling process.

     [EINVAL]	nfds was greater than the number of available file
		descriptors.

     [EINVAL]	The timeout passed to poll() was too large.

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

STANDARDS
     The poll() function is compliant with the X/Open Portability Guide Issue
     4.3 (``XPG4.3'') specification.

HISTORY
     A poll() system call appeared in AT&T System V.3 UNIX.

BUGS
     The POLLERR and POLLWRBAND flags are accepted but ignored by the kernel.

     Because OpenBSD does not implement STREAMS, there is no distinction
     between some of the fields in the events and revents bitmasks.  As a
     result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent.

     Internally to the kernel, poll() works poorly if multiple processes wait
     on the same file descriptor.

OpenBSD 4.9			 July 11, 2007			   OpenBSD 4.9
[top]

List of man pages available for OpenBSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net