1.\" $NetBSD: poll.2,v 1.38 2023/07/07 01:31:25 riastradh Exp $ 2.\" 3.\" Copyright (c) 1998, 2005, 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Charles M. Hannum. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 8, 2021 31.Dt POLL 2 32.Os 33.Sh NAME 34.Nm poll, pollts, ppoll 35.Nd synchronous I/O multiplexing 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In poll.h 40.Ft int 41.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" 42.In poll.h 43.In signal.h 44.In time.h 45.Ft int 46.Fn pollts "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask" 47.In poll.h 48.In signal.h 49.In time.h 50.Ft int 51.Fn ppoll "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask" 52.Sh DESCRIPTION 53.Fn poll , 54.Fn pollts 55and 56.Fn ppoll 57examine a set of file descriptors to see if some of them are ready for 58I/O. 59For each object inspected, the caller provides a list of conditions 60(called ``events'') to check for, and the kernel returns a list of 61conditions that are true. 62The intent, as with 63.Xr select 2 , 64is to check for whether I/O is possible before performing any, so as 65to permit a top-level event loop to process input from many sources 66(and output to many destinations) 67without blocking on any of them and thus becoming stuck. 68.Ss Arguments 69The 70.Fa fds 71argument is a pointer to an array of pollfd structures, one per file 72to inspect, as defined in 73.In poll.h 74(shown below). 75The 76.Fa nfds 77argument gives the size of the 78.Fa fds 79array. 80.Pp 81If 82.Fa timeout 83is neither zero nor INFTIM (\-1), it specifies a maximum interval to 84wait for any file descriptor to become ready, in milliseconds. 85If 86.Fa timeout 87is INFTIM (\-1), then 88.Fn poll 89blocks indefinitely. 90If 91.Fa timeout 92is zero, then 93.Fn poll 94will return without blocking. 95.Pp 96Similarly, if 97.Fa ts 98is not a null pointer, it references a timespec structure which specifies a 99maximum interval to wait for any file descriptor to become ready. 100If 101.Fa ts 102is a null pointer, 103.Fn pollts 104and 105.Fn ppoll 106block indefinitely. 107If 108.Fa ts 109is not a null pointer, referencing a zero-valued timespec structure, then 110.Fn pollts 111and 112.Fn ppoll 113will return without blocking. 114.Pp 115If 116.Fa sigmask 117is not a null pointer, then the 118.Fn pollts 119and 120.Fn ppoll 121functions replace the signal mask of the caller by the set of 122signals pointed to by 123.Fa sigmask 124while the call is in progress, and restore the caller's original 125signal mask before returning. 126.Pp 127The 128.Vt pollfd 129structure: 130.Bd -literal 131struct pollfd { 132 int fd; /* file descriptor */ 133 short events; /* events to look for */ 134 short revents; /* events returned */ 135}; 136.Ed 137.\" without this Pp there is no blank line after the struct which is ugly 138.Pp 139The fields of 140.Fa struct pollfd 141are as follows: 142.Pp 143.Bl -tag -width XXXrevents -compact 144.It Fa fd 145File descriptor to poll. 146(Input) 147.It Fa events 148Conditions to poll for. 149(Input) 150.It Fa revents 151Conditions that are true. 152(Output) 153.El 154.Ss Conditions 155There are four conditions that can be placed in 156.Fa events 157and reported in 158.Fa revents : 159.Pp 160.Bl -tag -width XXXPOLLWRNORM -compact 161.It POLLRDNORM 162Normal data may be read without blocking. 163.It POLLRDBAND 164Urgent/out-of-band data may be read without blocking. 165.It POLLWRNORM 166Normal data may be written without blocking. 167.It POLLWRBAND 168Urgent/out-of-band data may be written without blocking. 169.El 170.Pp 171There are three more conditions that are always checked for regardless 172of 173.Fa events 174and thus may always be reported in 175.Fa revents : 176.Pp 177.Bl -tag -width XXXPOLLWRNORM -compact 178.It POLLERR 179An exceptional condition has occurred on the object. 180.It POLLHUP 181The object has been disconnected. 182.It POLLNVAL 183The file descriptor is not open. 184.El 185.Pp 186The following additional flags are defined: 187.Pp 188.Bl -tag -width XXXPOLLWRNORM -compact 189.It POLLIN 190Synonym for POLLRDNORM. 191.It POLLOUT 192Synonym for POLLWRNORM. 193.It POLLPRI 194Synonym for POLLRDBAND. 195.El 196.Ss Notes 197If the value passed in 198.Fa fd 199is negative, the entry is ignored and 200.Fa revents 201is set to 0. 202(POLLNVAL is 203.Em not 204set.) 205.Pp 206No file descriptor will ever produce POLLHUP at the same time as POLLWRNORM. 207.\" (XXX but what about POLLWRBAND? POLLRDBAND? POLLRDNORM?) 208.Pp 209Sockets produce POLLIN rather than POLLHUP when the remote 210end is closed. 211.Sh RETURN VALUES 212.Fn poll 213returns the number of descriptors that are ready for I/O, or returns 214\-1 and sets 215.Dv errno 216if an error occurred. 217If the time limit expires, 218.Fn poll 219returns 0. 220If 221.Fn poll 222returns with an error, 223including one due to an interrupted call, 224the 225.Fa fds 226array will be unmodified. 227.Sh COMPATIBILITY 228This implementation differs from the historical one in that no individual 229file descriptor may cause 230.Fn poll 231to return with an error. 232In cases where this would have happened in the historical implementation 233(e.g. trying to poll a 234.Xr revoke 2 Ns d 235descriptor), this implementation instead copies the 236.Fa events 237bitmask to the 238.Fa revents 239bitmask. 240Attempting to perform I/O on this descriptor will then return an error. 241This behavior is believed to be more useful. 242.Pp 243The 244.Fn ppoll 245function is a wrapper for 246.Fn pollts 247to provide compatibility with the Linux implementation. 248.Sh ERRORS 249An error return from 250.Fn poll 251indicates: 252.Bl -tag -width Er 253.It Bq Er EFAULT 254.Fa fds 255points outside the process's allocated address space. 256.It Bq Er EINTR 257A signal was delivered before the time limit expired and 258before any of the selected events occurred. 259.It Bq Er EINVAL 260The specified time limit is negative or 261the number of pollfd structures specified is larger than the current 262file descriptor resource limit. 263.El 264.Sh SEE ALSO 265.Xr accept 2 , 266.Xr connect 2 , 267.Xr read 2 , 268.Xr recv 2 , 269.Xr select 2 , 270.Xr send 2 , 271.Xr write 2 272.Sh HISTORY 273The 274.Fn poll 275function appeared in 276.At V.3 , 277and was added to 278.Nx 279in 280.Nx 1.3 . 281The 282.Fn pollts 283function first appeared in 284.Nx 3.0 . 285The 286.Fn ppoll 287function first appeared in 288.Nx 10.0 . 289.Sh BUGS 290As of this writing, in the underlying implementation, POLLIN and 291POLLPRI are distinct flags from POLLRDNORM and POLLRDBAND 292(respectively) and the behavior is not always exactly identical. 293.Pp 294The detailed behavior of specific flags is not very portable from one 295OS to another. 296.\" The old note, which is too vague to be helpful: 297.\" 298.\" The distinction between some of the fields in the 299.\" .Fa events 300.\" and 301.\" .Fa revents 302.\" bitmasks is really not useful without STREAMS. 303.\" The fields are defined for compatibility with existing software. 304