1.\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)select.2 8.2 (Berkeley) 3/25/94 35.\" 36.Dd March 18, 2015 37.Dt SELECT 2 38.Os BSD 4.2 39.Sh NAME 40.Nm FD_CLR , 41.Nm FD_COPY , 42.Nm FD_ISSET , 43.Nm FD_SET , 44.Nm FD_ZERO , 45.Nm select 46.Nd synchronous I/O multiplexing 47.Sh SYNOPSIS 48.Fd #include <sys/select.h> 49.\" 50.Ft void 51.Fo FD_CLR 52.Fa fd 53.Fa "fd_set *fdset" 54.Fc 55.Ft void 56.Fo FD_COPY 57.Fa "fd_set *fdset_orig" 58.Fa "fd_set *fdset_copy" 59.Fc 60.Ft int 61.Fo FD_ISSET 62.Fa fd 63.Fa "fd_set *fdset" 64.Fc 65.Ft void 66.Fo FD_SET 67.Fa fd 68.Fa "fd_set *fdset" 69.Fc 70.Ft void 71.Fo FD_ZERO 72.Fa "fd_set *fdset" 73.Fc 74.Ft int 75.Fo select 76.Fa "int nfds" 77.Fa "fd_set *restrict readfds" 78.Fa "fd_set *restrict writefds" 79.Fa "fd_set *restrict errorfds" 80.Fa "struct timeval *restrict timeout" 81.Fc 82.Sh DESCRIPTION 83.Fn select 84examines the I/O descriptor sets whose addresses are passed in 85.Fa readfds , 86.Fa writefds , 87and 88.Fa errorfds 89to see if some of their descriptors 90are ready for reading, are ready for writing, or have an exceptional 91condition pending, respectively. 92The first 93.Fa nfds 94descriptors are checked in each set; 95i.e., the descriptors from 0 through 96.Fa nfds Ns No -1 97in the descriptor sets are examined. (Example: If you have set two file descriptors "4" and "17", 98.Fa nfds 99should not be "2", but rather "17 + 1" or "18".) 100On return, 101.Fn select 102replaces the given descriptor sets 103with subsets consisting of those descriptors that are ready 104for the requested operation. 105.Fn select 106returns the total number of ready descriptors in all the sets. 107.Pp 108The descriptor sets are stored as bit fields in arrays of integers. 109The following macros are provided for manipulating such descriptor sets: 110.Fn FD_ZERO &fdset 111initializes a descriptor set 112.Fa fdset 113to the null set. 114.Fn FD_SET fd &fdset 115includes a particular descriptor 116.Fa fd 117in 118.Fa fdset . 119.Fn FD_CLR fd &fdset 120removes 121.Fa fd 122from 123.Fa fdset . 124.Fn FD_ISSET fd &fdset 125is non-zero if 126.Fa fd 127is a member of 128.Fa fdset , 129zero otherwise. 130.Fn FD_COPY &fdset_orig &fdset_copy 131replaces an already allocated 132.Fa &fdset_copy 133file descriptor set with a copy of 134.Fa &fdset_orig . 135The behavior of these macros is undefined if 136a descriptor value is less than zero or greater than or equal to 137.Dv FD_SETSIZE , 138which is normally at least equal 139to the maximum number of descriptors supported by the system. 140.Pp 141If 142.Fa timeout 143is not a null pointer, it specifies a maximum interval to wait for the 144selection to complete. 145.Pp 146If 147.Fa timeout 148is a null pointer, the select blocks indefinitely. 149.Pp 150To effect a poll, the 151.Fa timeout 152argument should be not be a null pointer, 153but it should point to a zero-valued timeval structure. 154.Pp 155.Fa timeout 156is not changed by 157.Fn select , 158and may be reused on subsequent calls, however it is good style to re-initialize 159it before each invocation of 160.Fn select . 161.Pp 162Any of 163.Fa readfds , 164.Fa writefds , 165and 166.Fa errorfds 167may be given as null pointers if no descriptors are of interest. 168.Sh RETURN VALUES 169.Fn select 170returns the number of ready descriptors that are contained in 171the descriptor sets, 172or -1 if an error occurred. 173If the time limit expires, 174.Fn select 175returns 0. 176If 177.Fn select 178returns with an error, 179including one due to an interrupted call, 180the descriptor sets will be unmodified and the global variable 181.Va errno 182will be set to indicate the error. 183.Sh ERRORS 184An error return from 185.Fn select 186indicates: 187.Bl -tag -width Er 188.\" =========== 189.It Bq Er EAGAIN 190The kernel was (perhaps temporarily) unable 191to allocate the requested number of file descriptors. 192.\" =========== 193.It Bq Er EBADF 194One of the descriptor sets specified an invalid descriptor. 195.\" =========== 196.It Bq Er EINTR 197A signal was delivered before the time limit expired and 198before any of the selected events occurred. 199.\" =========== 200.It Bq Er EINVAL 201The specified time limit is invalid. One of its components is 202negative or too large. 203.\" =========== 204.It Bq Er EINVAL 205.Fa ndfs 206is greater than FD_SETSIZE and _DARWIN_UNLIMITED_SELECT is not defined. 207.El 208.Sh LEGACY SYNOPSIS 209.Fd #include <sys/select.h> 210.D1 "- or -" 211.Fd #include <sys/types.h> 212.Fd #include <sys/time.h> 213.Fd #include <unistd.h> 214.Pp 215.Fo FD_SET 216.Fa fd 217.Fa &fdset 218.Fc ; 219.Pp 220.Fo FD_CLR 221.Fa fd 222.Fa &fdset 223.Fc ; 224.Pp 225.Fo FD_ISSET 226.Fa fd 227.Fa &fdset 228.Fc ; 229.Pp 230.Fo FD_COPY 231.Fa &fdset_orig 232.Fa &fdset_copy 233.Fc ; 234.Pp 235.Fo FD_ZERO 236.Fa &fdset 237.Fc ; 238.Sh COMPATIBILITY 239.Fn select 240now returns with 241.Va errno 242set to EINVAL when 243.Fa nfds 244is greater than FD_SETSIZE. 245Use a smaller value for 246.Fa nfds 247or compile with -D_DARWIN_UNLIMITED_SELECT. 248.Sh SEE ALSO 249.Xr accept 2 , 250.Xr connect 2 , 251.Xr connectx 2 , 252.Xr getdtablesize 2 , 253.Xr gettimeofday 2 , 254.Xr read 2 , 255.Xr recv 2 , 256.Xr send 2 , 257.Xr write 2 , 258.Xr compat 5 259.Sh BUGS 260Although the provision of 261.Xr getdtablesize 2 262was intended to allow user programs to be written independent 263of the kernel limit on the number of open files, the dimension 264of a sufficiently large bit field for select remains a problem. 265The default size 266.Dv FD_SETSIZE 267(currently 1024) is somewhat smaller than 268the current kernel limit to the number of open files. 269However, in order to accommodate programs which might potentially 270use a larger number of open files with select, it is possible 271to increase this size within a program by providing 272a larger definition of 273.Dv FD_SETSIZE 274before the inclusion of 275.Aq Pa sys/types.h . 276.Pp 277.Fn select 278should probably have been designed to return the time remaining from the 279original timeout, if any, by modifying the time value in place. 280However, it is unlikely this semantic will ever be implemented, as the 281change would cause source code compatibility problems. 282In general it is unwise to assume that the timeout value will be 283unmodified by the 284.Fn select 285call, and the caller should reinitialize it on each invocation. 286.Sh HISTORY 287The 288.Fn select 289function call appeared in 290.Bx 4.2 . 291