1epoll_wait(2)                 System Calls 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

LIBRARY

10       Standard C library (libc, -lc)
11

SYNOPSIS

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

DESCRIPTION

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

RETURN VALUE

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

ERRORS

97       EBADF  epfd is not a valid file descriptor.
98
99       EFAULT The memory area pointed to by  events  is  not  accessible  with
100              write permissions.
101
102       EINTR  The  call  was interrupted by a signal handler before either (1)
103              any of the requested events occurred or (2) the timeout expired;
104              see signal(7).
105
106       EINVAL epfd  is not an epoll file descriptor, or maxevents is less than
107              or equal to zero.
108

STANDARDS

110       Linux.
111

HISTORY

113       epoll_wait()
114              Linux 2.6, glibc 2.3.2.
115
116       epoll_pwait()
117              Linux 2.6.19, glibc 2.6.
118
119       epoll_pwait2()
120              Linux 5.11.
121

NOTES

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

BUGS

149       Before Linux 2.6.37, a timeout value larger than approximately LONG_MAX
150       /  HZ  milliseconds is treated as -1 (i.e., infinity).  Thus, for exam‐
151       ple, on a system where sizeof(long) is 4 and the  kernel  HZ  value  is
152       1000,  this  means that timeouts greater than 35.79 minutes are treated
153       as infinity.
154

SEE ALSO

156       epoll_create(2), epoll_ctl(2), epoll(7)
157
158
159
160Linux man-pages 6.05              2023-05-03                     epoll_wait(2)
Impressum