1.\" $NetBSD: poll.2,v 1.9 2001/04/25 02:19:48 simonb Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Charles M. Hannum. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 7, 1996 38.Dt POLL 2 39.Os 40.Sh NAME 41.Nm poll 42.Nd synchronous I/O multiplexing 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.Fd #include <sys/types.h> 47.Fd #include <poll.h> 48.Ft int 49.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" 50.Sh DESCRIPTION 51.Fn poll 52examines a set of file descriptors to see if some of them are ready for 53I/O. 54The 55.Fa fds 56argument is a pointer to an array of pollfd structures as defined in 57.Aq Pa poll.h 58(shown below). The 59.Fa nfds 60argument determines the size of the 61.Fa fds 62array. 63.Bd -literal 64struct pollfd { 65 int fd; /* file descriptor */ 66 short events; /* events to look for */ 67 short revents; /* events returned */ 68}; 69.Ed 70.Pp 71The fields of 72.Fa struct pollfd 73are as follows: 74.Bl -tag -width XXXrevents 75.It fd 76File descriptor to poll. 77.It events 78Events to poll for. (See below.) 79.It revents 80Events which may occur. (See below.) 81.El 82.Pp 83The event bitmasks in 84.Fa events 85and 86.Fa revents 87have the following bits: 88.Bl -tag -width XXXPOLLWRNORM 89.It POLLIN 90Data other than high priority data may be read without blocking. 91.It POLLRDNORM 92Normal data may be read without blocking. 93.It POLLRDBAND 94Data with a non-zero priority may be read without blocking. 95.It POLLPRI 96High priority data may be read without blocking. 97.It POLLOUT 98.It POLLWRNORM 99Normal data may be written without blocking. 100.It POLLWRBAND 101Data with a non-zero priority may be written without blocking. 102.It POLLERR 103An exceptional condition has occurred on the device or socket. This 104flag is always checked, even if not present in the 105.Fa events 106bitmask. 107.It POLLHUP 108The device or socket has been disconnected. This flag is always 109checked, even if not present in the 110.Fa events 111bitmask. Note that 112POLLHUP 113and 114POLLOUT 115should never be present in the 116.Fa revents 117bitmask at the same time. 118.It POLLNVAL 119The file descriptor is not open. This flag is always checked, even 120if not present in the 121.Fa events 122bitmask. 123.El 124.Pp 125If 126.Fa timeout 127is neither zero nor INFTIM (-1), it specifies a maximum interval to 128wait for any file descriptor to become ready, in milliseconds. If 129.Fa timeout 130is INFTIM (-1), the poll blocks indefinitely. If 131.Fa timeout 132is zero, then 133.Fn poll 134will return without blocking. 135.Sh RETURN VALUES 136.Fn poll 137returns the number of descriptors that are ready for I/O, or -1 if an 138error occurred. If the time limit expires, 139.Fn poll 140returns 0. 141If 142.Fn poll 143returns with an error, 144including one due to an interrupted call, 145the 146.Fa fds 147array will be unmodified. 148.Sh COMPATIBILITY 149This implementation differs from the historical one in that a given 150file descriptor may not cause 151.Fn poll 152to return with an error. In cases where this would have happened in 153the historical implementation (e.g. trying to poll a 154.Xr revoke 2 ed 155descriptor), this implementation instead copies the 156.Fa events 157bitmask to the 158.Fa revents 159bitmask. Attempting to perform I/O on this descriptor will then 160return an error. This behaviour is believed to be more useful. 161.Sh ERRORS 162An error return from 163.Fn poll 164indicates: 165.Bl -tag -width Er 166.It Bq Er EFAULT 167.Fa fds 168points outside the process's allocated address space. 169.It Bq Er EINTR 170A signal was delivered before the time limit expired and 171before any of the selected events occurred. 172.It Bq Er EINVAL 173The specified time limit is negative. 174.El 175.Sh SEE ALSO 176.Xr accept 2 , 177.Xr connect 2 , 178.Xr read 2 , 179.Xr recv 2 , 180.Xr select 2 , 181.Xr send 2 , 182.Xr write 2 183.Sh BUGS 184The distinction between some of the fields in the 185.Fa events 186and 187.Fa revents 188bitmasks is really not useful without STREAMS. The fields are 189defined for compatibility with existing software. 190.Sh HISTORY 191The 192.Fn poll 193function call appeared in 194.At V.3 . 195