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.\" 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 December 1, 2016 32.Dt POLL 2 33.Os 34.Sh NAME 35.Nm poll , 36.Nm ppoll 37.Nd synchronous I/O multiplexing 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/types.h 42.In poll.h 43.Ft int 44.Fo poll 45.Fa "struct pollfd *fds" 46.Fa "nfds_t nfds" 47.Fa "int timeout" 48.Fc 49.Ft int 50.Fo ppoll 51.Fa "struct pollfd *fds" 52.Fa "nfds_t nfds" 53.Fa "const struct timespec *timeout" 54.Fa "const sigset_t *newsigmask" 55.Fc 56.Sh DESCRIPTION 57.Fn Poll 58and 59.Fn ppoll 60examine a set of file descriptors to see if some of them are ready for 61I/O. 62The 63.Fa fds 64argument is a pointer to an array of pollfd structures as defined in 65.In poll.h 66(shown below). 67The 68.Fa nfds 69argument determines the size of the 70.Fa fds 71array. 72.Bd -literal 73struct pollfd { 74 int fd; /* file descriptor */ 75 short events; /* events to look for */ 76 short revents; /* events returned */ 77}; 78.Ed 79.Pp 80The fields of 81.Fa struct pollfd 82are as follows: 83.Bl -tag -offset indent -width ".Fa revents" 84.It Fa fd 85File descriptor to poll. 86If fd is equal to -1 then 87.Fa revents 88is cleared (set to zero), and that pollfd is not checked. 89.It Fa events 90Events to poll for. 91(See below.) 92.It Fa revents 93Events which may occur. 94(See below.) 95.El 96.Pp 97The event bitmasks in 98.Fa events 99and 100.Fa revents 101have the following bits: 102.Bl -tag -offset indent -width ".Dv POLLRDNORM" 103.It Dv POLLIN 104Data other than high priority data may be read without blocking. 105.It Dv POLLRDNORM 106Normal data may be read without blocking. 107.It Dv POLLRDBAND 108Data with a non-zero priority may be read without blocking. 109.It Dv POLLPRI 110High priority data may be read without blocking. 111.It Dv POLLOUT 112.It Dv POLLWRNORM 113Normal data may be written without blocking. 114.It Dv POLLWRBAND 115Data with a non-zero priority may be written without blocking. 116.It Dv POLLERR 117An exceptional condition has occurred on the device or socket. 118This flag is always checked, even if not present in the 119.Fa events 120bitmask. 121.It Dv POLLHUP 122The device or socket has been disconnected. 123This flag is always checked, even if not present in the 124.Fa events 125bitmask. 126Note that 127.Dv POLLHUP 128and 129.Dv POLLOUT 130should never be present in the 131.Fa revents 132bitmask at the same time. 133.It Dv POLLNVAL 134The file descriptor is not open. 135This flag is always checked, even if not present in the 136.Fa events 137bitmask. 138.El 139.Pp 140If 141.Fa timeout 142is neither zero nor 143.Dv INFTIM Pq -1 , 144it specifies a maximum interval to 145wait for any file descriptor to become ready, in milliseconds. 146If 147.Fa timeout 148is 149.Dv INFTIM Pq -1 , 150the poll blocks indefinitely. 151If 152.Fa timeout 153is zero, then 154.Fn poll 155will return without blocking. 156.Pp 157The 158.Fn ppoll 159system call can be used to safely wait until either a set of file 160descriptors becomes ready, or until a signal is caught. 161The 162.Fa timeout 163argument in 164.Fn ppoll 165points to a 166.Vt "const struct timespec" 167rather than the 168.Vt "int timeout" 169used by 170.Fn poll . 171A null pointer may be passed to indicate that 172.Fn ppoll 173should wait indefinitely. 174Finally, 175.Fa newsigmask 176specifies a signal mask which is set while waiting for input. 177When 178.Fn ppoll 179returns, the original signal mask is restored. 180.Sh RETURN VALUES 181.Fn Poll 182returns the number of descriptors that are ready for I/O, or -1 if an 183error occurred. 184If the time limit expires, 185.Fn poll 186returns 0. 187If 188.Fn poll 189returns with an error, 190including one due to an interrupted call, 191the 192.Fa fds 193array will be unmodified. 194.Sh COMPATIBILITY 195This implementation differs from the historical one in that a given 196file descriptor may not cause 197.Fn poll 198to return with an error. 199In cases where this would have happened in the historical implementation 200(e.g.\& trying to poll a 201.Xr revoke 2 Ns ed 202descriptor), this implementation instead copies the 203.Fa events 204bitmask to the 205.Fa revents 206bitmask. 207Attempting to perform I/O on this descriptor will then return an error. 208This behaviour is believed to be more useful. 209.Pp 210The 211.Fn ppoll 212implementation uses a precise timeout which is intended to mimic the 213behaviour of this syscall in Linux. 214.Sh ERRORS 215An error return from 216.Fn poll 217indicates: 218.Bl -tag -width Er 219.It Bq Er EFAULT 220.Fa Fds 221points outside the process's allocated address space. 222.It Bq Er EINTR 223A signal was delivered before the time limit expired and 224before any of the selected events occurred. 225.It Bq Er EINVAL 226The specified time limit is negative. 227.El 228.Sh SEE ALSO 229.Xr accept 2 , 230.Xr connect 2 , 231.Xr pselect 2 , 232.Xr read 2 , 233.Xr recv 2 , 234.Xr select 2 , 235.Xr send 2 , 236.Xr write 2 237.Sh HISTORY 238The 239.Fn poll 240function call appeared in 241.At V . 242This manual page was taken from 243.Nx . 244The 245.Fn ppoll 246function first appeared in 247.Dx 4.6 . 248.Sh BUGS 249The distinction between some of the fields in the 250.Fa events 251and 252.Fa revents 253bitmasks is really not useful without STREAMS. 254The fields are defined for compatibility with existing software. 255