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.\" 31.Dd February 22, 2018 32.Dt SELECT 2 33.Os 34.Sh NAME 35.Nm select 36.Nd synchronous I/O multiplexing 37.Sh LIBRARY 38.Lb libc 39.Sh SYNOPSIS 40.In sys/select.h 41.Ft int 42.Fn select "int nfds" "fd_set * restrict readfds" "fd_set * restrict writefds" "fd_set * restrict exceptfds" "struct timeval * restrict timeout" 43.Fn FD_SET fd &fdset 44.Fn FD_CLR fd &fdset 45.Fn FD_ISSET fd &fdset 46.Fn FD_ZERO &fdset 47.Sh DESCRIPTION 48.Fn Select 49examines the I/O descriptor sets whose addresses are passed in 50.Fa readfds , 51.Fa writefds , 52and 53.Fa exceptfds 54to see if some of their descriptors 55are ready for reading, are ready for writing, or have an exceptional 56condition pending, respectively. 57The only exceptional condition detectable is out-of-band 58data received on a socket. 59The first 60.Fa nfds 61descriptors are checked in each set; 62i.e., the descriptors from 0 through 63.Fa nfds Ns No -1 64in the descriptor sets are examined. 65On return, 66.Fn select 67replaces the given descriptor sets 68with subsets consisting of those descriptors that are ready 69for the requested operation. 70.Fn Select 71returns the total number of ready descriptors in all the sets. 72.Pp 73The descriptor sets are stored as bit fields in arrays of integers. 74The following macros are provided for manipulating such descriptor sets: 75.Fn FD_ZERO &fdset 76initializes a descriptor set 77.Fa fdset 78to the null set. 79.Fn FD_SET fd &fdset 80includes a particular descriptor 81.Fa fd 82in 83.Fa fdset . 84.Fn FD_CLR fd &fdset 85removes 86.Fa fd 87from 88.Fa fdset . 89.Fn FD_ISSET fd &fdset 90is non-zero if 91.Fa fd 92is a member of 93.Fa fdset , 94zero otherwise. 95The behavior of these macros is undefined if 96a descriptor value is less than zero or greater than or equal to 97.Dv FD_SETSIZE , 98which is normally at least equal 99to the maximum number of descriptors supported by the system. 100.Pp 101If 102.Fa timeout 103is non-NULL, it specifies the maximum interval to wait for the 104selection to complete. System activity can lengthen the interval by 105an indeterminate amount. 106.Pp 107If 108.Fa timeout 109is a null pointer, the select blocks indefinitely. 110.Pp 111To effect a poll, the 112.Fa timeout 113argument should be non-NULL, pointing to a zero-valued timeval structure. 114.Pp 115Any of 116.Fa readfds , 117.Fa writefds , 118and 119.Fa exceptfds 120may be given as null pointers if no descriptors are of interest. 121.Pp 122Even if no descriptors are of interest, the timeout works as described, 123effectively putting the process into an interruptible sleep for the 124specified timeout. 125If 126.Fa timeout 127is NULL, the process will block until a signal is received. 128.Sh RETURN VALUES 129.Fn Select 130returns the number of ready descriptors that are contained in 131the descriptor sets, 132or -1 if an error occurred. 133If the time limit expires, 134.Fn select 135returns 0. 136If 137.Fn select 138returns with an error, 139including one due to an interrupted call, 140the descriptor sets will be unmodified. 141.Sh ERRORS 142An error return from 143.Fn select 144indicates: 145.Bl -tag -width Er 146.It Bq Er EBADF 147One of the descriptor sets specified an invalid descriptor. 148.It Bq Er EINTR 149A signal was delivered before the time limit expired and 150before any of the selected events occurred. 151.It Bq Er EINVAL 152The specified time limit is invalid. One of its components is 153negative or too large. 154.It Bq Er EINVAL 155.Fa nfds 156was invalid. 157.El 158.Sh SEE ALSO 159.Xr accept 2 , 160.Xr connect 2 , 161.Xr getdtablesize 2 , 162.Xr gettimeofday 2 , 163.Xr read 2 , 164.Xr recv 2 , 165.Xr send 2 , 166.Xr write 2 , 167.Xr clocks 7 168.Sh NOTES 169The default size of 170.Dv FD_SETSIZE 171is currently 1024. 172In order to accommodate programs which might potentially 173use a larger number of open files with 174.Fn select , 175it is possible 176to increase this size by having the program define 177.Dv FD_SETSIZE 178before the inclusion of any header which includes 179.In sys/types.h . 180.Pp 181If 182.Fa nfds 183is greater than the number of open files, 184.Fn select 185is not guaranteed to examine the unused file descriptors. For historical 186reasons, 187.Fn select 188will always examine the first 256 descriptors. 189.Sh HISTORY 190The 191.Fn select 192function call appeared in 193.Bx 4.2 . 194.Sh BUGS 195.St -susv2 196allows systems to modify the original timeout in place. 197Thus, it is unwise to assume that the timeout value will be unmodified 198by the 199.Fn select 200call. 201