Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 288 insertions, 0 deletions

diff --git a/man/man2/epoll_wait.2 b/man/man2/epoll_wait.2
new file mode 100644
index 0000000..3b1fbc8
--- /dev/null
+++ b/man/man2/epoll_wait.2
@@ -0,0 +1,288 @@
+.\"  Copyright (C) 2003  Davide Libenzi
+.\"  Davide Libenzi <davidel@xmailserver.org>
+.\" and Copyright 2007, 2012, 2014, 2018 Michael Kerrisk <tk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.\" 2007-04-30: mtk, Added description of epoll_pwait()
+.\"
+.TH epoll_wait 2 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+epoll_wait, epoll_pwait, epoll_pwait2 \-
+wait for an I/O event on an epoll file descriptor
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <sys/epoll.h>
+.P
+.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 *_Nullable " sigmask );
+.BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events ,
+.BI "               int " maxevents ", \
+const struct timespec *_Nullable " timeout ,
+.BI "               const sigset_t *_Nullable " sigmask );
+.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.
+.P
+The
+.I timeout
+argument specifies the number of milliseconds that
+.BR epoll_wait ()
+will block.
+Time is measured against the
+.B CLOCK_MONOTONIC
+clock.
+.P
+A call to
+.BR epoll_wait ()
+will block until either:
+.IP \[bu] 3
+a file descriptor delivers an event;
+.IP \[bu]
+the call is interrupted by a signal handler; or
+.IP \[bu]
+the timeout expires.
+.P
+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 causes
+.BR epoll_wait ()
+to return immediately, even if no events are available.
+.P
+The
+.I struct epoll_event
+is described in
+.BR epoll_event (3type).
+.P
+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.
+.P
+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.
+.P
+The following
+.BR epoll_pwait ()
+call:
+.P
+.in +4n
+.EX
+ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
+.EE
+.in
+.P
+is equivalent to
+.I atomically
+executing the following calls:
+.P
+.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
+.P
+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 operation,
+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 STANDARDS
+Linux.
+.SH HISTORY
+.TP
+.BR epoll_wait ()
+Linux 2.6,
+.\" To be precise: Linux 2.5.44.
+.\" The interface should be finalized by Linux 2.5.66.
+glibc 2.3.2.
+.TP
+.BR epoll_pwait ()
+Linux 2.6.19,
+glibc 2.6.
+.TP
+.BR epoll_pwait2 ()
+Linux 5.11.
+.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.
+.P
+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.
+.P
+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
+.I sigmask
+argument.
+The glibc
+.BR epoll_pwait ()
+wrapper function specifies this argument as a fixed value
+(equal to
+.IR sizeof(sigset_t) ).
+.SH BUGS
+Before Linux 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)