1.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ 2.\" 3.\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 3. All advertising materials mentioning features or use of this software 14.\" must display the following acknowledgement: 15.\" This product includes software developed by Charles M. Hannum. 16.\" 4. The name of the author may not be used to endorse or promote products 17.\" derived from this software without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 20.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 21.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 22.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 23.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 24.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 28.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 27, 2021 31.Dt POLL 2 32.Os 33.Sh NAME 34.Nm poll 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.Ft int 43.Fo ppoll 44.Fa "struct pollfd fds[]" 45.Fa "nfds_t nfds" 46.Fa "const struct timespec * restrict timeout" 47.Fa "const sigset_t * restrict newsigmask" 48.Fc 49.Sh DESCRIPTION 50The 51.Fn poll 52system call 53examines a set of file descriptors to see if some of them are ready for 54I/O. 55The 56.Fa fds 57argument is a pointer to an array of pollfd structures as defined in 58.In poll.h 59(shown below). 60The 61.Fa nfds 62argument determines the size of the 63.Fa fds 64array. 65.Bd -literal 66struct pollfd { 67 int fd; /* file descriptor */ 68 short events; /* events to look for */ 69 short revents; /* events returned */ 70}; 71.Ed 72.Pp 73The fields of 74.Fa struct pollfd 75are as follows: 76.Bl -tag -width XXXrevents 77.It fd 78File descriptor to poll. 79If fd is equal to -1 then 80.Fa revents 81is cleared (set to zero), and that pollfd is not checked. 82.It events 83Events to poll for. 84(See below.) 85.It revents 86Events which may occur. 87(See below.) 88.El 89.Pp 90The event bitmasks in 91.Fa events 92and 93.Fa revents 94have the following bits: 95.Bl -tag -width XXXPOLLWRNORM 96.It POLLIN 97Data other than high priority data may be read without blocking. 98.It POLLRDNORM 99Normal data may be read without blocking. 100.It POLLRDBAND 101Data with a non-zero priority may be read without blocking. 102.It POLLPRI 103High priority data may be read without blocking. 104.It POLLOUT 105.It POLLWRNORM 106Normal data may be written without blocking. 107.It POLLWRBAND 108Data with a non-zero priority may be written without blocking. 109.It POLLERR 110An exceptional condition has occurred on the device or socket. 111This 112flag is always checked, even if not present in the 113.Fa events 114bitmask. 115.It POLLHUP 116The device or socket has been disconnected. 117This flag is always 118checked, even if not present in the 119.Fa events 120bitmask. 121Note that 122POLLHUP 123and 124POLLOUT 125should never be present in the 126.Fa revents 127bitmask at the same time. 128.It POLLRDHUP 129Remote peer closed connection, or shut down writing. 130Unlike 131POLLHUP, 132POLLRDHUP 133must be present in the 134.Fa events 135bitmask to be reported. 136Applies only to stream sockets. 137.It POLLNVAL 138The file descriptor is not open, 139or in capability mode the file descriptor has insufficient rights. 140This flag is always checked, even 141if not present in the 142.Fa events 143bitmask. 144.El 145.Pp 146If 147.Fa timeout 148is neither zero nor INFTIM (-1), it specifies a maximum interval to 149wait for any file descriptor to become ready, in milliseconds. 150If 151.Fa timeout 152is INFTIM (-1), the poll blocks indefinitely. 153If 154.Fa timeout 155is zero, then 156.Fn poll 157will return without blocking. 158.Pp 159The 160.Fn ppoll 161system call, unlike 162.Fn poll , 163is used to safely wait until either a set of file descriptors becomes 164ready or until a signal is caught. 165The 166.Fa fds 167and 168.Fa nfds 169arguments are identical to the analogous arguments of 170.Fn poll . 171The 172.Fa timeout 173argument in 174.Fn ppoll 175points to a 176.Vt "const struct timespec" 177which is defined in 178.In sys/timespec.h 179(shown below) rather than the 180.Vt "int timeout" 181used by 182.Fn poll . 183A null pointer may be passed to indicate that 184.Fn ppoll 185should wait indefinitely. 186Finally, 187.Fa newsigmask 188specifies a signal mask which is set while waiting for input. 189When 190.Fn ppoll 191returns, the original signal mask is restored. 192.Bd -literal 193struct timespec { 194 time_t tv_sec; /* seconds */ 195 long tv_nsec; /* and nanoseconds */ 196}; 197.Ed 198.Sh RETURN VALUES 199The 200.Fn poll 201system call 202returns the number of descriptors that are ready for I/O, or -1 if an 203error occurred. 204If the time limit expires, 205.Fn poll 206returns 0. 207If 208.Fn poll 209returns with an error, 210including one due to an interrupted system call, 211the 212.Fa fds 213array will be unmodified. 214.Sh COMPATIBILITY 215This implementation differs from the historical one in that a given 216file descriptor may not cause 217.Fn poll 218to return with an error. 219In cases where this would have happened in 220the historical implementation (e.g.\& trying to poll a 221.Xr revoke 2 Ns ed 222descriptor), this implementation instead copies the 223.Fa events 224bitmask to the 225.Fa revents 226bitmask. 227Attempting to perform I/O on this descriptor will then 228return an error. 229This behaviour is believed to be more useful. 230.Sh ERRORS 231An error return from 232.Fn poll 233indicates: 234.Bl -tag -width Er 235.It Bq Er EFAULT 236The 237.Fa fds 238argument 239points outside the process's allocated address space. 240.It Bq Er EINTR 241A signal was delivered before the time limit expired and 242before any of the selected events occurred. 243.It Bq Er EINVAL 244The specified time limit is invalid. 245One of its components is negative or too large. 246.It Bq Er EINVAL 247The number of pollfd structures specified by 248.Fa nfds 249exceeds the system tunable 250.Va kern.maxfilesperproc 251and 252.Dv FD_SETSIZE . 253.El 254.Sh SEE ALSO 255.Xr accept 2 , 256.Xr connect 2 , 257.Xr kqueue 2 , 258.Xr pselect 2 , 259.Xr read 2 , 260.Xr recv 2 , 261.Xr select 2 , 262.Xr send 2 , 263.Xr write 2 264.Sh STANDARDS 265The 266.Fn poll 267function conforms to 268.St -p1003.1-2001 . 269The 270.Fn ppoll 271is not specified by POSIX. 272The 273POLLRDHUP 274flag is not specified by POSIX, but is compatible with Linux and illumos. 275.Sh HISTORY 276The 277.Fn poll 278function appeared in 279.At V . 280This manual page and the core of the implementation was taken from 281.Nx . 282The 283.Fn ppoll 284function first appeared in 285.Fx 11.0 286.Sh BUGS 287The distinction between some of the fields in the 288.Fa events 289and 290.Fa revents 291bitmasks is really not useful without STREAMS. 292The fields are 293defined for compatibility with existing software. 294