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>
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 --- EOF ---