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