1 .\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
34 .\" @(#)select.2 8.2 (Berkeley) 3/25/94
46 .Nd synchronous I/O multiplexing
48 .Fd #include <sys/select.h>
57 .Fa "fd_set *fdset_orig"
58 .Fa "fd_set *fdset_copy"
77 .Fa "fd_set *restrict readfds"
78 .Fa "fd_set *restrict writefds"
79 .Fa "fd_set *restrict errorfds"
80 .Fa "struct timeval *restrict timeout"
84 examines the I/O descriptor sets whose addresses are passed in
89 to see if some of their descriptors
90 are ready for reading, are ready for writing, or have an exceptional
91 condition pending, respectively.
94 descriptors are checked in each set;
95 i.e., the descriptors from 0 through
97 in the descriptor sets are examined. (Example: If you have set two file descriptors "4" and "17",
99 should not be "2", but rather "17 + 1" or "18".)
102 replaces the given descriptor sets
103 with subsets consisting of those descriptors that are ready
104 for the requested operation.
106 returns the total number of ready descriptors in all the sets.
108 The descriptor sets are stored as bit fields in arrays of integers.
109 The following macros are provided for manipulating such descriptor sets:
111 initializes a descriptor set
115 includes a particular descriptor
124 .Fn FD_ISSET fd &fdset
130 .Fn FD_COPY &fdset_orig &fdset_copy
131 replaces an already allocated
133 file descriptor set with a copy of
135 The behavior of these macros is undefined if
136 a descriptor value is less than zero or greater than or equal to
138 which is normally at least equal
139 to the maximum number of descriptors supported by the system.
143 is not a null pointer, it specifies a maximum interval to wait for the
144 selection to complete.
148 is a null pointer, the select blocks indefinitely.
150 To effect a poll, the
152 argument should be not be a null pointer,
153 but it should point to a zero-valued timeval structure.
158 and may be reused on subsequent calls, however it is good style to re-initialize
159 it before each invocation of
167 may be given as null pointers if no descriptors are of interest.
170 returns the number of ready descriptors that are contained in
172 or -1 if an error occurred.
173 If the time limit expires,
178 returns with an error,
179 including one due to an interrupted call,
180 the descriptor sets will be unmodified and the global variable
182 will be set to indicate the error.
190 The kernel was (perhaps temporarily) unable
191 to allocate the requested number of file descriptors.
194 One of the descriptor sets specified an invalid descriptor.
197 A signal was delivered before the time limit expired and
198 before any of the selected events occurred.
201 The specified time limit is invalid. One of its components is
202 negative or too large.
206 is greater than FD_SETSIZE and _DARWIN_UNLIMITED_SELECT is not defined.
209 .Fd #include <sys/select.h>
211 .Fd #include <sys/types.h>
212 .Fd #include <sys/time.h>
213 .Fd #include <unistd.h>
244 is greater than FD_SETSIZE.
245 Use a smaller value for
247 or compile with -D_DARWIN_UNLIMITED_SELECT.
252 .Xr getdtablesize 2 ,
260 Although the provision of
262 was intended to allow user programs to be written independent
263 of the kernel limit on the number of open files, the dimension
264 of a sufficiently large bit field for select remains a problem.
267 (currently 1024) is somewhat smaller than
268 the current kernel limit to the number of open files.
269 However, in order to accommodate programs which might potentially
270 use a larger number of open files with select, it is possible
271 to increase this size within a program by providing
272 a larger definition of
274 before the inclusion of
278 should probably have been designed to return the time remaining from the
279 original timeout, if any, by modifying the time value in place.
280 However, it is unlikely this semantic will ever be implemented, as the
281 change would cause source code compatibility problems.
282 In general it is unwise to assume that the timeout value will be
285 call, and the caller should reinitialize it on each invocation.
289 function call appeared in
projects / apple / xnu.git / blob