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 readfds
 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 writefds
 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 readfds ,
 195 .Fa writefds ,
 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 readfds ,
 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