diff options
Diffstat (limited to 'man2/epoll_wait.2')
| -rw-r--r-- | man2/epoll_wait.2 | 288 |
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) |