draft/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 .\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO
  24 .\"         all rights reserved.
  25 .\" Translated Wed Jun 16 03:05:40 JST 2004
  26 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  27 .\" Updated & Modified Tue Apr 19 07:05:42 JST 2005 by Yuichi SATO
  28 .\" Updated 2007-06-02, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.51
  29 .\" Updated 2009-02-23, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.18
  30 .\"
  31 .TH EPOLL_WAIT 2 2009-01-17 "Linux" "Linux Programmer's Manual"
  32 .\"O .SH NAME
  33 .SH Ì¾Á°
  34 .\"O epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
  35 epoll_wait, epoll_pwait \- epoll ¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿¤Î I/O ¥¤¥Ù¥ó¥È¤òÂÔ¤Ä
  36 .\"O .SH SYNOPSIS
  37 .SH ½ñ¼°
  38 .nf
  39 .B #include <sys/epoll.h>
  40 .sp
  41 .BI "int epoll_wait(int " epfd ", struct epoll_event *" events ,
  42 .BI "               int " maxevents ", int " timeout );
  43 .BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
  44 .BI "               int " maxevents ", int " timeout ,
  45 .BI "               const sigset_t *" sigmask );
  46 .fi
  47 .\"O .SH DESCRIPTION
  48 .SH ÀâÌÀ
  49 .\"O The
  50 .\"O .BR epoll_wait ()
  51 .\"O system call waits for events on the
  52 .\"O .B epoll
  53 .\"O instance referred to by the file descriptor
  54 .\"O .IR epfd .
  55 .\"O The memory area pointed to by
  56 .\"O .I events
  57 .\"O will contain the events that will be available for the caller.
  58 .BR epoll_wait ()
  59 ¥·¥¹¥Æ¥à¥³¡¼¥ë¤Ï¡¢
  60 ¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿
  61 .I epfd
  62 ¤Ç»²¾È¤µ¤ì¤ë
  63 .B epoll
  64 ¥¤¥ó¥¹¥¿¥ó¥¹¤ËÂÐ¤¹¤ë¥¤¥Ù¥ó¥È¤òÂÔ¤Ä¡£
  65 .I events
  66 ¤¬»Ø¤¹¥á¥â¥êÎÎ°è¤Ë¤Ï¡¢¸Æ¤Ó½Ð¤·Â¦¤¬ÍøÍÑ²ÄÇ½¤Ê¥¤¥Ù¥ó¥È¤¬³ÊÇ¼¤µ¤ì¤ë¡£
  67 .\"O Up to
  68 .\"O .I maxevents
  69 .\"O are returned by
  70 .\"O .BR epoll_wait ().
  71 ºÇÂç
  72 .I maxevents
  73 ¸Ä¤Î¥¤¥Ù¥ó¥È¤¬
  74 .BR epoll_wait ()
  75 ¤Ë¤è¤Ã¤ÆÊÖ¤µ¤ì¤ë¡£
  76 .\"O The
  77 .\"O .I maxevents
  78 .\"O argument must be greater than zero.
  79 .I maxevents
  80 °ú¤¿ô¤Ï 0 ¤è¤êÂç¤¤¯¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
  81
  82 .\"O The call waits for a maximum time of
  83 .\"O .I timeout
  84 .\"O milliseconds.
  85 .\"O Specifying a
  86 .\"O .I timeout
  87 .\"O of \-1 makes
  88 .\"O .BR epoll_wait ()
  89 .\"O wait indefinitely, while specifying a
  90 .\"O .I timeout
  91 .\"O equal to zero makes
  92 .\"O .BR epoll_wait ()
  93 .\"O to return immediately even if no events are available
  94 .\"O (return code equal to zero).
  95 ºÇÂç¤Ç
  96 .I timeout
  97 ¥ß¥êÉÃ´Ö¥¤¥Ù¥ó¥È¤òÂÔ¤Ä¡£
  98 .I timeout
  99 ¤ò \-1 ¤Ë»ØÄê¤¹¤ë¤È¡¢
 100 .BR epoll_wait ()
 101 ¤ÏÌµ¸Â¤ËÂÔ¤Ä¡£
 102 ¤Þ¤¿
 103 .I timeout
 104 ¤ò 0 ¤Ë»ØÄê¤¹¤ë¤È¡¢
 105 .BR epoll_wait ()
 106 ¤Ï¥¤¥Ù¥ó¥È¤¬ÍøÍÑ²ÄÇ½¤Ç¤Ê¤¯¤Æ¤â¡¢¤¹¤°¤ËÊÖ¤ë (ÊÖ¤êÃÍ¤Ï 0 ¤Ç¤¢¤ë)¡£
 107
 108 .\"O The
 109 .\"O .I struct epoll_event
 110 .\"O is defined as :
 111 .I struct epoll_event
 112 ¤Ï°Ê²¼¤Î¤è¤¦¤ËÄêµÁ¤µ¤ì¤ë:
 113 .sp
 114 .in +4n
 115 .nf
 116 typedef union epoll_data {
 117     void    *ptr;
 118     int      fd;
 119     uint32_t u32;
 120     uint64_t u64;
 121 } epoll_data_t;
 122
 123 .\"O struct epoll_event {
 124 .\"O     uint32_t     events;    /* Epoll events */
 125 .\"O     epoll_data_t data;      /* User data variable */
 126 .\"O };
 127 struct epoll_event {
 128     uint32_t     events;    /* epoll ¥¤¥Ù¥ó¥È */
 129     epoll_data_t data;      /* ¥æ¡¼¥¶¥Ç¡¼¥¿ÊÑ¿ô */
 130 };
 131 .fi
 132 .in
 133
 134 .\"O The
 135 .\"O .I data
 136 .\"O of each returned structure will contain the same data the user set with an
 137 .\"O .BR epoll_ctl (2)
 138 .\"O .RB ( EPOLL_CTL_ADD , EPOLL_CTL_MOD )
 139 .\"O while the
 140 .\"O .I events
 141 .\"O member will contain the returned event bit field.
 142 ÊÖ¤µ¤ì¤ë¹½Â¤ÂÎ¤Î
 143 .I data
 144 ¥á¥ó¥Ð¤Ë¤Ï¡¢¥æ¡¼¥¶¤¬
 145 .BR epoll_ctl (2)
 146 .RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
 147 ¤Ç»ØÄê¤·¤¿¥Ç¡¼¥¿¤¬³ÊÇ¼¤µ¤ì¤ë¡£
 148 °ìÊý¡¢
 149 .I events
 150 ¥á¥ó¥Ð¤Ë¤ÏÊÖ¤µ¤ì¤¿ÍøÍÑ²ÄÇ½¤Ê¥¤¥Ù¥ó¥È¤Î¥Ó¥Ã¥È¥Õ¥£¡¼¥ë¥É¤¬³ÊÇ¼¤µ¤ì¤ë¡£
 151 .SS epoll_pwait()
 152 .\"O The relationship between
 153 .\"O .BR epoll_wait ()
 154 .\"O and
 155 .\"O .BR epoll_pwait ()
 156 .\"O is analogous to the relationship between
 157 .\"O .BR select (2)
 158 .\"O and
 159 .\"O .BR pselect (2):
 160 .\"O like
 161 .\"O .BR pselect (2),
 162 .\"O .BR epoll_pwait ()
 163 .\"O allows an application to safely wait until either a file descriptor
 164 .\"O becomes ready or until a signal is caught.
 165 .BR epoll_wait ()
 166 ¤È
 167 .BR epoll_pwait ()
 168 ¤Î´Ø·¸¤Ï¡¢
 169 .BR select (2)
 170 ¤È
 171 .BR pselect (2)
 172 ¤Î´Ø·¸¤ÈÆ±ÍÍ¤Ç¤¢¤ë¡£
 173 .BR pselect (2)
 174 Æ±ÍÍ¡¢
 175 .BR epoll_pwait ()
 176 ¤ò»È¤¦¤È¡¢¥¢¥×¥ê¥±¡¼¥·¥ç¥ó¤Ï¡¢¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿¤¬½àÈ÷¤Ç¤¤¿¾õÂÖ¤Ë¤Ê¤ë¤«¡¢
 177 ¥·¥°¥Ê¥ë¤¬ÊáÂª¤µ¤ì¤ë¤Þ¤Ç¡¢°ÂÁ´¤ËÂÔ¤Ä¤³¤È¤¬¤Ç¤¤ë¡£
 178
 179 .\"O The following
 180 .\"O .BR epoll_pwait ()
 181 .\"O call:
 182 °Ê²¼¤Î
 183 .BR epoll_pwait ()
 184 ¤Î¸Æ¤Ó½Ð¤·¤Ï¡¢
 185 .nf
 186
 187     ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 188
 189 .fi
 190 .\"O is equivalent to
 191 .\"O .I atomically
 192 .\"O executing the following calls:
 193 ¼¡¤Î¸Æ¤Ó½Ð¤·¤ò
 194 .I atomic
 195 ¤Ë¼Â¹Ô¤¹¤ë¤Î¤ÈÅù²Á¤Ç¤¢¤ë¡£
 196 .nf
 197
 198     sigset_t origmask;
 199
 200     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 201     ready = epoll_wait(epfd, &events, maxevents, timeout);
 202     sigprocmask(SIG_SETMASK, &origmask, NULL);
 203 .fi
 204 .PP
 205 .\"O The
 206 .\"O .I sigmask
 207 .\"O argument may be specified as NULL, in which case
 208 .\"O .BR epoll_pwait ()
 209 .\"O is equivalent to
 210 .\"O .BR epoll_wait ().
 211 .I sigmask
 212 °ú¤¿ô¤Ë¤Ï NULL ¤ò»ØÄê¤·¤Æ¤â¤è¤¤¡£
 213 ¤½¤Î¾ì¹ç¤Ë¤Ï¡¢
 214 .BR epoll_pwait ()
 215 ¤Ï
 216 .BR epoll_wait ()
 217 ¤ÈÅù²Á¤È¤Ê¤ë¡£
 218 .\"O .SH "RETURN VALUE"
 219 .SH ÊÖ¤êÃÍ
 220 .\"O When successful,
 221 .\"O .BR epoll_wait ()
 222 .\"O returns the number of file descriptors ready for the requested I/O, or zero
 223 .\"O if no file descriptor became ready during the requested
 224 .\"O .I timeout
 225 .\"O milliseconds.
 226 .\"O When an error occurs,
 227 .\"O .BR epoll_wait ()
 228 .\"O returns \-1 and
 229 .\"O .I errno
 230 .\"O is set appropriately.
 231 À®¸ù¤·¤¿¾ì¹ç¡¢
 232 .BR epoll_wait ()
 233 ¤ÏÍ×µá¤µ¤ì¤¿ I/O ¤ËÂÐ¤·¤Æ½àÈ÷¤¬¤Ç¤¤Æ¤¤¤ë¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿¤Î¿ô¤òÊÖ¤¹¡£
 234 ¤Þ¤¿Í×µá¤µ¤ì¤¿
 235 .I timeout
 236 ¥ß¥êÉÃ¤Î´Ö¤Ë¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿¤¬½àÈ÷¤Ç¤¤Ê¤¤¾ì¹ç¤Ï¡¢0 ¤òÊÖ¤¹¡£
 237 ¥¨¥é¡¼¤¬µ¯¤³¤Ã¤¿¾ì¹ç¡¢
 238 .BR epoll_wait ()
 239 ¤Ï \-1 ¤òÊÖ¤·¡¢
 240 .I errno
 241 ¤òÅ¬ÀÚ¤ËÀßÄê¤¹¤ë¡£
 242 .\"O .SH ERRORS
 243 .SH ¥¨¥é¡¼
 244 .TP
 245 .B EBADF
 246 .\"O .I epfd
 247 .\"O is not a valid file descriptor.
 248 .I epfd
 249 ¤¬Í¸ú¤Ê¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿¤Ç¤Ê¤¤¡£
 250 .TP
 251 .B EFAULT
 252 .\"O The memory area pointed to by
 253 .\"O .I events
 254 .\"O is not accessible with write permissions.
 255 .I events
 256 ¤Ç»Ø¤µ¤ì¤ë¥á¥â¥êÎÎ°è¤Ë½ñ¤¹þ¤ß¸¢¸Â¤Ç¥¢¥¯¥»¥¹¤Ç¤¤Ê¤¤¡£
 257 .TP
 258 .B EINTR
 259 .\"O The call was interrupted by a signal handler before any of the
 260 .\"O requested events occurred or the
 261 .\"O .I timeout
 262 .\"O expired; see
 263 .\"O .BR signal (7).
 264 Í×µá¤µ¤ì¤¿¤É¤Î¥¤¥Ù¥ó¥È¤âÈ¯À¸¤»¤º¡¢¤«¤Ä
 265 .I timeout
 266 ¤Î´ü¸Â¤¬ÀÚ¤ì¤ëÁ°¤Ë¡¢¥·¥¹¥Æ¥à¥³¡¼¥ë¤¬¥·¥°¥Ê¥ë¥Ï¥ó¥É¥é¤Ë¤è¤Ã¤Æ³ä¤ê¹þ¤Þ¤ì¤¿¡£
 267 .BR signal (7)
 268 »²¾È¡£
 269 .TP
 270 .B EINVAL
 271 .\"O .I epfd
 272 .\"O is not an
 273 .\"O .B epoll
 274 .\"O file descriptor, or
 275 .\"O .I maxevents
 276 .\"O is less than or equal to zero.
 277 .I epfd
 278 ¤¬
 279 .B epoll
 280 ¥Õ¥¡¥¤¥ë¥Ç¥£¥¹¥¯¥ê¥×¥¿¤Ç¤Ê¤¤¡£
 281 ¤Þ¤¿¤Ï
 282 .I maxevents
 283 ¤¬ 0 °Ê²¼¤Ç¤¢¤ë¡£
 284 .\"O .SH VERSIONS
 285 .SH ¥Ð¡¼¥¸¥ç¥ó
 286 .\"O .BR epoll_pwait ()
 287 .\"O was added to Linux in kernel 2.6.19.
 288 .BR epoll_pwait ()
 289 ¤Ï¥«¡¼¥Í¥ë 2.6.19 ¤Ç Linux ¤ËÄÉ²Ã¤µ¤ì¤¿¡£
 290
 291 .\"O Glibc support for
 292 .\"O .BR epoll_pwait ()
 293 .\"O is provided starting with glibc 2.6.
 294 .BR epoll_pwait ()
 295 ¤Î glibc ¤Ç¤Î¥µ¥Ý¡¼¥È¤Ï glibc 2.6 °Ê¹ß¤ÇÄó¶¡¤µ¤ì¤Æ¤¤¤ë¡£
 296 .\"O .SH CONFORMING TO
 297 .SH ½àµò
 298 .\"O .BR epoll_wait ()
 299 .\"O is Linux-specific, and was introduced in kernel 2.5.44.
 300 .BR epoll_wait ()
 301 ¤Ï Linux ÆÈ¼«¤Ç¤¢¤ê¡¢¥«¡¼¥Í¥ë 2.5.44 ¤ÇÆ³Æþ¤µ¤ì¤¿¡£
 302 .\"O .\" The interface should be finalized by Linux kernel 2.5.66.
 303 .\" ¥¤¥ó¥¿¥Õ¥§¡¼¥¹¤Ï Linux ¥«¡¼¥Í¥ë 2.5.66 ¤Ç³ÎÄê¤µ¤ì¤ë¤Ù¤¤Ç¤¢¤ë¡£
 304 .\"O .SH "SEE ALSO"
 305 .SH ´ØÏ¢¹àÌÜ
 306 .BR epoll_create (2),
 307 .BR epoll_ctl (2),
 308 .BR epoll (7)