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