man2/epoll_wait.2

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