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.Pp 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. One of its components is negative or too large. 237.El 238.Sh SEE ALSO 239.Xr accept 2 , 240.Xr connect 2 , 241.Xr kqueue 2 , 242.Xr pselect 2 , 243.Xr read 2 , 244.Xr recv 2 , 245.Xr select 2 , 246.Xr send 2 , 247.Xr write 2 248.Sh STANDARDS 249The 250.Fn poll 251function conforms to 252.St -p1003.1-2001 . 253The 254.Fn ppoll 255is not specified by POSIX. 256.Sh HISTORY 257The 258.Fn poll 259function appeared in 260.At V . 261This manual page and the core of the implementation was taken from 262.Nx . 263The 264.Fn ppoll 265function first appeared in 266.Fx 11.0 267.Sh BUGS 268The distinction between some of the fields in the 269.Fa events 270and 271.Fa revents 272bitmasks is really not useful without STREAMS. 273The fields are 274defined for compatibility with existing software. 275