1.\" $OpenBSD: poll.2,v 1.32 2015/12/25 01:48:08 tb 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: December 25 2015 $ 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 186In addition to I/O multiplexing, 187.Fn poll 188can be used to generate simple timeouts. 189This functionality may be achieved by passing a null pointer for 190.Fa fds . 191.Pp 192The 193.Fn ppoll 194function is similar to 195.Fn poll 196except that it specifies the timeout using a timespec structure, 197and a null pointer is used to specify an indefinite timeout 198instead of 199.Dv INFTIM . 200Also, if 201.Fa mask 202is a non-null pointer, 203.Fn ppoll 204atomically sets the calling thread's signal mask to the signal set 205pointed to by 206.Fa mask 207for the duration of the function call. 208In this case, the original signal mask will be restored before 209.Fn ppoll 210returns. 211.Sh RETURN VALUES 212Upon error, 213.Fn poll 214and 215.Fn ppoll 216return \-1 and set the global variable 217.Va errno 218to indicate the error. 219If the timeout interval was reached before any events occurred, 220they return 0. 221Otherwise, they return the number of 222.Vt pollfd 223structures for which 224.Fa revents 225is non-zero. 226.Sh IDIOMS 227Care must be taken when converting code from 228.Xr select 2 229to 230.Fn poll 231as they have slightly different semantics. 232The first semantic difference is that, unlike 233.Xr select 2 , 234.Fn poll 235has a way of indicating that one or more file descriptors is invalid 236by setting a flag in the 237.Fa revents 238field of corresponding entry of 239.Fa fds , 240whereas 241.Xr select 2 242returns an error (-1) if any of the descriptors with bits set in 243the 244.Vt fd_set 245are invalid. 246The second difference is that on EOF there is no guarantee that 247.Dv POLLIN 248will be set in 249.Fa revents , 250the caller must also check for 251.Dv POLLHUP . 252This differs from 253.Xr select 2 254where EOF is considered as a read event. 255.Pp 256Consider the following usage of 257.Xr select 2 258that implements a read from the standard input with a 25960 second time out: 260.Bd -literal -offset indent 261struct timeval timeout; 262fd_set readfds; 263char buf[BUFSIZ]; 264int nready; 265 266timeout.tv_sec = 60; 267timeout.tv_usec = 0; 268FD_ZERO(&readfds); 269FD_SET(STDIN_FILENO, &readfds); 270nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); 271if (nready == -1) 272 err(1, "select"); 273if (nready == 0) 274 errx(1, "time out"); 275if (FD_ISSET(STDIN_FILENO, &readfds)) { 276 if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) 277 err(1, "read"); 278} 279.Ed 280.Pp 281This can be converted to 282.Fn poll 283as follows: 284.Bd -literal -offset indent 285struct pollfd pfd[1]; 286char buf[BUFSIZ]; 287int nready; 288 289pfd[0].fd = STDIN_FILENO; 290pfd[0].events = POLLIN; 291nready = poll(pfd, 1, 60 * 1000); 292if (nready == -1) 293 err(1, "poll"); 294if (nready == 0) 295 errx(1, "time out"); 296if ((pfd[0].revents & (POLLERR|POLLNVAL))) 297 errx(1, "bad fd %d", pfd[0].fd); 298if ((pfd[0].revents & (POLLIN|POLLHUP))) 299 if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) 300 err(1, "read"); 301} 302.Ed 303.Sh ERRORS 304.Fn poll 305and 306.Fn ppoll 307will fail if: 308.Bl -tag -width Er 309.It Bq Er EFAULT 310.Fa fds 311points outside the process's allocated address space. 312.It Bq Er EINTR 313A signal was caught before any polled events occurred 314and before the timeout elapsed. 315.It Bq Er EINVAL 316.Fa nfds 317was greater than the number of available 318file descriptors. 319.It Bq Er EINVAL 320The timeout passed was invalid. 321.El 322.Sh SEE ALSO 323.Xr clock_gettime 2 , 324.Xr getrlimit 2 , 325.Xr read 2 , 326.Xr select 2 , 327.Xr write 2 328.Sh STANDARDS 329The 330.Fn poll 331function is compliant with the 332.St -p1003.1-2008 333specification. 334The 335.Fn ppoll 336function is a Linux extension. 337.Sh HISTORY 338A 339.Fn poll 340system call appeared in 341.At V.3 . 342The 343.Fn ppoll 344function appeared in 345.Ox 5.4 . 346.Sh BUGS 347The 348.Dv POLLWRBAND 349flag is accepted but ignored by the kernel. 350.Pp 351Because 352.Ox 353does not implement STREAMS, 354there is no distinction between some of the fields in the 355.Fa events 356and 357.Fa revents 358bitmasks. 359As a result, the 360.Dv POLLIN , 361.Dv POLLNORM , 362and 363.Dv POLLRDNORM 364flags are equivalent. 365Similarly, the 366.Dv POLLPRI 367and 368.Dv POLLRDBAND 369flags are also equivalent. 370.Pp 371Internally to the kernel, 372.Fn poll 373and 374.Fn ppoll 375work poorly if multiple processes wait on the same file descriptor. 376