Debian Codegraph @

upstream/debian-unstable/man2/select.2

raw
1 .\" Copyright 1992, Drew Eckhardt <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH select 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO, fd_set \-
9 synchronous I/O multiplexing
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <sys/select.h>
16 .P
17 .BR typedef " /* .\|.\|.\& */ " fd_set;
18 .P
19 .BI "int select(int " nfds ", fd_set *_Nullable restrict " readfds ,
20 .BI " fd_set *_Nullable restrict " writefds ,
21 .BI " fd_set *_Nullable restrict " exceptfds ,
22 .BI " struct timeval *_Nullable restrict " timeout );
23 .P
24 .BI "void FD_CLR(int " fd ", fd_set *" set );
25 .BI "int FD_ISSET(int " fd ", const fd_set *" set );
26 .BI "void FD_SET(int " fd ", fd_set *" set );
27 .BI "void FD_ZERO(fd_set *" set );
28 .P
29 .BI "int pselect(int " nfds ", fd_set *_Nullable restrict " readfds ,
30 .BI " fd_set *_Nullable restrict " writefds ,
31 .BI " fd_set *_Nullable restrict " exceptfds ,
32 .BI " const struct timespec *_Nullable restrict " timeout ,
33 .BI " const sigset_t *_Nullable restrict " sigmask );
34 .fi
35 .P
36 .RS -4
37 Feature Test Macro Requirements for glibc (see
38 .BR feature_test_macros (7)):
39 .RE
40 .P
41 .BR pselect ():
42 .nf
43 _POSIX_C_SOURCE >= 200112L
44 .fi
45 .SH DESCRIPTION
46 .BR "WARNING" :
47 .BR select ()
48 can monitor only file descriptors numbers that are less than
49 .B FD_SETSIZE
50 (1024)\[em]an unreasonably low limit for many modern applications\[em]and
51 this limitation will not change.
52 All modern applications should instead use
53 .BR poll (2)
54 or
55 .BR epoll (7),
56 which do not suffer this limitation.
57 .P
58 .BR select ()
59 allows a program to monitor multiple file descriptors,
60 waiting until one or more of the file descriptors become "ready"
61 for some class of I/O operation (e.g., input possible).
62 A file descriptor is considered ready if it is possible to
63 perform a corresponding I/O operation (e.g.,
64 .BR read (2),
65 or a sufficiently small
66 .BR write (2))
67 without blocking.
68 .\"
69 .SS fd_set
70 A structure type that can represent a set of file descriptors.
71 According to POSIX,
72 the maximum number of file descriptors in an
73 .I fd_set
74 structure is the value of the macro
75 .BR FD_SETSIZE .
76 .\"
77 .SS File descriptor sets
78 The principal arguments of
79 .BR select ()
80 are three "sets" of file descriptors (declared with the type
81 .IR fd_set ),
82 which allow the caller to wait for three classes of events
83 on the specified set of file descriptors.
84 Each of the
85 .I fd_set
86 arguments may be specified as NULL if no file descriptors are
87 to be watched for the corresponding class of events.
88 .P
89 .BR "Note well" :
90 Upon return, each of the file descriptor sets is modified in place
91 to indicate which file descriptors are currently "ready".
92 Thus, if using
93 .BR select ()
94 within a loop, the sets
95 .I must be reinitialized
96 before each call.
97 .P
98 The contents of a file descriptor set can be manipulated
99 using the following macros:
100 .TP
101 .BR FD_ZERO ()
102 This macro clears (removes all file descriptors from)
103 .IR set .
104 It should be employed as the first step in initializing a file descriptor set.
105 .TP
106 .BR FD_SET ()
107 This macro adds the file descriptor
108 .I fd
109 to
110 .IR set .
111 Adding a file descriptor that is already present in the set is a no-op,
112 and does not produce an error.
113 .TP
114 .BR FD_CLR ()
115 This macro removes the file descriptor
116 .I fd
117 from
118 .IR set .
119 Removing a file descriptor that is not present in the set is a no-op,
120 and does not produce an error.
121 .TP
122 .BR FD_ISSET ()
123 .BR select ()
124 modifies the contents of the sets according to the rules
125 described below.
126 After calling
127 .BR select (),
128 the
129 .BR FD_ISSET ()
130 macro
131 can be used to test if a file descriptor is still present in a set.
132 .BR FD_ISSET ()
133 returns nonzero if the file descriptor
134 .I fd
135 is present in
136 .IR set ,
137 and zero if it is not.
138 .\"
139 .SS Arguments
140 The arguments of
141 .BR select ()
142 are as follows:
143 .TP
144 .I readfds
145 The file descriptors in this set are watched to see if they are
146 ready for reading.
147 A file descriptor is ready for reading if a read operation will not block;
148 in particular,
149 a file descriptor is also ready on end-of-file.
150 .IP
151 After
152 .BR select ()
153 has returned,
154 .I readfds
155 will be
156 cleared of all file descriptors except for those that are ready for reading.
157 .TP
158 .I writefds
159 The file descriptors in this set are watched to see if they are
160 ready for writing.
161 A file descriptor is ready for writing if a write operation will not block.
162 However, even if a file descriptor indicates as writable,
163 a large write may still block.
164 .IP
165 After
166 .BR select ()
167 has returned,
168 .I writefds
169 will be
170 cleared of all file descriptors except for those that are ready for writing.
171 .TP
172 .I exceptfds
173 The file descriptors in this set are watched for "exceptional conditions".
174 For examples of some exceptional conditions, see the discussion of
175 .B POLLPRI
176 in
177 .BR poll (2).
178 .IP
179 After
180 .BR select ()
181 has returned,
182 .I exceptfds
183 will be cleared of all file descriptors except for those
184 for which an exceptional condition has occurred.
185 .TP
186 .I nfds
187 This argument should be set to the highest-numbered file descriptor in any
188 of the three sets, plus 1.
189 The indicated file descriptors in each set are checked, up to this limit
190 (but see BUGS).
191 .TP
192 .I timeout
193 The
194 .I timeout
195 argument is a
196 .I timeval
197 structure (shown below) that specifies the interval that
198 .BR select ()
199 should block waiting for a file descriptor to become ready.
200 The call will block until either:
201 .RS
202 .IP \[bu] 3
203 a file descriptor becomes ready;
204 .IP \[bu]
205 the call is interrupted by a signal handler;
206 or
207 .IP \[bu]
208 the timeout expires.
209 .RE
210 .IP
211 Note that the
212 .I timeout
213 interval will be rounded up to the system clock granularity,
214 and kernel scheduling delays mean that the blocking interval
215 may overrun by a small amount.
216 .IP
217 If both fields of the
218 .I timeval
219 structure are zero, then
220 .BR select ()
221 returns immediately.
222 (This is useful for polling.)
223 .IP
224 If
225 .I timeout
226 is specified as NULL,
227 .BR select ()
228 blocks indefinitely waiting for a file descriptor to become ready.
229 .\"
230 .SS pselect()
231 The
232 .BR pselect ()
233 system call allows an application to safely wait until either
234 a file descriptor becomes ready or until a signal is caught.
235 .P
236 The operation of
237 .BR select ()
238 and
239 .BR pselect ()
240 is identical, other than these three differences:
241 .IP \[bu] 3
242 .BR select ()
243 uses a timeout that is a
244 .I struct timeval
245 (with seconds and microseconds), while
246 .BR pselect ()
247 uses a
248 .I struct timespec
249 (with seconds and nanoseconds).
250 .IP \[bu]
251 .BR select ()
252 may update the
253 .I timeout
254 argument to indicate how much time was left.
255 .BR pselect ()
256 does not change this argument.
257 .IP \[bu]
258 .BR select ()
259 has no
260 .I sigmask
261 argument, and behaves as
262 .BR pselect ()
263 called with NULL
264 .IR sigmask .
265 .P
266 .I sigmask
267 is a pointer to a signal mask (see
268 .BR sigprocmask (2));
269 if it is not NULL, then
270 .BR pselect ()
271 first replaces the current signal mask by the one pointed to by
272 .IR sigmask ,
273 then does the "select" function, and then restores the original
274 signal mask.
275 (If
276 .I sigmask
277 is NULL,
278 the signal mask is not modified during the
279 .BR pselect ()
280 call.)
281 .P
282 Other than the difference in the precision of the
283 .I timeout
284 argument, the following
285 .BR pselect ()
286 call:
287 .P
288 .in +4n
289 .EX
290 ready = pselect(nfds, &readfds, &writefds, &exceptfds,
291 timeout, &sigmask);
292 .EE
293 .in
294 .P
295 is equivalent to
296 .I atomically
297 executing the following calls:
298 .P
299 .in +4n
300 .EX
301 sigset_t origmask;
302 \&
303 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
304 ready = select(nfds, &readfds, &writefds, &exceptfds, timeout);
305 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
306 .EE
307 .in
308 .P
309 The reason that
310 .BR pselect ()
311 is needed is that if one wants to wait for either a signal
312 or for a file descriptor to become ready, then
313 an atomic test is needed to prevent race conditions.
314 (Suppose the signal handler sets a global flag and
315 returns.
316 Then a test of this global flag followed by a call of
317 .BR select ()
318 could hang indefinitely if the signal arrived just after the test
319 but just before the call.
320 By contrast,
321 .BR pselect ()
322 allows one to first block signals, handle the signals that have come in,
323 then call
324 .BR pselect ()
325 with the desired
326 .IR sigmask ,
327 avoiding the race.)
328 .SS The timeout
329 The
330 .I timeout
331 argument for
332 .BR select ()
333 is a structure of the following type:
334 .P
335 .in +4n
336 .EX
337 struct timeval {
338 time_t tv_sec; /* seconds */
339 suseconds_t tv_usec; /* microseconds */
340 };
341 .EE
342 .in
343 .P
344 The corresponding argument for
345 .BR pselect ()
346 is a
347 .BR timespec (3)
348 structure.
349 .P
350 On Linux,
351 .BR select ()
352 modifies
353 .I timeout
354 to reflect the amount of time not slept;
355 most other implementations
356 do not do this.
357 (POSIX.1 permits either behavior.)
358 This causes problems both when Linux code which reads
359 .I timeout
360 is ported to other operating systems, and when code is ported to Linux
361 that reuses a
362 .I struct\ timeval
363 for multiple
364 .BR select ()s
365 in a loop without reinitializing it.
366 Consider
367 .I timeout
368 to be undefined after
369 .BR select ()
370 returns.
371 .\" .P - 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.
375 .SH RETURN VALUE
376 On success,
377 .BR select ()
378 and
379 .BR pselect ()
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
382 .IR readfds ,
383 .IR writefds ,
384 .IR exceptfds ).
385 The return value may be zero if the timeout expired before any
386 file descriptors became ready.
387 .P
388 On error, \-1 is returned, and
389 .I errno
390 is set to indicate the error;
391 the file descriptor sets are unmodified,
392 and
393 .I timeout
394 becomes undefined.
395 .SH ERRORS
396 .TP
397 .B EBADF
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.)
401 However, see BUGS.
402 .TP
403 .B EINTR
404 A signal was caught;
405 see
406 .BR signal (7).
407 .TP
408 .B EINVAL
409 .I nfds
410 is negative or exceeds the
411 .B RLIMIT_NOFILE
412 resource limit (see
413 .BR getrlimit (2)).
414 .TP
415 .B EINVAL
416 The value contained within
417 .I timeout
418 is invalid.
419 .TP
420 .B ENOMEM
421 Unable to allocate memory for internal tables.
422 .SH VERSIONS
423 On some other UNIX systems,
424 .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
425 .BR select ()
426 can fail with the error
427 .B EAGAIN
428 if the system fails to allocate kernel-internal resources, rather than
429 .B ENOMEM
430 as Linux does.
431 POSIX specifies this error for
432 .BR poll (2),
433 but not for
434 .BR select ().
435 Portable programs may wish to check for
436 .B EAGAIN
437 and loop, just as with
438 .BR EINTR .
439 .SH STANDARDS
440 POSIX.1-2024.
441 .SH HISTORY
442 .TP
443 .BR select ()
444 POSIX.1-2001, 4.4BSD (first appeared in 4.2BSD).
445 .IP
446 Generally portable to/from
447 non-BSD systems supporting clones of the BSD socket layer (including
448 System\ V variants).
449 However, note that the System\ V variant typically
450 sets the timeout variable before returning, but the BSD variant does not.
451 .TP
452 .BR pselect ()
453 Linux 2.6.16.
454 POSIX.1g, POSIX.1-2001.
455 .IP
456 Prior to this,
457 it was emulated in glibc (but see BUGS).
458 .TP
459 .B fd_set
460 POSIX.1-2001.
461 .SH NOTES
462 The following header also provides the
463 .I fd_set
464 type:
465 .IR <sys/time.h> .
466 .P
467 An
468 .I fd_set
469 is a fixed size buffer.
470 Executing
471 .BR FD_CLR ()
472 or
473 .BR FD_SET ()
474 with a value of
475 .I fd
476 that is negative or is equal to or larger than
477 .B FD_SETSIZE
478 will result
479 in undefined behavior.
480 Moreover, POSIX requires
481 .I fd
482 to be a valid file descriptor.
483 .P
484 The operation of
485 .BR select ()
486 and
487 .BR pselect ()
488 is not affected by the
489 .B O_NONBLOCK
490 flag.
491 .\"
492 .SS The self-pipe trick
493 On systems that lack
494 .BR pselect (),
495 reliable (and more portable) signal trapping can be achieved
496 using the self-pipe trick.
497 In this technique,
498 a signal handler writes a byte to a pipe whose other end
499 is monitored by
500 .BR select ()
501 in the main program.
502 (To avoid possibly blocking when writing to a pipe that may be full
503 or reading from a pipe that may be empty,
504 nonblocking I/O is used when reading from and writing to the pipe.)
505 .\"
506 .SS Emulating usleep(3)
507 Before the advent of
508 .BR usleep (3),
509 some code employed a call to
510 .BR select ()
511 with all three sets empty,
512 .I nfds
513 zero, and a non-NULL
514 .I timeout
515 as a fairly portable way to sleep with subsecond precision.
516 .\"
517 .SS Correspondence between select() and poll() notifications
518 Within the Linux kernel source,
519 .\" fs/select.c
520 we find the following definitions which show the correspondence
521 between the readable, writable, and exceptional condition notifications of
522 .BR select ()
523 and the event notifications provided by
524 .BR poll (2)
525 and
526 .BR epoll (7):
527 .P
528 .in +4n
529 .EX
530 #define POLLIN_SET (EPOLLRDNORM | EPOLLRDBAND | EPOLLIN |
531 EPOLLHUP | EPOLLERR)
532 /* Ready for reading */
533 #define POLLOUT_SET (EPOLLWRBAND | EPOLLWRNORM | EPOLLOUT |
534 EPOLLERR)
535 /* Ready for writing */
536 #define POLLEX_SET (EPOLLPRI)
537 /* Exceptional condition */
538 .EE
539 .in
540 .\"
541 .SS Multithreaded applications
542 If a file descriptor being monitored by
543 .BR select ()
544 is closed in another thread, the result is unspecified.
545 On some UNIX systems,
546 .BR select ()
547 unblocks and returns, with an indication that the file descriptor is ready
548 (a subsequent I/O operation will likely fail with an error,
549 unless another process reopens the file descriptor between the time
550 .BR select ()
551 returned and the I/O operation is performed).
552 On Linux (and some other systems),
553 closing the file descriptor in another thread has no effect on
554 .BR select ().
555 In summary, any application that relies on a particular behavior
556 in this scenario must be considered buggy.
557 .\"
558 .SS C library/kernel differences
559 The Linux kernel allows file descriptor sets of arbitrary size,
560 determining the length of the sets to be checked from the value of
561 .IR nfds .
562 However, in the glibc implementation, the
563 .I fd_set
564 type is fixed in size.
565 See also BUGS.
566 .P
567 The
568 .BR pselect ()
569 interface described in this page is implemented by glibc.
570 The underlying Linux system call is named
571 .BR pselect6 ().
572 This system call has somewhat different behavior from the glibc
573 wrapper function.
574 .P
575 The Linux
576 .BR pselect6 ()
577 system call modifies its
578 .I timeout
579 argument.
580 However, the glibc wrapper function hides this behavior
581 by using a local variable for the timeout argument that
582 is passed to the system call.
583 Thus, the glibc
584 .BR pselect ()
585 function does not modify its
586 .I timeout
587 argument;
588 this is the behavior required by POSIX.1-2001.
589 .P
590 The final argument of the
591 .BR pselect6 ()
592 system call is not a
593 .I "sigset_t\ *"
594 pointer, but is instead a structure of the form:
595 .P
596 .in +4n
597 .EX
598 struct {
599 const kernel_sigset_t *ss; /* Pointer to signal set */
600 size_t ss_len; /* Size (in bytes) of object
601 pointed to by \[aq]ss\[aq] */
602 };
603 .EE
604 .in
605 .P
606 This allows the system call to obtain both
607 a pointer to the signal set and its size,
608 while allowing for the fact that most architectures
609 support a maximum of 6 arguments to a system call.
610 See
611 .BR sigprocmask (2)
612 for a discussion of the difference between the kernel and libc
613 notion of the signal set.
614 .\"
615 .SS Historical glibc details
616 glibc 2.0 provided an incorrect version of
617 .BR pselect ()
618 that did not take a
619 .I sigmask
620 argument.
621 .P
622 From glibc 2.1 to glibc 2.2.1,
623 one must define
624 .B _GNU_SOURCE
625 in order to obtain the declaration of
626 .BR pselect ()
627 from
628 .IR <sys/select.h> .
629 .SH BUGS
630 POSIX allows an implementation to define an upper limit,
631 advertised via the constant
632 .BR FD_SETSIZE ,
633 on the range of file descriptors that can be specified
634 in a file descriptor set.
635 The Linux kernel imposes no fixed limit, but the glibc implementation makes
636 .I fd_set
637 a fixed-size type, with
638 .B FD_SETSIZE
639 defined as 1024, and the
640 .BR FD_* ()
641 macros operating according to that limit.
642 To monitor file descriptors greater than 1023, use
643 .BR poll (2)
644 or
645 .BR epoll (7)
646 instead.
647 .P
648 The implementation of the
649 .I fd_set
650 arguments as value-result arguments is a design error that is avoided in
651 .BR poll (2)
652 and
653 .BR epoll (7).
654 .P
655 According to POSIX,
656 .BR select ()
657 should check all specified file descriptors in the three file descriptor sets,
658 up to the limit
659 .IR nfds\-1 .
660 However, the current implementation ignores any file descriptor in
661 these sets that is greater than the maximum file descriptor number
662 that the process currently has open.
663 According to POSIX, any such file descriptor that is specified in one
664 of the sets should result in the error
665 .BR EBADF .
666 .P
667 Starting with glibc 2.1, glibc provided an emulation of
668 .BR pselect ()
669 that was implemented using
670 .BR sigprocmask (2)
671 and
672 .BR select ().
673 This implementation remained vulnerable to the very race condition that
674 .BR pselect ()
675 was designed to prevent.
676 Modern versions of glibc use the (race-free)
677 .BR pselect ()
678 system call on kernels where it is provided.
679 .P
680 On Linux,
681 .BR select ()
682 may report a socket file descriptor as "ready for reading", while
683 nevertheless a subsequent read blocks.
684 This could for example
685 happen when data has arrived but upon examination has the wrong
686 checksum and is discarded.
687 There may be other circumstances
688 in which a file descriptor is spuriously reported as ready.
689 .\" Stevens discusses a case where accept can block after select
690 .\" returns successfully because of an intervening RST from the client.
691 Thus it may be safer to use
692 .B O_NONBLOCK
693 on sockets that should not block.
694 .\" Maybe the kernel should have returned EIO in such a situation?
695 .P
696 On Linux,
697 .BR select ()
698 also modifies
699 .I timeout
700 if the call is interrupted by a signal handler (i.e., the
701 .B EINTR
702 error return).
703 This is not permitted by POSIX.1.
704 The Linux
705 .BR pselect ()
706 system call has the same behavior,
707 but the glibc wrapper hides this behavior by internally copying the
708 .I timeout
709 to a local variable and passing that variable to the system call.
710 .SH EXAMPLES
711 .\" SRC BEGIN (select.c)
712 .EX
713 #include <stdio.h>
714 #include <stdlib.h>
715 #include <sys/select.h>
716 #include <sys/time.h>
717 \&
718 int
719 main(void)
720 {
721 int retval;
722 fd_set rfds;
723 struct timeval tv;
724 \&
725 /* Watch stdin (fd 0) to see when it has input. */
726 \&
727 FD_ZERO(&rfds);
728 FD_SET(0, &rfds);
729 \&
730 /* Wait up to five seconds. */
731 \&
732 tv.tv_sec = 5;
733 tv.tv_usec = 0;
734 \&
735 retval = select(1, &rfds, NULL, NULL, &tv);
736 /* Don\[aq]t rely on the value of tv now! */
737 \&
738 if (retval == \-1)
739 perror("select()");
740 else if (retval)
741 printf("Data is available now.\[rs]n");
742 /* FD_ISSET(0, &rfds) will be true. */
743 else
744 printf("No data within five seconds.\[rs]n");
745 \&
746 exit(EXIT_SUCCESS);
747 }
748 .EE
749 .\" SRC END
750 .SH SEE ALSO
751 .BR accept (2),
752 .BR connect (2),
753 .BR poll (2),
754 .BR read (2),
755 .BR recv (2),
756 .BR restart_syscall (2),
757 .BR send (2),
758 .BR sigprocmask (2),
759 .BR write (2),
760 .BR timespec (3),
761 .BR epoll (7),
762 .BR time (7)
763 .P
764 For a tutorial with discussion and examples, see
765 .BR select_tut (2).