man2/epoll_wait.2

   1 .\"  Copyright (C) 2003  Davide Libenzi
   2 .\"  Davide Libenzi <davidel@xmailserver.org>
   3 .\" and Copyright 2007, 2012, 2014, 2018 Michael Kerrisk <tk.manpages@gmail.com>
   4 .\"
   5 .\" SPDX-License-Identifier: GPL-2.0-or-later
   6 .\"
   7 .\" 2007-04-30: mtk, Added description of epoll_pwait()
   8 .\"
   9 .TH epoll_wait 2 (date) "Linux man-pages (unreleased)"
  10 .SH NAME
  11 epoll_wait, epoll_pwait, epoll_pwait2 \-
  12 wait for an I/O event on an epoll file descriptor
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <sys/epoll.h>
  19 .PP
  20 .BI "int epoll_wait(int " epfd ", struct epoll_event *" events ,
  21 .BI "               int " maxevents ", int " timeout );
  22 .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
  23 .BI "               int " maxevents ", int " timeout ,
  24 .BI "               const sigset_t *_Nullable " sigmask );
  25 .BI "int epoll_pwait2(int " epfd ", struct epoll_event *" events ,
  26 .BI "               int " maxevents ", \
  27 const struct timespec *_Nullable " timeout ,
  28 .BI "               const sigset_t *_Nullable " sigmask );
  29 .fi
  30 .SH DESCRIPTION
  31 The
  32 .BR epoll_wait ()
  33 system call waits for events on the
  34 .BR epoll (7)
  35 instance referred to by the file descriptor
  36 .IR epfd .
  37 The buffer pointed to by
  38 .I events
  39 is used to return information from the ready list
  40 about file descriptors in the interest list that
  41 have some events available.
  42 Up to
  43 .I maxevents
  44 are returned by
  45 .BR epoll_wait ().
  46 The
  47 .I maxevents
  48 argument must be greater than zero.
  49 .PP
  50 The
  51 .I timeout
  52 argument specifies the number of milliseconds that
  53 .BR epoll_wait ()
  54 will block.
  55 Time is measured against the
  56 .B CLOCK_MONOTONIC
  57 clock.
  58 .PP
  59 A call to
  60 .BR epoll_wait ()
  61 will block until either:
  62 .IP \[bu] 3
  63 a file descriptor delivers an event;
  64 .IP \[bu]
  65 the call is interrupted by a signal handler; or
  66 .IP \[bu]
  67 the timeout expires.
  68 .PP
  69 Note that the
  70 .I timeout
  71 interval will be rounded up to the system clock granularity,
  72 and kernel scheduling delays mean that the blocking interval
  73 may overrun by a small amount.
  74 Specifying a
  75 .I timeout
  76 of \-1 causes
  77 .BR epoll_wait ()
  78 to block indefinitely, while specifying a
  79 .I timeout
  80 equal to zero cause
  81 .BR epoll_wait ()
  82 to return immediately, even if no events are available.
  83 .PP
  84 The
  85 .I struct epoll_event
  86 is described in
  87 .BR epoll_event (3type).
  88 .PP
  89 The
  90 .I data
  91 field of each returned
  92 .I epoll_event
  93 structure contains the same data as was specified
  94 in the most recent call to
  95 .BR epoll_ctl (2)
  96 .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
  97 for the corresponding open file descriptor.
  98 .PP
  99 The
 100 .I events
 101 field is a bit mask that indicates the events that have occurred for the
 102 corresponding open file description.
 103 See
 104 .BR epoll_ctl (2)
 105 for a list of the bits that may appear in this mask.
 106 .\"
 107 .SS epoll_pwait()
 108 The relationship between
 109 .BR epoll_wait ()
 110 and
 111 .BR epoll_pwait ()
 112 is analogous to the relationship between
 113 .BR select (2)
 114 and
 115 .BR pselect (2):
 116 like
 117 .BR pselect (2),
 118 .BR epoll_pwait ()
 119 allows an application to safely wait until either a file descriptor
 120 becomes ready or until a signal is caught.
 121 .PP
 122 The following
 123 .BR epoll_pwait ()
 124 call:
 125 .PP
 126 .in +4n
 127 .EX
 128 ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 129 .EE
 130 .in
 131 .PP
 132 is equivalent to
 133 .I atomically
 134 executing the following calls:
 135 .PP
 136 .in +4n
 137 .EX
 138 sigset_t origmask;
 139 \&
 140 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
 141 ready = epoll_wait(epfd, &events, maxevents, timeout);
 142 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
 143 .EE
 144 .in
 145 .PP
 146 The
 147 .I sigmask
 148 argument may be specified as NULL, in which case
 149 .BR epoll_pwait ()
 150 is equivalent to
 151 .BR epoll_wait ().
 152 .\"
 153 .SS epoll_pwait2()
 154 The
 155 .BR epoll_pwait2 ()
 156 system call is equivalent to
 157 .BR epoll_pwait ()
 158 except for the
 159 .I timeout
 160 argument.
 161 It takes an argument of type
 162 .I timespec
 163 to be able to specify nanosecond resolution timeout.
 164 This argument functions the same as in
 165 .BR pselect (2)
 166 and
 167 .BR ppoll (2).
 168 If
 169 .I timeout
 170 is NULL, then
 171 .BR epoll_pwait2 ()
 172 can block indefinitely.
 173 .SH RETURN VALUE
 174 On success,
 175 .BR epoll_wait ()
 176 returns the number of file descriptors ready for the requested I/O, or zero
 177 if no file descriptor became ready during the requested
 178 .I timeout
 179 milliseconds.
 180 On failure,
 181 .BR epoll_wait ()
 182 returns \-1 and
 183 .I errno
 184 is set to indicate the error.
 185 .SH ERRORS
 186 .TP
 187 .B EBADF
 188 .I epfd
 189 is not a valid file descriptor.
 190 .TP
 191 .B EFAULT
 192 The memory area pointed to by
 193 .I events
 194 is not accessible with write permissions.
 195 .TP
 196 .B EINTR
 197 The call was interrupted by a signal handler before either (1) any of the
 198 requested events occurred or (2) the
 199 .I timeout
 200 expired; see
 201 .BR signal (7).
 202 .TP
 203 .B EINVAL
 204 .I epfd
 205 is not an
 206 .B epoll
 207 file descriptor, or
 208 .I maxevents
 209 is less than or equal to zero.
 210 .SH STANDARDS
 211 Linux.
 212 .SH HISTORY
 213 .TP
 214 .BR epoll_wait ()
 215 Linux 2.6,
 216 .\" To be precise: Linux 2.5.44.
 217 .\" The interface should be finalized by Linux 2.5.66.
 218 glibc 2.3.2.
 219 .TP
 220 .BR epoll_pwait ()
 221 Linux 2.6.19,
 222 glibc 2.6.
 223 .TP
 224 .BR epoll_pwait2 ()
 225 Linux 5.11.
 226 .SH NOTES
 227 While one thread is blocked in a call to
 228 .BR epoll_wait (),
 229 it is possible for another thread to add a file descriptor to the waited-upon
 230 .B epoll
 231 instance.
 232 If the new file descriptor becomes ready,
 233 it will cause the
 234 .BR epoll_wait ()
 235 call to unblock.
 236 .PP
 237 If more than
 238 .I maxevents
 239 file descriptors are ready when
 240 .BR epoll_wait ()
 241 is called, then successive
 242 .BR epoll_wait ()
 243 calls will round robin through the set of ready file descriptors.
 244 This behavior helps avoid starvation scenarios,
 245 where a process fails to notice that additional file descriptors
 246 are ready because it focuses on a set of file descriptors that
 247 are already known to be ready.
 248 .PP
 249 Note that it is possible to call
 250 .BR epoll_wait ()
 251 on an
 252 .B epoll
 253 instance whose interest list is currently empty
 254 (or whose interest list becomes empty because file descriptors are closed
 255 or removed from the interest in another thread).
 256 The call will block until some file descriptor is later added to the
 257 interest list (in another thread) and that file descriptor becomes ready.
 258 .SS C library/kernel differences
 259 The raw
 260 .BR epoll_pwait ()
 261 and
 262 .BR epoll_pwait2 ()
 263 system calls have a sixth argument,
 264 .IR "size_t sigsetsize" ,
 265 which specifies the size in bytes of the
 266 .I sigmask
 267 argument.
 268 The glibc
 269 .BR epoll_pwait ()
 270 wrapper function specifies this argument as a fixed value
 271 (equal to
 272 .IR sizeof(sigset_t) ).
 273 .SH BUGS
 274 Before Linux 2.6.37, a
 275 .I timeout
 276 value larger than approximately
 277 .I LONG_MAX / HZ
 278 milliseconds is treated as \-1 (i.e., infinity).
 279 Thus, for example, on a system where
 280 .I sizeof(long)
 281 is 4 and the kernel
 282 .I HZ
 283 value is 1000,
 284 this means that timeouts greater than 35.79 minutes are treated as infinity.
 285 .SH SEE ALSO
 286 .BR epoll_create (2),
 287 .BR epoll_ctl (2),
 288 .BR epoll (7)