]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" This manpage is copyright (C) 1992 Drew Eckhardt, |
2 | .\" copyright (C) 1995 Michael Shields. | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
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> | |
d02aa9bc MK |
35 | .\" 2005-03-11, mtk, modified pselect() text (it is now a system |
36 | .\" call in 2.6.16. | |
fea681da | 37 | .\" |
9ba01802 | 38 | .TH SELECT 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 39 | .SH NAME |
c13182ef | 40 | select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- |
35478399 | 41 | synchronous I/O multiplexing |
fea681da | 42 | .SH SYNOPSIS |
cc9befa9 | 43 | .nf |
e9419385 | 44 | /* According to POSIX.1-2001, POSIX.1-2008 */ |
fea681da | 45 | .B #include <sys/select.h> |
dbfe9c70 | 46 | .PP |
fea681da | 47 | /* According to earlier standards */ |
fea681da | 48 | .B #include <sys/time.h> |
fea681da | 49 | .B #include <sys/types.h> |
fea681da | 50 | .B #include <unistd.h> |
68e4db0a | 51 | .PP |
cc4615cc MK |
52 | .BI "int select(int " nfds ", fd_set *" readfds ", fd_set *" writefds , |
53 | .BI " fd_set *" exceptfds ", struct timeval *" timeout ); | |
68e4db0a | 54 | .PP |
071dbad9 | 55 | .BI "void FD_CLR(int " fd ", fd_set *" set ); |
521bf584 | 56 | .BI "int FD_ISSET(int " fd ", fd_set *" set ); |
071dbad9 | 57 | .BI "void FD_SET(int " fd ", fd_set *" set ); |
071dbad9 | 58 | .BI "void FD_ZERO(fd_set *" set ); |
f90f031e | 59 | |
9b813741 | 60 | .B #include <sys/select.h> |
68e4db0a | 61 | .PP |
cc4615cc MK |
62 | .BI "int pselect(int " nfds ", fd_set *" readfds ", fd_set *" writefds , |
63 | .BI " fd_set *" exceptfds ", const struct timespec *" timeout , | |
64 | .BI " const sigset_t *" sigmask ); | |
fea681da | 65 | .fi |
68e4db0a | 66 | .PP |
cc4615cc MK |
67 | .in -4n |
68 | Feature Test Macro Requirements for glibc (see | |
69 | .BR feature_test_macros (7)): | |
70 | .in | |
68e4db0a | 71 | .PP |
cc4615cc | 72 | .BR pselect (): |
a446ac0c | 73 | _POSIX_C_SOURCE\ >=\ 200112L |
fea681da | 74 | .SH DESCRIPTION |
e511ffb6 | 75 | .BR select () |
fea681da | 76 | and |
e511ffb6 | 77 | .BR pselect () |
39179b3e | 78 | allow a program to monitor multiple file descriptors, |
5e01a1de MK |
79 | waiting until one or more of the file descriptors become "ready" |
80 | for some class of I/O operation (e.g., input possible). | |
39179b3e | 81 | A file descriptor is considered ready if it is possible to |
d2e7d1bb | 82 | perform a corresponding I/O operation (e.g., |
43e3c551 MK |
83 | .BR read (2), |
84 | or a sufficiently small | |
85 | .BR write (2)) | |
86 | without blocking. | |
fea681da | 87 | .PP |
6b6e9185 | 88 | .BR select () |
6c345305 MK |
89 | can monitor only file descriptors numbers that are less than |
90 | .BR FD_SETSIZE ; | |
91 | .BR poll (2) | |
6b6e9185 | 92 | does not have this limitation. |
6c345305 | 93 | See BUGS. |
6b6e9185 | 94 | .PP |
5e01a1de MK |
95 | The operation of |
96 | .BR select () | |
97 | and | |
98 | .BR pselect () | |
8c1d94ae | 99 | is identical, other than these three differences: |
fea681da MK |
100 | .TP |
101 | (i) | |
e511ffb6 | 102 | .BR select () |
cc9befa9 | 103 | uses a timeout that is a |
fea681da MK |
104 | .I struct timeval |
105 | (with seconds and microseconds), while | |
e511ffb6 | 106 | .BR pselect () |
fea681da MK |
107 | uses a |
108 | .I struct timespec | |
109 | (with seconds and nanoseconds). | |
110 | .TP | |
111 | (ii) | |
e511ffb6 | 112 | .BR select () |
cc9befa9 | 113 | may update the |
fea681da | 114 | .I timeout |
cc9befa9 | 115 | argument to indicate how much time was left. |
e511ffb6 | 116 | .BR pselect () |
cc9befa9 | 117 | does not change this argument. |
fea681da MK |
118 | .TP |
119 | (iii) | |
e511ffb6 | 120 | .BR select () |
cc9befa9 | 121 | has no |
fea681da | 122 | .I sigmask |
cc9befa9 | 123 | argument, and behaves as |
e511ffb6 | 124 | .BR pselect () |
fea681da MK |
125 | called with NULL |
126 | .IR sigmask . | |
127 | .PP | |
c13182ef | 128 | Three independent sets of file descriptors are watched. |
47da6ce7 | 129 | The file descriptors listed in |
fea681da MK |
130 | .I readfds |
131 | will be watched to see if characters become | |
132 | available for reading (more precisely, to see if a read will not | |
47da6ce7 MK |
133 | block; in particular, a file descriptor is also ready on end-of-file). |
134 | The file descriptors in | |
fea681da | 135 | .I writefds |
d2e7d1bb | 136 | will be watched to see if space is available for write (though a large |
47da6ce7 MK |
137 | write may still block). |
138 | The file descriptors in | |
fea681da | 139 | .I exceptfds |
47da6ce7 | 140 | will be watched for exceptional conditions. |
d871cf85 MK |
141 | (For examples of some exceptional conditions, see the discussion of |
142 | .B POLLPRI | |
143 | in | |
144 | .BR poll (2).) | |
efeece04 | 145 | .PP |
47da6ce7 | 146 | On exit, each of the file descriptor sets is modified in place |
22f348ca | 147 | to indicate which file descriptors actually changed status. |
cd2ea4b4 MK |
148 | (Thus, if using |
149 | .BR select () | |
150 | within a loop, the sets must be reinitialized before each call.) | |
efeece04 | 151 | .PP |
22f348ca | 152 | Each of the three file descriptor sets may be specified as NULL |
c13182ef | 153 | if no file descriptors are to be watched for the corresponding class |
22f348ca | 154 | of events. |
fea681da MK |
155 | .PP |
156 | Four macros are provided to manipulate the sets. | |
e511ffb6 | 157 | .BR FD_ZERO () |
21045df8 | 158 | clears a set. |
e511ffb6 | 159 | .BR FD_SET () |
fea681da | 160 | and |
e511ffb6 | 161 | .BR FD_CLR () |
83a9c27c | 162 | add and remove a given file descriptor from a set. |
e511ffb6 | 163 | .BR FD_ISSET () |
c13182ef | 164 | tests to see if a file descriptor is part of the set; |
22f348ca | 165 | this is useful after |
e511ffb6 | 166 | .BR select () |
fea681da MK |
167 | returns. |
168 | .PP | |
6efed4df | 169 | .I nfds |
8b58a9d4 MK |
170 | should be set to the highest-numbered file descriptor in any |
171 | of the three sets, plus 1. | |
172 | The indicated file descriptors in each set are checked, up to this limit | |
173 | (but see BUGS). | |
fea681da | 174 | .PP |
8c121f40 | 175 | The |
fea681da | 176 | .I timeout |
073f0240 | 177 | argument specifies the interval that |
e511ffb6 | 178 | .BR select () |
8c121f40 | 179 | should block waiting for a file descriptor to become ready. |
40df3d00 MK |
180 | The call will block until either: |
181 | .IP * 3 | |
182 | a file descriptor becomes ready; | |
183 | .IP * | |
184 | the call is interrupted by a signal handler; or | |
185 | .IP * | |
71e7d7f1 | 186 | the timeout expires. |
40df3d00 MK |
187 | .PP |
188 | Note that the | |
189 | .I timeout | |
190 | interval will be rounded up to the system clock granularity, | |
8c121f40 | 191 | and kernel scheduling delays mean that the blocking interval |
073f0240 | 192 | may overrun by a small amount. |
485eb4ad MK |
193 | If both fields of the |
194 | .I timeval | |
c808bb16 | 195 | structure are zero, then |
e511ffb6 | 196 | .BR select () |
485eb4ad | 197 | returns immediately. |
c13182ef MK |
198 | (This is useful for polling.) |
199 | If | |
fea681da MK |
200 | .I timeout |
201 | is NULL (no timeout), | |
e511ffb6 | 202 | .BR select () |
fea681da MK |
203 | can block indefinitely. |
204 | .PP | |
205 | .I sigmask | |
206 | is a pointer to a signal mask (see | |
207 | .BR sigprocmask (2)); | |
208 | if it is not NULL, then | |
e511ffb6 | 209 | .BR pselect () |
fea681da MK |
210 | first replaces the current signal mask by the one pointed to by |
211 | .IR sigmask , | |
2d986c92 | 212 | then does the "select" function, and then restores the original |
cc9befa9 | 213 | signal mask. |
fea681da | 214 | .PP |
d02aa9bc MK |
215 | Other than the difference in the precision of the |
216 | .I timeout | |
c13182ef | 217 | argument, the following |
d02aa9bc MK |
218 | .BR pselect () |
219 | call: | |
408731d4 MK |
220 | .PP |
221 | .in +4n | |
222 | .EX | |
223 | ready = pselect(nfds, &readfds, &writefds, &exceptfds, | |
224 | timeout, &sigmask); | |
225 | .EE | |
226 | .in | |
227 | .PP | |
d02aa9bc MK |
228 | is equivalent to |
229 | .I atomically | |
230 | executing the following calls: | |
408731d4 MK |
231 | .PP |
232 | .in +4n | |
233 | .EX | |
234 | sigset_t origmask; | |
d02aa9bc | 235 | |
408731d4 MK |
236 | pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); |
237 | ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); | |
238 | pthread_sigmask(SIG_SETMASK, &origmask, NULL); | |
239 | .EE | |
240 | .in | |
241 | .PP | |
d02aa9bc | 242 | .PP |
c13182ef | 243 | The reason that |
e511ffb6 | 244 | .BR pselect () |
d02aa9bc MK |
245 | is needed is that if one wants to wait for either a signal |
246 | or for a file descriptor to become ready, then | |
c13182ef | 247 | an atomic test is needed to prevent race conditions. |
d02aa9bc | 248 | (Suppose the signal handler sets a global flag and |
c13182ef MK |
249 | returns. |
250 | Then a test of this global flag followed by a call of | |
fea681da MK |
251 | .BR select () |
252 | could hang indefinitely if the signal arrived just after the test | |
c13182ef | 253 | but just before the call. |
d02aa9bc | 254 | By contrast, |
e511ffb6 | 255 | .BR pselect () |
fea681da MK |
256 | allows one to first block signals, handle the signals that have come in, |
257 | then call | |
258 | .BR pselect () | |
259 | with the desired | |
260 | .IR sigmask , | |
261 | avoiding the race.) | |
73d8cece | 262 | .SS The timeout |
fea681da MK |
263 | The time structures involved are defined in |
264 | .I <sys/time.h> | |
265 | and look like | |
efeece04 | 266 | .PP |
088a639b | 267 | .in +4n |
b8302363 | 268 | .EX |
c13182ef | 269 | struct timeval { |
fea681da MK |
270 | long tv_sec; /* seconds */ |
271 | long tv_usec; /* microseconds */ | |
272 | }; | |
b8302363 | 273 | .EE |
a08ea57c | 274 | .in |
efeece04 | 275 | .PP |
fea681da | 276 | and |
efeece04 | 277 | .PP |
088a639b | 278 | .in +4n |
b8302363 | 279 | .EX |
fea681da MK |
280 | struct timespec { |
281 | long tv_sec; /* seconds */ | |
282 | long tv_nsec; /* nanoseconds */ | |
283 | }; | |
b8302363 | 284 | .EE |
a08ea57c | 285 | .in |
efeece04 | 286 | .PP |
e9419385 | 287 | (However, see below on the POSIX.1 versions.) |
fea681da MK |
288 | .PP |
289 | Some code calls | |
e511ffb6 | 290 | .BR select () |
fea681da | 291 | with all three sets empty, |
79b8032e | 292 | .I nfds |
22f348ca | 293 | zero, and a non-NULL |
fea681da MK |
294 | .I timeout |
295 | as a fairly portable way to sleep with subsecond precision. | |
296 | .PP | |
c13182ef | 297 | On Linux, |
e511ffb6 | 298 | .BR select () |
fea681da MK |
299 | modifies |
300 | .I timeout | |
301 | to reflect the amount of time not slept; most other implementations | |
77f00d75 | 302 | do not do this. |
e9419385 | 303 | (POSIX.1 permits either behavior.) |
77f00d75 | 304 | This causes problems both when Linux code which reads |
fea681da MK |
305 | .I timeout |
306 | is ported to other operating systems, and when code is ported to Linux | |
0c2ec4f1 | 307 | that reuses a \fIstruct timeval\fP for multiple |
e511ffb6 | 308 | .BR select ()s |
c13182ef MK |
309 | in a loop without reinitializing it. |
310 | Consider | |
fea681da MK |
311 | .I timeout |
312 | to be undefined after | |
e511ffb6 | 313 | .BR select () |
fea681da | 314 | returns. |
d9bfdb9c | 315 | .\" .PP - it is rumored that: |
fea681da MK |
316 | .\" On BSD, when a timeout occurs, the file descriptor bits are not changed. |
317 | .\" - it is certainly true that: | |
318 | .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. | |
47297adb | 319 | .SH RETURN VALUE |
fea681da | 320 | On success, |
e511ffb6 | 321 | .BR select () |
fea681da | 322 | and |
e511ffb6 | 323 | .BR pselect () |
22f348ca MK |
324 | return the number of file descriptors contained in the three returned |
325 | descriptor sets (that is, the total number of bits that are set in | |
fea681da MK |
326 | .IR readfds , |
327 | .IR writefds , | |
328 | .IR exceptfds ) | |
329 | which may be zero if the timeout expires before anything interesting happens. | |
330 | On error, \-1 is returned, and | |
331 | .I errno | |
8dc33675 MK |
332 | is set to indicate the error; |
333 | the file descriptor sets are unmodified, | |
334 | and | |
fea681da | 335 | .I timeout |
8dc33675 | 336 | becomes undefined. |
fea681da MK |
337 | .SH ERRORS |
338 | .TP | |
339 | .B EBADF | |
340 | An invalid file descriptor was given in one of the sets. | |
c13182ef | 341 | (Perhaps a file descriptor that was already closed, |
6efed4df | 342 | or one on which an error has occurred.) |
8b58a9d4 | 343 | However, see BUGS. |
fea681da MK |
344 | .TP |
345 | .B EINTR | |
01538d0d MK |
346 | A signal was caught; see |
347 | .BR signal (7). | |
fea681da MK |
348 | .TP |
349 | .B EINVAL | |
6efed4df | 350 | .I nfds |
b9ebc9b7 MK |
351 | is negative or exceeds the |
352 | .BR RLIMIT_NOFILE | |
353 | resource limit (see | |
354 | .BR getrlimit (2)). | |
355 | .TP | |
356 | .B EINVAL | |
02959ce2 | 357 | The value contained within |
fea681da MK |
358 | .I timeout |
359 | is invalid. | |
360 | .TP | |
361 | .B ENOMEM | |
02959ce2 | 362 | Unable to allocate memory for internal tables. |
a1d5f77c MK |
363 | .SH VERSIONS |
364 | .BR pselect () | |
365 | was added to Linux in kernel 2.6.16. | |
366 | Prior to this, | |
367 | .BR pselect () | |
368 | was emulated in glibc (but see BUGS). | |
47297adb | 369 | .SH CONFORMING TO |
c13182ef | 370 | .BR select () |
e9419385 | 371 | conforms to POSIX.1-2001, POSIX.1-2008, and |
c13182ef | 372 | 4.4BSD |
cc9befa9 | 373 | .RB ( select () |
c13182ef MK |
374 | first appeared in 4.2BSD). |
375 | Generally portable to/from | |
fea681da | 376 | non-BSD systems supporting clones of the BSD socket layer (including |
efbfd7ec MK |
377 | System\ V variants). |
378 | However, note that the System\ V variant typically | |
fea681da MK |
379 | sets the timeout variable before exit, but the BSD variant does not. |
380 | .PP | |
e511ffb6 | 381 | .BR pselect () |
97c1eac8 | 382 | is defined in POSIX.1g, and in |
e9419385 | 383 | POSIX.1-2001 and POSIX.1-2008. |
fea681da | 384 | .SH NOTES |
c13182ef MK |
385 | An |
386 | .I fd_set | |
387 | is a fixed size buffer. | |
388 | Executing | |
22f348ca | 389 | .BR FD_CLR () |
c13182ef | 390 | or |
22f348ca MK |
391 | .BR FD_SET () |
392 | with a value of | |
fea681da | 393 | .I fd |
682edefb MK |
394 | that is negative or is equal to or larger than |
395 | .B FD_SETSIZE | |
396 | will result | |
c13182ef MK |
397 | in undefined behavior. |
398 | Moreover, POSIX requires | |
fea681da MK |
399 | .I fd |
400 | to be a valid file descriptor. | |
efeece04 | 401 | .PP |
e795580f MK |
402 | The operation of |
403 | .BR select () | |
404 | and | |
405 | .BR pselect () | |
406 | is not affected by the | |
407 | .BR O_NONBLOCK | |
408 | flag. | |
409 | .PP | |
20cc8fa8 MK |
410 | On some other UNIX systems, |
411 | .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett | |
412 | .BR select () | |
413 | can fail with the error | |
414 | .B EAGAIN | |
415 | if the system fails to allocate kernel-internal resources, rather than | |
416 | .B ENOMEM | |
417 | as Linux does. | |
418 | POSIX specifies this error for | |
419 | .BR poll (2), | |
420 | but not for | |
421 | .BR select (). | |
422 | Portable programs may wish to check for | |
423 | .B EAGAIN | |
424 | and loop, just as with | |
425 | .BR EINTR . | |
efeece04 | 426 | .PP |
3116bbe0 MK |
427 | On systems that lack |
428 | .BR pselect (), | |
429 | reliable (and more portable) signal trapping can be achieved | |
430 | using the self-pipe trick. | |
431 | In this technique, | |
432 | a signal handler writes a byte to a pipe whose other end | |
433 | is monitored by | |
434 | .BR select () | |
435 | in the main program. | |
436 | (To avoid possibly blocking when writing to a pipe that may be full | |
437 | or reading from a pipe that may be empty, | |
438 | nonblocking I/O is used when reading from and writing to the pipe.) | |
efeece04 | 439 | .PP |
fea681da | 440 | Concerning the types involved, the classical situation is that |
22f348ca | 441 | the two fields of a |
c13182ef | 442 | .I timeval |
e3e25559 MK |
443 | structure are typed as |
444 | .I long | |
445 | (as shown above), and the structure is defined in | |
fea681da | 446 | .IR <sys/time.h> . |
e9419385 | 447 | The POSIX.1 situation is |
efeece04 | 448 | .PP |
088a639b | 449 | .in +4n |
b8302363 | 450 | .EX |
fea681da MK |
451 | struct timeval { |
452 | time_t tv_sec; /* seconds */ | |
453 | suseconds_t tv_usec; /* microseconds */ | |
454 | }; | |
b8302363 | 455 | .EE |
a08ea57c | 456 | .in |
efeece04 | 457 | .PP |
22f348ca | 458 | where the structure is defined in |
fea681da | 459 | .I <sys/select.h> |
c13182ef MK |
460 | and the data types |
461 | .I time_t | |
462 | and | |
463 | .I suseconds_t | |
22f348ca | 464 | are defined in |
fea681da | 465 | .IR <sys/types.h> . |
dd3568a1 | 466 | .PP |
fea681da MK |
467 | Concerning prototypes, the classical situation is that one should |
468 | include | |
469 | .I <time.h> | |
470 | for | |
e511ffb6 | 471 | .BR select (). |
e9419385 | 472 | The POSIX.1 situation is that one should include |
fea681da MK |
473 | .I <sys/select.h> |
474 | for | |
e511ffb6 | 475 | .BR select () |
fea681da | 476 | and |
e511ffb6 | 477 | .BR pselect (). |
efeece04 | 478 | .PP |
083e5b2f MK |
479 | Under glibc 2.0, |
480 | .I <sys/select.h> | |
481 | gives the wrong prototype for | |
8b98e6fc | 482 | .BR pselect (). |
565ee767 | 483 | Under glibc 2.1 to 2.2.1, it gives |
e511ffb6 | 484 | .BR pselect () |
fea681da MK |
485 | when |
486 | .B _GNU_SOURCE | |
8b98e6fc | 487 | is defined. |
565ee767 | 488 | Since glibc 2.2.2, the requirements are as shown in the SYNOPSIS. |
ab264bff MK |
489 | .\" |
490 | .SS Correspondence between select() and poll() notifications | |
491 | Within the Linux kernel source, | |
492 | .\" fs/select.c | |
493 | we find the following definitions which show the correspondence | |
494 | between the readable, writable, and exceptional condition notifications of | |
495 | .BR select () | |
496 | and the event notifications provided by | |
497 | .BR poll (2) | |
498 | (and | |
499 | .BR epoll (7)): | |
efeece04 | 500 | .PP |
ab264bff | 501 | .in +4n |
b8302363 | 502 | .EX |
ab264bff MK |
503 | #define POLLIN_SET (POLLRDNORM | POLLRDBAND | POLLIN | POLLHUP | |
504 | POLLERR) | |
505 | /* Ready for reading */ | |
506 | #define POLLOUT_SET (POLLWRBAND | POLLWRNORM | POLLOUT | POLLERR) | |
507 | /* Ready for writing */ | |
508 | #define POLLEX_SET (POLLPRI) | |
509 | /* Exceptional condition */ | |
b8302363 | 510 | .EE |
e646a1ba | 511 | .in |
ab264bff | 512 | .\" |
10ed041e MK |
513 | .SS Multithreaded applications |
514 | If a file descriptor being monitored by | |
515 | .BR select () | |
516 | is closed in another thread, the result is unspecified. | |
517 | On some UNIX systems, | |
518 | .BR select () | |
519 | unblocks and returns, with an indication that the file descriptor is ready | |
520 | (a subsequent I/O operation will likely fail with an error, | |
be914947 | 521 | unless another process reopens file descriptor between the time |
10ed041e | 522 | .BR select () |
be914947 | 523 | returned and the I/O operation is performed). |
10ed041e MK |
524 | On Linux (and some other systems), |
525 | closing the file descriptor in another thread has no effect on | |
526 | .BR select (). | |
527 | In summary, any application that relies on a particular behavior | |
528 | in this scenario must be considered buggy. | |
17ec2d27 | 529 | .\" |
0722a578 | 530 | .SS C library/kernel differences |
6c345305 MK |
531 | The Linux kernel allows file descriptor sets of arbitrary size, |
532 | determining the length of the sets to be checked from the value of | |
533 | .IR nfds . | |
534 | However, in the glibc implementation, the | |
535 | .IR fd_set | |
536 | type is fixed in size. | |
537 | See also BUGS. | |
efeece04 | 538 | .PP |
a16eec1e | 539 | The |
77f00d75 | 540 | .BR pselect () |
a16eec1e MK |
541 | interface described in this page is implemented by glibc. |
542 | The underlying Linux system call is named | |
543 | .BR pselect6 (). | |
a59e64be | 544 | This system call has somewhat different behavior from the glibc |
a16eec1e | 545 | wrapper function. |
efeece04 | 546 | .PP |
a16eec1e MK |
547 | The Linux |
548 | .BR pselect6 () | |
c13182ef MK |
549 | system call modifies its |
550 | .I timeout | |
2f11acf5 | 551 | argument. |
d9bfdb9c | 552 | However, the glibc wrapper function hides this behavior |
77f00d75 MK |
553 | by using a local variable for the timeout argument that |
554 | is passed to the system call. | |
c13182ef | 555 | Thus, the glibc |
77f00d75 | 556 | .BR pselect () |
d53de2a7 MK |
557 | function does not modify its |
558 | .I timeout | |
559 | argument; | |
d9bfdb9c | 560 | this is the behavior required by POSIX.1-2001. |
efeece04 | 561 | .PP |
a16eec1e | 562 | The final argument of the |
02ace852 | 563 | .BR pselect6 () |
0ab8aeec | 564 | system call is not a |
a16eec1e MK |
565 | .I "sigset_t\ *" |
566 | pointer, but is instead a structure of the form: | |
408731d4 | 567 | .PP |
a16eec1e | 568 | .in +4 |
408731d4 | 569 | .EX |
a16eec1e | 570 | struct { |
1a116ea0 MK |
571 | const kernel_sigset_t *ss; /* Pointer to signal set */ |
572 | size_t ss_len; /* Size (in bytes) of object | |
573 | pointed to by 'ss' */ | |
a16eec1e | 574 | }; |
e646a1ba | 575 | .EE |
a16eec1e | 576 | .in |
e646a1ba | 577 | .PP |
a16eec1e MK |
578 | This allows the system call to obtain both |
579 | a pointer to the signal set and its size, | |
580 | while allowing for the fact that most architectures | |
f8dcca84 MK |
581 | support a maximum of 6 arguments to a system call. |
582 | See | |
583 | .BR sigprocmask (2) | |
f25ea51b N |
584 | for a discussion of the difference between the kernel and libc |
585 | notion of the signal set. | |
fea681da | 586 | .SH BUGS |
6c345305 MK |
587 | POSIX allows an implementation to define an upper limit, |
588 | advertised via the constant | |
589 | .BR FD_SETSIZE , | |
590 | on the range of file descriptors that can be specified | |
591 | in a file descriptor set. | |
592 | The Linux kernel imposes no fixed limit, but the glibc implementation makes | |
593 | .IR fd_set | |
594 | a fixed-size type, with | |
595 | .BR FD_SETSIZE | |
596 | defined as 1024, and the | |
597 | .BR FD_* () | |
598 | macros operating according to that limit. | |
599 | To monitor file descriptors greater than 1023, use | |
600 | .BR poll (2) | |
601 | instead. | |
efeece04 | 602 | .PP |
4c974cba MK |
603 | The implementation of the |
604 | .I fd_set | |
605 | arguments as value-result arguments means that they must be | |
606 | reinitialized on each call to | |
607 | .BR select (). | |
608 | This design error is avoided by | |
609 | .BR poll (2), | |
610 | which uses separate structure fields for the input and output of the call. | |
611 | .PP | |
8b58a9d4 MK |
612 | According to POSIX, |
613 | .BR select () | |
614 | should check all specified file descriptors in the three file descriptor sets, | |
615 | up to the limit | |
616 | .IR nfds\-1 . | |
617 | However, the current implementation ignores any file descriptor in | |
618 | these sets that is greater than the maximum file descriptor number | |
619 | that the process currently has open. | |
620 | According to POSIX, any such file descriptor that is specified in one | |
621 | of the sets should result in the error | |
622 | .BR EBADF . | |
efeece04 | 623 | .PP |
cc9befa9 | 624 | Glibc 2.0 provided a version of |
e511ffb6 | 625 | .BR pselect () |
c13182ef MK |
626 | that did not take a |
627 | .I sigmask | |
cc9befa9 | 628 | argument. |
efeece04 | 629 | .PP |
3fa2e4b9 | 630 | Starting with version 2.1, glibc provided an emulation of |
c13182ef | 631 | .BR pselect () |
3fa2e4b9 | 632 | that was implemented using |
cc9befa9 MK |
633 | .BR sigprocmask (2) |
634 | and | |
635 | .BR select (). | |
3fa2e4b9 | 636 | This implementation remained vulnerable to the very race condition that |
cc9befa9 MK |
637 | .BR pselect () |
638 | was designed to prevent. | |
3fa2e4b9 MK |
639 | Modern versions of glibc use the (race-free) |
640 | .BR pselect () | |
641 | system call on kernels where it is provided. | |
efeece04 | 642 | .PP |
fea681da | 643 | Under Linux, |
e511ffb6 | 644 | .BR select () |
fea681da | 645 | may report a socket file descriptor as "ready for reading", while |
c13182ef MK |
646 | nevertheless a subsequent read blocks. |
647 | This could for example | |
fea681da | 648 | happen when data has arrived but upon examination has wrong |
c13182ef MK |
649 | checksum and is discarded. |
650 | There may be other circumstances | |
2f11acf5 | 651 | in which a file descriptor is spuriously reported as ready. |
fea681da MK |
652 | .\" Stevens discusses a case where accept can block after select |
653 | .\" returns successfully because of an intervening RST from the client. | |
682edefb MK |
654 | Thus it may be safer to use |
655 | .B O_NONBLOCK | |
656 | on sockets that should not block. | |
fea681da | 657 | .\" Maybe the kernel should have returned EIO in such a situation? |
efeece04 | 658 | .PP |
5766b196 MK |
659 | On Linux, |
660 | .BR select () | |
661 | also modifies | |
662 | .I timeout | |
663 | if the call is interrupted by a signal handler (i.e., the | |
664 | .B EINTR | |
665 | error return). | |
e9419385 | 666 | This is not permitted by POSIX.1. |
5766b196 | 667 | The Linux |
2777b1ca | 668 | .BR pselect () |
5766b196 MK |
669 | system call has the same behavior, |
670 | but the glibc wrapper hides this behavior by internally copying the | |
671 | .I timeout | |
672 | to a local variable and passing that variable to the system call. | |
2b2581ee | 673 | .SH EXAMPLE |
408731d4 | 674 | .EX |
2b2581ee | 675 | #include <stdio.h> |
af9c7ff2 | 676 | #include <stdlib.h> |
2b2581ee MK |
677 | #include <sys/time.h> |
678 | #include <sys/types.h> | |
679 | #include <unistd.h> | |
680 | ||
681 | int | |
682 | main(void) | |
683 | { | |
684 | fd_set rfds; | |
685 | struct timeval tv; | |
686 | int retval; | |
687 | ||
688 | /* Watch stdin (fd 0) to see when it has input. */ | |
887f19e8 | 689 | |
2b2581ee MK |
690 | FD_ZERO(&rfds); |
691 | FD_SET(0, &rfds); | |
692 | ||
693 | /* Wait up to five seconds. */ | |
887f19e8 | 694 | |
2b2581ee MK |
695 | tv.tv_sec = 5; |
696 | tv.tv_usec = 0; | |
697 | ||
698 | retval = select(1, &rfds, NULL, NULL, &tv); | |
699 | /* Don't rely on the value of tv now! */ | |
700 | ||
701 | if (retval == \-1) | |
702 | perror("select()"); | |
703 | else if (retval) | |
d1a71985 | 704 | printf("Data is available now.\en"); |
2b2581ee MK |
705 | /* FD_ISSET(0, &rfds) will be true. */ |
706 | else | |
d1a71985 | 707 | printf("No data within five seconds.\en"); |
2b2581ee MK |
708 | |
709 | exit(EXIT_SUCCESS); | |
710 | } | |
408731d4 | 711 | .EE |
47297adb | 712 | .SH SEE ALSO |
fea681da MK |
713 | .BR accept (2), |
714 | .BR connect (2), | |
715 | .BR poll (2), | |
716 | .BR read (2), | |
717 | .BR recv (2), | |
25a7bfe6 | 718 | .BR restart_syscall (2), |
fea681da MK |
719 | .BR send (2), |
720 | .BR sigprocmask (2), | |
50e5322c | 721 | .BR write (2), |
1d7c4d16 MK |
722 | .BR epoll (7), |
723 | .BR time (7) | |
efeece04 | 724 | .PP |
173fe7e7 DP |
725 | For a tutorial with discussion and examples, see |
726 | .BR select_tut (2). |