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