.\"	$OpenBSD: poll.2,v 1.40 2023/07/18 04:17:17 asou 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 $Mdocdate: July 18 2023 $
.Dt POLL 2
.Os
.Sh NAME
.Nm poll ,
.Nm ppoll
.Nd synchronous I/O multiplexing
.Sh SYNOPSIS
.In poll.h
.Ft int
.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout"
.Ft int
.Fn ppoll "struct pollfd *fds" "nfds_t nfds" "const struct timespec *timeout" "const sigset_t *mask"
.Sh DESCRIPTION
.Fn poll
provides a mechanism for multiplexing I/O across a set of file
descriptors.
It is similar in function to
.Xr select 2 .
Unlike
.Xr select 2 ,
however, it is possible to only pass in data corresponding to the
file descriptors for which events are wanted.
This makes
.Fn poll
more efficient than
.Xr select 2
in most cases.
.Pp
The arguments are as follows:
.Bl -tag -width timeout
.It Fa fds
Points to an array of
.Vt pollfd
structures, which are defined as:
.Bd -literal -offset indent
struct pollfd {
	int   fd;
	short events;
	short revents;
};
.Ed
.Pp
The
.Fa fd
member is an open file descriptor.
If
.Fa fd
is -1,
the
.Vt pollfd
structure is considered unused, and
.Fa revents
will be cleared.
.Pp
The
.Fa events
and
.Fa revents
members are bitmasks of conditions to monitor and conditions found,
respectively.
.It Fa nfds
An unsigned integer specifying the number of
.Vt pollfd
structures in the array.
.It Fa timeout
Maximum interval to wait for the poll to complete, in milliseconds.
If this value is 0,
.Fn poll
will return immediately.
If this value is
.Dv INFTIM Pq -1 ,
.Fn poll
will block indefinitely until a condition is found.
.El
.Pp
The calling process sets the
.Fa events
bitmask and
.Fn poll
sets the
.Fa revents
bitmask.
Each call to
.Fn poll
resets the
.Fa revents
bitmask for accuracy.
The condition flags in the bitmasks are defined as:
.Bl -tag -width POLLRDNORM
.It Dv POLLIN
Data other than high-priority data may be read without blocking.
.It Dv POLLRDNORM
Normal data may be read without blocking.
.It Dv POLLRDBAND
Priority data may be read without blocking.
.It Dv POLLNORM
Same as
.Dv POLLRDNORM .
This flag is provided for source code compatibility with older
programs and should not be used in new code.
.It Dv POLLPRI
High-priority data may be read without blocking.
.It Dv POLLOUT
Normal data may be written without blocking.
.It Dv POLLWRNORM
Same as
.Dv POLLOUT .
.It Dv POLLWRBAND
Priority data may be written.
.It Dv POLLERR
An error has occurred on the device or socket.
This flag is only valid in the
.Fa revents
bitmask; it is ignored in the
.Fa events
member.
.It Dv POLLHUP
The device or socket has been disconnected.
This event and
.Dv POLLOUT
are mutually-exclusive; a descriptor can never be writable if a hangup has
occurred.
However, this event and
.Dv POLLIN ,
.Dv POLLRDNORM ,
.Dv POLLRDBAND ,
or
.Dv POLLPRI
are not mutually-exclusive.
This flag is only valid in the
.Fa revents
bitmask; it is ignored in the
.Fa events
member.
.It Dv POLLNVAL
The corresponding file descriptor is invalid.
This flag is only valid in the
.Fa revents
bitmask; it is ignored in the
.Fa events
member.
.El
.Pp
The significance and semantics of normal, priority, and high-priority
data are device-specific.
For example, on
.Ox ,
the
.Dv POLLPRI
and
.Dv POLLRDBAND
flags may be used to detect when out-of-band socket data may be read
without blocking.
.Pp
The
.Fn ppoll
function is similar to
.Fn poll
except that it specifies the timeout using a timespec structure,
and a null pointer is used to specify an indefinite timeout
instead of
.Dv INFTIM .
Also, if
.Fa mask
is a non-null pointer,
.Fn ppoll
atomically sets the calling thread's signal mask to the signal set
pointed to by
.Fa mask
for the duration of the function call.
In this case, the original signal mask will be restored before
.Fn ppoll
returns.
.Sh RETURN VALUES
Upon error,
.Fn poll
and
.Fn ppoll
return \-1 and set the global variable
.Va errno
to indicate the error.
If the timeout interval was reached before any events occurred,
they return 0.
Otherwise, they return the number of
.Vt pollfd
structures for which
.Fa revents
is non-zero.
.Sh IDIOMS
Care must be taken when converting code from
.Xr select 2
to
.Fn poll
as they have slightly different semantics.
The first semantic difference is that, unlike
.Xr select 2 ,
.Fn poll
has a way of indicating that one or more file descriptors is invalid
by setting a flag in the
.Fa revents
field of corresponding entry of
.Fa fds ,
whereas
.Xr select 2
returns an error (-1) if any of the descriptors with bits set in
the
.Vt fd_set
are invalid.
The second difference is that on EOF there is no guarantee that
.Dv POLLIN
will be set in
.Fa revents ,
the caller must also check for
.Dv POLLHUP .
This differs from
.Xr select 2
where EOF is considered as a read event.
.Pp
Consider the following usage of
.Xr select 2
that implements a read from the standard input with a
60 second time out:
.Bd -literal -offset indent
struct timeval timeout;
fd_set readfds;
char buf[BUFSIZ];
int nready;

timeout.tv_sec = 60;
timeout.tv_usec = 0;
FD_ZERO(&readfds);
FD_SET(STDIN_FILENO, &readfds);
nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout);
if (nready == -1)
	err(1, "select");
if (nready == 0)
	errx(1, "time out");
if (FD_ISSET(STDIN_FILENO, &readfds)) {
	if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
		err(1, "read");
}
.Ed
.Pp
This can be converted to
.Fn poll
as follows:
.Bd -literal -offset indent
struct pollfd pfd[1];
char buf[BUFSIZ];
int nready;

pfd[0].fd = STDIN_FILENO;
pfd[0].events = POLLIN;
nready = poll(pfd, 1, 60 * 1000);
if (nready == -1)
	err(1, "poll");
if (nready == 0)
	errx(1, "time out");
if (pfd[0].revents & (POLLERR|POLLNVAL))
	errx(1, "bad fd %d", pfd[0].fd);
if (pfd[0].revents & (POLLIN|POLLHUP)) {
	if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
		err(1, "read");
}
.Ed
.Sh ERRORS
.Fn poll
and
.Fn ppoll
will fail if:
.Bl -tag -width Er
.It Bq Er EAGAIN
The kernel failed to allocate memory for temporary data structures;
a later call may succeed.
.It Bq Er EFAULT
.Fa fds
points outside the process's allocated address space.
.It Bq Er EINTR
A signal was caught before any polled events occurred
and before the timeout elapsed.
.It Bq Er EINVAL
.Fa nfds
was greater than the number of available
file descriptors.
.It Bq Er EINVAL
The timeout passed was invalid.
.El
.Sh SEE ALSO
.Xr clock_gettime 2 ,
.Xr getrlimit 2 ,
.Xr read 2 ,
.Xr select 2 ,
.Xr write 2
.Sh STANDARDS
The
.Fn poll
function is compliant with the
.St -p1003.1-2008
specification.
The
.Fn ppoll
function is a Linux extension.
.Sh HISTORY
A
.Fn poll
system call appeared in
.At V.3 .
The
.Fn ppoll
function appeared in
.Ox 5.4 .
.Sh BUGS
The
.Dv POLLWRBAND
flag is accepted but ignored by the kernel.
.Pp
Because
.Ox
does not implement STREAMS,
there is no distinction between some of the fields in the
.Fa events
and
.Fa revents
bitmasks.
As a result, the
.Dv POLLIN ,
.Dv POLLNORM ,
and
.Dv POLLRDNORM
flags are equivalent.
Similarly, the
.Dv POLLPRI
and
.Dv POLLRDBAND
flags are also equivalent.