original/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 2014-08-19 "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 The call will block until either:
  59 .IP * 3
  60 a file descriptor delivers an event;
  61 .IP *
  62 the call is interrupted by a signal handler; or
  63 .IP *
  64 the timeout expires.
  65 .PP
  66 Note that the
  67 .I timeout
  68 interval will be rounded up to the system clock granularity,
  69 and kernel scheduling delays mean that the blocking interval
  70 may overrun by a small amount.
  71 Specifying a
  72 .I timeout
  73 of \-1 causes
  74 .BR epoll_wait ()
  75 to block indefinitely, while specifying a
  76 .I timeout
  77 equal to zero cause
  78 .BR epoll_wait ()
  79 to return immediately, even if no events are available.
  80
  81 The
  82 .I struct epoll_event
  83 is defined as:
  84 .sp
  85 .in +4n
  86 .nf
  87 typedef union epoll_data {
  88     void    *ptr;
  89     int      fd;
  90     uint32_t u32;
  91     uint64_t u64;
  92 } epoll_data_t;
  93
  94 struct epoll_event {
  95     uint32_t     events;    /* Epoll events */
  96     epoll_data_t data;      /* User data variable */
  97 };
  98 .fi
  99 .in
 100
 101 The
 102 .I data
 103 of each returned structure will contain the same data the user set with an
 104 .BR epoll_ctl (2)
 105 .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
 106 while the
 107 .I events
 108 member will contain the returned event bit field.
 109 .SS epoll_pwait()
 110 The relationship between
 111 .BR epoll_wait ()
 112 and
 113 .BR epoll_pwait ()
 114 is analogous to the relationship between
 115 .BR select (2)
 116 and
 117 .BR pselect (2):
 118 like
 119 .BR pselect (2),
 120 .BR epoll_pwait ()
 121 allows an application to safely wait until either a file descriptor
 122 becomes ready or until a signal is caught.
 123
 124 The following
 125 .BR epoll_pwait ()
 126 call:
 127 .nf
 128
 129     ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 130
 131 .fi
 132 is equivalent to
 133 .I atomically
 134 executing the following calls:
 135 .nf
 136
 137     sigset_t origmask;
 138
 139     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 140     ready = epoll_wait(epfd, &events, maxevents, timeout);
 141     sigprocmask(SIG_SETMASK, &origmask, NULL);
 142 .fi
 143 .PP
 144 The
 145 .I sigmask
 146 argument may be specified as NULL, in which case
 147 .BR epoll_pwait ()
 148 is equivalent to
 149 .BR epoll_wait ().
 150 .SH RETURN VALUE
 151 When successful,
 152 .BR epoll_wait ()
 153 returns the number of file descriptors ready for the requested I/O, or zero
 154 if no file descriptor became ready during the requested
 155 .I timeout
 156 milliseconds.
 157 When an error occurs,
 158 .BR epoll_wait ()
 159 returns \-1 and
 160 .I errno
 161 is set appropriately.
 162 .SH ERRORS
 163 .TP
 164 .B EBADF
 165 .I epfd
 166 is not a valid file descriptor.
 167 .TP
 168 .B EFAULT
 169 The memory area pointed to by
 170 .I events
 171 is not accessible with write permissions.
 172 .TP
 173 .B EINTR
 174 The call was interrupted by a signal handler before either (1) any of the
 175 requested events occurred or (2) the
 176 .I timeout
 177 expired; see
 178 .BR signal (7).
 179 .TP
 180 .B EINVAL
 181 .I epfd
 182 is not an
 183 .B epoll
 184 file descriptor, or
 185 .I maxevents
 186 is less than or equal to zero.
 187 .SH VERSIONS
 188 .BR epoll_wait ()
 189 was added to the kernel in version 2.6.
 190 .\" To be precise: kernel 2.5.44.
 191 .\" The interface should be finalized by Linux kernel 2.5.66.
 192 Library support is provided in glibc starting with version 2.3.2.
 193
 194 .BR epoll_pwait ()
 195 was added to Linux in kernel 2.6.19.
 196 Library support is provided in glibc starting with version 2.6.
 197 .SH CONFORMING TO
 198 .BR epoll_wait ()
 199 is Linux-specific.
 200 .SH NOTES
 201 While one thread is blocked in a call to
 202 .BR epoll_pwait (),
 203 it is possible for another thread to add a file descriptor to the waited-upon
 204 .B epoll
 205 instance.
 206 If the new file descriptor becomes ready,
 207 it will cause the
 208 .BR epoll_wait ()
 209 call to unblock.
 210
 211 For a discussion of what may happen if a file descriptor in an
 212 .B epoll
 213 instance being monitored by
 214 .BR epoll_wait ()
 215 is closed in another thread, see
 216 .BR select (2).
 217 .SH BUGS
 218 In kernels before 2.6.37, a
 219 .I timeout
 220 value larger than approximately
 221 .I LONG_MAX / HZ
 222 milliseconds is treated as \-1 (i.e., infinity).
 223 Thus, for example, on a system where the
 224 .I sizeof(long)
 225 is 4 and the kernel
 226 .I HZ
 227 value is 1000,
 228 this means that timeouts greater than 35.79 minutes are treated as infinity.
 229 .SS C library/kernel ABI differences
 230 The raw
 231 .BR epoll_pwait ()
 232 system call has a sixth argument,
 233 .IR "size_t sigsetsize" ,
 234 which specifies the size in bytes of the
 235 .IR sigmask
 236 argument.
 237 The glibc
 238 .BR epoll_pwait ()
 239 wrapper function specifies this argument as a fixed value
 240 (equal to
 241 .IR sizeof(sigset_t) ).
 242 .SH SEE ALSO
 243 .BR epoll_create (2),
 244 .BR epoll_ctl (2),
 245 .BR epoll (7)
 246 .SH COLOPHON
 247 This page is part of release 3.79 of the Linux
 248 .I man-pages
 249 project.
 250 A description of the project,
 251 information about reporting bugs,
 252 and the latest version of this page,
 253 can be found at
 254 \%http://www.kernel.org/doc/man\-pages/.