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