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