1.\" $OpenBSD: poll.2,v 1.12 2001/11/02 22:34:21 jj Exp $ 2.\" 3.\" Copyright (c) 1994 Jason R. Thorpe 4.\" 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 Jason R. Thorpe. 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, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" 31.Dd December 13, 1994 32.Dt POLL 2 33.Os 34.Sh NAME 35.Nm poll 36.Nd synchronous I/O multiplexing 37.Sh SYNOPSIS 38.Fd #include <poll.h> 39.Ft int 40.Fn poll "struct pollfd *fds" "int nfds" "int timeout" 41.Sh DESCRIPTION 42.Fn poll 43provides a mechanism for reporting I/O conditions across a set of file 44descriptors. 45.Pp 46The arguments are as follows: 47.Bl -tag -width timeout 48.It Pa fds 49Points to an array of 50.Nm pollfd 51structures, which are defined as: 52.Bd -literal -offset indent 53struct pollfd { 54 int fd; 55 short events; 56 short revents; 57}; 58.Ed 59.Pp 60The 61.Pa fd 62member is an open file descriptor. 63The 64.Pa events 65and 66.Pa revents 67members are bitmasks of conditions to monitor and conditions found, 68respectively. 69.It Pa nfds 70The number of 71.Nm pollfd 72structures in the array. 73.It Pa timeout 74Maximum interval to wait for the poll to complete, in milliseconds. 75If this value is 0, then 76.Fn poll 77will return immediately. 78If this value is INFTIM (-1), 79.Fn poll 80will block indefinitely until a condition is found. 81.El 82.Pp 83The calling process sets the 84.Pa events 85bitmask and 86.Fn poll 87sets the 88.Pa revents 89bitmask. 90Each call to 91.Fn poll 92resets the 93.Pa revents 94bitmask for accuracy. 95The condition flags in the bitmasks are defined as: 96.Bl -tag -width POLLRDNORM 97.It Nm POLLIN 98Data is available on the file descriptor for reading. 99.It Nm POLLNORM 100Same as 101.Nm POLLIN . 102.It Nm POLLPRI 103Same as 104.Nm POLLIN . 105.It Nm POLLOUT 106Data can be written to the file descriptor without blocking. 107.It Nm POLLERR 108This flag is not used in this implementation and is provided only for source 109code compatibility. 110.It Nm POLLHUP 111The file descriptor was valid before the polling process and invalid after. 112Presumably, this means that the file descriptor was closed sometime during 113the poll. 114.It Nm POLLNVAL 115The corresponding file descriptor is invalid. 116.It Nm POLLRDNORM 117Same as 118.Nm POLLIN . 119.It Nm POLLRDBAND 120Same as 121.Nm POLLIN . 122.It Nm POLLWRNORM 123Same as 124.Nm POLLOUT . 125.It Nm POLLWRBAND 126Same as 127.Nm POLLOUT . 128.It Nm POLLMSG 129This flag is not used in this implementation and is provided only for source 130code compatibility. 131.El 132.Pp 133All flags except 134.Nm POLLIN , 135.Nm POLLOUT , 136and their synonyms are for use only in the 137.Pa revents 138member of the 139.Nm pollfd 140structure. 141An attempt to set any of these flags in the 142.Pa events 143member will generate an error condition. 144.Pp 145In addition to I/O multiplexing, 146.Fn poll 147can be used to generate simple timeouts. 148This functionality may be achieved by passing a null pointer for 149.Pa fds . 150.Sh WARNINGS 151The 152.Nm POLLHUP 153flag is only a close approximation and may not always be accurate. 154.Sh RETURN VALUES 155Upon error, 156.Fn poll 157returns a \-1 and sets the global variable 158.Va errno 159to indicate the error. 160If the timeout interval was reached before any events occurred, 161a 0 is returned. 162Otherwise, 163.Fn poll 164returns the number of file descriptors for which 165.Pa revents 166is non-zero. 167.Sh ERRORS 168.Fn poll 169will fail if: 170.Bl -tag -width "EINVAL " 171.It Bq Er EINVAL 172.Pa nfds 173was either a negative number or greater than the number of available 174file descriptors. 175.It Bq Er EINVAL 176An invalid flags was set in the 177.Pa events 178member of the 179.Nm pollfd 180structure. 181.It Bq Er EINVAL 182The timeout passed to 183.Fn poll 184was too large. 185.It Bq Er EAGAIN 186Resource allocation failed inside of 187.Fn poll . 188Subsequent calls to 189.Fn poll 190may succeed. 191.It Bq Er EINTR 192.Fn poll 193caught a signal during the polling process. 194.El 195.Sh SEE ALSO 196.Xr select 2 , 197.Xr sysconf 3 198.Sh HISTORY 199A 200.Fn poll 201system call appeared in 202.At V . 203