1.\" $NetBSD: poll.2,v 1.28 2010/03/22 19:30:55 joerg 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd September 8, 2006 31.Dt POLL 2 32.Os 33.Sh NAME 34.Nm poll, pollts 35.Nd synchronous I/O multiplexing 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In poll.h 40.Ft int 41.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" 42.In poll.h 43.In signal.h 44.In time.h 45.Ft int 46.Fn pollts "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask" 47.Sh DESCRIPTION 48.Fn poll 49and 50.Fn pollts 51examine a set of file descriptors to see if some of them are ready for 52I/O. 53The 54.Fa fds 55argument is a pointer to an array of pollfd structures as defined in 56.In poll.h 57(shown below). 58The 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. 77If the value in 78.Em fd 79is negative, the file descriptor is ignored and 80.Em revents 81is set to 0. 82.It events 83Events to poll for. 84(See below.) 85.It revents 86Events which may occur. 87(See below.) 88.El 89.Pp 90The event bitmasks in 91.Fa events 92and 93.Fa revents 94have the following bits: 95.Bl -tag -width XXXPOLLWRNORM 96.It POLLIN 97Data other than high priority data may be read without blocking. 98.It POLLRDNORM 99Normal data may be read without blocking. 100.It POLLRDBAND 101Data with a non-zero priority may be read without blocking. 102.It POLLPRI 103High priority data may be read without blocking. 104.It POLLOUT 105Normal data may be written without blocking. 106.It POLLWRNORM 107Equivalent to 108POLLOUT. 109.It POLLWRBAND 110Data with a non-zero priority may be written without blocking. 111.It POLLERR 112An exceptional condition has occurred on the device or socket. 113This flag is always checked, even if not present in the 114.Fa events 115bitmask. 116.It POLLHUP 117The device or socket has been disconnected. 118This flag is always 119checked, even if not present in the 120.Fa events 121bitmask. 122Note that 123POLLHUP 124and 125POLLOUT 126should never be present in the 127.Fa revents 128bitmask at the same time. 129If the remote end of a socket is closed, 130.Fn poll 131returns a 132POLLIN 133event, rather than a 134POLLHUP. 135.It POLLNVAL 136The file descriptor is not open. 137This flag is always checked, even 138if not present in the 139.Fa events 140bitmask. 141.El 142.Pp 143If 144.Fa timeout 145is neither zero nor INFTIM (\-1), it specifies a maximum interval to 146wait for any file descriptor to become ready, in milliseconds. 147If 148.Fa timeout 149is INFTIM (\-1), the poll blocks indefinitely. 150If 151.Fa timeout 152is zero, then 153.Fn poll 154will return without blocking. 155.Pp 156If 157.Fa ts 158is a non-null pointer, it references a timespec structure which specifies a 159maximum interval to wait for any file descriptor to become ready. 160If 161.Fa ts 162is a null pointer, 163.Fn pollts 164blocks indefinitely. 165If 166.Fa ts 167is a non-null pointer, referencing a zero-valued timespec structure, then 168.Fn pollts 169will return without blocking. 170.Pp 171If 172.Fa sigmask 173is a non-null pointer, then the 174.Fn pollts 175function shall replace the signal mask of the caller by the set of 176signals pointed to by 177.Fa sigmask 178before examining the descriptors, and shall restore the signal mask 179of the caller before returning. 180.Sh RETURN VALUES 181.Fn poll 182returns the number of descriptors that are ready for I/O, or \-1 if an 183error occurred. 184If the time limit expires, 185.Fn poll 186returns 0. 187If 188.Fn poll 189returns with an error, 190including one due to an interrupted call, 191the 192.Fa fds 193array will be unmodified. 194.Sh COMPATIBILITY 195This implementation differs from the historical one in that a given 196file descriptor may not cause 197.Fn poll 198to return with an error. 199In cases where this would have happened in the historical implementation 200(e.g. trying to poll a 201.Xr revoke 2 Ns d 202descriptor), this implementation instead copies the 203.Fa events 204bitmask to the 205.Fa revents 206bitmask. 207Attempting to perform I/O on this descriptor will then return an error. 208This behaviour is believed to be more useful. 209.Sh ERRORS 210An error return from 211.Fn poll 212indicates: 213.Bl -tag -width Er 214.It Bq Er EFAULT 215.Fa fds 216points outside the process's allocated address space. 217.It Bq Er EINTR 218A signal was delivered before the time limit expired and 219before any of the selected events occurred. 220.It Bq Er EINVAL 221The specified time limit is negative. 222.El 223.Sh SEE ALSO 224.Xr accept 2 , 225.Xr connect 2 , 226.Xr read 2 , 227.Xr recv 2 , 228.Xr select 2 , 229.Xr send 2 , 230.Xr write 2 231.Sh HISTORY 232The 233.Fn poll 234function appeared in 235.At V.3 . 236The 237.Fn pollts 238function first appeared in 239.Nx 3.0 . 240.Sh BUGS 241The distinction between some of the fields in the 242.Fa events 243and 244.Fa revents 245bitmasks is really not useful without STREAMS. 246The fields are defined for compatibility with existing software. 247