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