| .\" 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. |
| .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. |
| .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 SEE ALSO |
| .BR epoll_create (2), |
| .BR epoll_ctl (2), |
| .BR epoll (7) |