1.\" $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $ 2.\" $FreeBSD: src/lib/libc/sys/poll.2,v 1.4.2.3 2001/12/14 18:34:01 ru Exp $ 3.\" $DragonFly: src/lib/libc/sys/poll.2,v 1.7 2008/05/25 14:04:32 swildner Exp $ 4.\" 5.\" Copyright (c) 1996 Charles M. Hannum. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgement: 17.\" This product includes software developed by Charles M. Hannum. 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31.\" 32.Dd January 12, 2008 33.Dt POLL 2 34.Os 35.Sh NAME 36.Nm poll , 37.Nm ppoll 38.Nd synchronous I/O multiplexing 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/types.h 43.In poll.h 44.Ft int 45.Fo poll 46.Fa "struct pollfd *fds" 47.Fa "nfds_t nfds" 48.Fa "int timeout" 49.Fc 50.Ft int 51.Fo ppoll 52.Fa "struct pollfd *fds" 53.Fa "nfds_t nfds" 54.Fa "const struct timespec *timeout" 55.Fa "const sigset_t *newsigmask" 56.Fc 57.Sh DESCRIPTION 58.Fn Poll 59and 60.Fn ppoll 61examine a set of file descriptors to see if some of them are ready for 62I/O. 63The 64.Fa fds 65argument is a pointer to an array of pollfd structures as defined in 66.In poll.h 67(shown below). 68The 69.Fa nfds 70argument determines the size of the 71.Fa fds 72array. 73.Bd -literal 74struct pollfd { 75 int fd; /* file descriptor */ 76 short events; /* events to look for */ 77 short revents; /* events returned */ 78}; 79.Ed 80.Pp 81The fields of 82.Fa struct pollfd 83are as follows: 84.Bl -tag -offset indent -width ".Fa revents" 85.It Fa fd 86File descriptor to poll. 87If fd is equal to -1 then 88.Fa revents 89is cleared (set to zero), and that pollfd is not checked. 90.It Fa events 91Events to poll for. 92(See below.) 93.It Fa revents 94Events which may occur. 95(See below.) 96.El 97.Pp 98The event bitmasks in 99.Fa events 100and 101.Fa revents 102have the following bits: 103.Bl -tag -offset indent -width ".Dv POLLRDNORM" 104.It Dv POLLIN 105Data other than high priority data may be read without blocking. 106.It Dv POLLRDNORM 107Normal data may be read without blocking. 108.It Dv POLLRDBAND 109Data with a non-zero priority may be read without blocking. 110.It Dv POLLPRI 111High priority data may be read without blocking. 112.It Dv POLLOUT 113.It Dv POLLWRNORM 114Normal data may be written without blocking. 115.It Dv POLLWRBAND 116Data with a non-zero priority may be written without blocking. 117.It Dv 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 Dv POLLHUP 123The device or socket has been disconnected. 124This flag is always checked, even if not present in the 125.Fa events 126bitmask. 127Note that 128.Dv POLLHUP 129and 130.Dv POLLOUT 131should never be present in the 132.Fa revents 133bitmask at the same time. 134.It Dv POLLNVAL 135The file descriptor is not open. 136This flag is always checked, even if not present in the 137.Fa events 138bitmask. 139.El 140.Pp 141If 142.Fa timeout 143is neither zero nor 144.Dv INFTIM Pq -1 , 145it specifies a maximum interval to 146wait for any file descriptor to become ready, in milliseconds. 147If 148.Fa timeout 149is 150.Dv INFTIM Pq -1 , 151the poll blocks indefinitely. 152If 153.Fa timeout 154is zero, then 155.Fn poll 156will return without blocking. 157.Sh RETURN VALUES 158.Fn Poll 159returns the number of descriptors that are ready for I/O, or -1 if an 160error occurred. 161If the time limit expires, 162.Fn poll 163returns 0. 164If 165.Fn poll 166returns with an error, 167including one due to an interrupted call, 168the 169.Fa fds 170array will be unmodified. 171.Sh COMPATIBILITY 172This implementation differs from the historical one in that a given 173file descriptor may not cause 174.Fn poll 175to return with an error. 176In cases where this would have happened in the historical implementation 177(e.g.\& trying to poll a 178.Xr revoke 2 Ns ed 179descriptor), this implementation instead copies the 180.Fa events 181bitmask to the 182.Fa revents 183bitmask. 184Attempting to perform I/O on this descriptor will then return an error. 185This behaviour is believed to be more useful. 186.Sh ERRORS 187An error return from 188.Fn poll 189indicates: 190.Bl -tag -width Er 191.It Bq Er EFAULT 192.Fa Fds 193points outside the process's allocated address space. 194.It Bq Er EINTR 195A signal was delivered before the time limit expired and 196before any of the selected events occurred. 197.It Bq Er EINVAL 198The specified time limit is negative. 199.El 200.Sh SEE ALSO 201.Xr accept 2 , 202.Xr connect 2 , 203.Xr read 2 , 204.Xr recv 2 , 205.Xr select 2 , 206.Xr send 2 , 207.Xr write 2 208.Sh HISTORY 209The 210.Fn poll 211function call appeared in 212.At V . 213This manual page was taken from 214.Nx . 215.Sh BUGS 216The distinction between some of the fields in the 217.Fa events 218and 219.Fa revents 220bitmasks is really not useful without STREAMS. 221The fields are defined for compatibility with existing software. 222