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 .\"
  22 .TH EPOLL_WAIT 2 "23 October 2002" Linux "Linux Programmer's Manual"
  23 .SH NAME
  24 epoll_wait \- wait for an I/O event on an epoll file descriptor
  25 .SH SYNOPSIS
  26 .B #include <sys/epoll.h>
  27 .sp
  28 .BR "int epoll_wait(int " epfd ", struct epoll_event * " events ", int " maxevents ", int " timeout)
  29 .SH DESCRIPTION
  30 Wait for events on the
  31 .B epoll
  32 file descriptor
  33 .I epfd
  34 for a maximum time of
  35 .I timeout
  36 milliseconds. The memory area pointed to by
  37 .I events
  38 will contain the events that will be available for the caller.
  39 Up to
  40 .I maxevents
  41 are returned by
  42 .BR epoll_wait (2).
  43 The
  44 .I maxevents
  45 parameter must be greater than zero. Specifying a
  46 .I timeout
  47 of \-1 makes
  48 .BR epoll_wait (2)
  49 wait indefinitely, while specifying a
  50 .I timeout
  51 equal to zero makes
  52 .BR epoll_wait (2)
  53 to return immediately even if no events are available ( return code equal to zero ).
  54 The
  55 .B struct epoll_event
  56 is defined as :
  57 .sp
  58 .nf
  59
  60         typedef union epoll_data {
  61                 void *ptr;
  62                 int fd;
  63                 __uint32_t u32;
  64                 __uint64_t u64;
  65         } epoll_data_t;
  66
  67         struct epoll_event {
  68                 __uint32_t events;      /* Epoll events */
  69                 epoll_data_t data;      /* User data variable */
  70         };
  71
  72 .fi
  73
  74 The
  75 .I data
  76 of each returned structure will contain the same data the user set with a
  77 .BR epoll_ctl (2)
  78 .IR ( EPOLL_CTL_ADD , EPOLL_CTL_MOD )
  79 while the
  80 .I events
  81 member will contain the returned event bit field.
  82 .SH "RETURN VALUE"
  83 When successful,
  84 .BR epoll_wait (2)
  85 returns the number of file descriptors ready for the requested I/O, or zero
  86 if no file descriptor became ready during the requested
  87 .I timeout
  88 milliseconds.  When an error occurs,
  89 .BR epoll_wait (2)
  90 returns \-1 and
  91 .I errno
  92 is set appropriately.
  93 .SH ERRORS
  94 .TP
  95 .B EBADF
  96 .I epfd
  97 is not a valid file descriptor.
  98 .TP
  99 .B EFAULT
 100 The memory area pointed to by
 101 .I events
 102 is not accessible with write permissions.
 103 .TP
 104 .B EINTR
 105 The call was interrupted by a signal handler before any of the
 106 requested events occurred or the
 107 .I timeout
 108 expired.
 109 .TP
 110 .B EINVAL
 111 .IR epfd
 112 is not an
 113 .B epoll
 114 file descriptor, or
 115 .I maxevents
 116 is less than or equal to zero.
 117 .SH CONFORMING TO
 118 .BR epoll_wait (2)
 119 is a new API introduced in Linux kernel 2.5.44.
 120 The interface should be finalized by Linux kernel 2.5.66.
 121 .SH "SEE ALSO"
 122 .BR epoll_create (2),
 123 .BR epoll_ctl (2),
 124 .BR epoll (4)