man2/poll.2

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