- Uniformly use .In for header file references.
[dragonfly.git] / lib / libc / sys / select.2
CommitLineData
984263bc
MD
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 $
44cb301e 34.\" $DragonFly: src/lib/libc/sys/select.2,v 1.7 2006/05/26 19:39:37 swildner Exp $
984263bc
MD
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.
56c95343
SS
128.Pp
129Even if no descriptors are of interest, the timeout works as described,
89ea1e59
SS
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.
984263bc
MD
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
44cb301e 186.In sys/types.h .
984263bc
MD
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.
0b84df5c
SW
196.Sh HISTORY
197The
198.Fn select
199function call appeared in
200.Bx 4.2 .
984263bc
MD
201.Sh BUGS
202.St -susv2
203allows systems to modify the original timeout in place.
204Thus, it is unwise to assume that the timeout value will be unmodified
205by the
206.Fn select
207call.