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 July 8, 2002 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.Sh DESCRIPTION 44The 45.Fn poll 46system call 47examines a set of file descriptors to see if some of them are ready for 48I/O. 49The 50.Fa fds 51argument is a pointer to an array of pollfd structures as defined in 52.In poll.h 53(shown below). 54The 55.Fa nfds 56argument determines the size of the 57.Fa fds 58array. 59.Bd -literal 60struct pollfd { 61 int fd; /* file descriptor */ 62 short events; /* events to look for */ 63 short revents; /* events returned */ 64}; 65.Ed 66.Pp 67The fields of 68.Fa struct pollfd 69are as follows: 70.Bl -tag -width XXXrevents 71.It fd 72File descriptor to poll. 73If fd is equal to -1 then 74.Fa revents 75is cleared (set to zero), and that pollfd is not checked. 76.It events 77Events to poll for. 78(See below.) 79.It revents 80Events which may occur. 81(See below.) 82.El 83.Pp 84The event bitmasks in 85.Fa events 86and 87.Fa revents 88have the following bits: 89.Bl -tag -width XXXPOLLWRNORM 90.It POLLIN 91Data other than high priority data may be read without blocking. 92.It POLLRDNORM 93Normal data may be read without blocking. 94.It POLLRDBAND 95Data with a non-zero priority may be read without blocking. 96.It POLLPRI 97High priority data may be read without blocking. 98.It POLLOUT 99.It POLLWRNORM 100Normal data may be written without blocking. 101.It POLLWRBAND 102Data with a non-zero priority may be written without blocking. 103.It POLLERR 104An exceptional condition has occurred on the device or socket. 105This 106flag is always checked, even if not present in the 107.Fa events 108bitmask. 109.It POLLHUP 110The device or socket has been disconnected. 111This flag is always 112checked, even if not present in the 113.Fa events 114bitmask. 115Note that 116POLLHUP 117and 118POLLOUT 119should never be present in the 120.Fa revents 121bitmask at the same time. 122.It POLLNVAL 123The file descriptor is not open. 124This flag is always checked, even 125if not present in the 126.Fa events 127bitmask. 128.El 129.Pp 130If 131.Fa timeout 132is neither zero nor INFTIM (-1), it specifies a maximum interval to 133wait for any file descriptor to become ready, in milliseconds. 134If 135.Fa timeout 136is INFTIM (-1), the poll blocks indefinitely. 137If 138.Fa timeout 139is zero, then 140.Fn poll 141will return without blocking. 142.Sh RETURN VALUES 143The 144.Fn poll 145system call 146returns the number of descriptors that are ready for I/O, or -1 if an 147error occurred. 148If the time limit expires, 149.Fn poll 150returns 0. 151If 152.Fn poll 153returns with an error, 154including one due to an interrupted system call, 155the 156.Fa fds 157array will be unmodified. 158.Sh COMPATIBILITY 159This implementation differs from the historical one in that a given 160file descriptor may not cause 161.Fn poll 162to return with an error. 163In cases where this would have happened in 164the historical implementation (e.g.\& trying to poll a 165.Xr revoke 2 Ns ed 166descriptor), this implementation instead copies the 167.Fa events 168bitmask to the 169.Fa revents 170bitmask. 171Attempting to perform I/O on this descriptor will then 172return an error. 173This behaviour is believed to be more useful. 174.Sh ERRORS 175An error return from 176.Fn poll 177indicates: 178.Bl -tag -width Er 179.It Bq Er EFAULT 180The 181.Fa fds 182argument 183points outside the process's allocated address space. 184.It Bq Er EINTR 185A signal was delivered before the time limit expired and 186before any of the selected events occurred. 187.It Bq Er EINVAL 188The specified time limit is negative. 189.El 190.Sh SEE ALSO 191.Xr accept 2 , 192.Xr connect 2 , 193.Xr kqueue 2 , 194.Xr read 2 , 195.Xr recv 2 , 196.Xr select 2 , 197.Xr send 2 , 198.Xr write 2 199.Sh BUGS 200The distinction between some of the fields in the 201.Fa events 202and 203.Fa revents 204bitmasks is really not useful without STREAMS. 205The fields are 206defined for compatibility with existing software. 207.Sh HISTORY 208The 209.Fn poll 210function appeared in 211.At V . 212This manual page and the core of the implementation was taken from 213.Nx . 214