original/man2/poll.2

   1 .\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl)
   2 .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\"
  14 .\" Since the Linux kernel and libraries are constantly changing, this
  15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  16 .\" responsibility for errors or omissions, or for damages resulting from
  17 .\" the use of the information contained herein.  The author(s) may not
  18 .\" have taken the same level of care in the production of this manual,
  19 .\" which is licensed free of charge, as they might when working
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207
  27 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings
  28 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
  29 .\"     formatting changes.
  30 .\"
  31 .TH POLL 2 2012-08-17 "Linux" "Linux Programmer's Manual"
  32 .SH NAME
  33 poll, ppoll \- wait for some event on a file descriptor
  34 .SH SYNOPSIS
  35 .nf
  36 .B #include <poll.h>
  37 .sp
  38 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
  39 .sp
  40 .BR "#define _GNU_SOURCE" "         /* See feature_test_macros(7) */"
  41 .B #include <poll.h>
  42 .sp
  43 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
  44 .BI "        const struct timespec *" timeout_ts ", const sigset_t *" sigmask );
  45 .fi
  46 .SH DESCRIPTION
  47 .BR poll ()
  48 performs a similar task to
  49 .BR select (2):
  50 it waits for one of a set of file descriptors to become ready
  51 to perform I/O.
  52
  53 The set of file descriptors to be monitored is specified in the
  54 .I fds
  55 argument, which is an array of structures of the following form:
  56 .in +4n
  57 .nf
  58
  59 struct pollfd {
  60     int   fd;         /* file descriptor */
  61     short events;     /* requested events */
  62     short revents;    /* returned events */
  63 };
  64 .in
  65 .fi
  66 .PP
  67 The caller should specify the number of items in the
  68 .I fds
  69 array in
  70 .IR nfds .
  71
  72 The field
  73 .I fd
  74 contains a file descriptor for an open file.
  75 If this field is negative, then the corresponding
  76 .I events
  77 field is ignored and the
  78 .I revents
  79 field returns zero.
  80 (This provides an easy way of ignoring a
  81 file descriptor for a single
  82 .BR poll ()
  83 call: simply negate the
  84 .I fd
  85 field.)
  86
  87 The field
  88 .I events
  89 is an input parameter, a bit mask specifying the events the application
  90 is interested in for the file descriptor
  91 .IR fd .
  92 If this field is specified as zero,
  93 then all events are ignored for
  94 .IR fd
  95 and
  96 .I revents
  97 returns zero.
  98
  99 The field
 100 .I revents
 101 is an output parameter, filled by the kernel with the events that
 102 actually occurred.
 103 The bits returned in
 104 .I revents
 105 can include any of those specified in
 106 .IR events ,
 107 or one of the values
 108 .BR POLLERR ,
 109 .BR POLLHUP ,
 110 or
 111 .BR POLLNVAL .
 112 (These three bits are meaningless in the
 113 .I events
 114 field, and will be set in the
 115 .I revents
 116 field whenever the corresponding condition is true.)
 117
 118 If none of the events requested (and no error) has occurred for any
 119 of the file descriptors, then
 120 .BR poll ()
 121 blocks until one of the events occurs.
 122
 123 The
 124 .I timeout
 125 argument specifies the minimum number of milliseconds that
 126 .BR poll ()
 127 will block.
 128 (This interval will be rounded up to the system clock granularity,
 129 and kernel scheduling delays mean that the blocking interval
 130 may overrun by a small amount.)
 131 Specifying a negative value in
 132 .I timeout
 133 means an infinite timeout.
 134 Specifying a
 135 .I timeout
 136 of zero causes
 137 .BR poll ()
 138 to return immediately, even if no file descriptors are ready.
 139
 140 The bits that may be set/returned in
 141 .I events
 142 and
 143 .I revents
 144 are defined in \fI<poll.h>\fP:
 145 .RS
 146 .TP
 147 .B POLLIN
 148 There is data to read.
 149 .TP
 150 .B POLLPRI
 151 There is urgent data to read (e.g., out-of-band data on TCP socket;
 152 pseudoterminal master in packet mode has seen state change in slave).
 153 .TP
 154 .B POLLOUT
 155 Writing now will not block.
 156 .TP
 157 .BR POLLRDHUP " (since Linux 2.6.17)"
 158 Stream socket peer closed connection,
 159 or shut down writing half of connection.
 160 The
 161 .B _GNU_SOURCE
 162 feature test macro must be defined
 163 (before including
 164 .I any
 165 header files)
 166 in order to obtain this definition.
 167 .TP
 168 .B POLLERR
 169 Error condition (output only).
 170 .TP
 171 .B POLLHUP
 172 Hang up (output only).
 173 .TP
 174 .B POLLNVAL
 175 Invalid request:
 176 .I fd
 177 not open (output only).
 178 .RE
 179 .PP
 180 When compiling with
 181 .B _XOPEN_SOURCE
 182 defined, one also has the following,
 183 which convey no further information beyond the bits listed above:
 184 .RS
 185 .TP
 186 .B POLLRDNORM
 187 Equivalent to
 188 .BR POLLIN .
 189 .TP
 190 .B POLLRDBAND
 191 Priority band data can be read (generally unused on Linux).
 192 .\" POLLRDBAND is used in the DECnet protocol.
 193 .TP
 194 .B POLLWRNORM
 195 Equivalent to
 196 .BR POLLOUT .
 197 .TP
 198 .B POLLWRBAND
 199 Priority data may be written.
 200 .RE
 201 .PP
 202 Linux also knows about, but does not use
 203 .BR POLLMSG .
 204 .SS ppoll()
 205 The relationship between
 206 .BR poll ()
 207 and
 208 .BR ppoll ()
 209 is analogous to the relationship between
 210 .BR select (2)
 211 and
 212 .BR pselect (2):
 213 like
 214 .BR pselect (2),
 215 .BR ppoll ()
 216 allows an application to safely wait until either a file descriptor
 217 becomes ready or until a signal is caught.
 218 .PP
 219 Other than the difference in the precision of the
 220 .I timeout
 221 argument, the following
 222 .BR ppoll ()
 223 call:
 224 .nf
 225
 226     ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
 227
 228 .fi
 229 is equivalent to
 230 .I atomically
 231 executing the following calls:
 232 .nf
 233
 234     sigset_t origmask;
 235     int timeout;
 236
 237     timeout = (timeout_ts == NULL) ? \-1 :
 238               (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
 239     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 240     ready = poll(&fds, nfds, timeout);
 241     sigprocmask(SIG_SETMASK, &origmask, NULL);
 242 .fi
 243 .PP
 244 See the description of
 245 .BR pselect (2)
 246 for an explanation of why
 247 .BR ppoll ()
 248 is necessary.
 249
 250 If the
 251 .I sigmask
 252 argument is specified as NULL, then
 253 no signal mask manipulation is performed
 254 (and thus
 255 .BR ppoll ()
 256 differs from
 257 .BR poll ()
 258 only in the precision of the
 259 .I timeout
 260 argument).
 261
 262 The
 263 .I timeout_ts
 264 argument specifies an upper limit on the amount of time that
 265 .BR ppoll ()
 266 will block.
 267 This argument is a pointer to a structure of the following form:
 268 .in +4n
 269 .nf
 270
 271 struct timespec {
 272     long    tv_sec;         /* seconds */
 273     long    tv_nsec;        /* nanoseconds */
 274 };
 275 .fi
 276 .in
 277
 278 If
 279 .I timeout_ts
 280 is specified as NULL, then
 281 .BR ppoll ()
 282 can block indefinitely.
 283 .SH RETURN VALUE
 284 On success, a positive number is returned; this is
 285 the number of structures which have nonzero
 286 .I revents
 287 fields (in other words, those descriptors with events or errors reported).
 288 A value of 0 indicates that the call timed out and no file
 289 descriptors were ready.
 290 On error, \-1 is returned, and
 291 .I errno
 292 is set appropriately.
 293 .SH ERRORS
 294 .TP
 295 .B EFAULT
 296 The array given as argument was not contained in the calling program's
 297 address space.
 298 .TP
 299 .B EINTR
 300 A signal occurred before any requested event; see
 301 .BR signal (7).
 302 .TP
 303 .B EINVAL
 304 The
 305 .I nfds
 306 value exceeds the
 307 .B RLIMIT_NOFILE
 308 value.
 309 .TP
 310 .B ENOMEM
 311 There was no space to allocate file descriptor tables.
 312 .SH VERSIONS
 313 The
 314 .BR poll ()
 315 system call was introduced in Linux 2.1.23.
 316 On older kernels that lack this system call,
 317 .\" library call was introduced in libc 5.4.28
 318 the glibc (and the old Linux libc)
 319 .BR poll ()
 320 wrapper function provides emulation using
 321 .BR select (2).
 322
 323 The
 324 .BR ppoll ()
 325 system call was added to Linux in kernel 2.6.16.
 326 The
 327 .BR ppoll ()
 328 library call was added in glibc 2.4.
 329 .SH CONFORMING TO
 330 .BR poll ()
 331 conforms to POSIX.1-2001.
 332 .BR ppoll ()
 333 is Linux-specific.
 334 .\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
 335 .SH NOTES
 336 Some implementations define the nonstandard constant
 337 .B INFTIM
 338 with the value \-1 for use as a
 339 .IR timeout
 340 for
 341 .BR poll ().
 342 This constant is not provided in glibc.
 343
 344 For a discussion of what may happen if a file descriptor being monitored by
 345 .BR poll ()
 346 is closed in another thread, see
 347 .BR select (2).
 348 .SS Linux notes
 349 The Linux
 350 .BR ppoll ()
 351 system call modifies its
 352 .I timeout_ts
 353 argument.
 354 However, the glibc wrapper function hides this behavior
 355 by using a local variable for the timeout argument that
 356 is passed to the system call.
 357 Thus, the glibc
 358 .BR ppoll ()
 359 function does not modify its
 360 .I timeout_ts
 361 argument.
 362 .SH BUGS
 363 See the discussion of spurious readiness notifications under the
 364 BUGS section of
 365 .BR select (2).
 366 .SH SEE ALSO
 367 .BR select (2),
 368 .BR select_tut (2),
 369 .BR time (7)