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