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