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