| blob | 5379c38470bdc2eaf8320a558ec2185cb72b1ac7 |
1 .\" $NetBSD: select.2,v 1.38 2010/04/05 21:25:56 joerg Exp $
2 .\"
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)select.2 8.2 (Berkeley) 3/25/94
31 .\"
32 .Dd October 18, 2008
33 .Dt SELECT 2
34 .Os
35 .Sh NAME
36 .Nm select ,
37 .Nm pselect
38 .Nd synchronous I/O multiplexing
39 .Sh LIBRARY
40 .Lb libc
41 .Sh SYNOPSIS
42 .In sys/select.h
43 .Ft int
44 .Fn select "int nfds" "fd_set * restrict readfds" "fd_set * restrict writefds" "fd_set * restrict exceptfds" "struct timeval * restrict timeout"
45 .Ft int
46 .Fn pselect "int nfds" "fd_set * restrict readfds" "fd_set * restrict writefds" "fd_set * restrict exceptfds" "const struct timespec *restrict timeout" "const sigset_t * restrict sigmask"
47 .Fn FD_SET "int fd" "fd_set *fdset"
48 .Fn FD_CLR "int fd" "fd_set *fdset"
49 .Fn FD_ISSET "int fd" "fd_set *fdset"
50 .Fn FD_ZERO "fd_set *fdset"
51 .Sh DESCRIPTION
52 .Fn select
53 and
54 .Fn pselect
55 examine the I/O descriptor sets whose addresses are passed in
56 .Fa readfds ,
57 .Fa writefds ,
58 and
59 .Fa exceptfds
60 to see if some of their descriptors
61 are ready for reading, are ready for writing, or have an exceptional
62 condition pending, respectively.
63 The first
64 .Fa nfds
65 descriptors are checked in each set;
66 i.e., the descriptors from 0 through
67 .Fa nfds Ns No \-1
68 in the descriptor sets are examined.
69 This means that
70 .Fa nfds
71 must be set to the highest file descriptor of the three sets, plus one.
72 On return,
73 .Fn select
74 and
75 .Fn pselect
76 replace the given descriptor sets
77 with subsets consisting of those descriptors that are ready
78 for the requested operation.
79 .Fn select
80 and
81 .Fn pselect
82 return the total number of ready descriptors in all the sets.
83 .Pp
84 The descriptor sets are stored as bit fields in arrays of integers.
85 The following macros are provided for manipulating such descriptor sets:
86 .Fn FD_ZERO fdset
87 initializes a descriptor set pointed to by
88 .Fa fdset
89 to the null set.
90 .Fn FD_SET fd fdset
91 includes a particular descriptor
92 .Fa fd
93 in
94 .Fa fdset .
95 .Fn FD_CLR fd fdset
96 removes
97 .Fa fd
98 from
99 .Fa fdset .
100 .Fn FD_ISSET fd fdset
101 is non-zero if
102 .Fa fd
103 is a member of
104 .Fa fdset ,
105 zero otherwise.
106 The behavior of these macros is undefined if
107 a descriptor value is less than zero or greater than or equal to
108 .Dv FD_SETSIZE ,
109 which is normally at least equal
110 to the maximum number of descriptors supported by the system.
111 .Pp
112 If
113 .Fa timeout
114 is a non-null pointer, it specifies a maximum interval to wait for the
115 selection to complete.
116 If
117 .Fa timeout
118 is a null pointer, the select blocks indefinitely.
119 To poll without blocking, the
120 .Fa timeout
121 argument should be non-null, pointing to a zero-valued timeval or timespec
122 structure, as appropriate.
123 .Fa timeout
124 is not changed by
125 .Fn select ,
126 and may be reused on subsequent calls; however, it is good style to
127 re-initialize it before each invocation of
128 .Fn select .
129 .Pp
130 If
131 .Fa sigmask
132 is a non-null pointer, then the
133 .Fn pselect
134 function shall replace the signal mask of the caller by the set of
135 signals pointed to by
136 .Fa sigmask
137 before examining the descriptors, and shall restore the signal mask
138 of the calling thread before returning.
139 .Pp
140 Any of
141 .Fa readfds ,
142 .Fa writefds ,
143 and
144 .Fa exceptfds
145 may be given as null pointers if no descriptors are of interest.
146 .Sh NOTES
147 It is recommended to use the
148 .Xr poll 2
149 interface instead, which tends to be more portable and efficient.
150 .Sh RETURN VALUES
151 .Fn select
152 returns the number of ready descriptors that are contained in
153 the descriptor sets,
154 or \-1 if an error occurred.
155 If the time limit expires,
156 .Fn select
157 returns 0.
158 If
159 .Fn select
160 returns with an error,
161 including one due to an interrupted call,
162 the descriptor sets will be unmodified.
163 .Sh EXAMPLES
164 .Bd -literal
165 #include \*[Lt]stdio.h\*[Gt]
166 #include \*[Lt]stdlib.h\*[Gt]
167 #include \*[Lt]unistd.h\*[Gt]
168 #include \*[Lt]string.h\*[Gt]
169 #include \*[Lt]err.h\*[Gt]
170 #include \*[Lt]errno.h\*[Gt]
171 #include \*[Lt]sys/types.h\*[Gt]
172 #include \*[Lt]sys/time.h\*[Gt]
174 int
175 main(int argc, char **argv)
176 {
177 fd_set read_set;
178 struct timeval timeout;
179 int ret, fd, i;
181 /* file descriptor 1 is stdout */
182 fd = 1;
184 /* Wait for ten seconds. */
185 timeout.tv_sec = 10;
186 timeout.tv_usec = 0;
188 /* Initialize the read set to null */
189 FD_ZERO(\*[Am]read_set);
191 /* Add file descriptor 1 to read_set */
192 FD_SET(fd, \*[Am]read_set);
194 /*
195 * Check if data is ready to be readen on
196 * file descriptor 1, give up after 10 seconds.
197 */
198 ret = select(fd + 1, \*[Am]read_set, NULL, NULL, \*[Am]timeout);
200 /*
201 * Returned value is the number of file
202 * descriptors ready for I/O, or -1 on error.
203 */
204 switch (ret) {
205 case \-1:
206 err(EXIT_FAILURE, "select() failed");
207 break;
209 case 0:
210 printf("Timeout, no data received.\en");
211 break;
213 default:
214 printf("Data received on %d file desciptor(s)\en", ret);
216 /*
217 * select(2) hands back a file descriptor set where
218 * only descriptors ready for I/O are set. These can
219 * be tested using FD_ISSET
220 */
221 for (i = 0; i \*[Lt]= fd; i++) {
222 if (FD_ISSET(i, \*[Am]read_set)) {
223 printf("Data on file descriptor %d\en", i);
224 /* Remove the file descriptor from the set */
225 FD_CLR(fd, \*[Am]read_set);
226 }
227 }
228 break;
229 }
231 return 0;
232 }
233 .Ed
234 .Sh ERRORS
235 An error return from
236 .Fn select
237 indicates:
238 .Bl -tag -width Er
239 .It Bq Er EBADF
240 One of the descriptor sets specified an invalid descriptor.
241 .It Bq Er EFAULT
242 One or more of
243 .Fa readfds ,
244 .Fa writefds ,
245 or
246 .Fa exceptfds
247 points outside the process's allocated address space.
248 .It Bq Er EINTR
249 A signal was delivered before the time limit expired and
250 before any of the selected events occurred.
251 .It Bq Er EINVAL
252 The specified time limit is invalid.
253 One of its components is negative or too large.
254 .El
255 .Sh SEE ALSO
256 .Xr accept 2 ,
257 .Xr connect 2 ,
258 .Xr gettimeofday 2 ,
259 .Xr poll 2 ,
260 .Xr read 2 ,
261 .Xr recv 2 ,
262 .Xr send 2 ,
263 .Xr write 2 ,
264 .Xr getdtablesize 3
265 .Sh HISTORY
266 The
267 .Fn select
268 function call appeared in
269 .Bx 4.2 .
270 .Sh BUGS
271 Although the provision of
272 .Xr getdtablesize 3
273 was intended to allow user programs to be written independent
274 of the kernel limit on the number of open files, the dimension
275 of a sufficiently large bit field for select remains a problem.
276 The default bit size of
277 .Ft fd_set
278 is based on the symbol
279 .Dv FD_SETSIZE
280 (currently 256),
281 but that is somewhat smaller than the current kernel limit
282 to the number of open files.
283 However, in order to accommodate programs which might potentially
284 use a larger number of open files with select, it is possible
285 to increase this size within a program by providing
286 a larger definition of
287 .Dv FD_SETSIZE
288 before the inclusion of
289 .In sys/types.h .
290 The kernel will cope, and the userland libraries provided with the
291 system are also ready for large numbers of file descriptors.
292 .Pp
293 Note:
294 .Xr rpc 3
295 library uses
296 .Ft fd_set
297 with the default
298 .Dv FD_SETSIZE
299 as part of its ABI.
300 Therefore, programs that use
301 .Xr rpc 3
302 routines cannot change
303 .Dv FD_SETSIZE .
304 .Pp
305 Alternatively, to be really safe, it is possible to allocate
306 .Ft fd_set
307 bit-arrays dynamically.
308 The idea is to permit a program to work properly even if it is
309 .Xr execve 2 Ns 'd
310 with 4000 file descriptors pre-allocated.
311 The following illustrates the technique which is used by
312 userland libraries:
313 .Pp
314 .Bd -literal -offset indent -compact
315 fd_set *fdsr;
316 int max = fd;
318 fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
319 sizeof(fd_mask));
320 if (fdsr == NULL) {
321 ...
322 return (-1);
323 }
324 FD_SET(fd, fdsr);
325 n = select(max+1, fdsr, NULL, NULL, \*[Am]tv);
326 ...
327 free(fdsr);
328 .Ed
329 .Pp
330 .Fn select
331 should probably have been designed to return the time remaining from the
332 original timeout, if any, by modifying the time value in place.
333 Even though some systems stupidly act in this different way, it is
334 unlikely this semantic will ever be commonly implemented, as the
335 change causes massive source code compatibility problems.
336 Furthermore, recent new standards have dictated the current behaviour.
337 In general, due to the existence of those
338 non-conforming systems, it is unwise to assume that the timeout
339 value will be unmodified by the
340 .Fn select
341 call, and the caller should reinitialize it on each invocation.
342 Calculating the delta is easily done by calling
343 .Xr gettimeofday 2
344 before and after the call to
345 .Fn select ,
346 and using
347 .Fn timersub
348 (as described in
349 .Xr getitimer 2 ) .
350 .Pp
351 Internally to the kernel,
352 .Fn select
353 works poorly if multiple processes wait on the same file descriptor.