mirror of https://github.com/mkerrisk/man-pages
319 lines
7.7 KiB
Groff
319 lines
7.7 KiB
Groff
.\" Copyright (C) 2003 Davide Libenzi
|
|
.\" Davide Libenzi <davidel@xmailserver.org>
|
|
.\" and Copyright 2007, 2012, 2014, 2018 Michael Kerrisk <tk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
|
|
.\" This program is free software; you can redistribute it and/or modify
|
|
.\" it under the terms of the GNU General Public License as published by
|
|
.\" the Free Software Foundation; either version 2 of the License, or
|
|
.\" (at your option) any later version.
|
|
.\"
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
.\" GNU General Public License for more details.
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public
|
|
.\" License along with this manual; if not, see
|
|
.\" <http://www.gnu.org/licenses/>.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" 2007-04-30: mtk, Added description of epoll_pwait()
|
|
.\"
|
|
.TH EPOLL_WAIT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
epoll_wait, epoll_pwait, epoll_pwait2 \- wait for an I/O event on an epoll file descriptor
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <sys/epoll.h>
|
|
.PP
|
|
.BI "int epoll_wait(int " epfd ", struct epoll_event *" events ,
|
|
.BI " int " maxevents ", int " timeout );
|
|
.BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
|
|
.BI " int " maxevents ", int " timeout ,
|
|
.BI " const sigset_t *" sigmask );
|
|
.BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events ,
|
|
.BI " int " maxevents ", const struct timespec *" timeout ,
|
|
.BI " const sigset_t *" sigmask );
|
|
.\" FIXME: Check if glibc has added a wrapper for epoll_pwait2(),
|
|
.\" and if so, check the prototype.
|
|
.\" https://sourceware.org/bugzilla/show_bug.cgi?id=27359
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.BR epoll_wait ()
|
|
system call waits for events on the
|
|
.BR epoll (7)
|
|
instance referred to by the file descriptor
|
|
.IR epfd .
|
|
The buffer pointed to by
|
|
.I events
|
|
is used to return information from the ready list
|
|
about file descriptors in the interest list that
|
|
have some events available.
|
|
Up to
|
|
.I maxevents
|
|
are returned by
|
|
.BR epoll_wait ().
|
|
The
|
|
.I maxevents
|
|
argument must be greater than zero.
|
|
.PP
|
|
The
|
|
.I timeout
|
|
argument specifies the number of milliseconds that
|
|
.BR epoll_wait ()
|
|
will block.
|
|
Time is measured against the
|
|
.B CLOCK_MONOTONIC
|
|
clock.
|
|
.PP
|
|
A call to
|
|
.BR epoll_wait ()
|
|
will block until either:
|
|
.IP \(bu 2
|
|
a file descriptor delivers an event;
|
|
.IP \(bu
|
|
the call is interrupted by a signal handler; or
|
|
.IP \(bu
|
|
the timeout expires.
|
|
.PP
|
|
Note that the
|
|
.I timeout
|
|
interval will be rounded up to the system clock granularity,
|
|
and kernel scheduling delays mean that the blocking interval
|
|
may overrun by a small amount.
|
|
Specifying a
|
|
.I timeout
|
|
of \-1 causes
|
|
.BR epoll_wait ()
|
|
to block indefinitely, while specifying a
|
|
.I timeout
|
|
equal to zero cause
|
|
.BR epoll_wait ()
|
|
to return immediately, even if no events are available.
|
|
.PP
|
|
The
|
|
.I struct epoll_event
|
|
is defined as:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
typedef union epoll_data {
|
|
void *ptr;
|
|
int fd;
|
|
uint32_t u32;
|
|
uint64_t u64;
|
|
} epoll_data_t;
|
|
|
|
struct epoll_event {
|
|
uint32_t events; /* Epoll events */
|
|
epoll_data_t data; /* User data variable */
|
|
};
|
|
.EE
|
|
.in
|
|
.PP
|
|
The
|
|
.I data
|
|
field of each returned
|
|
.I epoll_event
|
|
structure contains the same data as was specified
|
|
in the most recent call to
|
|
.BR epoll_ctl (2)
|
|
.RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
|
|
for the corresponding open file descriptor.
|
|
.PP
|
|
The
|
|
.I events
|
|
field is a bit mask that indicates the events that have occurred for the
|
|
corresponding open file description.
|
|
See
|
|
.BR epoll_ctl (2)
|
|
for a list of the bits that may appear in this mask.
|
|
.\"
|
|
.SS epoll_pwait()
|
|
The relationship between
|
|
.BR epoll_wait ()
|
|
and
|
|
.BR epoll_pwait ()
|
|
is analogous to the relationship between
|
|
.BR select (2)
|
|
and
|
|
.BR pselect (2):
|
|
like
|
|
.BR pselect (2),
|
|
.BR epoll_pwait ()
|
|
allows an application to safely wait until either a file descriptor
|
|
becomes ready or until a signal is caught.
|
|
.PP
|
|
The following
|
|
.BR epoll_pwait ()
|
|
call:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
|
|
.EE
|
|
.in
|
|
.PP
|
|
is equivalent to
|
|
.I atomically
|
|
executing the following calls:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
sigset_t origmask;
|
|
|
|
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
|
|
ready = epoll_wait(epfd, &events, maxevents, timeout);
|
|
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
|
|
.EE
|
|
.in
|
|
.PP
|
|
The
|
|
.I sigmask
|
|
argument may be specified as NULL, in which case
|
|
.BR epoll_pwait ()
|
|
is equivalent to
|
|
.BR epoll_wait ().
|
|
.\"
|
|
.SS epoll_pwait2()
|
|
The
|
|
.BR epoll_pwait2 ()
|
|
system call is equivalent to
|
|
.BR epoll_pwait ()
|
|
except for the
|
|
.I timeout
|
|
argument.
|
|
It takes an argument of type
|
|
.I timespec
|
|
to be able to specify nanosecond resolution timeout.
|
|
This argument functions the same as in
|
|
.BR pselect (2)
|
|
and
|
|
.BR ppoll (2).
|
|
If
|
|
.I timeout
|
|
is NULL, then
|
|
.BR epoll_pwait2 ()
|
|
can block indefinitely.
|
|
.SH RETURN VALUE
|
|
On success,
|
|
.BR epoll_wait ()
|
|
returns the number of file descriptors ready for the requested I/O, or zero
|
|
if no file descriptor became ready during the requested
|
|
.I timeout
|
|
milliseconds.
|
|
On failure,
|
|
.BR epoll_wait ()
|
|
returns \-1 and
|
|
.I errno
|
|
is set to indicate the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EBADF
|
|
.I epfd
|
|
is not a valid file descriptor.
|
|
.TP
|
|
.B EFAULT
|
|
The memory area pointed to by
|
|
.I events
|
|
is not accessible with write permissions.
|
|
.TP
|
|
.B EINTR
|
|
The call was interrupted by a signal handler before either (1) any of the
|
|
requested events occurred or (2) the
|
|
.I timeout
|
|
expired; see
|
|
.BR signal (7).
|
|
.TP
|
|
.B EINVAL
|
|
.I epfd
|
|
is not an
|
|
.B epoll
|
|
file descriptor, or
|
|
.I maxevents
|
|
is less than or equal to zero.
|
|
.SH VERSIONS
|
|
.BR epoll_wait ()
|
|
was added to the kernel in version 2.6.
|
|
.\" To be precise: kernel 2.5.44.
|
|
.\" The interface should be finalized by Linux kernel 2.5.66.
|
|
Library support is provided in glibc starting with version 2.3.2.
|
|
.PP
|
|
.BR epoll_pwait ()
|
|
was added to Linux in kernel 2.6.19.
|
|
Library support is provided in glibc starting with version 2.6.
|
|
.PP
|
|
.BR epoll_pwait2 ()
|
|
was added to Linux in kernel 5.11.
|
|
.SH CONFORMING TO
|
|
.BR epoll_wait (),
|
|
.BR epoll_pwait (),
|
|
and
|
|
.BR epoll_pwait2 ()
|
|
are Linux-specific.
|
|
.SH NOTES
|
|
While one thread is blocked in a call to
|
|
.BR epoll_wait (),
|
|
it is possible for another thread to add a file descriptor to the waited-upon
|
|
.B epoll
|
|
instance.
|
|
If the new file descriptor becomes ready,
|
|
it will cause the
|
|
.BR epoll_wait ()
|
|
call to unblock.
|
|
.PP
|
|
If more than
|
|
.I maxevents
|
|
file descriptors are ready when
|
|
.BR epoll_wait ()
|
|
is called, then successive
|
|
.BR epoll_wait ()
|
|
calls will round robin through the set of ready file descriptors.
|
|
This behavior helps avoid starvation scenarios,
|
|
where a process fails to notice that additional file descriptors
|
|
are ready because it focuses on a set of file descriptors that
|
|
are already known to be ready.
|
|
.PP
|
|
Note that it is possible to call
|
|
.BR epoll_wait ()
|
|
on an
|
|
.B epoll
|
|
instance whose interest list is currently empty
|
|
(or whose interest list becomes empty because file descriptors are closed
|
|
or removed from the interest in another thread).
|
|
The call will block until some file descriptor is later added to the
|
|
interest list (in another thread) and that file descriptor becomes ready.
|
|
.SS C library/kernel differences
|
|
The raw
|
|
.BR epoll_pwait ()
|
|
and
|
|
.BR epoll_pwait2 ()
|
|
system calls have a sixth argument,
|
|
.IR "size_t sigsetsize" ,
|
|
which specifies the size in bytes of the
|
|
.IR sigmask
|
|
argument.
|
|
The glibc
|
|
.BR epoll_pwait ()
|
|
wrapper function specifies this argument as a fixed value
|
|
(equal to
|
|
.IR sizeof(sigset_t) ).
|
|
.SH BUGS
|
|
In kernels before 2.6.37, a
|
|
.I timeout
|
|
value larger than approximately
|
|
.I LONG_MAX / HZ
|
|
milliseconds is treated as \-1 (i.e., infinity).
|
|
Thus, for example, on a system where
|
|
.I sizeof(long)
|
|
is 4 and the kernel
|
|
.I HZ
|
|
value is 1000,
|
|
this means that timeouts greater than 35.79 minutes are treated as infinity.
|
|
.SH SEE ALSO
|
|
.BR epoll_create (2),
|
|
.BR epoll_ctl (2),
|
|
.BR epoll (7)
|