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.2 2003/06/17 04:26:47 dillon 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.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.Aq Pa 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 BUGS 190.St -susv2 191allows systems to modify the original timeout in place. 192Thus, it is unwise to assume that the timeout value will be unmodified 193by the 194.Fn select 195call. 196.Sh HISTORY 197The 198.Fn select 199function call appeared in 200.Bx 4.2 . 201