poll.3p (10765B)
- '\" et
- .TH POLL "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- poll
- \(em input/output multiplexing
- .SH SYNOPSIS
- .LP
- .nf
- #include <poll.h>
- .P
- int poll(struct pollfd \fIfds\fP[], nfds_t \fInfds\fP, int \fItimeout\fP);
- .fi
- .SH DESCRIPTION
- The
- \fIpoll\fR()
- function provides applications with a mechanism for multiplexing
- input/output over a set of file descriptors. For each member of the
- array pointed to by
- .IR fds ,
- \fIpoll\fR()
- shall examine the given file descriptor for the event(s) specified in
- .IR events .
- The number of
- .BR pollfd
- structures in the
- .IR fds
- array is specified by
- .IR nfds .
- The
- \fIpoll\fR()
- function shall identify those file descriptors on which an application
- can read or write data, or on which certain events have occurred.
- .P
- The
- .IR 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
- .BR pollfd
- structures within which
- .IR fd
- specifies an open file descriptor and
- .IR events
- and
- .IR revents
- are bitmasks constructed by OR'ing a combination of the following event
- flags:
- .IP POLLIN 12
- Data other than high-priority data may be read without blocking.
- .RS 12
- .P
- For STREAMS, this flag is set in
- .IR revents
- even if the message is of zero length. This flag shall be equivalent
- to POLLRDNORM | POLLRDBAND.
- .RE
- .IP POLLRDNORM 12
- Normal data may be read without blocking.
- .RS 12
- .P
- For STREAMS, data on priority band 0 may be read without blocking. This
- flag is set in
- .IR revents
- even if the message is of zero length.
- .RE
- .IP POLLRDBAND 12
- Priority data may be read without blocking.
- .RS 12
- .P
- For STREAMS, data on priority bands greater than 0 may be read without
- blocking. This flag is set in
- .IR revents
- even if the message is of zero length.
- .RE
- .IP POLLPRI 12
- High-priority data may be read without blocking.
- .RS 12
- .P
- For STREAMS, this flag is set in
- .IR revents
- even if the message is of zero length.
- .RE
- .IP POLLOUT 12
- Normal data may be written without blocking.
- .RS 12
- .P
- For STREAMS, data on priority band 0 may be written without blocking.
- .RE
- .IP POLLWRNORM 12
- Equivalent to POLLOUT.
- .IP POLLWRBAND 12
- Priority data may be written.
- .RS 12
- .P
- For STREAMS, data on priority bands greater than 0 may be written
- without blocking. If any priority band has been written to on this
- STREAM, this event only examines bands that have been written
- to at least once.
- .RE
- .IP POLLERR 12
- An error has occurred on the device or stream. This flag is only valid
- in the
- .IR revents
- bitmask; it shall be ignored in the
- .IR events
- member.
- .IP POLLHUP 12
- A device has been disconnected, or a pipe or FIFO has been closed by the
- last process that had it open for writing. Once set, the hangup state of a
- FIFO shall persist until some process opens the FIFO for writing or until
- all read-only file descriptors for the FIFO are closed. 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
- .IR revents
- bitmask; it shall be ignored in the
- .IR events
- member.
- .IP POLLNVAL 12
- The specified
- .IR fd
- value is invalid. This flag is only valid in the
- .IR revents
- member; it shall ignored in the
- .IR events
- member.
- .P
- The significance and semantics of normal, priority, and high-priority
- data are file and device-specific.
- .P
- If the value of
- .IR fd
- is less than 0,
- .IR events
- shall be ignored, and
- .IR revents
- shall be set to 0 in that entry on return from
- \fIpoll\fR().
- .P
- In each
- .BR pollfd
- structure,
- \fIpoll\fR()
- shall clear the
- .IR revents
- member, except that where the application requested a report on a
- condition by setting one of the bits of
- .IR events
- listed above,
- \fIpoll\fR()
- shall set the corresponding bit in
- .IR revents
- if the requested condition is true. In addition,
- \fIpoll\fR()
- shall set the POLLHUP, POLLERR, and POLLNVAL flag in
- .IR revents
- if the condition is true, even if the application did not set the
- corresponding bit in
- .IR events .
- .P
- If none of the defined events have occurred on any selected file
- descriptor,
- \fIpoll\fR()
- shall wait at least
- .IR timeout
- milliseconds for an event to occur on any of the selected file
- descriptors. If the value of
- .IR timeout
- is 0,
- \fIpoll\fR()
- shall return immediately. If the value of
- .IR timeout
- is \-1,
- \fIpoll\fR()
- shall block until a requested event occurs or until the call is
- interrupted.
- .P
- Implementations may place limitations on the granularity of timeout
- intervals. If the requested timeout interval requires a finer
- granularity than the implementation supports, the actual timeout
- interval shall be rounded up to the next supported value.
- .P
- The
- \fIpoll\fR()
- function shall not be affected by the O_NONBLOCK flag.
- .P
- The
- \fIpoll\fR()
- function shall support regular files, terminal and pseudo-terminal
- devices, FIFOs, pipes, sockets and
- STREAMS-based files.
- The behavior of
- \fIpoll\fR()
- on elements of
- .IR fds
- that refer to other types of file is unspecified.
- .P
- Regular files shall always poll TRUE for reading and writing.
- .P
- A file descriptor for a socket that is listening for connections shall
- indicate that it is ready for reading, once connections are available.
- A file descriptor for a socket that is connecting asynchronously shall
- indicate that it is ready for writing, once a connection has been
- established.
- .P
- Provided the application does not perform any action that results in
- unspecified or undefined behavior, the value of the
- .IR fd
- and
- .IR events
- members of each element of
- .IR fds
- shall not be modified by
- \fIpoll\fR().
- .SH "RETURN VALUE"
- Upon successful completion,
- \fIpoll\fR()
- shall return a non-negative value. A positive value indicates the total
- number of
- .BR pollfd
- structures that have selected events (that is, those for which the
- .IR revents
- member is non-zero). A value of 0 indicates that the call timed out and
- no file descriptors have been selected. Upon failure,
- \fIpoll\fR()
- shall return \-1 and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- The
- \fIpoll\fR()
- function shall fail if:
- .TP
- .BR EAGAIN
- The allocation of internal data structures failed but a subsequent
- request may succeed.
- .TP
- .BR EINTR
- A signal was caught during
- \fIpoll\fR().
- .TP
- .BR EINVAL
- The
- .IR nfds
- argument is greater than
- {OPEN_MAX},
- or one of the
- .IR fd
- members refers to a STREAM or multiplexer that is linked (directly or
- indirectly) downstream from a multiplexer.
- .LP
- .IR "The following sections are informative."
- .SH EXAMPLES
- .SS "Checking for Events on a Stream"
- .P
- The following example opens a pair of STREAMS devices and then waits
- for either one to become writable. This example proceeds as follows:
- .IP " 1." 4
- Sets the
- .IR timeout
- parameter to 500 milliseconds.
- .IP " 2." 4
- Opens the STREAMS devices
- .BR /dev/dev0
- and
- .BR /dev/dev1 ,
- and then polls them, specifying POLLOUT and POLLWRBAND as the events of
- interest.
- .RS 4
- .P
- The STREAMS device names
- .BR /dev/dev0
- and
- .BR /dev/dev1
- are only examples of how STREAMS devices can be named; STREAMS naming
- conventions may vary among systems conforming to the POSIX.1\(hy2008.
- .RE
- .IP " 3." 4
- Uses the
- .IR ret
- variable to determine whether an event has occurred on either of the
- two STREAMS. The
- \fIpoll\fR()
- function is given 500 milliseconds to wait for an event to occur (if it
- has not occurred prior to the
- \fIpoll\fR()
- call).
- .IP " 4." 4
- Checks the returned value of
- .IR ret .
- If a positive value is returned, one of the following can be done:
- .RS 4
- .IP " a." 4
- Priority data can be written to the open STREAM on priority bands
- greater than 0, because the POLLWRBAND event occurred on the open
- STREAM (\c
- .IR fds [0]
- or
- .IR fds [1]).
- .IP " b." 4
- Data can be written to the open STREAM on priority-band 0, because the
- POLLOUT event occurred on the open STREAM (\c
- .IR fds [0]
- or
- .IR fds [1]).
- .RE
- .IP " 5." 4
- If the returned value is not a positive value, permission to write data
- to the open STREAM (on any priority band) is denied.
- .IP " 6." 4
- If the POLLHUP event occurs on the open STREAM (\c
- .IR fds [0]
- or
- .IR fds [1]),
- the device on the open STREAM has disconnected.
- .sp
- .RS 4
- .nf
- #include <stropts.h>
- #include <poll.h>
- \&...
- struct pollfd fds[2];
- int timeout_msecs = 500;
- int ret;
- int i;
- .P
- /* Open STREAMS device. */
- fds[0].fd = open("/dev/dev0", ...);
- fds[1].fd = open("/dev/dev1", ...);
- fds[0].events = POLLOUT | POLLWRBAND;
- fds[1].events = POLLOUT | POLLWRBAND;
- .P
- ret = poll(fds, 2, timeout_msecs);
- .P
- if (ret > 0) {
- /* An event on one of the fds has occurred. */
- for (i=0; i<2; i++) {
- if (fds[i].revents & POLLWRBAND) {
- /* Priority data may be written on device number i. */
- \&...
- }
- if (fds[i].revents & POLLOUT) {
- /* Data may be written on device number i. */
- \&...
- }
- if (fds[i].revents & POLLHUP) {
- /* A hangup has occurred on device number i. */
- \&...
- }
- }
- }
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- The POLLHUP event does not occur for FIFOs just because the FIFO is not
- open for writing. It only occurs when the FIFO is closed by the last
- writer and persists until some process opens the FIFO for writing or
- until all read-only file descriptors for the FIFO are closed.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.6" ", " "STREAMS",
- .IR "\fIgetmsg\fR\^(\|)",
- .IR "\fIpselect\fR\^(\|)",
- .IR "\fIputmsg\fR\^(\|)",
- .IR "\fIread\fR\^(\|)",
- .IR "\fIwrite\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "\fB<poll.h>\fP",
- .IR "\fB<stropts.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version 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 .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .