1 .\" This manpage is copyright (C) 1992 Drew Eckhardt,
2 .\" copyright (C) 1995 Michael Shields,
3 .\" copyright (C) 2001 Paul Sheer,
4 .\" copyright (C) 2006, 2019 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
9 .\" Modified 1995-05-18 by Jim Van Zandt <jrv@vanzandt.mv.com>
10 .\" Sun Feb 11 14:07:00 MET 1996 Martin Schulze <joey@linux.de>
11 .\" * layout slightly modified
13 .\" Modified Mon Oct 21 23:05:29 EDT 1996 by Eric S. Raymond <esr@thyrsus.com>
14 .\" Modified Thu Feb 24 01:41:09 CET 2000 by aeb
15 .\" Modified Thu Feb 9 22:32:09 CET 2001 by bert hubert <ahu@ds9a.nl>, aeb
16 .\" Modified Mon Nov 11 14:35:00 PST 2002 by Ben Woodard <ben@zork.net>
17 .\" 2005-03-11, mtk, modified pselect() text (it is now a system
20 .TH SELECT 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
22 select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \-
23 synchronous I/O multiplexing
26 .RI ( libc ", " \-lc )
29 .B #include <sys/select.h>
31 .BR typedef " /* ... */ " fd_set;
33 .BI "int select(int " nfds ", fd_set *restrict " readfds ,
34 .BI " fd_set *restrict " writefds ", fd_set *restrict " exceptfds ,
35 .BI " struct timeval *restrict " timeout );
37 .BI "void FD_CLR(int " fd ", fd_set *" set );
38 .BI "int FD_ISSET(int " fd ", fd_set *" set );
39 .BI "void FD_SET(int " fd ", fd_set *" set );
40 .BI "void FD_ZERO(fd_set *" set );
42 .BI "int pselect(int " nfds ", fd_set *restrict " readfds ,
43 .BI " fd_set *restrict " writefds ", fd_set *restrict " exceptfds ,
44 .BI " const struct timespec *restrict " timeout ,
45 .BI " const sigset_t *restrict " sigmask );
49 Feature Test Macro Requirements for glibc (see
50 .BR feature_test_macros (7)):
55 _POSIX_C_SOURCE >= 200112L
60 can monitor only file descriptors numbers that are less than
62 (1024)\(eman unreasonably low limit for many modern applications\(emand
63 this limitation will not change.
64 All modern applications should instead use
68 which do not suffer this limitation.
71 allows a program to monitor multiple file descriptors,
72 waiting until one or more of the file descriptors become "ready"
73 for some class of I/O operation (e.g., input possible).
74 A file descriptor is considered ready if it is possible to
75 perform a corresponding I/O operation (e.g.,
77 or a sufficiently small
82 A structure type that can represent a set of file descriptors.
84 the maximum number of file descriptors in an
86 structure is the value of the macro
89 .SS File descriptor sets
90 The principal arguments of
92 are three "sets" of file descriptors (declared with the type
94 which allow the caller to wait for three classes of events
95 on the specified set of file descriptors.
98 arguments may be specified as NULL if no file descriptors are
99 to be watched for the corresponding class of events.
102 Upon return, each of the file descriptor sets is modified in place
103 to indicate which file descriptors are currently "ready".
106 within a loop, the sets \fImust be reinitialized\fP before each call.
108 The contents of a file descriptor set can be manipulated
109 using the following macros:
112 This macro clears (removes all file descriptors from)
114 It should be employed as the first step in initializing a file descriptor set.
117 This macro adds the file descriptor
121 Adding a file descriptor that is already present in the set is a no-op,
122 and does not produce an error.
125 This macro removes the file descriptor
129 Removing a file descriptor that is not present in the set is a no-op,
130 and does not produce an error.
134 modifies the contents of the sets according to the rules
141 can be used to test if a file descriptor is still present in a set.
143 returns nonzero if the file descriptor
147 and zero if it is not.
155 The file descriptors in this set are watched to see if they are
157 A file descriptor is ready for reading if a read operation will not
158 block; in particular, a file descriptor is also ready on end-of-file.
162 has returned, \fIreadfds\fP will be
163 cleared of all file descriptors except for those that are ready for reading.
166 The file descriptors in this set are watched to see if they are
168 A file descriptor is ready for writing if a write operation will not block.
169 However, even if a file descriptor indicates as writable,
170 a large write may still block.
174 has returned, \fIwritefds\fP will be
175 cleared of all file descriptors except for those that are ready for writing.
178 The file descriptors in this set are watched for "exceptional conditions".
179 For examples of some exceptional conditions, see the discussion of
187 \fIexceptfds\fP will be cleared of all file descriptors except for those
188 for which an exceptional condition has occurred.
191 This argument should be set to the highest-numbered file descriptor in any
192 of the three sets, plus 1.
193 The indicated file descriptors in each set are checked, up to this limit
201 structure (shown below) that specifies the interval that
203 should block waiting for a file descriptor to become ready.
204 The call will block until either:
207 a file descriptor becomes ready;
209 the call is interrupted by a signal handler; or
216 interval will be rounded up to the system clock granularity,
217 and kernel scheduling delays mean that the blocking interval
218 may overrun by a small amount.
220 If both fields of the
222 structure are zero, then
225 (This is useful for polling.)
229 is specified as NULL,
231 blocks indefinitely waiting for a file descriptor to become ready.
236 system call allows an application to safely wait until either
237 a file descriptor becomes ready or until a signal is caught.
243 is identical, other than these three differences:
246 uses a timeout that is a
248 (with seconds and microseconds), while
252 (with seconds and nanoseconds).
257 argument to indicate how much time was left.
259 does not change this argument.
264 argument, and behaves as
270 is a pointer to a signal mask (see
271 .BR sigprocmask (2));
272 if it is not NULL, then
274 first replaces the current signal mask by the one pointed to by
276 then does the "select" function, and then restores the original
281 the signal mask is not modified during the
285 Other than the difference in the precision of the
287 argument, the following
293 ready = pselect(nfds, &readfds, &writefds, &exceptfds,
300 executing the following calls:
306 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
307 ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
308 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
314 is needed is that if one wants to wait for either a signal
315 or for a file descriptor to become ready, then
316 an atomic test is needed to prevent race conditions.
317 (Suppose the signal handler sets a global flag and
319 Then a test of this global flag followed by a call of
321 could hang indefinitely if the signal arrived just after the test
322 but just before the call.
325 allows one to first block signals, handle the signals that have come in,
336 is a structure of the following type:
341 time_t tv_sec; /* seconds */
342 suseconds_t tv_usec; /* microseconds */
347 The corresponding argument for
357 to reflect the amount of time not slept; most other implementations
359 (POSIX.1 permits either behavior.)
360 This causes problems both when Linux code which reads
362 is ported to other operating systems, and when code is ported to Linux
363 that reuses a \fIstruct timeval\fP for multiple
365 in a loop without reinitializing it.
368 to be undefined after
371 .\" .PP - it is rumored that:
372 .\" On BSD, when a timeout occurs, the file descriptor bits are not changed.
373 .\" - it is certainly true that:
374 .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout.
380 return the number of file descriptors contained in the three returned
381 descriptor sets (that is, the total number of bits that are set in
385 The return value may be zero if the timeout expired before any
386 file descriptors became ready.
388 On error, \-1 is returned, and
390 is set to indicate the error;
391 the file descriptor sets are unmodified,
398 An invalid file descriptor was given in one of the sets.
399 (Perhaps a file descriptor that was already closed,
400 or one on which an error has occurred.)
404 A signal was caught; see
409 is negative or exceeds the
415 The value contained within
420 Unable to allocate memory for internal tables.
423 was added to Linux in kernel 2.6.16.
426 was emulated in glibc (but see BUGS).
429 conforms to POSIX.1-2001, POSIX.1-2008, and
432 first appeared in 4.2BSD).
433 Generally portable to/from
434 non-BSD systems supporting clones of the BSD socket layer (including
436 However, note that the System\ V variant typically
437 sets the timeout variable before returning, but the BSD variant does not.
440 is defined in POSIX.1g, and in
441 POSIX.1-2001 and POSIX.1-2008.
444 is defined in POSIX.1-2001 and later.
446 The following header also provides the
453 is a fixed size buffer.
460 that is negative or is equal to or larger than
463 in undefined behavior.
464 Moreover, POSIX requires
466 to be a valid file descriptor.
472 is not affected by the
476 On some other UNIX systems,
477 .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
479 can fail with the error
481 if the system fails to allocate kernel-internal resources, rather than
484 POSIX specifies this error for
488 Portable programs may wish to check for
490 and loop, just as with
493 .SS The self-pipe trick
496 reliable (and more portable) signal trapping can be achieved
497 using the self-pipe trick.
499 a signal handler writes a byte to a pipe whose other end
503 (To avoid possibly blocking when writing to a pipe that may be full
504 or reading from a pipe that may be empty,
505 nonblocking I/O is used when reading from and writing to the pipe.)
507 .SS Emulating usleep(3)
510 some code employed a call to
512 with all three sets empty,
516 as a fairly portable way to sleep with subsecond precision.
518 .SS Correspondence between select() and poll() notifications
519 Within the Linux kernel source,
521 we find the following definitions which show the correspondence
522 between the readable, writable, and exceptional condition notifications of
524 and the event notifications provided by
531 #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
533 /* Ready for reading */
534 #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT |
536 /* Ready for writing */
537 #define POLLEX_SET (EPOLLPRI)
538 /* Exceptional condition */
542 .SS Multithreaded applications
543 If a file descriptor being monitored by
545 is closed in another thread, the result is unspecified.
546 On some UNIX systems,
548 unblocks and returns, with an indication that the file descriptor is ready
549 (a subsequent I/O operation will likely fail with an error,
550 unless another process reopens file descriptor between the time
552 returned and the I/O operation is performed).
553 On Linux (and some other systems),
554 closing the file descriptor in another thread has no effect on
556 In summary, any application that relies on a particular behavior
557 in this scenario must be considered buggy.
559 .SS C library/kernel differences
560 The Linux kernel allows file descriptor sets of arbitrary size,
561 determining the length of the sets to be checked from the value of
563 However, in the glibc implementation, the
565 type is fixed in size.
570 interface described in this page is implemented by glibc.
571 The underlying Linux system call is named
573 This system call has somewhat different behavior from the glibc
578 system call modifies its
581 However, the glibc wrapper function hides this behavior
582 by using a local variable for the timeout argument that
583 is passed to the system call.
586 function does not modify its
589 this is the behavior required by POSIX.1-2001.
591 The final argument of the
595 pointer, but is instead a structure of the form:
600 const kernel_sigset_t *ss; /* Pointer to signal set */
601 size_t ss_len; /* Size (in bytes) of object
602 pointed to by \(aqss\(aq */
607 This allows the system call to obtain both
608 a pointer to the signal set and its size,
609 while allowing for the fact that most architectures
610 support a maximum of 6 arguments to a system call.
613 for a discussion of the difference between the kernel and libc
614 notion of the signal set.
616 .SS Historical glibc details
617 Glibc 2.0 provided an incorrect version of
623 In glibc versions 2.1 to 2.2.1,
626 in order to obtain the declaration of
631 POSIX allows an implementation to define an upper limit,
632 advertised via the constant
634 on the range of file descriptors that can be specified
635 in a file descriptor set.
636 The Linux kernel imposes no fixed limit, but the glibc implementation makes
638 a fixed-size type, with
640 defined as 1024, and the
642 macros operating according to that limit.
643 To monitor file descriptors greater than 1023, use
649 The implementation of the
651 arguments as value-result arguments is a design error that is avoided in
658 should check all specified file descriptors in the three file descriptor sets,
661 However, the current implementation ignores any file descriptor in
662 these sets that is greater than the maximum file descriptor number
663 that the process currently has open.
664 According to POSIX, any such file descriptor that is specified in one
665 of the sets should result in the error
668 Starting with version 2.1, glibc provided an emulation of
670 that was implemented using
674 This implementation remained vulnerable to the very race condition that
676 was designed to prevent.
677 Modern versions of glibc use the (race-free)
679 system call on kernels where it is provided.
683 may report a socket file descriptor as "ready for reading", while
684 nevertheless a subsequent read blocks.
685 This could for example
686 happen when data has arrived but upon examination has the wrong
687 checksum and is discarded.
688 There may be other circumstances
689 in which a file descriptor is spuriously reported as ready.
690 .\" Stevens discusses a case where accept can block after select
691 .\" returns successfully because of an intervening RST from the client.
692 Thus it may be safer to use
694 on sockets that should not block.
695 .\" Maybe the kernel should have returned EIO in such a situation?
701 if the call is interrupted by a signal handler (i.e., the
704 This is not permitted by POSIX.1.
707 system call has the same behavior,
708 but the glibc wrapper hides this behavior by internally copying the
710 to a local variable and passing that variable to the system call.
712 .\" SRC BEGIN (select.c)
716 #include <sys/select.h>
725 /* Watch stdin (fd 0) to see when it has input. */
730 /* Wait up to five seconds. */
735 retval = select(1, &rfds, NULL, NULL, &tv);
736 /* Don\(aqt rely on the value of tv now! */
741 printf("Data is available now.\en");
742 /* FD_ISSET(0, &rfds) will be true. */
744 printf("No data within five seconds.\en");
756 .BR restart_syscall (2),
764 For a tutorial with discussion and examples, see