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 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   6 .\"  This program is free software; you can redistribute it and/or modify
   7 .\"  it under the terms of the GNU General Public License as published by
   8 .\"  the Free Software Foundation; either version 2 of the License, or
   9 .\"  (at your option) any later version.
  10 .\"
  11 .\"  This program is distributed in the hope that it will be useful,
  12 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14 .\"  GNU General Public License for more details.
  15 .\"
  16 .\" You should have received a copy of the GNU General Public
  17 .\" License along with this manual; if not, see
  18 .\" <http://www.gnu.org/licenses/>.
  19 .\" %%%LICENSE_END
  20 .\"
  21 .\" 2007-04-30: mtk, Added description of epoll_pwait()
  22 .\"
  23 .TH EPOLL_WAIT 2 2020-04-11 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
  26 .SH SYNOPSIS
  27 .nf
  28 .B #include <sys/epoll.h>
  29 .PP
  30 .BI "int epoll_wait(int " epfd ", struct epoll_event *" events ,
  31 .BI "               int " maxevents ", int " timeout );
  32 .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
  33 .BI "               int " maxevents ", int " timeout ,
  34 .BI "               const sigset_t *" sigmask );
  35 .fi
  36 .SH DESCRIPTION
  37 The
  38 .BR epoll_wait ()
  39 system call waits for events on the
  40 .BR epoll (7)
  41 instance referred to by the file descriptor
  42 .IR epfd .
  43 The buffer pointed to by
  44 .I events
  45 is used to return information from the ready list
  46 about file descriptors in the interest list that
  47 have some events available.
  48 Up to
  49 .I maxevents
  50 are returned by
  51 .BR epoll_wait ().
  52 The
  53 .I maxevents
  54 argument must be greater than zero.
  55 .PP
  56 The
  57 .I timeout
  58 argument specifies the number of milliseconds that
  59 .BR epoll_wait ()
  60 will block.
  61 Time is measured against the
  62 .B CLOCK_MONOTONIC
  63 clock.
  64 .PP
  65 A call to
  66 .BR epoll_wait ()
  67 will block until either:
  68 .IP \(bu 2
  69 a file descriptor delivers an event;
  70 .IP \(bu
  71 the call is interrupted by a signal handler; or
  72 .IP \(bu
  73 the timeout expires.
  74 .PP
  75 Note that the
  76 .I timeout
  77 interval will be rounded up to the system clock granularity,
  78 and kernel scheduling delays mean that the blocking interval
  79 may overrun by a small amount.
  80 Specifying a
  81 .I timeout
  82 of \-1 causes
  83 .BR epoll_wait ()
  84 to block indefinitely, while specifying a
  85 .I timeout
  86 equal to zero cause
  87 .BR epoll_wait ()
  88 to return immediately, even if no events are available.
  89 .PP
  90 The
  91 .I struct epoll_event
  92 is defined as:
  93 .PP
  94 .in +4n
  95 .EX
  96 typedef union epoll_data {
  97     void    *ptr;
  98     int      fd;
  99     uint32_t u32;
 100     uint64_t u64;
 101 } epoll_data_t;
 102
 103 struct epoll_event {
 104     uint32_t     events;    /* Epoll events */
 105     epoll_data_t data;      /* User data variable */
 106 };
 107 .EE
 108 .in
 109 .PP
 110 The
 111 .I data
 112 field of each returned
 113 .I epoll_event
 114 structure contains the same data as was specified
 115 in the most recent call to
 116 .BR epoll_ctl (2)
 117 .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
 118 for the corresponding open file descriptor.
 119 .PP
 120 The
 121 .I events
 122 field is a bit mask that indicates the events that have occurred for the
 123 corresponding open file description.
 124 See
 125 .BR epoll_ctl (2)
 126 for a list of the bits that may appear in this mask.
 127 .\"
 128 .SS epoll_pwait()
 129 The relationship between
 130 .BR epoll_wait ()
 131 and
 132 .BR epoll_pwait ()
 133 is analogous to the relationship between
 134 .BR select (2)
 135 and
 136 .BR pselect (2):
 137 like
 138 .BR pselect (2),
 139 .BR epoll_pwait ()
 140 allows an application to safely wait until either a file descriptor
 141 becomes ready or until a signal is caught.
 142 .PP
 143 The following
 144 .BR epoll_pwait ()
 145 call:
 146 .PP
 147 .in +4n
 148 .EX
 149 ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 150 .EE
 151 .in
 152 .PP
 153 is equivalent to
 154 .I atomically
 155 executing the following calls:
 156 .PP
 157 .in +4n
 158 .EX
 159 sigset_t origmask;
 160
 161 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
 162 ready = epoll_wait(epfd, &events, maxevents, timeout);
 163 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
 164 .EE
 165 .in
 166 .PP
 167 The
 168 .I sigmask
 169 argument may be specified as NULL, in which case
 170 .BR epoll_pwait ()
 171 is equivalent to
 172 .BR epoll_wait ().
 173 .SH RETURN VALUE
 174 When successful,
 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 When an error occurs,
 181 .BR epoll_wait ()
 182 returns \-1 and
 183 .I errno
 184 is set appropriately.
 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 VERSIONS
 211 .BR epoll_wait ()
 212 was added to the kernel in version 2.6.
 213 .\" To be precise: kernel 2.5.44.
 214 .\" The interface should be finalized by Linux kernel 2.5.66.
 215 Library support is provided in glibc starting with version 2.3.2.
 216 .PP
 217 .BR epoll_pwait ()
 218 was added to Linux in kernel 2.6.19.
 219 Library support is provided in glibc starting with version 2.6.
 220 .SH CONFORMING TO
 221 .BR epoll_wait ()
 222 is Linux-specific.
 223 .SH NOTES
 224 While one thread is blocked in a call to
 225 .BR epoll_wait (),
 226 it is possible for another thread to add a file descriptor to the waited-upon
 227 .B epoll
 228 instance.
 229 If the new file descriptor becomes ready,
 230 it will cause the
 231 .BR epoll_wait ()
 232 call to unblock.
 233 .PP
 234 If more than
 235 .I maxevents
 236 file descriptors are ready when
 237 .BR epoll_wait ()
 238 is called, then successive
 239 .BR epoll_wait ()
 240 calls will round robin through the set of ready file descriptors.
 241 This behavior helps avoid starvation scenarios,
 242 where a process fails to notice that additional file descriptors
 243 are ready because it focuses on a set of file descriptors that
 244 are already known to be ready.
 245 .PP
 246 Note that it is possible to call
 247 .BR epoll_wait ()
 248 on an
 249 .B epoll
 250 instance whose interest list is currently empty
 251 (or whose interest list becomes empty because file descriptors are closed
 252 or removed from the interest in another thread).
 253 The call will block until some file descriptor is later added to the
 254 interest list (in another thread) and that file descriptor becomes ready.
 255 .SH BUGS
 256 In kernels before 2.6.37, a
 257 .I timeout
 258 value larger than approximately
 259 .I LONG_MAX / HZ
 260 milliseconds is treated as \-1 (i.e., infinity).
 261 Thus, for example, on a system where
 262 .I sizeof(long)
 263 is 4 and the kernel
 264 .I HZ
 265 value is 1000,
 266 this means that timeouts greater than 35.79 minutes are treated as infinity.
 267 .SS C library/kernel differences
 268 The raw
 269 .BR epoll_pwait ()
 270 system call has a sixth argument,
 271 .IR "size_t sigsetsize" ,
 272 which specifies the size in bytes of the
 273 .IR sigmask
 274 argument.
 275 The glibc
 276 .BR epoll_pwait ()
 277 wrapper function specifies this argument as a fixed value
 278 (equal to
 279 .IR sizeof(sigset_t) ).
 280 .SH SEE ALSO
 281 .BR epoll_create (2),
 282 .BR epoll_ctl (2),
 283 .BR epoll (7)