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