1.\" $NetBSD: poll.2,v 1.37 2021/02/09 09:01:29 wiz 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 \-1 if an 214error occurred. 215If the time limit expires, 216.Fn poll 217returns 0. 218If 219.Fn poll 220returns with an error, 221including one due to an interrupted call, 222the 223.Fa fds 224array will be unmodified. 225.Sh COMPATIBILITY 226This implementation differs from the historical one in that no individual 227file descriptor may cause 228.Fn poll 229to return with an error. 230In cases where this would have happened in the historical implementation 231(e.g. trying to poll a 232.Xr revoke 2 Ns d 233descriptor), this implementation instead copies the 234.Fa events 235bitmask to the 236.Fa revents 237bitmask. 238Attempting to perform I/O on this descriptor will then return an error. 239This behavior is believed to be more useful. 240.Pp 241The 242.Fn ppoll 243function is a wrapper for 244.Fn pollts 245to provide compatibility with the Linux implementation. 246.Sh ERRORS 247An error return from 248.Fn poll 249indicates: 250.Bl -tag -width Er 251.It Bq Er EFAULT 252.Fa fds 253points outside the process's allocated address space. 254.It Bq Er EINTR 255A signal was delivered before the time limit expired and 256before any of the selected events occurred. 257.It Bq Er EINVAL 258The specified time limit is negative or 259the number of pollfd structures specified is larger than the current 260file descriptor resource limit. 261.El 262.Sh SEE ALSO 263.Xr accept 2 , 264.Xr connect 2 , 265.Xr read 2 , 266.Xr recv 2 , 267.Xr select 2 , 268.Xr send 2 , 269.Xr write 2 270.Sh HISTORY 271The 272.Fn poll 273function appeared in 274.At V.3 , 275and was added to 276.Nx 277in 278.Nx 1.3 . 279The 280.Fn pollts 281function first appeared in 282.Nx 3.0 . 283The 284.Fn ppoll 285function first appeared in 286.Nx 10.0 . 287.Sh BUGS 288As of this writing, in the underlying implementation, POLLIN and 289POLLPRI are distinct flags from POLLRDNORM and POLLRDBAND 290(respectively) and the behavior is not always exactly identical. 291.Pp 292The detailed behavior of specific flags is not very portable from one 293OS to another. 294.\" The old note, which is too vague to be helpful: 295.\" 296.\" The distinction between some of the fields in the 297.\" .Fa events 298.\" and 299.\" .Fa revents 300.\" bitmasks is really not useful without STREAMS. 301.\" The fields are defined for compatibility with existing software. 302