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