]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" This manpage is copyright (C) 1992 Drew Eckhardt, | |
4 | .\" copyright (C) 1995 Michael Shields. | |
5 | .\" | |
6 | .\" Permission is granted to make and distribute verbatim copies of this | |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
14 | .\" | |
15 | .\" Since the Linux kernel and libraries are constantly changing, this | |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
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 | .\" |
d02aa9bc | 38 | .TH SELECT 2 2006-03-11 "Linux 2.6.16" "Linux Programmer's Manual" |
fea681da MK |
39 | .SH NAME |
40 | select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \- synchronous I/O multiplexing | |
41 | .SH SYNOPSIS | |
cc9befa9 | 42 | .nf |
fea681da MK |
43 | /* According to POSIX 1003.1-2001 */ |
44 | .br | |
45 | .B #include <sys/select.h> | |
46 | .sp | |
47 | /* According to earlier standards */ | |
48 | .br | |
49 | .B #include <sys/time.h> | |
50 | .br | |
51 | .B #include <sys/types.h> | |
52 | .br | |
53 | .B #include <unistd.h> | |
54 | .sp | |
6efed4df | 55 | \fBint select(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, |
cc9befa9 | 56 | fd_set *\fIexceptfds\fB, struct timeval *\fItimeout\fB); |
fea681da | 57 | .sp |
071dbad9 | 58 | .BI "void FD_CLR(int " fd ", fd_set *" set ); |
fea681da | 59 | .br |
071dbad9 | 60 | .BI "int FD_ISSET(int " fd ", fd_set *" set ); |
fea681da | 61 | .br |
071dbad9 | 62 | .BI "void FD_SET(int " fd ", fd_set *" set ); |
fea681da | 63 | .br |
071dbad9 | 64 | .BI "void FD_ZERO(fd_set *" set ); |
9b813741 MK |
65 | .sp |
66 | .B #define _XOPEN_SOURCE 600 | |
67 | .B #include <sys/select.h> | |
68 | .sp | |
6efed4df | 69 | \fBint pselect(int \fInfds\fB, fd_set *\fIreadfds\fB, fd_set *\fIwritefds\fB, |
616c0fd3 MK |
70 | fd_set *\fIexceptfds\fB, const struct timespec *\fItimeout\fB, |
71 | const sigset_t *\fIsigmask\fB); | |
fea681da MK |
72 | .fi |
73 | .SH DESCRIPTION | |
e511ffb6 | 74 | .BR select () |
fea681da | 75 | and |
e511ffb6 | 76 | .BR pselect () |
39179b3e | 77 | allow a program to monitor multiple file descriptors, |
5e01a1de MK |
78 | waiting until one or more of the file descriptors become "ready" |
79 | for some class of I/O operation (e.g., input possible). | |
39179b3e | 80 | A file descriptor is considered ready if it is possible to |
5e01a1de MK |
81 | perform the corresponding I/O operation (e.g., |
82 | .BR read (2)) | |
83 | without blocking. | |
fea681da | 84 | .PP |
5e01a1de MK |
85 | The operation of |
86 | .BR select () | |
87 | and | |
88 | .BR pselect () | |
89 | is identical, with three differences: | |
fea681da MK |
90 | .TP |
91 | (i) | |
e511ffb6 | 92 | .BR select () |
cc9befa9 | 93 | uses a timeout that is a |
fea681da MK |
94 | .I struct timeval |
95 | (with seconds and microseconds), while | |
e511ffb6 | 96 | .BR pselect () |
fea681da MK |
97 | uses a |
98 | .I struct timespec | |
99 | (with seconds and nanoseconds). | |
100 | .TP | |
101 | (ii) | |
e511ffb6 | 102 | .BR select () |
cc9befa9 | 103 | may update the |
fea681da | 104 | .I timeout |
cc9befa9 | 105 | argument to indicate how much time was left. |
e511ffb6 | 106 | .BR pselect () |
cc9befa9 | 107 | does not change this argument. |
fea681da MK |
108 | .TP |
109 | (iii) | |
e511ffb6 | 110 | .BR select () |
cc9befa9 | 111 | has no |
fea681da | 112 | .I sigmask |
cc9befa9 | 113 | argument, and behaves as |
e511ffb6 | 114 | .BR pselect () |
fea681da MK |
115 | called with NULL |
116 | .IR sigmask . | |
117 | .PP | |
22f348ca MK |
118 | Three independent sets of file descriptors are watched. |
119 | Those listed in | |
fea681da MK |
120 | .I readfds |
121 | will be watched to see if characters become | |
122 | available for reading (more precisely, to see if a read will not | |
e9496f74 | 123 | block; in particular, a file descriptor is also ready on end-of-file), |
fea681da MK |
124 | those in |
125 | .I writefds | |
126 | will be watched to see if a write will not block, and | |
127 | those in | |
128 | .I exceptfds | |
129 | will be watched for exceptions. On exit, the sets are modified in place | |
22f348ca MK |
130 | to indicate which file descriptors actually changed status. |
131 | Each of the three file descriptor sets may be specified as NULL | |
132 | if no file descriptors are to be watched for the corresponding class | |
133 | of events. | |
fea681da MK |
134 | .PP |
135 | Four macros are provided to manipulate the sets. | |
e511ffb6 | 136 | .BR FD_ZERO () |
21045df8 | 137 | clears a set. |
e511ffb6 | 138 | .BR FD_SET () |
fea681da | 139 | and |
e511ffb6 | 140 | .BR FD_CLR () |
22f348ca | 141 | respectively add and remove a given file descriptor from a set. |
e511ffb6 | 142 | .BR FD_ISSET () |
22f348ca MK |
143 | tests to see if a file descriptor is part of the set; |
144 | this is useful after | |
e511ffb6 | 145 | .BR select () |
fea681da MK |
146 | returns. |
147 | .PP | |
6efed4df | 148 | .I nfds |
22f348ca | 149 | is the highest-numbered file descriptor in any of the three sets, plus 1. |
fea681da MK |
150 | .PP |
151 | .I timeout | |
152 | is an upper bound on the amount of time elapsed before | |
e511ffb6 | 153 | .BR select () |
fea681da | 154 | returns. It may be zero, causing |
e511ffb6 | 155 | .BR select () |
fea681da MK |
156 | to return immediately. (This is useful for polling.) If |
157 | .I timeout | |
158 | is NULL (no timeout), | |
e511ffb6 | 159 | .BR select () |
fea681da MK |
160 | can block indefinitely. |
161 | .PP | |
162 | .I sigmask | |
163 | is a pointer to a signal mask (see | |
164 | .BR sigprocmask (2)); | |
165 | if it is not NULL, then | |
e511ffb6 | 166 | .BR pselect () |
fea681da MK |
167 | first replaces the current signal mask by the one pointed to by |
168 | .IR sigmask , | |
169 | then does the `select' function, and then restores the original | |
cc9befa9 | 170 | signal mask. |
fea681da | 171 | .PP |
d02aa9bc MK |
172 | Other than the difference in the precision of the |
173 | .I timeout | |
174 | argument, the following | |
175 | .BR pselect () | |
176 | call: | |
177 | .nf | |
178 | ||
6efed4df | 179 | ready = pselect(nfds, &readfds, &writefds, &exceptfds, |
d02aa9bc MK |
180 | timeout, &sigmask); |
181 | ||
182 | .fi | |
183 | is equivalent to | |
184 | .I atomically | |
185 | executing the following calls: | |
186 | .nf | |
187 | ||
188 | sigset_t origmask; | |
189 | ||
190 | sigprocmask(SIG_SETMASK, &sigmask, &origmask); | |
191 | ready = select(nfds, &readfds, &writefds, &exceptfds, timeout); | |
192 | sigprocmask(SIG_SETMASK, &origmask, NULL); | |
193 | .fi | |
194 | .PP | |
195 | The reason that | |
e511ffb6 | 196 | .BR pselect () |
d02aa9bc MK |
197 | is needed is that if one wants to wait for either a signal |
198 | or for a file descriptor to become ready, then | |
199 | an atomic test is needed to prevent race conditions. | |
200 | (Suppose the signal handler sets a global flag and | |
fea681da MK |
201 | returns. Then a test of this global flag followed by a call of |
202 | .BR select () | |
203 | could hang indefinitely if the signal arrived just after the test | |
d02aa9bc MK |
204 | but just before the call. |
205 | By contrast, | |
e511ffb6 | 206 | .BR pselect () |
fea681da MK |
207 | allows one to first block signals, handle the signals that have come in, |
208 | then call | |
209 | .BR pselect () | |
210 | with the desired | |
211 | .IR sigmask , | |
212 | avoiding the race.) | |
fea681da MK |
213 | .SS "The timeout" |
214 | The time structures involved are defined in | |
215 | .I <sys/time.h> | |
216 | and look like | |
217 | ||
2f11acf5 | 218 | .in +0.25i |
fea681da MK |
219 | .nf |
220 | struct timeval { | |
221 | long tv_sec; /* seconds */ | |
222 | long tv_usec; /* microseconds */ | |
223 | }; | |
224 | .fi | |
2f11acf5 | 225 | .in -0.25i |
fea681da MK |
226 | |
227 | and | |
228 | ||
2f11acf5 | 229 | .in +0.25i |
fea681da MK |
230 | .nf |
231 | struct timespec { | |
232 | long tv_sec; /* seconds */ | |
233 | long tv_nsec; /* nanoseconds */ | |
234 | }; | |
235 | .fi | |
2f11acf5 | 236 | .in -0.25i |
fea681da MK |
237 | |
238 | (However, see below on the POSIX 1003.1-2001 versions.) | |
239 | .PP | |
240 | Some code calls | |
e511ffb6 | 241 | .BR select () |
fea681da MK |
242 | with all three sets empty, |
243 | .I n | |
22f348ca | 244 | zero, and a non-NULL |
fea681da MK |
245 | .I timeout |
246 | as a fairly portable way to sleep with subsecond precision. | |
247 | .PP | |
cc9befa9 | 248 | On Linux, |
e511ffb6 | 249 | .BR select () |
fea681da MK |
250 | modifies |
251 | .I timeout | |
252 | to reflect the amount of time not slept; most other implementations | |
77f00d75 MK |
253 | do not do this. |
254 | (POSIX.1-2001 permits either behaviour.) | |
255 | This causes problems both when Linux code which reads | |
fea681da MK |
256 | .I timeout |
257 | is ported to other operating systems, and when code is ported to Linux | |
258 | that reuses a struct timeval for multiple | |
e511ffb6 | 259 | .BR select ()s |
fea681da MK |
260 | in a loop without reinitializing it. Consider |
261 | .I timeout | |
262 | to be undefined after | |
e511ffb6 | 263 | .BR select () |
fea681da MK |
264 | returns. |
265 | .\" .PP - it is rumoured that: | |
266 | .\" On BSD, when a timeout occurs, the file descriptor bits are not changed. | |
267 | .\" - it is certainly true that: | |
268 | .\" Linux follows SUSv2 and sets the bit masks to zero upon a timeout. | |
269 | .SH "RETURN VALUE" | |
270 | On success, | |
e511ffb6 | 271 | .BR select () |
fea681da | 272 | and |
e511ffb6 | 273 | .BR pselect () |
22f348ca MK |
274 | return the number of file descriptors contained in the three returned |
275 | descriptor sets (that is, the total number of bits that are set in | |
fea681da MK |
276 | .IR readfds , |
277 | .IR writefds , | |
278 | .IR exceptfds ) | |
279 | which may be zero if the timeout expires before anything interesting happens. | |
280 | On error, \-1 is returned, and | |
281 | .I errno | |
282 | is set appropriately; the sets and | |
283 | .I timeout | |
284 | become undefined, so do not | |
285 | rely on their contents after an error. | |
286 | .SH ERRORS | |
287 | .TP | |
288 | .B EBADF | |
289 | An invalid file descriptor was given in one of the sets. | |
6efed4df MK |
290 | (Perhaps a file descriptor that was already closed, |
291 | or one on which an error has occurred.) | |
fea681da MK |
292 | .TP |
293 | .B EINTR | |
6efed4df | 294 | A signal was caught. |
fea681da MK |
295 | .TP |
296 | .B EINVAL | |
6efed4df | 297 | .I nfds |
fea681da MK |
298 | is negative or the value contained within |
299 | .I timeout | |
300 | is invalid. | |
301 | .TP | |
302 | .B ENOMEM | |
6efed4df | 303 | unable to allocate memory for internal tables. |
fea681da MK |
304 | .SH EXAMPLE |
305 | .nf | |
306 | #include <stdio.h> | |
307 | #include <sys/time.h> | |
308 | #include <sys/types.h> | |
309 | #include <unistd.h> | |
310 | ||
311 | int | |
312 | main(void) { | |
313 | fd_set rfds; | |
314 | struct timeval tv; | |
315 | int retval; | |
316 | ||
317 | /* Watch stdin (fd 0) to see when it has input. */ | |
318 | FD_ZERO(&rfds); | |
319 | FD_SET(0, &rfds); | |
6efed4df | 320 | |
fea681da MK |
321 | /* Wait up to five seconds. */ |
322 | tv.tv_sec = 5; | |
323 | tv.tv_usec = 0; | |
324 | ||
325 | retval = select(1, &rfds, NULL, NULL, &tv); | |
326 | /* Don't rely on the value of tv now! */ | |
327 | ||
2bc2f479 | 328 | if (retval == \-1) |
fea681da MK |
329 | perror("select()"); |
330 | else if (retval) | |
331 | printf("Data is available now.\\n"); | |
332 | /* FD_ISSET(0, &rfds) will be true. */ | |
333 | else | |
334 | printf("No data within five seconds.\\n"); | |
335 | ||
336 | return 0; | |
337 | } | |
338 | .fi | |
339 | .SH "CONFORMING TO" | |
cc9befa9 MK |
340 | 4.4BSD |
341 | .RB ( select () | |
342 | first appeared in 4.2BSD). Generally portable to/from | |
fea681da MK |
343 | non-BSD systems supporting clones of the BSD socket layer (including |
344 | System V variants). However, note that the System V variant typically | |
345 | sets the timeout variable before exit, but the BSD variant does not. | |
346 | .PP | |
e511ffb6 | 347 | .BR pselect () |
cc9befa9 | 348 | is defined in IEEE Std 1003.1g-2000 (POSIX.1g), and in |
fea681da | 349 | POSIX 1003.1-2001. |
fea681da | 350 | .SH NOTES |
22f348ca MK |
351 | An |
352 | .I fd_set | |
353 | is a fixed size buffer. | |
354 | Executing | |
355 | .BR FD_CLR () | |
356 | or | |
357 | .BR FD_SET () | |
358 | with a value of | |
fea681da MK |
359 | .I fd |
360 | that is negative or is equal to or larger than FD_SETSIZE will result | |
361 | in undefined behavior. Moreover, POSIX requires | |
362 | .I fd | |
363 | to be a valid file descriptor. | |
364 | ||
365 | Concerning the types involved, the classical situation is that | |
22f348ca MK |
366 | the two fields of a |
367 | .I timeval | |
368 | structure are longs (as shown above), | |
369 | and the structure is defined in | |
fea681da MK |
370 | .IR <sys/time.h> . |
371 | The POSIX 1003.1-2001 situation is | |
372 | ||
373 | .RS | |
374 | .nf | |
375 | struct timeval { | |
376 | time_t tv_sec; /* seconds */ | |
377 | suseconds_t tv_usec; /* microseconds */ | |
378 | }; | |
379 | .fi | |
380 | .RE | |
381 | ||
22f348ca | 382 | where the structure is defined in |
fea681da | 383 | .I <sys/select.h> |
d883fde0 | 384 | and the data types |
22f348ca MK |
385 | .I time_t |
386 | and | |
387 | .I suseconds_t | |
388 | are defined in | |
fea681da MK |
389 | .IR <sys/types.h> . |
390 | .LP | |
391 | Concerning prototypes, the classical situation is that one should | |
392 | include | |
393 | .I <time.h> | |
394 | for | |
e511ffb6 | 395 | .BR select (). |
fea681da MK |
396 | The POSIX 1003.1-2001 situation is that one should include |
397 | .I <sys/select.h> | |
398 | for | |
e511ffb6 | 399 | .BR select () |
fea681da | 400 | and |
e511ffb6 | 401 | .BR pselect (). |
fea681da MK |
402 | Libc4 and libc5 do not have a |
403 | .I <sys/select.h> | |
404 | header; under glibc 2.0 and later this header exists. | |
405 | Under glibc 2.0 it unconditionally gives the wrong prototype for | |
e511ffb6 | 406 | .BR pselect (), |
fea681da | 407 | under glibc 2.1-2.2.1 it gives |
e511ffb6 | 408 | .BR pselect () |
fea681da MK |
409 | when |
410 | .B _GNU_SOURCE | |
411 | is defined, under glibc 2.2.2-2.2.4 it gives it when | |
412 | .B _XOPEN_SOURCE | |
413 | is defined and has a value of 600 or larger. | |
414 | No doubt, since POSIX 1003.1-2001, it should give the prototype by default. | |
cc9befa9 MK |
415 | .SH VERSIONS |
416 | .BR pselect () | |
417 | was added to Linux in kernel 2.6.16. | |
418 | ||
419 | Prior to this, | |
420 | .BR pselect () | |
421 | was emulated in glibc (but see BUGS). | |
77f00d75 MK |
422 | .SH "LINUX NOTES" |
423 | The Linux | |
424 | .BR pselect () | |
2f11acf5 MK |
425 | system call modifies its |
426 | .I timeout | |
427 | argument. | |
428 | However, the glibc wrapper function hides this behaviour | |
77f00d75 MK |
429 | by using a local variable for the timeout argument that |
430 | is passed to the system call. | |
431 | Thus, the glibc | |
432 | .BR pselect () | |
433 | function does not modify its timeout argument; | |
434 | this is the behaviour required by POSIX.1-2001. | |
fea681da | 435 | .SH BUGS |
cc9befa9 | 436 | Glibc 2.0 provided a version of |
e511ffb6 | 437 | .BR pselect () |
cc9befa9 MK |
438 | that did not take a |
439 | .I sigmask | |
440 | argument. | |
441 | ||
442 | Since version 2.1, glibc has provided an emulation of | |
443 | .BR pselect () | |
444 | that is implemented using | |
445 | .BR sigprocmask (2) | |
446 | and | |
447 | .BR select (). | |
448 | This implementation remains vulnerable to the very race condition that | |
449 | .BR pselect () | |
450 | was designed to prevent. | |
451 | On systems that lack | |
452 | .BR pselect () | |
453 | reliable (and more portable) signal trapping can be achieved | |
454 | using the self-pipe trick | |
455 | (where a signal handler writes a byte to a pipe whose other end | |
456 | is monitored by | |
457 | .BR select () | |
458 | in the main program.) | |
fea681da MK |
459 | |
460 | Under Linux, | |
e511ffb6 | 461 | .BR select () |
fea681da MK |
462 | may report a socket file descriptor as "ready for reading", while |
463 | nevertheless a subsequent read blocks. This could for example | |
464 | happen when data has arrived but upon examination has wrong | |
2f11acf5 MK |
465 | checksum and is discarded. There may be other circumstances |
466 | in which a file descriptor is spuriously reported as ready. | |
fea681da MK |
467 | .\" Stevens discusses a case where accept can block after select |
468 | .\" returns successfully because of an intervening RST from the client. | |
469 | Thus it may be safer to use O_NONBLOCK on sockets that should not block. | |
470 | .\" Maybe the kernel should have returned EIO in such a situation? | |
d02aa9bc MK |
471 | .\" |
472 | .\" FIXME select() (and pselect()?) also modify the timeout | |
777f5a9e | 473 | .\" on an EINTR error return; POSIX.1-2001 doesn't permit this. |
fea681da MK |
474 | .SH "SEE ALSO" |
475 | For a tutorial with discussion and examples, see | |
476 | .BR select_tut (2). | |
477 | .LP | |
478 | For vaguely related stuff, see | |
479 | .BR accept (2), | |
480 | .BR connect (2), | |
481 | .BR poll (2), | |
482 | .BR read (2), | |
483 | .BR recv (2), | |
484 | .BR send (2), | |
485 | .BR sigprocmask (2), | |
50e5322c | 486 | .BR write (2), |
6efed4df | 487 | .BR epoll (7), |
a8e7c990 | 488 | .BR feature_test_macros (7) |