diff options
Diffstat (limited to 'static/netbsd/man2/poll.2')
| -rw-r--r-- | static/netbsd/man2/poll.2 | 303 |
1 files changed, 303 insertions, 0 deletions
diff --git a/static/netbsd/man2/poll.2 b/static/netbsd/man2/poll.2 new file mode 100644 index 00000000..93c2b5ae --- /dev/null +++ b/static/netbsd/man2/poll.2 @@ -0,0 +1,303 @@ +.\" $NetBSD: poll.2,v 1.38 2023/07/07 01:31:25 riastradh Exp $ +.\" +.\" Copyright (c) 1998, 2005, 2020 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Charles M. Hannum. +.\" +.\" 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. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``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 FOUNDATION OR CONTRIBUTORS +.\" 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 SUCH DAMAGE. +.\" +.Dd February 8, 2021 +.Dt POLL 2 +.Os +.Sh NAME +.Nm poll, pollts, ppoll +.Nd synchronous I/O multiplexing +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In poll.h +.Ft int +.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" +.In poll.h +.In signal.h +.In time.h +.Ft int +.Fn pollts "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask" +.In poll.h +.In signal.h +.In time.h +.Ft int +.Fn ppoll "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask" +.Sh DESCRIPTION +.Fn poll , +.Fn pollts +and +.Fn ppoll +examine a set of file descriptors to see if some of them are ready for +I/O. +For each object inspected, the caller provides a list of conditions +(called ``events'') to check for, and the kernel returns a list of +conditions that are true. +The intent, as with +.Xr select 2 , +is to check for whether I/O is possible before performing any, so as +to permit a top-level event loop to process input from many sources +(and output to many destinations) +without blocking on any of them and thus becoming stuck. +.Ss Arguments +The +.Fa fds +argument is a pointer to an array of pollfd structures, one per file +to inspect, as defined in +.In poll.h +(shown below). +The +.Fa nfds +argument gives the size of the +.Fa fds +array. +.Pp +If +.Fa timeout +is neither zero nor INFTIM (\-1), it specifies a maximum interval to +wait for any file descriptor to become ready, in milliseconds. +If +.Fa timeout +is INFTIM (\-1), then +.Fn poll +blocks indefinitely. +If +.Fa timeout +is zero, then +.Fn poll +will return without blocking. +.Pp +Similarly, if +.Fa ts +is not a null pointer, it references a timespec structure which specifies a +maximum interval to wait for any file descriptor to become ready. +If +.Fa ts +is a null pointer, +.Fn pollts +and +.Fn ppoll +block indefinitely. +If +.Fa ts +is not a null pointer, referencing a zero-valued timespec structure, then +.Fn pollts +and +.Fn ppoll +will return without blocking. +.Pp +If +.Fa sigmask +is not a null pointer, then the +.Fn pollts +and +.Fn ppoll +functions replace the signal mask of the caller by the set of +signals pointed to by +.Fa sigmask +while the call is in progress, and restore the caller's original +signal mask before returning. +.Pp +The +.Vt pollfd +structure: +.Bd -literal +struct pollfd { + int fd; /* file descriptor */ + short events; /* events to look for */ + short revents; /* events returned */ +}; +.Ed +.\" without this Pp there is no blank line after the struct which is ugly +.Pp +The fields of +.Fa struct pollfd +are as follows: +.Pp +.Bl -tag -width XXXrevents -compact +.It Fa fd +File descriptor to poll. +(Input) +.It Fa events +Conditions to poll for. +(Input) +.It Fa revents +Conditions that are true. +(Output) +.El +.Ss Conditions +There are four conditions that can be placed in +.Fa events +and reported in +.Fa revents : +.Pp +.Bl -tag -width XXXPOLLWRNORM -compact +.It POLLRDNORM +Normal data may be read without blocking. +.It POLLRDBAND +Urgent/out-of-band data may be read without blocking. +.It POLLWRNORM +Normal data may be written without blocking. +.It POLLWRBAND +Urgent/out-of-band data may be written without blocking. +.El +.Pp +There are three more conditions that are always checked for regardless +of +.Fa events +and thus may always be reported in +.Fa revents : +.Pp +.Bl -tag -width XXXPOLLWRNORM -compact +.It POLLERR +An exceptional condition has occurred on the object. +.It POLLHUP +The object has been disconnected. +.It POLLNVAL +The file descriptor is not open. +.El +.Pp +The following additional flags are defined: +.Pp +.Bl -tag -width XXXPOLLWRNORM -compact +.It POLLIN +Synonym for POLLRDNORM. +.It POLLOUT +Synonym for POLLWRNORM. +.It POLLPRI +Synonym for POLLRDBAND. +.El +.Ss Notes +If the value passed in +.Fa fd +is negative, the entry is ignored and +.Fa revents +is set to 0. +(POLLNVAL is +.Em not +set.) +.Pp +No file descriptor will ever produce POLLHUP at the same time as POLLWRNORM. +.\" (XXX but what about POLLWRBAND? POLLRDBAND? POLLRDNORM?) +.Pp +Sockets produce POLLIN rather than POLLHUP when the remote +end is closed. +.Sh RETURN VALUES +.Fn poll +returns the number of descriptors that are ready for I/O, or returns +\-1 and sets +.Dv errno +if an error occurred. +If the time limit expires, +.Fn poll +returns 0. +If +.Fn poll +returns with an error, +including one due to an interrupted call, +the +.Fa fds +array will be unmodified. +.Sh COMPATIBILITY +This implementation differs from the historical one in that no individual +file descriptor may cause +.Fn poll +to return with an error. +In cases where this would have happened in the historical implementation +(e.g. trying to poll a +.Xr revoke 2 Ns d +descriptor), this implementation instead copies the +.Fa events +bitmask to the +.Fa revents +bitmask. +Attempting to perform I/O on this descriptor will then return an error. +This behavior is believed to be more useful. +.Pp +The +.Fn ppoll +function is a wrapper for +.Fn pollts +to provide compatibility with the Linux implementation. +.Sh ERRORS +An error return from +.Fn poll +indicates: +.Bl -tag -width Er +.It Bq Er EFAULT +.Fa fds +points outside the process's allocated address space. +.It Bq Er EINTR +A signal was delivered before the time limit expired and +before any of the selected events occurred. +.It Bq Er EINVAL +The specified time limit is negative or +the number of pollfd structures specified is larger than the current +file descriptor resource limit. +.El +.Sh SEE ALSO +.Xr accept 2 , +.Xr connect 2 , +.Xr read 2 , +.Xr recv 2 , +.Xr select 2 , +.Xr send 2 , +.Xr write 2 +.Sh HISTORY +The +.Fn poll +function appeared in +.At V.3 , +and was added to +.Nx +in +.Nx 1.3 . +The +.Fn pollts +function first appeared in +.Nx 3.0 . +The +.Fn ppoll +function first appeared in +.Nx 10.0 . +.Sh BUGS +As of this writing, in the underlying implementation, POLLIN and +POLLPRI are distinct flags from POLLRDNORM and POLLRDBAND +(respectively) and the behavior is not always exactly identical. +.Pp +The detailed behavior of specific flags is not very portable from one +OS to another. +.\" The old note, which is too vague to be helpful: +.\" +.\" The distinction between some of the fields in the +.\" .Fa events +.\" and +.\" .Fa revents +.\" bitmasks is really not useful without STREAMS. +.\" The fields are defined for compatibility with existing software. |