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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)select.2 8.2 (Berkeley) 3/25/94 33.\" $FreeBSD: src/lib/libc/sys/select.2,v 1.14.2.5 2001/12/14 18:34:01 ru Exp $ 34.\" $DragonFly: src/lib/libc/sys/select.2,v 1.5 2005/08/03 16:07:39 corecode Exp $ 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.In sys/types.h 46.In sys/time.h 47.In unistd.h 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 &fdset 51.Fn FD_CLR fd &fdset 52.Fn FD_ISSET fd &fdset 53.Fn FD_ZERO &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 only exceptional condition detectable is out-of-band 65data received on a socket. 66The first 67.Fa nfds 68descriptors are checked in each set; 69i.e., the descriptors from 0 through 70.Fa nfds Ns No -1 71in the descriptor sets are examined. 72On return, 73.Fn select 74replaces the given descriptor sets 75with subsets consisting of those descriptors that are ready 76for the requested operation. 77.Fn Select 78returns the total number of ready descriptors in all the sets. 79.Pp 80The descriptor sets are stored as bit fields in arrays of integers. 81The following macros are provided for manipulating such descriptor sets: 82.Fn FD_ZERO &fdset 83initializes a descriptor set 84.Fa fdset 85to the null set. 86.Fn FD_SET fd &fdset 87includes a particular descriptor 88.Fa fd 89in 90.Fa fdset . 91.Fn FD_CLR fd &fdset 92removes 93.Fa fd 94from 95.Fa fdset . 96.Fn FD_ISSET fd &fdset 97is non-zero if 98.Fa fd 99is a member of 100.Fa fdset , 101zero otherwise. 102The behavior of these macros is undefined if 103a descriptor value is less than zero or greater than or equal to 104.Dv FD_SETSIZE , 105which is normally at least equal 106to the maximum number of descriptors supported by the system. 107.Pp 108If 109.Fa timeout 110is a non-nil pointer, it specifies the maximum interval to wait for the 111selection to complete. System activity can lengthen the interval by 112an indeterminate amount. 113.Pp 114If 115.Fa timeout 116is a nil pointer, the select blocks indefinitely. 117.Pp 118To effect a poll, the 119.Fa timeout 120argument should be non-nil, pointing to a zero-valued timeval structure. 121.Pp 122Any of 123.Fa readfds , 124.Fa writefds , 125and 126.Fa exceptfds 127may be given as nil pointers if no descriptors are of interest. 128.Pp 129Even if no descriptors are of interest, the timeout works as described, 130effectively putting the process into an interruptible sleep for the 131specified timeout. 132If 133.Fa timeout 134is nil, the process will block until a signal is received. 135.Sh RETURN VALUES 136.Fn Select 137returns the number of ready descriptors that are contained in 138the descriptor sets, 139or -1 if an error occurred. 140If the time limit expires, 141.Fn select 142returns 0. 143If 144.Fn select 145returns with an error, 146including one due to an interrupted call, 147the descriptor sets will be unmodified. 148.Sh ERRORS 149An error return from 150.Fn select 151indicates: 152.Bl -tag -width Er 153.It Bq Er EBADF 154One of the descriptor sets specified an invalid descriptor. 155.It Bq Er EINTR 156A signal was delivered before the time limit expired and 157before any of the selected events occurred. 158.It Bq Er EINVAL 159The specified time limit is invalid. One of its components is 160negative or too large. 161.It Bq Er EINVAL 162.Fa nfds 163was invalid. 164.El 165.Sh SEE ALSO 166.Xr accept 2 , 167.Xr connect 2 , 168.Xr getdtablesize 2 , 169.Xr gettimeofday 2 , 170.Xr read 2 , 171.Xr recv 2 , 172.Xr send 2 , 173.Xr write 2 , 174.Xr clocks 7 175.Sh NOTES 176The default size of 177.Dv FD_SETSIZE 178is currently 1024. 179In order to accommodate programs which might potentially 180use a larger number of open files with 181.Fn select , 182it is possible 183to increase this size by having the program define 184.Dv FD_SETSIZE 185before the inclusion of any header which includes 186.Aq Pa sys/types.h . 187.Pp 188If 189.Fa nfds 190is greater than the number of open files, 191.Fn select 192is not guaranteed to examine the unused file descriptors. For historical 193reasons, 194.Fn select 195will always examine the first 256 descriptors. 196.Sh BUGS 197.St -susv2 198allows systems to modify the original timeout in place. 199Thus, it is unwise to assume that the timeout value will be unmodified 200by the 201.Fn select 202call. 203.Sh HISTORY 204The 205.Fn select 206function call appeared in 207.Bx 4.2 . 208