summaryrefslogtreecommitdiffstats
path: root/man2/epoll_wait.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/epoll_wait.2')
-rw-r--r--man2/epoll_wait.2288
1 files changed, 0 insertions, 288 deletions
diff --git a/man2/epoll_wait.2 b/man2/epoll_wait.2
deleted file mode 100644
index 72d6fab..0000000
--- a/man2/epoll_wait.2
+++ /dev/null
@@ -1,288 +0,0 @@
-.\" 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-03-03 "Linux man-pages 6.7"
-.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)