| blob | 95c94d7e3b5d7db1af38f02bea2083814c8e9fe8 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
45 .\"
46 .Dd "Dec 28, 2016"
47 .Dt SELECT 3C
48 .Os
49 .Sh NAME
50 .Nm select ,
51 .Nm pselect ,
52 .Nm FD_SET ,
53 .Nm FD_CLR ,
54 .Nm FD_ISSET ,
55 .Nm FD_ZERO
56 .Nd synchronous I/O multiplexing
57 .Sh SYNOPSIS
58 .In sys/time.h
59 .Ft int
60 .Fo select
61 .Fa "int nfds"
62 .Fa "fd_set *restrict readfds"
63 .Fa "fd_set *restrict writefds"
64 .Fa "fd_set *restrict errorfds"
65 .Fa "struct timeval *restrict timeout"
66 .Fc
67 .Ft int
68 .Fo pselect
69 .Fa "int nfds"
70 .Fa "fd_set *restrict readfds"
71 .Fa "fd_set *restrict writefds"
72 .Fa "fd_set *restrict errorfds"
73 .Fa "const struct timespec *restrict timeout"
74 .Fa "const sigset_t *restrict sigmask"
75 .Fc
76 .Ft void
77 .Fo FD_SET
78 .Fa "int fd"
79 .Fa "fd_set *fdset"
80 .Fc
81 .Ft void
82 .Fo FD_CLR
83 .Fa "int fd"
84 .Fa "fd_set *fdset"
85 .Fc
86 .Ft int
87 .Fo FD_ISSET
88 .Fa "int fd"
89 .Fa "fd_set *fd_set"
90 .Fc
91 .Ft void
92 .Fo FD_ZERO
93 .Fa "fd_set *fdset"
94 .Fc
95 .Sh DESCRIPTION
96 The
97 .Fn pselect
98 function examines the file descriptor sets whose addresses
99 are passed in the
100 .Fa readfds ,
101 .Fa writefds ,
102 and
103 .Fa errorfds
104 parameters to see if some of their descriptors are ready for reading,
105 are ready for writing, or have an exceptional condition pending,
106 respectively.
107 .Pp
108 The
109 .Fn select
110 function is equivalent to the
111 .Fn pselect
112 function, except as follows:
113 .Bl -bullet
114 .It
115 For the
116 .Fn select
117 function, the timeout period is given in seconds and
118 microseconds in an argument of type
119 .Vt struct timeval ,
120 whereas for the
121 .Fn pselect
122 function the timeout period is given in seconds and nanoseconds
123 in an argument of type
124 .Vt struct timespec
125 .It
126 The
127 .Fn select
128 function has no
129 .Fa sigmask
130 argument.
131 It behaves as
132 .Fn pselect
133 does when
134 .Fa sigmask
135 is a null pointer.
136 .It
137 Upon successful completion, the
138 .Fn select
139 function might modify the object pointed to by the
140 .Fa Itimeout
141 argument.
142 .El
143 .Pp
144 The
145 .Fn select
146 and
147 .Fn pselect
148 functions support regular files, terminal and pseudo-terminal devices,
149 STREAMS-based files, FIFOs, pipes, and sockets.
150 The behavior of
151 .Fn select
152 and
153 .Fn pselect
154 on file descriptors that refer to other types of file is unspecified.
155 .Pp
156 The
157 .Fa nfds
158 argument specifies the range of file descriptors to be tested.
159 The first
160 .Fa nfds
161 descriptors are checked in each set; that is, the
162 descriptors from zero through
163 .Dq Li nfds - 1
164 in the descriptor sets are examined.
165 .Pp
166 If the
167 .Fa readfs
168 argument is not a null pointer, it points to an object of
169 type
170 .Vt fd_set
171 that on input specifies the file descriptors to be checked
172 for being ready to read, and on output indicates which file descriptors are
173 ready to read.
174 .Pp
175 If the
176 .Fa writefs
177 argument is not a null pointer, it points to an object of
178 type
179 .Vt fd_set
180 that on input specifies the file descriptors to be checked
181 for being ready to write, and on output indicates which file descriptors are
182 ready to write.
183 .Pp
184 If the
185 .Fa errorfds
186 argument is not a null pointer, it points to an object of
187 type
188 .Vt fd_set
189 that on input specifies the file descriptors to be checked
190 for error conditions pending, and on output indicates which file descriptors
191 have error conditions pending.
192 .Pp
193 Upon successful completion, the objects pointed to by the
194 .Fa readfs ,
195 .Fa writefs ,
196 and
197 .Fa errorfds
198 arguments are modified to indicate which file descriptors are ready for reading,
199 ready for writing, or have an error condition pending, respectively, and return
200 the total number of ready descriptors in all the output sets.
201 For each file descriptor less than
202 .Fa nfds ,
203 the corresponding bit will be set on successful completion if it was set on
204 input and the associated condition is true for that file descriptor.
205 .Pp
206 If none of the selected descriptors are ready for the requested operation, the
207 .Fn select
208 or
209 .Fn pselect
210 function blocks until at least one of the
211 requested operations becomes ready, until the timeout occurs, or until
212 interrupted by a signal.
213 The
214 .Fa timeout
215 parameter controls how long the
216 .Fn select
217 or
218 .Fn pselect
219 function takes before timing out.
220 If the
221 .Fa timeout
222 parameter is not a null pointer, it specifies a maximum interval
223 to wait for the selection to complete.
224 If the specified time interval expires without any requested operation becoming
225 ready, the function returns.
226 If the
227 .Fa timeout
228 parameter is a null pointer, then the call to
229 .Fn select
230 or
231 .Fn pselect
232 blocks indefinitely until at least one descriptor meets the
233 specified criteria.
234 To effect a poll, the
235 .Fa timeout
236 parameter should not be a null pointer, and should point to a zero-valued
237 .Vt timespec
238 structure.
239 .Pp
240 The use of a
241 .Fa timeout
242 does not affect any pending timers set up by
243 .Xr alarm 2 ,
244 .Xr ualarm 3C ,
245 or
246 .Xr setitimer 2 .
247 .Pp
248 If
249 .Fa sigmask
250 is not a null pointer, then the
251 .Fn pselect
252 function replaces the signal mask of the process by the set of signals pointed
253 to by
254 .Fa sigmask
255 before examining the descriptors, and restores the signal mask of
256 the process before returning.
257 .Pp
258 A descriptor is considered ready for reading when a call to an input function
259 with
260 .Dv O_NONBLOCK
261 clear would not block, whether or not the function would
262 transfer data successfully.
263 (The function might return data, an end-of-file indication, or an error other
264 than one indicating that it is blocked, and in each of these cases the
265 descriptor will be considered ready for reading.)
266 .Pp
267 A descriptor is considered ready for writing when a call to an output function
268 with
269 .Dv O_NONBLOCK
270 clear would not block, whether or not the function would
271 transfer data successfully.
272 .Pp
273 If a socket has a pending error, it is considered to have an exceptional
274 condition pending.
275 Otherwise, what constitutes an exceptional condition is file type-specific.
276 For a file descriptor for use with a socket, it is protocol-specific except as
277 noted below.
278 For other file types, if the operation is meaningless for a particular file
279 type,
280 .Fn select
281 or
282 .Fn pselect
283 indicates that the descriptor is ready for read or write operations and
284 indicates that the descriptor has no exceptional condition pending.
285 .Pp
286 If a descriptor refers to a socket, the implied input function is the
287 .Xr recvmsg 3XNET
288 function with parameters requesting normal and ancillary
289 data, such that the presence of either type causes the socket to be marked as
290 readable.
291 The presence of out-of-band data is checked if the socket option
292 .Dv SO_OOBINLINE
293 has been enabled, as out-of-band data is enqueued with
294 normal data.
295 If the socket is currently listening, then it is marked as readable if an
296 incoming connection request has been received, and a call to the accept function
297 completes without blocking.
298 .Pp
299 If a descriptor refers to a socket, the implied output function is the
300 .Xr sendmsg 3XNET
301 function supplying an amount of normal data equal to the
302 current value of the
303 .Dv SO_SNDLOWAT
304 option for the socket.
305 If a non-blocking call to the connect function has been made for a socket, and
306 the connection attempt has either succeeded or failed leaving a pending error,
307 the socket is marked as writable.
308 .Pp
309 A socket is considered to have an exceptional condition pending if a receive
310 operation with
311 .Dv O_NONBLOCK
312 clear for the open file description and with the
313 .Dv MSG_OOB
314 flag set would return out-of-band data without blocking.
315 (It is protocol-specific whether the
316 .Dv MSG_OOB
317 flag would be used to read out-of-band data.)
318 A socket will also be considered to have an exceptional condition pending if an
319 out-of-band data mark is present in the receive queue.
320 .Pp
321 A file descriptor for a socket that is listening for connections will indicate
322 that it is ready for reading, when connections are available.
323 A file descriptor for a socket that is connecting asynchronously will indicate
324 that it is ready for writing, when a connection has been established.
325 .Pp
326 Selecting true for reading on a socket descriptor upon which a
327 .Xr listen 3XNET
328 call has been performed indicates that a subsequent
329 .Xr accept 3XNET
330 call on that descriptor will not block.
331 .Pp
332 If the
333 .Fa timeout
334 argument is not a null pointer, it points to an object of type
335 .Vt struct timeval
336 that specifies a maximum interval to wait for the
337 selection to complete.
338 If the
339 .Fa timeout
340 argument points to an object of type
341 .Vt struct timeval
342 whose members are 0,
343 .Fn select
344 does not block.
345 If the
346 .Fa timeout
347 argument is a null pointer,
348 .Fn select
349 blocks until an event causes one of the masks to be returned with a valid
350 (non-zero) value.
351 If the time limit expires before any event occurs that would cause one of the
352 masks to be set to a non-zero value,
353 .Fn select
354 completes successfully and returns 0.
355 .Pp
356 If the
357 .Fa readfs ,
358 .Fa writefds ,
359 and
360 .Fa errorfds
361 arguments are all null pointers and the
362 .Fa timeout
363 argument is not a null pointer,
364 .Fn select
365 or
366 .Fn pselect
367 blocks for the time specified, or until interrupted by a
368 signal.
369 If the
370 .Fa readfds ,
371 .Fa writefds ,
372 and
373 .Fa errorfds
374 arguments are all null pointers and the
375 .Fa timeout
376 argument is a null pointer,
377 .Fn select
378 blocks until interrupted by a signal.
379 .Pp
380 File descriptors associated with regular files always select true for ready to
381 read, ready to write, and error conditions.
382 .Pp
383 On failure, the objects pointed to by the
384 .Fa readfds ,
385 .Fa writefds ,
386 and
387 .Fa errorfds
388 arguments are not modified.
389 If the timeout interval expires without the specified condition being true for
390 any of the specified file descriptors, the objects pointed to by the
391 .Fa readfds ,
392 .Fa writefds ,
393 and
394 .Fa errorfds
395 arguments have all bits set to 0.
396 .Pp
397 File descriptor masks of type
398 .Vt fd_set
399 can be initialized and tested with the macros
400 .Fn FD_CLR ,
401 .Fn FD_ISSET ,
402 .Fn FD_SET ,
403 and
404 .Fn FD_ZERO .
405 .Bl -tag -width indent
406 .It Fn FD_CLR "fd" "&fdset"
407 Clears the bit for the file descriptor
408 .Fa fd
409 in the file descriptor set
410 .Fa fdset .
411 .It Fn FD_ISSET "fd" "&fdset"
412 Returns a non-zero value if the bit for the file descriptor
413 .Fa fd
414 is set in
415 the file descriptor set pointed to by
416 .Fa fdset ,
417 and 0 otherwise.
418 .It Fn FD_SET "fd" "&fdset"
419 Sets the bit for the file descriptor
420 .Fa fd
421 in the file descriptor set
422 .Fa fdset
423 .It Fn FD_ZERO "&fdset"
424 Initializes the file descriptor set \fIfdset\fR to have zero bits for all file
425 descriptors.
426 .El
427 .Pp
428 The behavior of these macros is undefined if the
429 .Fa fd
430 argument is less than 0 or greater than or equal to
431 .Dv FD_SETSIZE ,
432 or if
433 .Fa fd
434 is not a valid file descriptor, or if any of the arguments are expressions
435 with side effects.
436 .Sh RETURN VALUES
437 On successful completion,
438 .Fn select
439 and
440 .Fn pselect
441 return the total
442 number of bits set in the bit masks.
443 Otherwise,
444 .Sy 1
445 is returned and
446 .Dv errno
447 is set to indicate the error.
448 .Pp
449 The
450 .Fn FD_CLR ,
451 .Fn FD_SET ,
452 and
453 .Fn FD_ZERO ,
454 macros return no value.
455 The
456 .Fn FD_ISSET
457 macro returns a non-zero value if the bit for the file
458 descriptor
459 .Fa fd
460 is set in the file descriptor set pointed to by
461 .Fa fdset ,
462 and
463 .Sy 0
464 otherwise.
465 .Sh ERRORS
466 The
467 .Fn select
468 and
469 .Fn pselect
470 functions will fail if:
471 .Bl -tag -width indent
472 .It Er EBADF
473 One or more of the file descriptor sets specified a file descriptor that is not
474 a valid open file descriptor.
475 .It Er EINTR
476 The function was interrupted before any of the selected events occurred and
477 before the timeout interval expired.
478 .Pp
479 If
480 .Dv SA_RESTART
481 has been set for the interrupting signal, it is implementation-dependent whether
482 .Fn select
483 restarts or returns with
484 .Dv EINTR
485 .It Er EINVAL
486 An invalid timeout interval was specified.
487 .It Er EINVAL
488 The
489 .Fa nfds
490 argument is less than 0 or greater than
491 .Dv FD_SETSIZE .
492 .It Er EINVAL
493 One of the specified file descriptors refers to a STREAM or multiplexer that is
494 linked (directly or indirectly) downstream from a multiplexer.
495 .It Er EINVAL
496 A component of the pointed-to time limit is outside the acceptable range:
497 .Dv t_sec
498 must be between 0 and 10^8, inclusive.
499 .Dv t_usec
500 must be greater than or equal to 0, and less than 10^6.
501 .El
502 .Sh USAGE
503 The
504 .Xr poll 2
505 function is preferred over this function.
506 .Pp
507 The use of a timeout does not affect any pending timers set up by
508 .Xr alarm 2 ,
509 .Xr ualarm 3C ,
510 or
511 .Xr setitimer 2 .
512 .Pp
513 On successful completion, the object pointed to by the
514 .Fa timeout
515 argument may be modified.
516 .Sh INTERFACE STABILITY
517 .Sy Standard
518 .Sh MT Level
519 .Sy MT-Safe
520 .Sh SEE ALSO
521 .Xr alarm 2 ,
522 .Xr fcntl 2 ,
523 .Xr poll 2 ,
524 .Xr read 2 ,
525 .Xr setitimer 2 ,
526 .Xr write 2 ,
527 .Xr ualarm 3C ,
528 .Xr accept 3SOCKET ,
529 .Xr listen 3SOCKET ,
530 .Xr attributes 5 ,
531 .Xr standards 5