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 November 13, 2014 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. 131This flag is always checked, even 132if not present in the 133.Fa events 134bitmask. 135.El 136.Pp 137If 138.Fa timeout 139is neither zero nor INFTIM (-1), it specifies a maximum interval to 140wait for any file descriptor to become ready, in milliseconds. 141If 142.Fa timeout 143is INFTIM (-1), the poll blocks indefinitely. 144If 145.Fa timeout 146is zero, then 147.Fn poll 148will return without blocking. 149.Pp 150The 151.Fn ppoll 152system call, unlike 153.Fn poll , 154is used to safely wait until either a set of file descriptors becomes 155ready or until a signal is caught. 156The 157.Fa fds 158and 159.Fa nfds 160arguments are identical to the analogous arguments of 161.Fn poll . 162The 163.Fa timeout 164argument in 165.Fn ppoll 166points to a 167.Vt "const struct timespec" 168which is defined in 169.In sys/timespec.h 170(shown below) rather than the 171.Vt "int timeout" 172used by 173.Fn poll . 174A null pointer may be passed to indicate that 175.Fn ppoll 176should wait indefinitely. 177Finally, 178.Fa newsigmask 179specifies a signal mask which is set while waiting for input. 180When 181.Fn ppoll 182returns, the original signal mask is restored. 183.Bd -literal 184struct timespec { 185 time_t tv_sec; /* seconds */ 186 long tv_nsec; /* and nanoseconds */ 187}; 188.Ed 189.Sh RETURN VALUES 190The 191.Fn poll 192system call 193returns the number of descriptors that are ready for I/O, or -1 if an 194error occurred. 195If the time limit expires, 196.Fn poll 197returns 0. 198If 199.Fn poll 200returns with an error, 201including one due to an interrupted system call, 202the 203.Fa fds 204array will be unmodified. 205.Sh COMPATIBILITY 206This implementation differs from the historical one in that a given 207file descriptor may not cause 208.Fn poll 209to return with an error. 210In cases where this would have happened in 211the historical implementation (e.g.\& trying to poll a 212.Xr revoke 2 Ns ed 213descriptor), this implementation instead copies the 214.Fa events 215bitmask to the 216.Fa revents 217bitmask. 218Attempting to perform I/O on this descriptor will then 219return an error. 220This behaviour is believed to be more useful. 221.Sh ERRORS 222An error return from 223.Fn poll 224indicates: 225.Bl -tag -width Er 226.It Bq Er EFAULT 227The 228.Fa fds 229argument 230points outside the process's allocated address space. 231.It Bq Er EINTR 232A signal was delivered before the time limit expired and 233before any of the selected events occurred. 234.It Bq Er EINVAL 235The specified time limit is invalid. One of its components is negative or too large. 236.El 237.Sh SEE ALSO 238.Xr accept 2 , 239.Xr connect 2 , 240.Xr kqueue 2 , 241.Xr pselect 2 , 242.Xr read 2 , 243.Xr recv 2 , 244.Xr select 2 , 245.Xr send 2 , 246.Xr write 2 247.Sh STANDARDS 248The 249.Fn poll 250function conforms to 251.St -p1003.1-2001 . 252The 253.Fn ppoll 254is not specified by POSIX. 255.Sh HISTORY 256The 257.Fn poll 258function appeared in 259.At V . 260This manual page and the core of the implementation was taken from 261.Nx . 262The 263.Fn ppoll 264function first appeared in 265.Fx 11.0 266.Sh BUGS 267The distinction between some of the fields in the 268.Fa events 269and 270.Fa revents 271bitmasks is really not useful without STREAMS. 272The fields are 273defined for compatibility with existing software. 274