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