man2/epoll_wait.2

   1 .\"
   2 .\"  epoll by Davide Libenzi ( efficient event notification retrieval )
   3 .\"  Copyright (C) 2003  Davide Libenzi
   4 .\"
   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 License
  16 .\"  along with this program; if not, write to the Free Software
  17 .\"  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18 .\"
  19 .\"  Davide Libenzi <davidel@xmailserver.org>
  20 .\"
  21 .\" 2007-04-30: mtk, Added description of epoll_pwait()
  22 .\"
  23 .TH EPOLL_WAIT 2 2012-08-17 "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 .sp
  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 memory area pointed to by
  44 .I events
  45 will contain the events that will be available for the caller.
  46 Up to
  47 .I maxevents
  48 are returned by
  49 .BR epoll_wait ().
  50 The
  51 .I maxevents
  52 argument must be greater than zero.
  53
  54 The
  55 .I timeout
  56 argument specifies the minimum number of milliseconds that
  57 .BR epoll_wait ()
  58 will block.
  59 (This interval will be rounded up to the system clock granularity,
  60 and kernel scheduling delays mean that the blocking interval
  61 may overrun by a small amount.)
  62 Specifying a
  63 .I timeout
  64 of \-1 causes
  65 .BR epoll_wait ()
  66 to block indefinitely, while specifying a
  67 .I timeout
  68 equal to zero cause
  69 .BR epoll_wait ()
  70 to return immediately, even if no events are available.
  71
  72 The
  73 .I struct epoll_event
  74 is defined as :
  75 .sp
  76 .in +4n
  77 .nf
  78 typedef union epoll_data {
  79     void    *ptr;
  80     int      fd;
  81     uint32_t u32;
  82     uint64_t u64;
  83 } epoll_data_t;
  84
  85 struct epoll_event {
  86     uint32_t     events;    /* Epoll events */
  87     epoll_data_t data;      /* User data variable */
  88 };
  89 .fi
  90 .in
  91
  92 The
  93 .I data
  94 of each returned structure will contain the same data the user set with an
  95 .BR epoll_ctl (2)
  96 .RB ( EPOLL_CTL_ADD , EPOLL_CTL_MOD )
  97 while the
  98 .I events
  99 member will contain the returned event bit field.
 100 .SS epoll_pwait()
 101 The relationship between
 102 .BR epoll_wait ()
 103 and
 104 .BR epoll_pwait ()
 105 is analogous to the relationship between
 106 .BR select (2)
 107 and
 108 .BR pselect (2):
 109 like
 110 .BR pselect (2),
 111 .BR epoll_pwait ()
 112 allows an application to safely wait until either a file descriptor
 113 becomes ready or until a signal is caught.
 114
 115 The following
 116 .BR epoll_pwait ()
 117 call:
 118 .nf
 119
 120     ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 121
 122 .fi
 123 is equivalent to
 124 .I atomically
 125 executing the following calls:
 126 .nf
 127
 128     sigset_t origmask;
 129
 130     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 131     ready = epoll_wait(epfd, &events, maxevents, timeout);
 132     sigprocmask(SIG_SETMASK, &origmask, NULL);
 133 .fi
 134 .PP
 135 The
 136 .I sigmask
 137 argument may be specified as NULL, in which case
 138 .BR epoll_pwait ()
 139 is equivalent to
 140 .BR epoll_wait ().
 141 .SH RETURN VALUE
 142 When successful,
 143 .BR epoll_wait ()
 144 returns the number of file descriptors ready for the requested I/O, or zero
 145 if no file descriptor became ready during the requested
 146 .I timeout
 147 milliseconds.
 148 When an error occurs,
 149 .BR epoll_wait ()
 150 returns \-1 and
 151 .I errno
 152 is set appropriately.
 153 .SH ERRORS
 154 .TP
 155 .B EBADF
 156 .I epfd
 157 is not a valid file descriptor.
 158 .TP
 159 .B EFAULT
 160 The memory area pointed to by
 161 .I events
 162 is not accessible with write permissions.
 163 .TP
 164 .B EINTR
 165 The call was interrupted by a signal handler before either any of the
 166 requested events occurred or the
 167 .I timeout
 168 expired; see
 169 .BR signal (7).
 170 .TP
 171 .B EINVAL
 172 .I epfd
 173 is not an
 174 .B epoll
 175 file descriptor, or
 176 .I maxevents
 177 is less than or equal to zero.
 178 .SH VERSIONS
 179 .BR epoll_wait ()
 180 was added to the kernel in version 2.6.
 181 .\" To be precise: kernel 2.5.44.
 182 .\" The interface should be finalized by Linux kernel 2.5.66.
 183 Library support is provided in glibc starting with version 2.3.2.
 184
 185 .BR epoll_pwait ()
 186 was added to Linux in kernel 2.6.19.
 187 Library support is provided in glibc starting with version 2.6.
 188 .SH CONFORMING TO
 189 .BR epoll_wait ()
 190 is Linux-specific.
 191 .SH NOTES
 192 While one thread is blocked in a call to
 193 .BR epoll_pwait (),
 194 it is possible for another thread to add a file descriptor to the waited-upon
 195 .B epoll
 196 instance.
 197 If the new file descriptor becomes ready,
 198 it will cause the
 199 .BR epoll_wait ()
 200 call to unblock.
 201
 202 For a discussion of what may happen if a file descriptor in an
 203 .B epoll
 204 instance being monitored by
 205 .BR epoll_wait ()
 206 is closed in another thread, see
 207 .BR select (2).
 208 .SH BUGS
 209 In kernels before 2.6.37, a
 210 .I timeout
 211 value larger than approximately
 212 .I LONG_MAX / HZ
 213 milliseconds is treated as \-1 (i.e., infinity).
 214 Thus, for example, on a system where the
 215 .I sizeof(long)
 216 is 4 and the kernel
 217 .I HZ
 218 value is 1000,
 219 this means that timeouts greater than 35.79 minutes are treated as infinity.
 220 .SH SEE ALSO
 221 .BR epoll_create (2),
 222 .BR epoll_ctl (2),
 223 .BR epoll (7)