1.\" $NetBSD: poll.2,v 1.26 2006/10/13 20:57:32 wiz Exp $ 2.\" 3.\" Copyright (c) 1998, 2005 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 8, 2006 38.Dt POLL 2 39.Os 40.Sh NAME 41.Nm poll, pollts 42.Nd synchronous I/O multiplexing 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.In poll.h 47.Ft int 48.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" 49.In poll.h 50.In signal.h 51.In time.h 52.Ft int 53.Fn pollts "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask" 54.Sh DESCRIPTION 55.Fn poll 56and 57.Fn pollts 58examine a set of file descriptors to see if some of them are ready for 59I/O. 60The 61.Fa fds 62argument is a pointer to an array of pollfd structures as defined in 63.Aq Pa poll.h 64(shown below). 65The 66.Fa nfds 67argument determines the size of the 68.Fa fds 69array. 70.Bd -literal 71struct pollfd { 72 int fd; /* file descriptor */ 73 short events; /* events to look for */ 74 short revents; /* events returned */ 75}; 76.Ed 77.Pp 78The fields of 79.Fa struct pollfd 80are as follows: 81.Bl -tag -width XXXrevents 82.It fd 83File descriptor to poll. 84If the value in 85.Em fd 86is negative, the file descriptor is ignored and 87.Em revents 88is set to 0. 89.It events 90Events to poll for. 91(See below.) 92.It revents 93Events which may occur. 94(See below.) 95.El 96.Pp 97The event bitmasks in 98.Fa events 99and 100.Fa revents 101have the following bits: 102.Bl -tag -width XXXPOLLWRNORM 103.It POLLIN 104Data other than high priority data may be read without blocking. 105.It POLLRDNORM 106Normal data may be read without blocking. 107.It POLLRDBAND 108Data with a non-zero priority may be read without blocking. 109.It POLLPRI 110High priority data may be read without blocking. 111.It POLLOUT 112Normal data may be written without blocking. 113.It POLLWRNORM 114Equivalent to 115POLLOUT. 116.It POLLWRBAND 117Data with a non-zero priority may be written without blocking. 118.It POLLERR 119An exceptional condition has occurred on the device or socket. 120This flag is always checked, even if not present in the 121.Fa events 122bitmask. 123.It POLLHUP 124The device or socket has been disconnected. 125This flag is always 126checked, even if not present in the 127.Fa events 128bitmask. 129Note that 130POLLHUP 131and 132POLLOUT 133should never be present in the 134.Fa revents 135bitmask at the same time. 136If the remote end of a socket is closed, 137.Fn poll 138returns a 139POLLIN 140event, rather than a 141POLLHUP. 142.It POLLNVAL 143The file descriptor is not open. 144This flag is always checked, even 145if not present in the 146.Fa events 147bitmask. 148.El 149.Pp 150If 151.Fa timeout 152is neither zero nor INFTIM (\-1), it specifies a maximum interval to 153wait for any file descriptor to become ready, in milliseconds. 154If 155.Fa timeout 156is INFTIM (\-1), the poll blocks indefinitely. 157If 158.Fa timeout 159is zero, then 160.Fn poll 161will return without blocking. 162.Pp 163If 164.Fa ts 165is a non-null pointer, it references a timespec structure which specifies a 166maximum interval to wait for any file descriptor to become ready. 167If 168.Fa ts 169is a null pointer, 170.Fn pollts 171blocks indefinitely. 172If 173.Fa ts 174is a non-null pointer, referencing a zero-valued timespec structure, then 175.Fn pollts 176will return without blocking. 177.Pp 178If 179.Fa sigmask 180is a non-null pointer, then the 181.Fn pollts 182function shall replace the signal mask of the caller by the set of 183signals pointed to by 184.Fa sigmask 185before examining the descriptors, and shall restore the signal mask 186of the caller before returning. 187.Sh RETURN VALUES 188.Fn poll 189returns the number of descriptors that are ready for I/O, or \-1 if an 190error occurred. 191If the time limit expires, 192.Fn poll 193returns 0. 194If 195.Fn poll 196returns with an error, 197including one due to an interrupted call, 198the 199.Fa fds 200array will be unmodified. 201.Sh COMPATIBILITY 202This implementation differs from the historical one in that a given 203file descriptor may not cause 204.Fn poll 205to return with an error. 206In cases where this would have happened in the historical implementation 207(e.g. trying to poll a 208.Xr revoke 2 Ns d 209descriptor), this implementation instead copies the 210.Fa events 211bitmask to the 212.Fa revents 213bitmask. 214Attempting to perform I/O on this descriptor will then return an error. 215This behaviour is believed to be more useful. 216.Sh ERRORS 217An error return from 218.Fn poll 219indicates: 220.Bl -tag -width Er 221.It Bq Er EFAULT 222.Fa fds 223points outside the process's allocated address space. 224.It Bq Er EINTR 225A signal was delivered before the time limit expired and 226before any of the selected events occurred. 227.It Bq Er EINVAL 228The specified time limit is negative. 229.El 230.Sh SEE ALSO 231.Xr accept 2 , 232.Xr connect 2 , 233.Xr read 2 , 234.Xr recv 2 , 235.Xr select 2 , 236.Xr send 2 , 237.Xr write 2 238.Sh HISTORY 239The 240.Fn poll 241function appeared in 242.At V.3 . 243The 244.Fn pollts 245function first appeared in 246.Nx 3.0 . 247.Sh BUGS 248The distinction between some of the fields in the 249.Fa events 250and 251.Fa revents 252bitmasks is really not useful without STREAMS. 253The fields are defined for compatibility with existing software. 254