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