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