1.\" $NetBSD: select.2,v 1.17 2002/08/10 01:18:18 wiz 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 25, 1994 37.Dt SELECT 2 38.Os 39.Sh NAME 40.Nm select 41.Nd synchronous I/O multiplexing 42.Sh LIBRARY 43.Lb libc 44.Sh SYNOPSIS 45.Fd #include \*[Lt]sys/types.h\*[Gt] 46.Fd #include \*[Lt]sys/time.h\*[Gt] 47.Fd #include \*[Lt]unistd.h\*[Gt] 48.Ft int 49.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout" 50.Fn FD_SET fd \*[Am]fdset 51.Fn FD_CLR fd \*[Am]fdset 52.Fn FD_ISSET fd \*[Am]fdset 53.Fn FD_ZERO \*[Am]fdset 54.Sh DESCRIPTION 55.Fn select 56examines the I/O descriptor sets whose addresses are passed in 57.Fa readfds , 58.Fa writefds , 59and 60.Fa exceptfds 61to see if some of their descriptors 62are ready for reading, are ready for writing, or have an exceptional 63condition pending, respectively. 64The first 65.Fa nfds 66descriptors are checked in each set; 67i.e., the descriptors from 0 through 68.Fa nfds Ns No -1 69in the descriptor sets are examined. 70On return, 71.Fn select 72replaces the given descriptor sets 73with subsets consisting of those descriptors that are ready 74for the requested operation. 75.Fn select 76returns the total number of ready descriptors in all the sets. 77.Pp 78The descriptor sets are stored as bit fields in arrays of integers. 79The following macros are provided for manipulating such descriptor sets: 80.Fn FD_ZERO \*[Am]fdset 81initializes a descriptor set 82.Fa fdset 83to the null set. 84.Fn FD_SET fd \*[Am]fdset 85includes a particular descriptor 86.Fa fd 87in 88.Fa fdset . 89.Fn FD_CLR fd \*[Am]fdset 90removes 91.Fa fd 92from 93.Fa fdset . 94.Fn FD_ISSET fd \*[Am]fdset 95is non-zero if 96.Fa fd 97is a member of 98.Fa fdset , 99zero otherwise. 100The behavior of these macros is undefined if 101a descriptor value is less than zero or greater than or equal to 102.Dv FD_SETSIZE , 103which is normally at least equal 104to the maximum number of descriptors supported by the system. 105.Pp 106If 107.Fa timeout 108is a non-nil pointer, it specifies a maximum interval to wait for the 109selection to complete. 110If 111.Fa timeout 112is a nil pointer, the select blocks indefinitely. 113To affect a poll, the 114.Fa timeout 115argument should be non-nil, pointing to a zero-valued timeval structure. 116.Fa timeout 117is not changed by 118.Fn select , 119and may be reused on subsequent calls; however, it is good style to 120re-initialize it before each invocation of 121.Fn select . 122.Pp 123Any of 124.Fa readfds , 125.Fa writefds , 126and 127.Fa exceptfds 128may be given as nil pointers if no descriptors are of interest. 129.Sh RETURN VALUES 130.Fn select 131returns the number of ready descriptors that are contained in 132the descriptor sets, 133or -1 if an error occurred. 134If the time limit expires, 135.Fn select 136returns 0. 137If 138.Fn select 139returns with an error, 140including one due to an interrupted call, 141the descriptor sets will be unmodified. 142.Sh ERRORS 143An error return from 144.Fn select 145indicates: 146.Bl -tag -width Er 147.It Bq Er EFAULT 148One or more of 149.Fa readfds , 150.Fa writefds , 151or 152.Fa exceptfds 153points outside the process's allocated address space. 154.It Bq Er EBADF 155One of the descriptor sets specified an invalid descriptor. 156.It Bq Er EINTR 157A signal was delivered before the time limit expired and 158before any of the selected events occurred. 159.It Bq Er EINVAL 160The specified time limit is invalid. 161One of its components is negative or too large. 162.El 163.Sh SEE ALSO 164.Xr accept 2 , 165.Xr connect 2 , 166.Xr gettimeofday 2 , 167.Xr poll 2 , 168.Xr read 2 , 169.Xr recv 2 , 170.Xr send 2 , 171.Xr write 2 , 172.Xr getdtablesize 3 173.Sh HISTORY 174The 175.Fn select 176function call appeared in 177.Bx 4.2 . 178.Sh BUGS 179Although the provision of 180.Xr getdtablesize 3 181was intended to allow user programs to be written independent 182of the kernel limit on the number of open files, the dimension 183of a sufficiently large bit field for select remains a problem. 184The default bit size of 185.Ft fd_set 186is based on the symbol 187.Dv FD_SETSIZE 188(currently 256), 189but that is somewhat smaller than the current kernel limit 190to the number of open files. 191However, in order to accommodate programs which might potentially 192use a larger number of open files with select, it is possible 193to increase this size within a program by providing 194a larger definition of 195.Dv FD_SETSIZE 196before the inclusion of 197.Aq Pa sys/types.h . 198The kernel will cope, and the userland libraries provided with the 199system are also ready for large numbers of file descriptors. 200.Pp 201Alternatively, to be really safe, it is possible to allocate 202.Ft fd_set 203bit-arrays dynamically. 204The idea is to permit a program to work properly even if it is 205.Xr execve 2 Ns 'd 206with 4000 file descriptors pre-allocated. 207The following illustrates the technique which is used by 208userland libraries: 209.Pp 210.Bd -literal -offset indent -compact 211 fd_set *fdsr; 212 int max = fd; 213 214 fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS), 215 sizeof(fd_mask)); 216 if (fdsr == NULL) { 217 ... 218 return (-1); 219 } 220 FD_SET(fd, fdsr); 221 n = select(max+1, fdsr, NULL, NULL, &tv); 222 ... 223 free(fdsr); 224.Ed 225.Pp 226Alternatively, it is possible to use the 227.Xr poll 2 228interface. 229.Xr poll 2 230is more efficient when the size of 231.Fn select Ns 's 232.Ft fd_set 233bit-arrays are very large, and for fixed numbers of 234file descriptors one need not size and dynamically allocate a 235memory object. 236.Pp 237.Fn select 238should probably have been designed to return the time remaining from the 239original timeout, if any, by modifying the time value in place. 240Even though some systems stupidly act in this different way, it is 241unlikely this semantic will ever be commonly implemented, as the 242change causes massive source code compatibility problems. 243Furthermore, recent new standards have dictated the current behaviour. 244In general, due to the existence of those 245non-conforming systems, it is unwise to assume that the timeout 246value will be unmodified by the 247.Fn select 248call, and the caller should reinitialize it on each invocation. 249Calculating the delta is easily done by calling 250.Xr gettimeofday 2 251before and after the call to 252.Fn select , 253and using 254.Fn timersub 255(as described in 256.Xr getitimer 2 ) . 257.Pp 258Internally to the kernel, 259.Fn select 260works poorly if multiple processes wait on the same file descriptor. 261