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 2007-12-19 "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 .B epoll
  41 file descriptor
  42 .I epfd
  43 for a maximum time of
  44 .I timeout
  45 milliseconds.
  46 The memory area pointed to by
  47 .I events
  48 will contain the events that will be available for the caller.
  49 Up to
  50 .I maxevents
  51 are returned by
  52 .BR epoll_wait ().
  53 The
  54 .I maxevents
  55 parameter must be greater than zero.
  56 Specifying a
  57 .I timeout
  58 of \-1 makes
  59 .BR epoll_wait ()
  60 wait indefinitely, while specifying a
  61 .I timeout
  62 equal to zero makes
  63 .BR epoll_wait ()
  64 to return immediately even if no events are available
  65 (return code equal to zero).
  66 The
  67 .I struct epoll_event
  68 is defined as :
  69 .sp
  70 .in +4n
  71 .nf
  72 typedef union epoll_data {
  73     void    *ptr;
  74     int      fd;
  75     uint32_t u32;
  76     uint64_t u64;
  77 } epoll_data_t;
  78
  79 struct epoll_event {
  80     uint32_t     events;    /* Epoll events */
  81     epoll_data_t data;      /* User data variable */
  82 };
  83 .fi
  84 .in
  85
  86 The
  87 .I data
  88 of each returned structure will contain the same data the user set with a
  89 .BR epoll_ctl (2)
  90 .RB ( EPOLL_CTL_ADD , EPOLL_CTL_MOD )
  91 while the
  92 .I events
  93 member will contain the returned event bit field.
  94 .SS epoll_pwait()
  95 The relationship between
  96 .BR epoll_wait ()
  97 and
  98 .BR epoll_pwait ()
  99 is analogous to the relationship between
 100 .BR select (2)
 101 and
 102 .BR pselect (2):
 103 like
 104 .BR pselect (2),
 105 .BR epoll_pwait ()
 106 allows an application to safely wait until either a file descriptor
 107 becomes ready or until a signal is caught.
 108
 109 The following
 110 .BR epoll_pwait ()
 111 call:
 112 .nf
 113
 114     ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
 115
 116 .fi
 117 is equivalent to
 118 .I atomically
 119 executing the following calls:
 120 .nf
 121
 122     sigset_t origmask;
 123
 124     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 125     ready = epoll_wait(epfd, &events, maxevents, timeout);
 126     sigprocmask(SIG_SETMASK, &origmask, NULL);
 127 .fi
 128 .SH "RETURN VALUE"
 129 When successful,
 130 .BR epoll_wait ()
 131 returns the number of file descriptors ready for the requested I/O, or zero
 132 if no file descriptor became ready during the requested
 133 .I timeout
 134 milliseconds.
 135 When an error occurs,
 136 .BR epoll_wait ()
 137 returns \-1 and
 138 .I errno
 139 is set appropriately.
 140 .SH ERRORS
 141 .TP
 142 .B EBADF
 143 .I epfd
 144 is not a valid file descriptor.
 145 .TP
 146 .B EFAULT
 147 The memory area pointed to by
 148 .I events
 149 is not accessible with write permissions.
 150 .TP
 151 .B EINTR
 152 The call was interrupted by a signal handler before any of the
 153 requested events occurred or the
 154 .I timeout
 155 expired.
 156 .TP
 157 .B EINVAL
 158 .I epfd
 159 is not an
 160 .B epoll
 161 file descriptor, or
 162 .I maxevents
 163 is less than or equal to zero.
 164 .SH VERSIONS
 165 .BR epoll_pwait ()
 166 was added to Linux in kernel 2.6.19.
 167
 168 Glibc support for
 169 .BR epoll_pwait ()
 170 is provided starting with version 2.6.
 171 .SH CONFORMING TO
 172 .BR epoll_wait ()
 173 is Linux-specific, and was introduced in kernel 2.5.44.
 174 .\" The interface should be finalized by Linux kernel 2.5.66.
 175 .SH "SEE ALSO"
 176 .BR epoll_create (2),
 177 .BR epoll_ctl (2),
 178 .BR epoll (7)