Debian Codegraph @

upstream/debian-trixie/man2/select.2

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