.\"	$OpenBSD: poll.2,v 1.13 2003/02/27 07:55:34 jmc Exp $
.\"
.\" Copyright (c) 1994 Jason R. Thorpe
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Jason R. Thorpe.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\"
.Dd December 13, 1994
.Dt POLL 2
.Os
.Sh NAME
.Nm poll
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.Fd #include <poll.h>
.Ft int
.Fn poll "struct pollfd *fds" "int nfds" "int timeout"
.Sh DESCRIPTION
.Fn poll
provides a mechanism for reporting I/O conditions across a set of file
descriptors.
.Pp
The arguments are as follows:
.Bl -tag -width timeout
.It Pa fds
Points to an array of
.Nm pollfd
structures, which are defined as:
.Bd -literal -offset indent
struct pollfd {
	int fd;
	short events;
	short revents;
};
.Ed
.Pp
The
.Pa fd
member is an open file descriptor.
The
.Pa events
and
.Pa revents
members are bitmasks of conditions to monitor and conditions found,
respectively.
.It Pa nfds
The number of
.Nm pollfd
structures in the array.
.It Pa timeout
Maximum interval to wait for the poll to complete, in milliseconds.
If this value is 0, then
.Fn poll
will return immediately.
If this value is INFTIM (-1),
.Fn poll
will block indefinitely until a condition is found.
.El
.Pp
The calling process sets the
.Pa events
bitmask and
.Fn poll
sets the
.Pa revents
bitmask.
Each call to
.Fn poll
resets the
.Pa revents
bitmask for accuracy.
The condition flags in the bitmasks are defined as:
.Bl -tag -width POLLRDNORM
.It Nm POLLIN
Data is available on the file descriptor for reading.
.It Nm POLLNORM
Same as
.Nm POLLIN .
.It Nm POLLPRI
Same as
.Nm POLLIN .
.It Nm POLLOUT
Data can be written to the file descriptor without blocking.
.It Nm POLLERR
This flag is not used in this implementation and is provided only for source
code compatibility.
.It Nm POLLHUP
The file descriptor was valid before the polling process and invalid after.
Presumably, this means that the file descriptor was closed sometime during
the poll.
.It Nm POLLNVAL
The corresponding file descriptor is invalid.
.It Nm POLLRDNORM
Same as
.Nm POLLIN .
.It Nm POLLRDBAND
Same as
.Nm POLLIN .
.It Nm POLLWRNORM
Same as
.Nm POLLOUT .
.It Nm POLLWRBAND
Same as
.Nm POLLOUT .
.It Nm POLLMSG
This flag is not used in this implementation and is provided only for source
code compatibility.
.El
.Pp
All flags except
.Nm POLLIN ,
.Nm POLLOUT ,
and their synonyms are for use only in the
.Pa revents
member of the
.Nm pollfd
structure.
An attempt to set any of these flags in the
.Pa events
member will generate an error condition.
.Pp
In addition to I/O multiplexing,
.Fn poll
can be used to generate simple timeouts.
This functionality may be achieved by passing a null pointer for
.Pa fds .
.Sh WARNINGS
The
.Nm POLLHUP
flag is only a close approximation and may not always be accurate.
.Sh RETURN VALUES
Upon error,
.Fn poll
returns a \-1 and sets the global variable
.Va errno
to indicate the error.
If the timeout interval was reached before any events occurred,
a 0 is returned.
Otherwise,
.Fn poll
returns the number of file descriptors for which
.Pa revents
is non-zero.
.Sh ERRORS
.Fn poll
will fail if:
.Bl -tag -width "EINVAL   "
.It Bq Er EINVAL
.Pa nfds
was either a negative number or greater than the number of available
file descriptors.
.It Bq Er EINVAL
An invalid flag was set in the
.Pa events
member of the
.Nm pollfd
structure.
.It Bq Er EINVAL
The timeout passed to
.Fn poll
was too large.
.It Bq Er EAGAIN
Resource allocation failed inside of
.Fn poll .
Subsequent calls to
.Fn poll
may succeed.
.It Bq Er EINTR
.Fn poll
caught a signal during the polling process.
.El
.Sh SEE ALSO
.Xr select 2 ,
.Xr sysconf 3
.Sh HISTORY
A
.Fn poll
system call appeared in
.At V .