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