1.\" $OpenBSD: poll.2,v 1.21 2007/07/11 08:12:15 jmc 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 11 2007 $ 32.Dt POLL 2 33.Os 34.Sh NAME 35.Nm poll 36.Nd synchronous I/O multiplexing 37.Sh SYNOPSIS 38.Fd #include <poll.h> 39.Ft int 40.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout" 41.Sh DESCRIPTION 42.Fn poll 43provides a mechanism for multiplexing I/O across a set of file 44descriptors. 45It is similar in function to 46.Xr select 2 . 47Unlike 48.Xr select 2 , 49however, it is possible to only pass in data corresponding to the 50file descriptors for which events are wanted. 51This makes 52.Fn poll 53more efficient than 54.Xr select 2 55in most cases. 56.Pp 57The arguments are as follows: 58.Bl -tag -width timeout 59.It Fa fds 60Points to an array of 61.Fa pollfd 62structures, which are defined as: 63.Bd -literal -offset indent 64struct pollfd { 65 int fd; 66 short events; 67 short revents; 68}; 69.Ed 70.Pp 71The 72.Fa fd 73member is an open file descriptor. 74If 75.Fa fd 76is -1, 77the 78.Fa pollfd 79structure is considered unused, and 80.Fa revents 81will be cleared. 82.Pp 83The 84.Fa events 85and 86.Fa revents 87members are bitmasks of conditions to monitor and conditions found, 88respectively. 89.It Fa nfds 90An unsigned integer specifying the number of 91.Fa pollfd 92structures in the array. 93.It Fa timeout 94Maximum interval to wait for the poll to complete, in milliseconds. 95If this value is 0, 96.Fn poll 97will return immediately. 98If this value is INFTIM (-1), 99.Fn poll 100will block indefinitely until a condition is found. 101.El 102.Pp 103The calling process sets the 104.Fa events 105bitmask and 106.Fn poll 107sets the 108.Fa revents 109bitmask. 110Each call to 111.Fn poll 112resets the 113.Fa revents 114bitmask for accuracy. 115The condition flags in the bitmasks are defined as: 116.Bl -tag -width POLLRDNORM 117.It Dv POLLIN 118Data other than high-priority data may be read without blocking. 119.It Dv POLLRDNORM 120Normal data may be read without blocking. 121.It Dv POLLRDBAND 122Priority data may be read without blocking. 123.It Dv POLLNORM 124Same as 125.Dv POLLRDNORM . 126This flag is provided for source code compatibility with older 127programs and should not be used in new code. 128.It Dv POLLPRI 129High-priority data may be read without blocking. 130.It Dv POLLOUT 131Normal data may be written without blocking. 132.It Dv POLLWRNORM 133Same as 134.Dv POLLOUT . 135.It Dv POLLWRBAND 136Priority data may be written. 137.It Dv POLLERR 138An error has occurred on the device or socket. 139This flag is only valid in the 140.Fa revents 141bitmask; it is ignored in the 142.Fa events 143member. 144.It Dv POLLHUP 145The device or socket has been disconnected. 146This event and 147.Dv POLLOUT 148are mutually-exclusive; a descriptor can never be writable if a hangup has 149occurred. 150However, this event and 151.Dv POLLIN , 152.Dv POLLRDNORM , 153.Dv POLLRDBAND , 154or 155.Dv POLLPRI 156are not mutually-exclusive. 157This flag is only valid in the 158.Fa revents 159bitmask; it is ignored in the 160.Fa events 161member. 162.It Dv POLLNVAL 163The corresponding file descriptor is invalid. 164This flag is only valid in the 165.Fa revents 166bitmask; it is ignored in the 167.Fa events 168member. 169.El 170.Pp 171The significance and semantics of normal, priority, and high-priority 172data are device-specific. 173.Pp 174In addition to I/O multiplexing, 175.Fn poll 176can be used to generate simple timeouts. 177This functionality may be achieved by passing a null pointer for 178.Fa fds . 179.Sh RETURN VALUES 180Upon error, 181.Fn poll 182returns \-1 and sets the global variable 183.Va errno 184to indicate the error. 185If the timeout interval was reached before any events occurred, 186.Fn poll 187returns 0. 188Otherwise, 189.Fn poll 190returns the number of file descriptors for which 191.Fa revents 192is non-zero. 193.Sh EXAMPLES 194The following example implements a read from the standard input that times 195out after 60 seconds: 196.Bd -literal -offset indent 197#include <err.h> 198#include <poll.h> 199#include <stdio.h> 200#include <unistd.h> 201 202struct pollfd pfd[1]; 203char buf[BUFSIZ]; 204int nfds; 205 206pfd[0].fd = STDIN_FILENO; 207pfd[0].events = POLLIN; 208nfds = poll(pfd, 1, 60 * 1000); 209if (nfds == -1 || (pfd[0].revents & (POLLERR|POLLHUP|POLLNVAL))) 210 errx(1, "poll error"); 211if (nfds == 0) 212 errx(1, "time out"); 213if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) 214 errx(1, "read"); 215.Ed 216.Sh ERRORS 217.Fn poll 218will fail if: 219.Bl -tag -width "EINVAL " 220.It Bq Er EFAULT 221.Fa fds 222points outside the process's allocated address space. 223.It Bq Er EINTR 224.Fn poll 225caught a signal during the polling process. 226.It Bq Er EINVAL 227.Fa nfds 228was greater than the number of available 229file descriptors. 230.It Bq Er EINVAL 231The timeout passed to 232.Fn poll 233was too large. 234.El 235.Sh SEE ALSO 236.Xr getrlimit 2 , 237.Xr read 2 , 238.Xr select 2 , 239.Xr write 2 240.Sh STANDARDS 241The 242.Fn poll 243function is compliant with the 244.St -xpg4.3 245specification. 246.Sh HISTORY 247A 248.Fn poll 249system call appeared in 250.At V.3 . 251.Sh BUGS 252The 253.Dv POLLERR 254and 255.Dv POLLWRBAND 256flags are accepted but ignored by the kernel. 257.Pp 258Because 259.Ox 260does not implement 261.Tn STREAMS , 262there is no distinction between some of the fields in the 263.Fa events 264and 265.Fa revents 266bitmasks. 267As a result, the 268.Dv POLLIN , 269.Dv POLLNORM , 270and 271.Dv POLLRDNORM 272flags are equivalent. 273.Pp 274Internally to the kernel, 275.Fn poll 276works poorly if multiple processes wait on the same file descriptor. 277