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 96The 97.Fn pselect 98function examines the file descriptor sets whose addresses 99are passed in the 100.Fa readfds , 101.Fa writefds , 102and 103.Fa errorfds 104parameters to see if some of their descriptors are ready for reading, 105are ready for writing, or have an exceptional condition pending, 106respectively. 107.Pp 108The 109.Fn select 110function is equivalent to the 111.Fn pselect 112function, except as follows: 113.Bl -bullet 114.It 115For the 116.Fn select 117function, the timeout period is given in seconds and 118microseconds in an argument of type 119.Vt struct timeval , 120whereas for the 121.Fn pselect 122function the timeout period is given in seconds and nanoseconds 123in an argument of type 124.Vt struct timespec 125.It 126The 127.Fn select 128function has no 129.Fa sigmask 130argument. 131It behaves as 132.Fn pselect 133does when 134.Fa sigmask 135is a null pointer. 136.It 137Upon successful completion, the 138.Fn select 139function might modify the object pointed to by the 140.Fa Itimeout 141argument. 142.El 143.Pp 144The 145.Fn select 146and 147.Fn pselect 148functions support regular files, terminal and pseudo-terminal devices, 149STREAMS-based files, FIFOs, pipes, and sockets. 150The behavior of 151.Fn select 152and 153.Fn pselect 154on file descriptors that refer to other types of file is unspecified. 155.Pp 156The 157.Fa nfds 158argument specifies the range of file descriptors to be tested. 159The first 160.Fa nfds 161descriptors are checked in each set; that is, the 162descriptors from zero through 163.Dq Li nfds - 1 164in the descriptor sets are examined. 165.Pp 166If the 167.Fa readfs 168argument is not a null pointer, it points to an object of 169type 170.Vt fd_set 171that on input specifies the file descriptors to be checked 172for being ready to read, and on output indicates which file descriptors are 173ready to read. 174.Pp 175If the 176.Fa writefs 177argument is not a null pointer, it points to an object of 178type 179.Vt fd_set 180that on input specifies the file descriptors to be checked 181for being ready to write, and on output indicates which file descriptors are 182ready to write. 183.Pp 184If the 185.Fa errorfds 186argument is not a null pointer, it points to an object of 187type 188.Vt fd_set 189that on input specifies the file descriptors to be checked 190for error conditions pending, and on output indicates which file descriptors 191have error conditions pending. 192.Pp 193Upon successful completion, the objects pointed to by the 194.Fa readfs , 195.Fa writefs , 196and 197.Fa errorfds 198arguments are modified to indicate which file descriptors are ready for reading, 199ready for writing, or have an error condition pending, respectively, and return 200the total number of ready descriptors in all the output sets. 201For each file descriptor less than 202.Fa nfds , 203the corresponding bit will be set on successful completion if it was set on 204input and the associated condition is true for that file descriptor. 205.Pp 206If none of the selected descriptors are ready for the requested operation, the 207.Fn select 208or 209.Fn pselect 210function blocks until at least one of the 211requested operations becomes ready, until the timeout occurs, or until 212interrupted by a signal. 213The 214.Fa timeout 215parameter controls how long the 216.Fn select 217or 218.Fn pselect 219function takes before timing out. 220If the 221.Fa timeout 222parameter is not a null pointer, it specifies a maximum interval 223to wait for the selection to complete. 224If the specified time interval expires without any requested operation becoming 225ready, the function returns. 226If the 227.Fa timeout 228parameter is a null pointer, then the call to 229.Fn select 230or 231.Fn pselect 232blocks indefinitely until at least one descriptor meets the 233specified criteria. 234To effect a poll, the 235.Fa timeout 236parameter should not be a null pointer, and should point to a zero-valued 237.Vt timespec 238structure. 239.Pp 240The use of a 241.Fa timeout 242does not affect any pending timers set up by 243.Xr alarm 2 , 244.Xr ualarm 3C , 245or 246.Xr setitimer 2 . 247.Pp 248If 249.Fa sigmask 250is not a null pointer, then the 251.Fn pselect 252function replaces the signal mask of the process by the set of signals pointed 253to by 254.Fa sigmask 255before examining the descriptors, and restores the signal mask of 256the process before returning. 257.Pp 258A descriptor is considered ready for reading when a call to an input function 259with 260.Dv O_NONBLOCK 261clear would not block, whether or not the function would 262transfer data successfully. 263(The function might return data, an end-of-file indication, or an error other 264than one indicating that it is blocked, and in each of these cases the 265descriptor will be considered ready for reading.) 266.Pp 267A descriptor is considered ready for writing when a call to an output function 268with 269.Dv O_NONBLOCK 270clear would not block, whether or not the function would 271transfer data successfully. 272.Pp 273If a socket has a pending error, it is considered to have an exceptional 274condition pending. 275Otherwise, what constitutes an exceptional condition is file type-specific. 276For a file descriptor for use with a socket, it is protocol-specific except as 277noted below. 278For other file types, if the operation is meaningless for a particular file 279type, 280.Fn select 281or 282.Fn pselect 283indicates that the descriptor is ready for read or write operations and 284indicates that the descriptor has no exceptional condition pending. 285.Pp 286If a descriptor refers to a socket, the implied input function is the 287.Xr recvmsg 3XNET 288function with parameters requesting normal and ancillary 289data, such that the presence of either type causes the socket to be marked as 290readable. 291The presence of out-of-band data is checked if the socket option 292.Dv SO_OOBINLINE 293has been enabled, as out-of-band data is enqueued with 294normal data. 295If the socket is currently listening, then it is marked as readable if an 296incoming connection request has been received, and a call to the accept function 297completes without blocking. 298.Pp 299If a descriptor refers to a socket, the implied output function is the 300.Xr sendmsg 3XNET 301function supplying an amount of normal data equal to the 302current value of the 303.Dv SO_SNDLOWAT 304option for the socket. 305If a non-blocking call to the connect function has been made for a socket, and 306the connection attempt has either succeeded or failed leaving a pending error, 307the socket is marked as writable. 308.Pp 309A socket is considered to have an exceptional condition pending if a receive 310operation with 311.Dv O_NONBLOCK 312clear for the open file description and with the 313.Dv MSG_OOB 314flag set would return out-of-band data without blocking. 315(It is protocol-specific whether the 316.Dv MSG_OOB 317flag would be used to read out-of-band data.) 318A socket will also be considered to have an exceptional condition pending if an 319out-of-band data mark is present in the receive queue. 320.Pp 321A file descriptor for a socket that is listening for connections will indicate 322that it is ready for reading, when connections are available. 323A file descriptor for a socket that is connecting asynchronously will indicate 324that it is ready for writing, when a connection has been established. 325.Pp 326Selecting true for reading on a socket descriptor upon which a 327.Xr listen 3XNET 328call has been performed indicates that a subsequent 329.Xr accept 3XNET 330call on that descriptor will not block. 331.Pp 332If the 333.Fa timeout 334argument is not a null pointer, it points to an object of type 335.Vt struct timeval 336that specifies a maximum interval to wait for the 337selection to complete. 338If the 339.Fa timeout 340argument points to an object of type 341.Vt struct timeval 342whose members are 0, 343.Fn select 344does not block. 345If the 346.Fa timeout 347argument is a null pointer, 348.Fn select 349blocks until an event causes one of the masks to be returned with a valid 350(non-zero) value. 351If the time limit expires before any event occurs that would cause one of the 352masks to be set to a non-zero value, 353.Fn select 354completes successfully and returns 0. 355.Pp 356If the 357.Fa readfs , 358.Fa writefds , 359and 360.Fa errorfds 361arguments are all null pointers and the 362.Fa timeout 363argument is not a null pointer, 364.Fn select 365or 366.Fn pselect 367blocks for the time specified, or until interrupted by a 368signal. 369If the 370.Fa readfds , 371.Fa writefds , 372and 373.Fa errorfds 374arguments are all null pointers and the 375.Fa timeout 376argument is a null pointer, 377.Fn select 378blocks until interrupted by a signal. 379.Pp 380File descriptors associated with regular files always select true for ready to 381read, ready to write, and error conditions. 382.Pp 383On failure, the objects pointed to by the 384.Fa readfds , 385.Fa writefds , 386and 387.Fa errorfds 388arguments are not modified. 389If the timeout interval expires without the specified condition being true for 390any of the specified file descriptors, the objects pointed to by the 391.Fa readfds , 392.Fa writefds , 393and 394.Fa errorfds 395arguments have all bits set to 0. 396.Pp 397File descriptor masks of type 398.Vt fd_set 399can be initialized and tested with the macros 400.Fn FD_CLR , 401.Fn FD_ISSET , 402.Fn FD_SET , 403and 404.Fn FD_ZERO . 405.Bl -tag -width indent 406.It Fn FD_CLR "fd" "&fdset" 407Clears the bit for the file descriptor 408.Fa fd 409in the file descriptor set 410.Fa fdset . 411.It Fn FD_ISSET "fd" "&fdset" 412Returns a non-zero value if the bit for the file descriptor 413.Fa fd 414is set in 415the file descriptor set pointed to by 416.Fa fdset , 417and 0 otherwise. 418.It Fn FD_SET "fd" "&fdset" 419Sets the bit for the file descriptor 420.Fa fd 421in the file descriptor set 422.Fa fdset 423.It Fn FD_ZERO "&fdset" 424Initializes the file descriptor set \fIfdset\fR to have zero bits for all file 425descriptors. 426.El 427.Pp 428The behavior of these macros is undefined if the 429.Fa fd 430argument is less than 0 or greater than or equal to 431.Dv FD_SETSIZE , 432or if 433.Fa fd 434is not a valid file descriptor, or if any of the arguments are expressions 435with side effects. 436.Sh RETURN VALUES 437On successful completion, 438.Fn select 439and 440.Fn pselect 441return the total 442number of bits set in the bit masks. 443Otherwise, 444.Sy 1 445is returned and 446.Dv errno 447is set to indicate the error. 448.Pp 449The 450.Fn FD_CLR , 451.Fn FD_SET , 452and 453.Fn FD_ZERO , 454macros return no value. 455The 456.Fn FD_ISSET 457macro returns a non-zero value if the bit for the file 458descriptor 459.Fa fd 460is set in the file descriptor set pointed to by 461.Fa fdset , 462and 463.Sy 0 464otherwise. 465.Sh ERRORS 466The 467.Fn select 468and 469.Fn pselect 470functions will fail if: 471.Bl -tag -width indent 472.It Er EBADF 473One or more of the file descriptor sets specified a file descriptor that is not 474a valid open file descriptor. 475.It Er EINTR 476The function was interrupted before any of the selected events occurred and 477before the timeout interval expired. 478.Pp 479If 480.Dv SA_RESTART 481has been set for the interrupting signal, it is implementation-dependent whether 482.Fn select 483restarts or returns with 484.Dv EINTR 485.It Er EINVAL 486An invalid timeout interval was specified. 487.It Er EINVAL 488The 489.Fa nfds 490argument is less than 0 or greater than 491.Dv FD_SETSIZE . 492.It Er EINVAL 493One of the specified file descriptors refers to a STREAM or multiplexer that is 494linked (directly or indirectly) downstream from a multiplexer. 495.It Er EINVAL 496A component of the pointed-to time limit is outside the acceptable range: 497.Dv t_sec 498must be between 0 and 10^8, inclusive. 499.Dv t_usec 500must be greater than or equal to 0, and less than 10^6. 501.El 502.Sh USAGE 503The 504.Xr poll 2 505function is preferred over this function. 506.Pp 507The use of a timeout does not affect any pending timers set up by 508.Xr alarm 2 , 509.Xr ualarm 3C , 510or 511.Xr setitimer 2 . 512.Pp 513On successful completion, the object pointed to by the 514.Fa timeout 515argument 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 532