diff options
Diffstat (limited to 'upstream/archlinux/man3p/poll.3p')
| -rw-r--r-- | upstream/archlinux/man3p/poll.3p | 401 |
1 files changed, 401 insertions, 0 deletions
diff --git a/upstream/archlinux/man3p/poll.3p b/upstream/archlinux/man3p/poll.3p new file mode 100644 index 00000000..d270ac42 --- /dev/null +++ b/upstream/archlinux/man3p/poll.3p @@ -0,0 +1,401 @@ +'\" 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 . |