Copyright (c) 2014, Joyent, Inc.
Copyright 1989 AT&T Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
http://www.opengroup.org/bookstore/.
The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
This notice shall appear on any product containing this material.
The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
#include <poll.h> int poll(struct pollfd fds[], nfds_t nfds, int timeout); int ppoll(struct pollfd *restrict fds, nfds_t nfds, const struct timespec *restrict tsp, const sigset_t *restrict sigmask);
The poll() and ppoll() functions provides applications with a mechanism for multiplexing input/output over a set of file descriptors. For each member of the array pointed to by fds, poll() and ppoll() examine the given file descriptor for the event(s) specified in events. The number of pollfd structures in the fds array is specified by nfds. The poll() and ppoll() functions identify those file descriptors on which an application can read or write data, or on which certain events have occurred.
The ppoll() function behaves identically to poll(), except as follows:
For the ppoll function, the timeout period is given in seconds and nanoseconds in an argument of type struct timespec, where as poll() takes a timeout in milliseconds in the form of an integer argument.
The ppoll() function takes an optional sigmask argument. When a non-NULL pointer is passed, the calling threads signal mask is replaced by the one specified in sigset before examining file descriptors, and restored before returning.
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 members:
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.
Normal data (priority band equals 0) may be read without blocking. For streams, this flag is set in revents even if the message is of zero length.
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.
High priority data may be received without blocking. For streams, this flag is set in revents even if the message is of zero length.
Normal data (priority band equals 0) may be written without blocking.
The same as POLLOUT.
Priority data (priority band > 0) may be written. This event only examines bands that have been written to at least once.
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.
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.
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() and ppoll().
The results of the poll() or ppoll() 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 specified bits are set in revents when either the poll() or ppoll() 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() and ppoll() wait at least timeout milliseconds for an event to occur on any of the selected file descriptors. On a computer where millisecond 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. If the value of tsp is NULL, then ppoll() blocks until a requested event occurs or until the call is interrupted. The poll() and ppoll() functions are not affected by the O_NDELAY and O_NONBLOCK flags.
The poll() and ppoll() functions support regular files, terminal and pseudo-terminal devices, streams-based files, FIFOs, pipes, and sockets. The behavior of poll() and ppoll() on elements of fds that refer to other types of file is unspecified.
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() and ppoll() TRUE for reading and writing.
Upon successful completion, a non-negative value is returned. A positive 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.
The poll() and ppoll() functions will fail if: EAGAIN
Allocation of internal data structures failed, but the request may be attempted again.
Some argument points to an illegal address.
A signal was caught during the poll() or ppoll() function.
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.
See attributes(5) for descriptions of the following attributes:
| ATTRIBUTE TYPE ATTRIBUTE VALUE |
| Interface Stability Standard |
Intro(2), getmsg(2), getrlimit(2), putmsg(2), read(2), write(2), select(3C), attributes(5), standards(5), chpoll(9E)
STREAMS Programming Guide
Non-STREAMS drivers use chpoll(9E) to implement poll() on these devices.