1.\" $NetBSD: poll.2,v 1.24 2005/03/10 19:53:22 kleink 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 March 10, 2005 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 112.It POLLWRNORM 113Normal data may be written without blocking. 114.It POLLWRBAND 115Data with a non-zero priority may be written without blocking. 116.It POLLERR 117An exceptional condition has occurred on the device or socket. 118This flag is always checked, even if not present in the 119.Fa events 120bitmask. 121.It POLLHUP 122The device or socket has been disconnected. 123This flag is always 124checked, even if not present in the 125.Fa events 126bitmask. 127Note that 128POLLHUP 129and 130POLLOUT 131should never be present in the 132.Fa revents 133bitmask at the same time. 134If the remote end of a socket is closed, 135.Fn poll 136returns a 137POLLIN 138event, rather than a 139POLLHUP. 140.It POLLNVAL 141The file descriptor is not open. 142This flag is always checked, even 143if not present in the 144.Fa events 145bitmask. 146.El 147.Pp 148If 149.Fa timeout 150is neither zero nor INFTIM (\-1), it specifies a maximum interval to 151wait for any file descriptor to become ready, in milliseconds. 152If 153.Fa timeout 154is INFTIM (\-1), the poll blocks indefinitely. 155If 156.Fa timeout 157is zero, then 158.Fn poll 159will return without blocking. 160.Pp 161If 162.Fa ts 163is a non-null pointer, it references a timespec structure which specifies a 164maximum interval to wait for any file descriptor to become ready. 165If 166.Fa ts 167is a null pointer, 168.Fn pollts 169blocks indefinitely. 170If 171.Fa ts 172is a non-null pointer, referencing a zero-valued timespec structure, then 173.Fn pollts 174will return without blocking. 175.Pp 176If 177.Fa sigmask 178is a non-null pointer, then the 179.Fn pollts 180function shall replace the signal mask of the caller by the set of 181signals pointed to by 182.Fa sigmask 183before examining the descriptors, and shall restore the signal mask 184of the caller before returning. 185.Sh RETURN VALUES 186.Fn poll 187returns the number of descriptors that are ready for I/O, or \-1 if an 188error occurred. 189If the time limit expires, 190.Fn poll 191returns 0. 192If 193.Fn poll 194returns with an error, 195including one due to an interrupted call, 196the 197.Fa fds 198array will be unmodified. 199.Sh COMPATIBILITY 200This implementation differs from the historical one in that a given 201file descriptor may not cause 202.Fn poll 203to return with an error. 204In cases where this would have happened in the historical implementation 205(e.g. trying to poll a 206.Xr revoke 2 Ns d 207descriptor), this implementation instead copies the 208.Fa events 209bitmask to the 210.Fa revents 211bitmask. 212Attempting to perform I/O on this descriptor will then return an error. 213This behaviour is believed to be more useful. 214.Sh ERRORS 215An error return from 216.Fn poll 217indicates: 218.Bl -tag -width Er 219.It Bq Er EFAULT 220.Fa fds 221points outside the process's allocated address space. 222.It Bq Er EINTR 223A signal was delivered before the time limit expired and 224before any of the selected events occurred. 225.It Bq Er EINVAL 226The specified time limit is negative. 227.El 228.Sh SEE ALSO 229.Xr accept 2 , 230.Xr connect 2 , 231.Xr read 2 , 232.Xr recv 2 , 233.Xr select 2 , 234.Xr send 2 , 235.Xr write 2 236.Sh HISTORY 237The 238.Fn poll 239function appeared in 240.At V.3 . 241The 242.Fn pollts 243function first appeared in 244.Nx 3.0 . 245.Sh BUGS 246The distinction between some of the fields in the 247.Fa events 248and 249.Fa revents 250bitmasks is really not useful without STREAMS. 251The fields are defined for compatibility with existing software. 252