1EPOLL_WAIT(2)              Linux Programmer's Manual             EPOLL_WAIT(2)
2
3
4

NAME

6       epoll_wait,  epoll_pwait,  epoll_pwait2  -  wait for an I/O event on an
7       epoll file descriptor
8

SYNOPSIS

10       #include <sys/epoll.h>
11
12       int epoll_wait(int epfd, struct epoll_event *events,
13                      int maxevents, int timeout);
14       int epoll_pwait(int epfd, struct epoll_event *events,
15                      int maxevents, int timeout,
16                      const sigset_t *sigmask);
17       int epoll_pwait2(int epfd, struct epoll_event *events,
18                      int maxevents, const struct timespec *timeout,
19                      const sigset_t *sigmask);
20

DESCRIPTION

22       The epoll_wait() system call waits for events on the epoll(7)  instance
23       referred  to  by  the  file  descriptor epfd.  The buffer pointed to by
24       events is used to return information from the ready list about file de‐
25       scriptors  in the interest list that have some events available.  Up to
26       maxevents are returned by epoll_wait().  The maxevents argument must be
27       greater than zero.
28
29       The   timeout  argument  specifies  the  number  of  milliseconds  that
30       epoll_wait() will block.  Time is measured against the  CLOCK_MONOTONIC
31       clock.
32
33       A call to epoll_wait() will block until either:
34
35       • a file descriptor delivers an event;
36
37       • the call is interrupted by a signal handler; or
38
39       • the timeout expires.
40
41       Note  that  the timeout interval will be rounded up to the system clock
42       granularity, and kernel scheduling delays mean that the blocking inter‐
43       val  may  overrun by a small amount.  Specifying a timeout of -1 causes
44       epoll_wait() to block indefinitely, while specifying a timeout equal to
45       zero  cause  epoll_wait()  to return immediately, even if no events are
46       available.
47
48       The struct epoll_event is defined as:
49
50           typedef union epoll_data {
51               void    *ptr;
52               int      fd;
53               uint32_t u32;
54               uint64_t u64;
55           } epoll_data_t;
56
57           struct epoll_event {
58               uint32_t     events;    /* Epoll events */
59               epoll_data_t data;      /* User data variable */
60           };
61
62       The data field of each returned epoll_event structure contains the same
63       data  as  was  specified  in  the  most  recent  call  to  epoll_ctl(2)
64       (EPOLL_CTL_ADD, EPOLL_CTL_MOD) for the corresponding open file descrip‐
65       tor.
66
67       The  events field is a bit mask that indicates the events that have oc‐
68       curred for the corresponding open file description.   See  epoll_ctl(2)
69       for a list of the bits that may appear in this mask.
70
71   epoll_pwait()
72       The relationship between epoll_wait() and epoll_pwait() is analogous to
73       the relationship between select(2)  and  pselect(2):  like  pselect(2),
74       epoll_pwait()  allows an application to safely wait until either a file
75       descriptor becomes ready or until a signal is caught.
76
77       The following epoll_pwait() call:
78
79           ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
80
81       is equivalent to atomically executing the following calls:
82
83           sigset_t origmask;
84
85           pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
86           ready = epoll_wait(epfd, &events, maxevents, timeout);
87           pthread_sigmask(SIG_SETMASK, &origmask, NULL);
88
89       The  sigmask  argument  may  be  specified  as  NULL,  in  which   case
90       epoll_pwait() is equivalent to epoll_wait().
91
92   epoll_pwait2()
93       The  epoll_pwait2()  system  call is equivalent to epoll_pwait() except
94       for the timeout argument.  It takes an argument of type timespec to  be
95       able to specify nanosecond resolution timeout.  This argument functions
96       the same as in pselect(2) and  ppoll(2).   If  timeout  is  NULL,  then
97       epoll_pwait2() can block indefinitely.
98

RETURN VALUE

100       On  success,  epoll_wait() returns the number of file descriptors ready
101       for the requested I/O, or zero if no file descriptor became ready  dur‐
102       ing  the  requested timeout milliseconds.  On failure, epoll_wait() re‐
103       turns -1 and errno is set to indicate the error.
104

ERRORS

106       EBADF  epfd is not a valid file descriptor.
107
108       EFAULT The memory area pointed to by  events  is  not  accessible  with
109              write permissions.
110
111       EINTR  The  call  was interrupted by a signal handler before either (1)
112              any of the requested events occurred or (2) the timeout expired;
113              see signal(7).
114
115       EINVAL epfd  is not an epoll file descriptor, or maxevents is less than
116              or equal to zero.
117

VERSIONS

119       epoll_wait() was added to the kernel in version 2.6.   Library  support
120       is provided in glibc starting with version 2.3.2.
121
122       epoll_pwait()  was added to Linux in kernel 2.6.19.  Library support is
123       provided in glibc starting with version 2.6.
124
125       epoll_pwait2() was added to Linux in kernel 5.11.
126

CONFORMING TO

128       epoll_wait(), epoll_pwait(), and epoll_pwait2() are Linux-specific.
129

NOTES

131       While one thread is blocked in a call to epoll_wait(), it  is  possible
132       for  another  thread  to add a file descriptor to the waited-upon epoll
133       instance.  If the new file descriptor becomes ready, it will cause  the
134       epoll_wait() call to unblock.
135
136       If  more than maxevents file descriptors are ready when epoll_wait() is
137       called, then successive epoll_wait() calls will round robin through the
138       set  of  ready  file descriptors.  This behavior helps avoid starvation
139       scenarios, where a process fails to notice  that  additional  file  de‐
140       scriptors  are  ready  because  it focuses on a set of file descriptors
141       that are already known to be ready.
142
143       Note that it is possible to call  epoll_wait()  on  an  epoll  instance
144       whose  interest list is currently empty (or whose interest list becomes
145       empty because file descriptors are closed or removed from the  interest
146       in  another thread).  The call will block until some file descriptor is
147       later added to the interest list (in another thread) and that file  de‐
148       scriptor becomes ready.
149
150   C library/kernel differences
151       The  raw epoll_pwait() and epoll_pwait2() system calls have a sixth ar‐
152       gument, size_t sigsetsize, which specifies the size  in  bytes  of  the
153       sigmask  argument.   The glibc epoll_pwait() wrapper function specifies
154       this argument as a fixed value (equal to sizeof(sigset_t)).
155

BUGS

157       In kernels before 2.6.37, a timeout  value  larger  than  approximately
158       LONG_MAX  /  HZ  milliseconds is treated as -1 (i.e., infinity).  Thus,
159       for example, on a system where sizeof(long) is  4  and  the  kernel  HZ
160       value  is 1000, this means that timeouts greater than 35.79 minutes are
161       treated as infinity.
162

SEE ALSO

164       epoll_create(2), epoll_ctl(2), epoll(7)
165

COLOPHON

167       This page is part of release 5.13 of the Linux  man-pages  project.   A
168       description  of  the project, information about reporting bugs, and the
169       latest    version    of    this    page,    can     be     found     at
170       https://www.kernel.org/doc/man-pages/.
171
172
173
174Linux                             2021-03-22                     EPOLL_WAIT(2)
Impressum