1.\" $NetBSD: select.2,v 1.29 2005/03/09 22:28:52 kleink 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. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)select.2 8.2 (Berkeley) 3/25/94 31.\" 32.Dd March 5, 2005 33.Dt SELECT 2 34.Os 35.Sh NAME 36.Nm select , 37.Nm pselect 38.Nd synchronous I/O multiplexing 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In sys/select.h 43.Ft int 44.Fn select "int nfds" "fd_set * restrict readfds" "fd_set * restrict writefds" "fd_set * restrict exceptfds" "struct timeval * restrict timeout" 45.Ft int 46.Fn pselect "int nfds" "fd_set * restrict readfds" "fd_set * restrict writefds" "fd_set * restrict exceptfds" "const struct timespec *restrict timeout" "const sigset_t * restrict sigmask" 47.Fn FD_SET "int fd" "fd_set *fdset" 48.Fn FD_CLR "int fd" "fd_set *fdset" 49.Fn FD_ISSET "int fd" "fd_set *fdset" 50.Fn FD_ZERO "fd_set *fdset" 51.Sh DESCRIPTION 52.Fn select 53and 54.Fn pselect 55examine the I/O descriptor sets whose addresses are passed in 56.Fa readfds , 57.Fa writefds , 58and 59.Fa exceptfds 60to see if some of their descriptors 61are ready for reading, are ready for writing, or have an exceptional 62condition pending, respectively. 63The first 64.Fa nfds 65descriptors are checked in each set; 66i.e., the descriptors from 0 through 67.Fa nfds Ns No \-1 68in the descriptor sets are examined. 69On return, 70.Fn select 71and 72.Fn pselect 73replace the given descriptor sets 74with subsets consisting of those descriptors that are ready 75for the requested operation. 76.Fn select 77and 78.Fn pselect 79return the total number of ready descriptors in all the sets. 80.Pp 81The descriptor sets are stored as bit fields in arrays of integers. 82The following macros are provided for manipulating such descriptor sets: 83.Fn FD_ZERO fdset 84initializes a descriptor set pointed to by 85.Fa fdset 86to the null set. 87.Fn FD_SET fd fdset 88includes a particular descriptor 89.Fa fd 90in 91.Fa fdset . 92.Fn FD_CLR fd fdset 93removes 94.Fa fd 95from 96.Fa fdset . 97.Fn FD_ISSET fd fdset 98is non-zero if 99.Fa fd 100is a member of 101.Fa fdset , 102zero otherwise. 103The behavior of these macros is undefined if 104a descriptor value is less than zero or greater than or equal to 105.Dv FD_SETSIZE , 106which is normally at least equal 107to the maximum number of descriptors supported by the system. 108.Pp 109If 110.Fa timeout 111is a non-null pointer, it specifies a maximum interval to wait for the 112selection to complete. 113If 114.Fa timeout 115is a null pointer, the select blocks indefinitely. 116To affect a poll, the 117.Fa timeout 118argument should be non-null, pointing to a zero-valued timeval or timespec 119structure, as appropriate. 120.Fa timeout 121is not changed by 122.Fn select , 123and may be reused on subsequent calls; however, it is good style to 124re-initialize it before each invocation of 125.Fn select . 126.Pp 127If 128.Fa sigmask 129is a non-null pointer, then the 130.Fn pselect 131function shall replace the signal mask of the caller by the set of 132signals pointed to by 133.Fa sigmask 134before examining the descriptors, and shall restore the signal mask 135of the calling thread before returning. 136.Pp 137Any of 138.Fa readfds , 139.Fa writefds , 140and 141.Fa exceptfds 142may be given as null pointers if no descriptors are of interest. 143.Sh RETURN VALUES 144.Fn select 145returns the number of ready descriptors that are contained in 146the descriptor sets, 147or \-1 if an error occurred. 148If the time limit expires, 149.Fn select 150returns 0. 151If 152.Fn select 153returns with an error, 154including one due to an interrupted call, 155the descriptor sets will be unmodified. 156.Sh ERRORS 157An error return from 158.Fn select 159indicates: 160.Bl -tag -width Er 161.It Bq Er EFAULT 162One or more of 163.Fa readfds , 164.Fa writefds , 165or 166.Fa exceptfds 167points outside the process's allocated address space. 168.It Bq Er EBADF 169One of the descriptor sets specified an invalid descriptor. 170.It Bq Er EINTR 171A signal was delivered before the time limit expired and 172before any of the selected events occurred. 173.It Bq Er EINVAL 174The specified time limit is invalid. 175One of its components is negative or too large. 176.El 177.Sh SEE ALSO 178.Xr accept 2 , 179.Xr connect 2 , 180.Xr gettimeofday 2 , 181.Xr poll 2 , 182.Xr read 2 , 183.Xr recv 2 , 184.Xr send 2 , 185.Xr write 2 , 186.Xr getdtablesize 3 187.Sh HISTORY 188The 189.Fn select 190function call appeared in 191.Bx 4.2 . 192.Sh BUGS 193Although the provision of 194.Xr getdtablesize 3 195was intended to allow user programs to be written independent 196of the kernel limit on the number of open files, the dimension 197of a sufficiently large bit field for select remains a problem. 198The default bit size of 199.Ft fd_set 200is based on the symbol 201.Dv FD_SETSIZE 202(currently 256), 203but that is somewhat smaller than the current kernel limit 204to the number of open files. 205However, in order to accommodate programs which might potentially 206use a larger number of open files with select, it is possible 207to increase this size within a program by providing 208a larger definition of 209.Dv FD_SETSIZE 210before the inclusion of 211.Aq Pa sys/types.h . 212The kernel will cope, and the userland libraries provided with the 213system are also ready for large numbers of file descriptors. 214.Pp 215Note: 216.Xr rpc 3 217library uses 218.Ft fd_set 219with the default 220.Dv FD_SETSIZE 221as part of its ABI. 222Therefore, programs that use 223.Xr rpc 3 224routines cannot change 225.Dv FD_SETSIZE . 226.Pp 227Alternatively, to be really safe, it is possible to allocate 228.Ft fd_set 229bit-arrays dynamically. 230The idea is to permit a program to work properly even if it is 231.Xr execve 2 Ns 'd 232with 4000 file descriptors pre-allocated. 233The following illustrates the technique which is used by 234userland libraries: 235.Pp 236.Bd -literal -offset indent -compact 237 fd_set *fdsr; 238 int max = fd; 239 240 fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS), 241 sizeof(fd_mask)); 242 if (fdsr == NULL) { 243 ... 244 return (-1); 245 } 246 FD_SET(fd, fdsr); 247 n = select(max+1, fdsr, NULL, NULL, \*[Am]tv); 248 ... 249 free(fdsr); 250.Ed 251.Pp 252Alternatively, it is possible to use the 253.Xr poll 2 254interface. 255.Xr poll 2 256is more efficient when the size of 257.Fn select Ns 's 258.Ft fd_set 259bit-arrays are very large, and for fixed numbers of 260file descriptors one need not size and dynamically allocate a 261memory object. 262.Pp 263.Fn select 264should probably have been designed to return the time remaining from the 265original timeout, if any, by modifying the time value in place. 266Even though some systems stupidly act in this different way, it is 267unlikely this semantic will ever be commonly implemented, as the 268change causes massive source code compatibility problems. 269Furthermore, recent new standards have dictated the current behaviour. 270In general, due to the existence of those 271non-conforming systems, it is unwise to assume that the timeout 272value will be unmodified by the 273.Fn select 274call, and the caller should reinitialize it on each invocation. 275Calculating the delta is easily done by calling 276.Xr gettimeofday 2 277before and after the call to 278.Fn select , 279and using 280.Fn timersub 281(as described in 282.Xr getitimer 2 ) . 283.Pp 284Internally to the kernel, 285.Fn select 286works poorly if multiple processes wait on the same file descriptor. 287