1.\" $OpenBSD: poll.2,v 1.40 2023/07/18 04:17:17 asou Exp $ 2.\" 3.\" Copyright (c) 1994 Jason R. Thorpe 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by Jason R. Thorpe. 17.\" 4. The name of the author may not be used to endorse or promote products 18.\" derived from this software without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 21.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 22.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 23.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 24.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 25.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 26.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 27.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" 31.Dd $Mdocdate: July 18 2023 $ 32.Dt POLL 2 33.Os 34.Sh NAME 35.Nm poll , 36.Nm ppoll 37.Nd synchronous I/O multiplexing 38.Sh SYNOPSIS 39.In poll.h 40.Ft int 41.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" 42.Ft int 43.Fn ppoll "struct pollfd *fds" "nfds_t nfds" "const struct timespec *timeout" "const sigset_t *mask" 44.Sh DESCRIPTION 45.Fn poll 46provides a mechanism for multiplexing I/O across a set of file 47descriptors. 48It is similar in function to 49.Xr select 2 . 50Unlike 51.Xr select 2 , 52however, it is possible to only pass in data corresponding to the 53file descriptors for which events are wanted. 54This makes 55.Fn poll 56more efficient than 57.Xr select 2 58in most cases. 59.Pp 60The arguments are as follows: 61.Bl -tag -width timeout 62.It Fa fds 63Points to an array of 64.Vt pollfd 65structures, which are defined as: 66.Bd -literal -offset indent 67struct pollfd { 68 int fd; 69 short events; 70 short revents; 71}; 72.Ed 73.Pp 74The 75.Fa fd 76member is an open file descriptor. 77If 78.Fa fd 79is -1, 80the 81.Vt pollfd 82structure is considered unused, and 83.Fa revents 84will be cleared. 85.Pp 86The 87.Fa events 88and 89.Fa revents 90members are bitmasks of conditions to monitor and conditions found, 91respectively. 92.It Fa nfds 93An unsigned integer specifying the number of 94.Vt pollfd 95structures in the array. 96.It Fa timeout 97Maximum interval to wait for the poll to complete, in milliseconds. 98If this value is 0, 99.Fn poll 100will return immediately. 101If this value is 102.Dv INFTIM Pq -1 , 103.Fn poll 104will block indefinitely until a condition is found. 105.El 106.Pp 107The calling process sets the 108.Fa events 109bitmask and 110.Fn poll 111sets the 112.Fa revents 113bitmask. 114Each call to 115.Fn poll 116resets the 117.Fa revents 118bitmask for accuracy. 119The condition flags in the bitmasks are defined as: 120.Bl -tag -width POLLRDNORM 121.It Dv POLLIN 122Data other than high-priority data may be read without blocking. 123.It Dv POLLRDNORM 124Normal data may be read without blocking. 125.It Dv POLLRDBAND 126Priority data may be read without blocking. 127.It Dv POLLNORM 128Same as 129.Dv POLLRDNORM . 130This flag is provided for source code compatibility with older 131programs and should not be used in new code. 132.It Dv POLLPRI 133High-priority data may be read without blocking. 134.It Dv POLLOUT 135Normal data may be written without blocking. 136.It Dv POLLWRNORM 137Same as 138.Dv POLLOUT . 139.It Dv POLLWRBAND 140Priority data may be written. 141.It Dv POLLERR 142An error has occurred on the device or socket. 143This flag is only valid in the 144.Fa revents 145bitmask; it is ignored in the 146.Fa events 147member. 148.It Dv POLLHUP 149The device or socket has been disconnected. 150This event and 151.Dv POLLOUT 152are mutually-exclusive; a descriptor can never be writable if a hangup has 153occurred. 154However, this event and 155.Dv POLLIN , 156.Dv POLLRDNORM , 157.Dv POLLRDBAND , 158or 159.Dv POLLPRI 160are not mutually-exclusive. 161This flag is only valid in the 162.Fa revents 163bitmask; it is ignored in the 164.Fa events 165member. 166.It Dv POLLNVAL 167The corresponding file descriptor is invalid. 168This flag is only valid in the 169.Fa revents 170bitmask; it is ignored in the 171.Fa events 172member. 173.El 174.Pp 175The significance and semantics of normal, priority, and high-priority 176data are device-specific. 177For example, on 178.Ox , 179the 180.Dv POLLPRI 181and 182.Dv POLLRDBAND 183flags may be used to detect when out-of-band socket data may be read 184without blocking. 185.Pp 186The 187.Fn ppoll 188function is similar to 189.Fn poll 190except that it specifies the timeout using a timespec structure, 191and a null pointer is used to specify an indefinite timeout 192instead of 193.Dv INFTIM . 194Also, if 195.Fa mask 196is a non-null pointer, 197.Fn ppoll 198atomically sets the calling thread's signal mask to the signal set 199pointed to by 200.Fa mask 201for the duration of the function call. 202In this case, the original signal mask will be restored before 203.Fn ppoll 204returns. 205.Sh RETURN VALUES 206Upon error, 207.Fn poll 208and 209.Fn ppoll 210return \-1 and set the global variable 211.Va errno 212to indicate the error. 213If the timeout interval was reached before any events occurred, 214they return 0. 215Otherwise, they return the number of 216.Vt pollfd 217structures for which 218.Fa revents 219is non-zero. 220.Sh IDIOMS 221Care must be taken when converting code from 222.Xr select 2 223to 224.Fn poll 225as they have slightly different semantics. 226The first semantic difference is that, unlike 227.Xr select 2 , 228.Fn poll 229has a way of indicating that one or more file descriptors is invalid 230by setting a flag in the 231.Fa revents 232field of corresponding entry of 233.Fa fds , 234whereas 235.Xr select 2 236returns an error (-1) if any of the descriptors with bits set in 237the 238.Vt fd_set 239are invalid. 240The second difference is that on EOF there is no guarantee that 241.Dv POLLIN 242will be set in 243.Fa revents , 244the caller must also check for 245.Dv POLLHUP . 246This differs from 247.Xr select 2 248where EOF is considered as a read event. 249.Pp 250Consider the following usage of 251.Xr select 2 252that implements a read from the standard input with a 25360 second time out: 254.Bd -literal -offset indent 255struct timeval timeout; 256fd_set readfds; 257char buf[BUFSIZ]; 258int nready; 259 260timeout.tv_sec = 60; 261timeout.tv_usec = 0; 262FD_ZERO(&readfds); 263FD_SET(STDIN_FILENO, &readfds); 264nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); 265if (nready == -1) 266 err(1, "select"); 267if (nready == 0) 268 errx(1, "time out"); 269if (FD_ISSET(STDIN_FILENO, &readfds)) { 270 if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) 271 err(1, "read"); 272} 273.Ed 274.Pp 275This can be converted to 276.Fn poll 277as follows: 278.Bd -literal -offset indent 279struct pollfd pfd[1]; 280char buf[BUFSIZ]; 281int nready; 282 283pfd[0].fd = STDIN_FILENO; 284pfd[0].events = POLLIN; 285nready = poll(pfd, 1, 60 * 1000); 286if (nready == -1) 287 err(1, "poll"); 288if (nready == 0) 289 errx(1, "time out"); 290if (pfd[0].revents & (POLLERR|POLLNVAL)) 291 errx(1, "bad fd %d", pfd[0].fd); 292if (pfd[0].revents & (POLLIN|POLLHUP)) { 293 if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) 294 err(1, "read"); 295} 296.Ed 297.Sh ERRORS 298.Fn poll 299and 300.Fn ppoll 301will fail if: 302.Bl -tag -width Er 303.It Bq Er EAGAIN 304The kernel failed to allocate memory for temporary data structures; 305a later call may succeed. 306.It Bq Er EFAULT 307.Fa fds 308points outside the process's allocated address space. 309.It Bq Er EINTR 310A signal was caught before any polled events occurred 311and before the timeout elapsed. 312.It Bq Er EINVAL 313.Fa nfds 314was greater than the number of available 315file descriptors. 316.It Bq Er EINVAL 317The timeout passed was invalid. 318.El 319.Sh SEE ALSO 320.Xr clock_gettime 2 , 321.Xr getrlimit 2 , 322.Xr read 2 , 323.Xr select 2 , 324.Xr write 2 325.Sh STANDARDS 326The 327.Fn poll 328function is compliant with the 329.St -p1003.1-2008 330specification. 331The 332.Fn ppoll 333function is a Linux extension. 334.Sh HISTORY 335A 336.Fn poll 337system call appeared in 338.At V.3 . 339The 340.Fn ppoll 341function appeared in 342.Ox 5.4 . 343.Sh BUGS 344The 345.Dv POLLWRBAND 346flag is accepted but ignored by the kernel. 347.Pp 348Because 349.Ox 350does not implement STREAMS, 351there is no distinction between some of the fields in the 352.Fa events 353and 354.Fa revents 355bitmasks. 356As a result, the 357.Dv POLLIN , 358.Dv POLLNORM , 359and 360.Dv POLLRDNORM 361flags are equivalent. 362Similarly, the 363.Dv POLLPRI 364and 365.Dv POLLRDBAND 366flags are also equivalent. 367