man2/select.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" This manpage is copyright (C) 1992 Drew Eckhardt,
   4 .\"                 copyright (C) 1995 Michael Shields.
   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 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
  27 .\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com>
  28 .\" Sun Feb 11 14:07:00 MET 1996  Martin Schulze  <joey@linux.de>
  29 .\"     * layout slightly modified
  30 .\"
  31 .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
  32 .\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb
  33 .\" Modified Thu Feb  9 22:32:09 CET 2001 by bert hubert <ahu@ds9a.nl>, aeb
  34 .\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard <ben@zork.net>
  35 .\" 2005-03-11, mtk, modified pselect() text (it is now a system
  36 .\"     call in 2.6.16.
  37 .\"
  38 .TH SELECT 2 2006-03-11 "Linux 2.6.16" "Linux Programmer's Manual"
  39 .SH NAME
  40 select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \-
  41 synchronous I/O multiplexing
  42 .SH SYNOPSIS
  43 .nf
  44 /* According to POSIX.1-2001 */
  45 .br
  46 .B #include <sys/select.h>
  47 .sp
  48 /* According to earlier standards */
  49 .br
  50 .B #include <sys/time.h>
  51 .br
  52 .B #include <sys/types.h>
  53 .br
  54 .B #include <unistd.h>
  55 .sp
  56 \fBint select(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB,
  57            fd_set *\fIexceptfds\fB, struct timeval *\fItimeout\fB);
  58 .sp
  59 .BI "void FD_CLR(int " fd ", fd_set *" set );
  60 .br
  61 .BI "int  FD_ISSET(int " fd ", fd_set *" set );
  62 .br
  63 .BI "void FD_SET(int " fd ", fd_set *" set );
  64 .br
  65 .BI "void FD_ZERO(fd_set *" set );
  66 .sp
  67 .B #define _XOPEN_SOURCE 600
  68 .B #include <sys/select.h>
  69 .sp
  70 \fBint pselect(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB,
  71             fd_set *\fIexceptfds\fB, const struct timespec *\fItimeout\fB,
  72             const sigset_t *\fIsigmask\fB);
  73 .fi
  74 .SH DESCRIPTION
  75 .BR select ()
  76 and
  77 .BR pselect ()
  78 allow a program to monitor multiple file descriptors,
  79 waiting until one or more of the file descriptors become "ready"
  80 for some class of I/O operation (e.g., input possible).
  81 A file descriptor is considered ready if it is possible to
  82 perform the corresponding I/O operation (e.g.,
  83 .BR read (2))
  84 without blocking.
  85 .PP
  86 The operation of
  87 .BR select ()
  88 and
  89 .BR pselect ()
  90 is identical, with three differences:
  91 .TP
  92 (i)
  93 .BR select ()
  94 uses a timeout that is a
  95 .I struct timeval
  96 (with seconds and microseconds), while
  97 .BR pselect ()
  98 uses a
  99 .I struct timespec
 100 (with seconds and nanoseconds).
 101 .TP
 102 (ii)
 103 .BR select ()
 104 may update the
 105 .I timeout
 106 argument to indicate how much time was left.
 107 .BR pselect ()
 108 does not change this argument.
 109 .TP
 110 (iii)
 111 .BR select ()
 112 has no
 113 .I sigmask
 114 argument, and behaves as
 115 .BR pselect ()
 116 called with NULL
 117 .IR sigmask .
 118 .PP
 119 Three independent sets of file descriptors are watched.
 120 Those listed in
 121 .I readfds
 122 will be watched to see if characters become
 123 available for reading (more precisely, to see if a read will not
 124 block; in particular, a file descriptor is also ready on end-of-file),
 125 those in
 126 .I writefds
 127 will be watched to see if a write will not block, and
 128 those in
 129 .I exceptfds
 130 will be watched for exceptions.
 131 On exit, the sets are modified in place
 132 to indicate which file descriptors actually changed status.
 133 Each of the three file descriptor sets may be specified as NULL
 134 if no file descriptors are to be watched for the corresponding class
 135 of events.
 136 .PP
 137 Four macros are provided to manipulate the sets.
 138 .BR FD_ZERO ()
 139 clears a set.
 140 .BR FD_SET ()
 141 and
 142 .BR FD_CLR ()
 143 respectively add and remove a given file descriptor from a set.
 144 .BR FD_ISSET ()
 145 tests to see if a file descriptor is part of the set;
 146 this is useful after
 147 .BR select ()
 148 returns.
 149 .PP
 150 .I nfds
 151 is the highest-numbered file descriptor in any of the three sets, plus 1.
 152 .PP
 153 .I timeout
 154 is an upper bound on the amount of time elapsed before
 155 .BR select ()
 156 returns.
 157 It may be zero, causing
 158 .BR select ()
 159 to return immediately.
 160 (This is useful for polling.)
 161 If
 162 .I timeout
 163 is NULL (no timeout),
 164 .BR select ()
 165 can block indefinitely.
 166 .PP
 167 .I sigmask
 168 is a pointer to a signal mask (see
 169 .BR sigprocmask (2));
 170 if it is not NULL, then
 171 .BR pselect ()
 172 first replaces the current signal mask by the one pointed to by
 173 .IR sigmask ,
 174 then does the `select' function, and then restores the original
 175 signal mask.
 176 .PP
 177 Other than the difference in the precision of the
 178 .I timeout
 179 argument, the following
 180 .BR pselect ()
 181 call:
 182 .nf
 183
 184     ready = pselect(nfds, &readfds, &writefds, &exceptfds,
 185                     timeout, &sigmask);
 186
 187 .fi
 188 is equivalent to
 189 .I atomically
 190 executing the following calls:
 191 .nf
 192
 193     sigset_t origmask;
 194
 195     sigprocmask(SIG_SETMASK, &sigmask, &origmask);
 196     ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
 197     sigprocmask(SIG_SETMASK, &origmask, NULL);
 198 .fi
 199 .PP
 200 The reason that
 201 .BR pselect ()
 202 is needed is that if one wants to wait for either a signal
 203 or for a file descriptor to become ready, then
 204 an atomic test is needed to prevent race conditions.
 205 (Suppose the signal handler sets a global flag and
 206 returns.
 207 Then a test of this global flag followed by a call of
 208 .BR select ()
 209 could hang indefinitely if the signal arrived just after the test
 210 but just before the call.
 211 By contrast,
 212 .BR pselect ()
 213 allows one to first block signals, handle the signals that have come in,
 214 then call
 215 .BR pselect ()
 216 with the desired
 217 .IR sigmask ,
 218 avoiding the race.)
 219 .SS "The timeout"
 220 The time structures involved are defined in
 221 .I <sys/time.h>
 222 and look like
 223
 224 .in +0.25i
 225 .nf
 226 struct timeval {
 227     long    tv_sec;         /* seconds */
 228     long    tv_usec;        /* microseconds */
 229 };
 230 .fi
 231 .in -0.25i
 232
 233 and
 234
 235 .in +0.25i
 236 .nf
 237 struct timespec {
 238     long    tv_sec;         /* seconds */
 239     long    tv_nsec;        /* nanoseconds */
 240 };
 241 .fi
 242 .in -0.25i
 243
 244 (However, see below on the POSIX.1-2001 versions.)
 245 .PP
 246 Some code calls
 247 .BR select ()
 248 with all three sets empty,
 249 .I nfds
 250 zero, and a non-NULL
 251 .I timeout
 252 as a fairly portable way to sleep with subsecond precision.
 253 .PP
 254 On Linux,
 255 .BR select ()
 256 modifies
 257 .I timeout
 258 to reflect the amount of time not slept; most other implementations
 259 do not do this.
 260 (POSIX.1-2001 permits either behaviour.)
 261 This causes problems both when Linux code which reads
 262 .I timeout
 263 is ported to other operating systems, and when code is ported to Linux
 264 that reuses a struct timeval for multiple
 265 .BR select ()s
 266 in a loop without reinitializing it.
 267 Consider
 268 .I timeout
 269 to be undefined after
 270 .BR select ()
 271 returns.
 272 .\" .PP - it is rumoured that:
 273 .\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
 274 .\" - it is certainly true that:
 275 .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
 276 .SH "RETURN VALUE"
 277 On success,
 278 .BR select ()
 279 and
 280 .BR pselect ()
 281 return the number of file descriptors contained in the three returned
 282 descriptor sets (that is, the total number of bits that are set in
 283 .IR readfds ,
 284 .IR writefds ,
 285 .IR exceptfds )
 286 which may be zero if the timeout expires before anything interesting happens.
 287 On error, \-1 is returned, and
 288 .I errno
 289 is set appropriately; the sets and
 290 .I timeout
 291 become undefined, so do not
 292 rely on their contents after an error.
 293 .SH ERRORS
 294 .TP
 295 .B EBADF
 296 An invalid file descriptor was given in one of the sets.
 297 (Perhaps a file descriptor that was already closed,
 298 or one on which an error has occurred.)
 299 .TP
 300 .B EINTR
 301 A signal was caught.
 302 .TP
 303 .B EINVAL
 304 .I nfds
 305 is negative or the value contained within
 306 .I timeout
 307 is invalid.
 308 .TP
 309 .B ENOMEM
 310 unable to allocate memory for internal tables.
 311 .SH EXAMPLE
 312 .nf
 313 #include <stdio.h>
 314 #include <sys/time.h>
 315 #include <sys/types.h>
 316 #include <unistd.h>
 317
 318 int
 319 main(void)
 320 {
 321     fd_set rfds;
 322     struct timeval tv;
 323     int retval;
 324
 325     /* Watch stdin (fd 0) to see when it has input. */
 326     FD_ZERO(&rfds);
 327     FD_SET(0, &rfds);
 328
 329     /* Wait up to five seconds. */
 330     tv.tv_sec = 5;
 331     tv.tv_usec = 0;
 332
 333     retval = select(1, &rfds, NULL, NULL, &tv);
 334     /* Don't rely on the value of tv now! */
 335
 336     if (retval == \-1)
 337         perror("select()");
 338     else if (retval)
 339         printf("Data is available now.\\n");
 340         /* FD_ISSET(0, &rfds) will be true. */
 341     else
 342         printf("No data within five seconds.\\n");
 343
 344     return 0;
 345 }
 346 .fi
 347 .SH "CONFORMING TO"
 348 .BR select ()
 349 conforms to POSIX.1-2001 and
 350 4.4BSD
 351 .RB ( select ()
 352 first appeared in 4.2BSD).
 353 Generally portable to/from
 354 non-BSD systems supporting clones of the BSD socket layer (including
 355 System V variants).
 356 However, note that the System V variant typically
 357 sets the timeout variable before exit, but the BSD variant does not.
 358 .PP
 359 .BR pselect ()
 360 is defined in POSIX.1g, and in
 361 POSIX.1-2001.
 362 .SH NOTES
 363 An
 364 .I fd_set
 365 is a fixed size buffer.
 366 Executing
 367 .BR FD_CLR ()
 368 or
 369 .BR FD_SET ()
 370 with a value of
 371 .I fd
 372 that is negative or is equal to or larger than FD_SETSIZE will result
 373 in undefined behavior.
 374 Moreover, POSIX requires
 375 .I fd
 376 to be a valid file descriptor.
 377
 378 Concerning the types involved, the classical situation is that
 379 the two fields of a
 380 .I timeval
 381 structure are longs (as shown above),
 382 and the structure is defined in
 383 .IR <sys/time.h> .
 384 The POSIX.1-2001 situation is
 385
 386 .RS
 387 .nf
 388 struct timeval {
 389     time_t         tv_sec;     /* seconds */
 390     suseconds_t    tv_usec;    /* microseconds */
 391 };
 392 .fi
 393 .RE
 394
 395 where the structure is defined in
 396 .I <sys/select.h>
 397 and the data types
 398 .I time_t
 399 and
 400 .I suseconds_t
 401 are defined in
 402 .IR <sys/types.h> .
 403 .LP
 404 Concerning prototypes, the classical situation is that one should
 405 include
 406 .I <time.h>
 407 for
 408 .BR select ().
 409 The POSIX.1-2001 situation is that one should include
 410 .I <sys/select.h>
 411 for
 412 .BR select ()
 413 and
 414 .BR pselect ().
 415 Libc4 and libc5 do not have a
 416 .I <sys/select.h>
 417 header; under glibc 2.0 and later this header exists.
 418 Under glibc 2.0 it unconditionally gives the wrong prototype for
 419 .BR pselect (),
 420 under glibc 2.1-2.2.1 it gives
 421 .BR pselect ()
 422 when
 423 .B _GNU_SOURCE
 424 is defined, under glibc 2.2.2-2.2.4 it gives it when
 425 .B _XOPEN_SOURCE
 426 is defined and has a value of 600 or larger.
 427 No doubt, since POSIX.1-2001, it should give the prototype by default.
 428 .SH VERSIONS
 429 .BR pselect ()
 430 was added to Linux in kernel 2.6.16.
 431 Prior to this,
 432 .BR pselect ()
 433 was emulated in glibc (but see BUGS).
 434 .SH "LINUX NOTES"
 435 The Linux
 436 .BR pselect ()
 437 system call modifies its
 438 .I timeout
 439 argument.
 440 However, the glibc wrapper function hides this behaviour
 441 by using a local variable for the timeout argument that
 442 is passed to the system call.
 443 Thus, the glibc
 444 .BR pselect ()
 445 function does not modify its timeout argument;
 446 this is the behaviour required by POSIX.1-2001.
 447 .SH BUGS
 448 Glibc 2.0 provided a version of
 449 .BR pselect ()
 450 that did not take a
 451 .I sigmask
 452 argument.
 453
 454 Since version 2.1, glibc has provided an emulation of
 455 .BR pselect ()
 456 that is implemented using
 457 .BR sigprocmask (2)
 458 and
 459 .BR select ().
 460 This implementation remains vulnerable to the very race condition that
 461 .BR pselect ()
 462 was designed to prevent.
 463 On systems that lack
 464 .BR pselect ()
 465 reliable (and more portable) signal trapping can be achieved
 466 using the self-pipe trick
 467 (where a signal handler writes a byte to a pipe whose other end
 468 is monitored by
 469 .BR select ()
 470 in the main program.)
 471
 472 Under Linux,
 473 .BR select ()
 474 may report a socket file descriptor as "ready for reading", while
 475 nevertheless a subsequent read blocks.
 476 This could for example
 477 happen when data has arrived but upon examination has wrong
 478 checksum and is discarded.
 479 There may be other circumstances
 480 in which a file descriptor is spuriously reported as ready.
 481 .\" Stevens discusses a case where accept can block after select
 482 .\" returns successfully because of an intervening RST from the client.
 483 Thus it may be safer to use O_NONBLOCK on sockets that should not block.
 484 .\" Maybe the kernel should have returned EIO in such a situation?
 485 .\"
 486 .\" FIXME select() (and pselect()?) also modify the timeout
 487 .\" on an EINTR error return; POSIX.1-2001 doesn't permit this.
 488 .SH "SEE ALSO"
 489 For a tutorial with discussion and examples, see
 490 .BR select_tut (2).
 491 .LP
 492 For vaguely related stuff, see
 493 .BR accept (2),
 494 .BR connect (2),
 495 .BR poll (2),
 496 .BR read (2),
 497 .BR recv (2),
 498 .BR send (2),
 499 .BR sigprocmask (2),
 500 .BR write (2),
 501 .BR epoll (7),
 502 .BR feature_test_macros (7)