1.\" $NetBSD: select.2,v 1.15 2002/02/08 01:28:21 ross 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. If 110.Fa timeout 111is a nil pointer, the select blocks indefinitely. To affect a poll, the 112.Fa timeout 113argument should be non-nil, 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 nil pointers if no descriptors are of interest. 121.Sh RETURN VALUES 122.Fn select 123returns the number of ready descriptors that are contained in 124the descriptor sets, 125or -1 if an error occurred. 126If the time limit expires, 127.Fn select 128returns 0. 129If 130.Fn select 131returns with an error, 132including one due to an interrupted call, 133the descriptor sets will be unmodified. 134.Sh ERRORS 135An error return from 136.Fn select 137indicates: 138.Bl -tag -width Er 139.It Bq Er EFAULT 140One or more of 141.Fa readfds , 142.Fa writefds , 143or 144.Fa exceptfds 145points outside the process's allocated address space. 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.El 155.Sh SEE ALSO 156.Xr accept 2 , 157.Xr connect 2 , 158.Xr gettimeofday 2 , 159.Xr poll 2 , 160.Xr read 2 , 161.Xr recv 2 , 162.Xr send 2 , 163.Xr write 2 , 164.Xr getdtablesize 3 165.Sh HISTORY 166The 167.Fn select 168function call appeared in 169.Bx 4.2 . 170.Sh BUGS 171Although the provision of 172.Xr getdtablesize 3 173was intended to allow user programs to be written independent 174of the kernel limit on the number of open files, the dimension 175of a sufficiently large bit field for select remains a problem. 176The default size 177.Dv FD_SETSIZE 178(currently 256) is somewhat larger than 179the current kernel limit to the number of open files. 180However, in order to accommodate programs which might potentially 181use a larger number of open files with select, it is possible 182to increase this size within a program by providing 183a larger definition of 184.Dv FD_SETSIZE 185before the inclusion of 186.Aq Pa sys/types.h . 187.Pp 188.Fn select 189should probably return the time remaining from the original timeout, 190if any, by modifying the time value in place. 191This may be implemented in future versions of the system. 192Thus, it is unwise to assume that the timeout value will be unmodified 193by the 194.Fn select 195call. 196