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 2016-10-08 "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 .sp
  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
  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
  84 The
  85 .I struct epoll_event
  86 is defined as:
  87 .sp
  88 .in +4n
  89 .nf
  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 .fi
 102 .in
 103
 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
 129 The following
 130 .BR epoll_pwait ()
 131 call:
 132 .nf
 133
 134     ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 135
 136 .fi
 137 is equivalent to
 138 .I atomically
 139 executing the following calls:
 140 .nf
 141
 142     sigset_t origmask;
 143
 144     pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
 145     ready = epoll_wait(epfd, &events, maxevents, timeout);
 146     pthread_sigmask(SIG_SETMASK, &origmask, NULL);
 147 .fi
 148 .PP
 149 The
 150 .I sigmask
 151 argument may be specified as NULL, in which case
 152 .BR epoll_pwait ()
 153 is equivalent to
 154 .BR epoll_wait ().
 155 .SH RETURN VALUE
 156 When successful,
 157 .BR epoll_wait ()
 158 returns the number of file descriptors ready for the requested I/O, or zero
 159 if no file descriptor became ready during the requested
 160 .I timeout
 161 milliseconds.
 162 When an error occurs,
 163 .BR epoll_wait ()
 164 returns \-1 and
 165 .I errno
 166 is set appropriately.
 167 .SH ERRORS
 168 .TP
 169 .B EBADF
 170 .I epfd
 171 is not a valid file descriptor.
 172 .TP
 173 .B EFAULT
 174 The memory area pointed to by
 175 .I events
 176 is not accessible with write permissions.
 177 .TP
 178 .B EINTR
 179 The call was interrupted by a signal handler before either (1) any of the
 180 requested events occurred or (2) the
 181 .I timeout
 182 expired; see
 183 .BR signal (7).
 184 .TP
 185 .B EINVAL
 186 .I epfd
 187 is not an
 188 .B epoll
 189 file descriptor, or
 190 .I maxevents
 191 is less than or equal to zero.
 192 .SH VERSIONS
 193 .BR epoll_wait ()
 194 was added to the kernel in version 2.6.
 195 .\" To be precise: kernel 2.5.44.
 196 .\" The interface should be finalized by Linux kernel 2.5.66.
 197 Library support is provided in glibc starting with version 2.3.2.
 198
 199 .BR epoll_pwait ()
 200 was added to Linux in kernel 2.6.19.
 201 Library support is provided in glibc starting with version 2.6.
 202 .SH CONFORMING TO
 203 .BR epoll_wait ()
 204 is Linux-specific.
 205 .SH NOTES
 206 While one thread is blocked in a call to
 207 .BR epoll_pwait (),
 208 it is possible for another thread to add a file descriptor to the waited-upon
 209 .B epoll
 210 instance.
 211 If the new file descriptor becomes ready,
 212 it will cause the
 213 .BR epoll_wait ()
 214 call to unblock.
 215
 216 For a discussion of what may happen if a file descriptor in an
 217 .B epoll
 218 instance being monitored by
 219 .BR epoll_wait ()
 220 is closed in another thread, see
 221 .BR select (2).
 222 .SH BUGS
 223 In kernels before 2.6.37, a
 224 .I timeout
 225 value larger than approximately
 226 .I LONG_MAX / HZ
 227 milliseconds is treated as \-1 (i.e., infinity).
 228 Thus, for example, on a system where the
 229 .I sizeof(long)
 230 is 4 and the kernel
 231 .I HZ
 232 value is 1000,
 233 this means that timeouts greater than 35.79 minutes are treated as infinity.
 234 .SS C library/kernel differences
 235 The raw
 236 .BR epoll_pwait ()
 237 system call has a sixth argument,
 238 .IR "size_t sigsetsize" ,
 239 which specifies the size in bytes of the
 240 .IR sigmask
 241 argument.
 242 The glibc
 243 .BR epoll_pwait ()
 244 wrapper function specifies this argument as a fixed value
 245 (equal to
 246 .IR sizeof(sigset_t) ).
 247 .SH SEE ALSO
 248 .BR epoll_create (2),
 249 .BR epoll_ctl (2),
 250 .BR epoll (7)