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