Commit | Line | Data |
---|---|---|
931b8415 | 1 | .\" Copyright (c) 1983, 1991 The Regents of the University of California. |
da268306 | 2 | .\" All rights reserved. |
0f4ff25c | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
da268306 | 5 | .\" |
931b8415 | 6 | .\" @(#)select.2 6.8 (Berkeley) %G% |
0f4ff25c | 7 | .\" |
931b8415 CL |
8 | .Dd |
9 | .Dt SELECT 2 | |
10 | .Os BSD 4.2 | |
11 | .Sh NAME | |
12 | .Nm select | |
13 | .Nd synchronous I/O multiplexing | |
14 | .Sh SYNOPSIS | |
15 | .Fd #include <unistd.h> | |
16 | .Fd #include <sys/types.h> | |
17 | .Fd #include <sys/time.h> | |
18 | .Ft int | |
19 | .Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout" | |
20 | .Fn FD_SET fd &fdset | |
21 | .Fn FD_CLR fd &fdset | |
22 | .Fn FD_ISSET fd &fdset | |
23 | .Fn FD_ZERO &fdset | |
24 | .Sh DESCRIPTION | |
25 | .Fn Select | |
3dc1a400 | 26 | examines the I/O descriptor sets whose addresses are passed in |
931b8415 CL |
27 | .Fa readfds , |
28 | .Fa writefds , | |
0f4ff25c | 29 | and |
931b8415 | 30 | .Fa exceptfds |
71f64171 DS |
31 | to see if some of their descriptors |
32 | are ready for reading, are ready for writing, or have an exceptional | |
0f4ff25c | 33 | condition pending, respectively. |
71f64171 | 34 | The first |
931b8415 | 35 | .Fa nfds |
71f64171 | 36 | descriptors are checked in each set; |
931b8415 CL |
37 | i.e., the descriptors from 0 through |
38 | .Fa nfds Ns No -1 | |
71f64171 DS |
39 | in the descriptor sets are examined. |
40 | On return, | |
931b8415 | 41 | .Fn select |
71f64171 | 42 | replaces the given descriptor sets |
3dc1a400 MK |
43 | with subsets consisting of those descriptors that are ready |
44 | for the requested operation. | |
931b8415 CL |
45 | .Fn Select |
46 | returns the total number of ready descriptors in all the sets. | |
47 | .Pp | |
3dc1a400 MK |
48 | The descriptor sets are stored as bit fields in arrays of integers. |
49 | The following macros are provided for manipulating such descriptor sets: | |
931b8415 | 50 | .Fn FD_ZERO &fdsetx |
71f64171 | 51 | initializes a descriptor set |
931b8415 | 52 | .Fa fdset |
71f64171 | 53 | to the null set. |
931b8415 | 54 | .Fn FD_SET fd &fdset |
71f64171 | 55 | includes a particular descriptor |
931b8415 | 56 | .Fa fd |
71f64171 | 57 | in |
931b8415 CL |
58 | .Fa fdset . |
59 | .Fn FD_CLR fd &fdset | |
71f64171 | 60 | removes |
931b8415 | 61 | .Fa fd |
71f64171 | 62 | from |
931b8415 CL |
63 | .Fa fdset . |
64 | .Fn FD_ISSET fd &fdset | |
65 | is non-zero if | |
66 | .Fa fd | |
71f64171 | 67 | is a member of |
931b8415 | 68 | .Fa fdset , |
71f64171 DS |
69 | zero otherwise. |
70 | The behavior of these macros is undefined if | |
71 | a descriptor value is less than zero or greater than or equal to | |
931b8415 | 72 | .Dv FD_SETSIZE , |
71f64171 DS |
73 | which is normally at least equal |
74 | to the maximum number of descriptors supported by the system. | |
931b8415 | 75 | .Pp |
0f4ff25c | 76 | If |
931b8415 CL |
77 | .Fa timeout |
78 | is a non-nil pointer, it specifies a maximum interval to wait for the | |
0f4ff25c | 79 | selection to complete. If |
931b8415 CL |
80 | .Fa timeout |
81 | is a nil pointer, the select blocks indefinitely. To affect a poll, the | |
82 | .Fa timeout | |
83 | argument should be non-nil, pointing to a zero-valued timeval structure. | |
84 | .Pp | |
0f4ff25c | 85 | Any of |
931b8415 CL |
86 | .Fa readfds , |
87 | .Fa writefds , | |
0f4ff25c | 88 | and |
931b8415 CL |
89 | .Fa exceptfds |
90 | may be given as nil pointers if no descriptors are of interest. | |
91 | .Sh RETURN VALUES | |
92 | .Fn Select | |
71f64171 DS |
93 | returns the number of ready descriptors that are contained in |
94 | the descriptor sets, | |
931b8415 CL |
95 | or -1 if an error occurred. |
96 | If the time limit expires, | |
97 | .Fn select | |
0f4ff25c | 98 | returns 0. |
3dc1a400 | 99 | If |
931b8415 | 100 | .Fn select |
3dc1a400 MK |
101 | returns with an error, |
102 | including one due to an interrupted call, | |
103 | the descriptor sets will be unmodified. | |
931b8415 CL |
104 | .Sh ERRORS |
105 | An error return from | |
106 | .Fn select | |
107 | indicates: | |
108 | .Bl -tag -width Er | |
109 | .It Bq Er EBADF | |
71f64171 | 110 | One of the descriptor sets specified an invalid descriptor. |
931b8415 | 111 | .It Bq Er EINTR |
da051635 SS |
112 | A signal was delivered before the time limit expired and |
113 | before any of the selected events occurred. | |
931b8415 | 114 | .It Bq Er EINVAL |
71f64171 | 115 | The specified time limit is invalid. One of its components is |
da051635 | 116 | negative or too large. |
931b8415 CL |
117 | .El |
118 | .Sh SEE ALSO | |
119 | .Xr accept 2 , | |
120 | .Xr connect 2 , | |
121 | .Xr read 2 , | |
122 | .Xr write 2 , | |
123 | .Xr recv 2 , | |
124 | .Xr send 2 , | |
125 | .Xr getdtablesize 2 | |
126 | .Sh BUGS | |
3dc1a400 | 127 | Although the provision of |
931b8415 | 128 | .Xr getdtablesize 2 |
3dc1a400 MK |
129 | was intended to allow user programs to be written independent |
130 | of the kernel limit on the number of open files, the dimension | |
131 | of a sufficiently large bit field for select remains a problem. | |
931b8415 CL |
132 | The default size |
133 | .Dv FD_SETSIZE | |
134 | (currently 256) is somewhat larger than | |
3dc1a400 | 135 | the current kernel limit to the number of open files. |
a5c56ebf | 136 | However, in order to accommodate programs which might potentially |
3dc1a400 MK |
137 | use a larger number of open files with select, it is possible |
138 | to increase this size within a program by providing | |
931b8415 CL |
139 | a larger definition of |
140 | .Dv FD_SETSIZE | |
141 | before the inclusion of | |
142 | .Aq Pa sys/types.h . | |
143 | .Pp | |
144 | .Fn Select | |
3dc1a400 MK |
145 | should probably return the time remaining from the original timeout, |
146 | if any, by modifying the time value in place. | |
147 | This may be implemented in future versions of the system. | |
148 | Thus, it is unwise to assume that the timeout value will be unmodified | |
149 | by the | |
931b8415 | 150 | .Fn select |
3dc1a400 | 151 | call. |
931b8415 CL |
152 | .Sh HISTORY |
153 | The | |
154 | .Nm | |
155 | function call appeared in | |
156 | .Bx 4.2 . |