diff options
Diffstat (limited to 'lib/libc/sys/poll.2')
| -rw-r--r-- | lib/libc/sys/poll.2 | 199 |
1 files changed, 199 insertions, 0 deletions
diff --git a/lib/libc/sys/poll.2 b/lib/libc/sys/poll.2 new file mode 100644 index 00000000000..f07df83eaec --- /dev/null +++ b/lib/libc/sys/poll.2 @@ -0,0 +1,199 @@ +.\" +.\" Copyright (c) 1994 Jason R. Thorpe +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by Jason R. Thorpe. +.\" 4. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED +.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" +.Dd December 13, 1994 +.Dt POLL 2 +.Os +.Sh NAME +.Nm poll +.Nd synchronous I/O multiplexing +.Sh SYNOPSIS +.Fd #include <poll.h> +.Ft int +.Fn poll "struct pollfd *fds" "int nfds" "int timeout" +.Sh DESCRIPTION +.Fn Poll +provides a mechanism for reporting I/O conditions across a set of file +descriptors. +.Pp +The arguments are as follows: +.Bl -tag -width timeout +.It Pa fds +Points to an array of +.Nm pollfd +structures, which are defined as: +.Bd -literal -offset indent +struct pollfd { + int fd; + short events; + short revents; +}; +.Ed +.Pp +The +.Pa fd +member is an open file descriptor. The +.Pa events +and +.Pa revents +members are bitmasks of conditions to monitor and conditions found, +respectively. +.It Pa nfds +The number of +.Nm pollfd +structures in the array. +.It Pa timeout +Maximum interval to wait for the poll to complete, in milliseconds. If +this value is 0, then +.Fn poll +will return immediately. If this value is less than 0, +.Fn poll +will block indefinitely until a condition is found. +.El +.Pp +The calling process sets the +.Pa events +bitmask and +.Fn poll +sets the +.Pa revents +bitmask. Each call to +.Fn poll +resets the +.Pa revents +bitmask for accuracy. The condition flags in the bitmasks are defined as: +.Bl -tag -width POLLRDNORM +.It Nm POLLIN +Data is available on the file descriptor for reading. +.It Nm POLLNORM +Same as +.Nm POLLIN . +.It Nm POLLPRI +Same as +.Nm POLLIN . +.It Nm POLLOUT +Data can be written to the file descriptor without blocking. +.It Nm POLLERR +This flag is not used in this implementation and is provided only for source +code compatibility. +.It Nm POLLHUP +The file descriptor was valid before the polling process and invalid after. +Presumably, this means that the file descriptor was closed sometime during +the poll. +.It Nm POLLNVAL +The corresponding file descriptor is invalid. +.It Nm POLLRDNORM +Same as +.Nm POLLIN . +.It Nm POLLRDBAND +Same as +.Nm POLLIN . +.It Nm POLLWRNORM +Same as +.Nm POLLOUT . +.It Nm POLLWRBAND +Same as +.Nm POLLOUT . +.It Nm POLLMSG +This flag is not used in this implementation and is provided only for source +code compatibility. +.El +.Pp +All flags except +.Nm POLLIN , +.Nm POLLOUT , +and their synonyms are for use only in the +.Pa revents +member of the +.Nm pollfd +structure. An attempt to set any of these flags in the +.Pa events +member will generate an error condition. +.Pp +In addition to I/O multiplexing, +.Fn poll +can be used to generate simple timeouts. This functionality may be achieved +by passing a NULL pointer for +.Pa fds . +.Sh WARNINGS +Since this implementation is a wrapper around +.Fn select , +functionality is limited to such. There is no differentiation between +standard and priority messages in the read or write queues. +.Pp +The +.Nm POLLHUP +flag is only a close approximation and may not always be accurate. +.Sh RETURN VALUES +Upon error, +.Fn poll +returns a -1 and sets the global variable +.Pa errno +to indicate the error. If the timeout interval was reached before any events +occurred, a 0 is returned. Otherwise, +.Fn poll +returns the number of file descriptors for which +.Pa revents +is non-zero. +.Sh ERRORS +.Fn Poll +will fail if: +.Bl -tag -width "EINVAL " +.It Bq Er EINVAL +.Pa nfds +was either a negative number or greater than the number of available +file descriptors. +.It Bq Er EINVAL +An invalid flags was set in the +.Pa events +member of the +.Nm pollfd +structure. +.It Bq Er EINVAL +The timeout passed to +.Fn select +was too large. +.It Bq Er EAGAIN +Resource allocation failed inside of +.Fn poll . +Subsequent calls to +.Fn poll +may succeed. +.It Bq Er EINTR +.Fn Select +caught a signal during the polling process. +.El +.Sh SEE ALSO +.Xr sysconf 3 , +.Xr select 2 +.Sh HISTORY +A +.Fn poll +system call appeared in +.At V |