1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)select.2 8.2 (Berkeley) 3/25/94 29.\" $FreeBSD: src/lib/libc/sys/select.2,v 1.14.2.5 2001/12/14 18:34:01 ru Exp $ 30.\" $DragonFly: src/lib/libc/sys/select.2,v 1.8 2007/08/02 00:21:54 swildner Exp $ 31.\" 32.Dd March 25, 1994 33.Dt SELECT 2 34.Os 35.Sh NAME 36.Nm select 37.Nd synchronous I/O multiplexing 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/select.h 42.Ft int 43.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout" 44.Fn FD_SET fd &fdset 45.Fn FD_CLR fd &fdset 46.Fn FD_ISSET fd &fdset 47.Fn FD_ZERO &fdset 48.Sh DESCRIPTION 49.Fn Select 50examines the I/O descriptor sets whose addresses are passed in 51.Fa readfds , 52.Fa writefds , 53and 54.Fa exceptfds 55to see if some of their descriptors 56are ready for reading, are ready for writing, or have an exceptional 57condition pending, respectively. 58The only exceptional condition detectable is out-of-band 59data received on a socket. 60The first 61.Fa nfds 62descriptors are checked in each set; 63i.e., the descriptors from 0 through 64.Fa nfds Ns No -1 65in the descriptor sets are examined. 66On return, 67.Fn select 68replaces the given descriptor sets 69with subsets consisting of those descriptors that are ready 70for the requested operation. 71.Fn Select 72returns the total number of ready descriptors in all the sets. 73.Pp 74The descriptor sets are stored as bit fields in arrays of integers. 75The following macros are provided for manipulating such descriptor sets: 76.Fn FD_ZERO &fdset 77initializes a descriptor set 78.Fa fdset 79to the null set. 80.Fn FD_SET fd &fdset 81includes a particular descriptor 82.Fa fd 83in 84.Fa fdset . 85.Fn FD_CLR fd &fdset 86removes 87.Fa fd 88from 89.Fa fdset . 90.Fn FD_ISSET fd &fdset 91is non-zero if 92.Fa fd 93is a member of 94.Fa fdset , 95zero otherwise. 96The behavior of these macros is undefined if 97a descriptor value is less than zero or greater than or equal to 98.Dv FD_SETSIZE , 99which is normally at least equal 100to the maximum number of descriptors supported by the system. 101.Pp 102If 103.Fa timeout 104is a non-nil pointer, it specifies the maximum interval to wait for the 105selection to complete. System activity can lengthen the interval by 106an indeterminate amount. 107.Pp 108If 109.Fa timeout 110is a nil pointer, the select blocks indefinitely. 111.Pp 112To effect a poll, the 113.Fa timeout 114argument should be non-nil, pointing to a zero-valued timeval structure. 115.Pp 116Any of 117.Fa readfds , 118.Fa writefds , 119and 120.Fa exceptfds 121may be given as nil pointers if no descriptors are of interest. 122.Pp 123Even if no descriptors are of interest, the timeout works as described, 124effectively putting the process into an interruptible sleep for the 125specified timeout. 126If 127.Fa timeout 128is nil, the process will block until a signal is received. 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 EBADF 148One of the descriptor sets specified an invalid descriptor. 149.It Bq Er EINTR 150A signal was delivered before the time limit expired and 151before any of the selected events occurred. 152.It Bq Er EINVAL 153The specified time limit is invalid. One of its components is 154negative or too large. 155.It Bq Er EINVAL 156.Fa nfds 157was invalid. 158.El 159.Sh SEE ALSO 160.Xr accept 2 , 161.Xr connect 2 , 162.Xr getdtablesize 2 , 163.Xr gettimeofday 2 , 164.Xr read 2 , 165.Xr recv 2 , 166.Xr send 2 , 167.Xr write 2 , 168.Xr clocks 7 169.Sh NOTES 170The default size of 171.Dv FD_SETSIZE 172is currently 1024. 173In order to accommodate programs which might potentially 174use a larger number of open files with 175.Fn select , 176it is possible 177to increase this size by having the program define 178.Dv FD_SETSIZE 179before the inclusion of any header which includes 180.In sys/types.h . 181.Pp 182If 183.Fa nfds 184is greater than the number of open files, 185.Fn select 186is not guaranteed to examine the unused file descriptors. For historical 187reasons, 188.Fn select 189will always examine the first 256 descriptors. 190.Sh HISTORY 191The 192.Fn select 193function call appeared in 194.Bx 4.2 . 195.Sh BUGS 196.St -susv2 197allows systems to modify the original timeout in place. 198Thus, it is unwise to assume that the timeout value will be unmodified 199by the 200.Fn select 201call. 202