1select(3C) Standard C Library Functions select(3C)
2
6 select, pselect, FD_SET, FD_CLR, FD_ISSET, FD_ZERO - synchronous I/O
7 multiplexing
8
10 #include <sys/time.h>
11 int select(int nfds,
13 fd_set *restrict readfds, fd_set *restrict writefds,
14 fd_set *restrict errorfds,
15 struct timeval *restrict timeout);
16 int pselect(int nfds,
19 fd_set *restrict readfds, fd_set *restrict writefds,
20 fd_set *restrict errorfds,
21 const struct timespec *restrict timeout,
22 const sigset_t *restrict sigmask);
23 void FD_SET(int fd, fd_set *fdset);
26 void FD_CLR(int fd, fd_set *fdset);
29 int FD_ISSET(int fd, fd_set *fdset);
32 void FD_ZERO(fd_set *fdset);
35
38 The pselect() function examines the file descriptor sets whose
39 addresses are passed in the readfds, writefds, and errorfds parameters
40 to see if some of their descriptors are ready for reading, are ready
41 for writing, or have an exceptional condition pending, respectively.
42 The select() function is equivalent to the pselect() function, except
45 as follows:
46 o For the select() function, the timeout period is given in
48 seconds and microseconds in an argument of type struct
49 timeval, whereas for the pselect() function the timeout
50 period is given in seconds and nanoseconds in an argument of
51 type struct timespec.
52 o The select() function has no sigmask argument. It behaves as
54 pselect() does when sigmask is a null pointer.
55 o Upon successful completion, the select() function might mod‐
57 ify the object pointed to by the timeout argument.
58 The select() and pselect() functions support regular files, terminal
61 and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and
62 sockets. The behavior of select() and pselect() on file descriptors
63 that refer to other types of file is unspecified.
64 The nfds argument specifies the range of file descriptors to be tested.
67 The first nfds descriptors are checked in each set; that is, the
68 descriptors from zero through nfds-1 in the descriptor sets are exam‐
69 ined.
70 If the readfs argument is not a null pointer, it points to an object of
73 type fd_set that on input specifies the file descriptors to be checked
74 for being ready to read, and on output indicates which file descriptors
75 are ready to read.
76 If the writefs argument is not a null pointer, it points to an object
79 of type fd_set that on input specifies the file descriptors to be
80 checked for being ready to write, and on output indicates which file
81 descriptors are ready to write.
82 If the errorfds argument is not a null pointer, it points to an object
85 of type fd_set that on input specifies the file descriptors to be
86 checked for error conditions pending, and on output indicates which
87 file descriptors have error conditions pending.
88 Upon successful completion, the objects pointed to by the readfs,
91 writefs, and errorfds arguments are modified to indicate which file
92 descriptors are ready for reading, ready for writing, or have an error
93 condition pending, respectively, and return the total number of ready
94 descriptors in all the output sets. For each file descriptor less than
95 nfds, the corresponding bit will be set on successful completion if it
96 was set on input and the associated condition is true for that file
97 descriptor.
98 If none of the selected descriptors are ready for the requested opera‐
101 tion, the select() or pselect() function blocks until at least one of
102 the requested operations becomes ready, until the timeout occurs, or
103 until interrupted by a signal. The timeout parameter controls how long
104 the select() or pselect() function takes before timing out. If the
105 timeout parameter is not a null pointer, it specifies a maximum inter‐
106 val to wait for the selection to complete. If the specified time inter‐
107 val expires without any requested operation becoming ready, the func‐
108 tion returns. If the timeout parameter is a null pointer, then the call
109 to select() or pselect() blocks indefinitely until at least one
110 descriptor meets the specified criteria. To effect a poll, the timeout
111 parameter should not be a null pointer, and should point to a zero-val‐
112 ued timespec structure.
113 The use of a timeout does not affect any pending timers set up by
116 alarm(2), ualarm(3C), or setitimer(2).
117 If sigmask is not a null pointer, then the pselect() function replaces
120 the signal mask of the process by the set of signals pointed to by sig‐
121 mask before examining the descriptors, and restores the signal mask of
122 the process before returning.
123 A descriptor is considered ready for reading when a call to an input
126 function with O_NONBLOCK clear would not block, whether or not the
127 function would transfer data successfully. (The function might return
128 data, an end-of-file indication, or an error other than one indicating
129 that it is blocked, and in each of these cases the descriptor will be
130 considered ready for reading.)
131 A descriptor is considered ready for writing when a call to an output
134 function with O_NONBLOCK clear would not block, whether or not the
135 function would transfer data successfully.
136 If a socket has a pending error, it is considered to have an excep‐
139 tional condition pending. Otherwise, what constitutes an exceptional
140 condition is file type-specific. For a file descriptor for use with a
141 socket, it is protocol-specific except as noted below. For other file
142 types, if the operation is meaningless for a particular file type,
143 select() or pselect() indicates that the descriptor is ready for read
144 or write operations and indicates that the descriptor has no excep‐
145 tional condition pending.
146 If a descriptor refers to a socket, the implied input function is the
149 recvmsg(3XNET) function with parameters requesting normal and ancillary
150 data, such that the presence of either type causes the socket to be
151 marked as readable. The presence of out-of-band data is checked if the
152 socket option SO_OOBINLINE has been enabled, as out-of-band data is
153 enqueued with normal data. If the socket is currently listening, then
154 it is marked as readable if an incoming connection request has been
155 received, and a call to the accept function completes without blocking.
156 If a descriptor refers to a socket, the implied output function is the
159 sendmsg(3XNET) function supplying an amount of normal data equal to the
160 current value of the SO_SNDLOWAT option for the socket. If a non-block‐
161 ing call to the connect function has been made for a socket, and the
162 connection attempt has either succeeded or failed leaving a pending
163 error, the socket is marked as writable.
164 A socket is considered to have an exceptional condition pending if a
167 receive operation with O_NONBLOCK clear for the open file description
168 and with the MSG_OOB flag set would return out-of-band data without
169 blocking. (It is protocol-specific whether the MSG_OOB flag would be
170 used to read out-of-band data.) A socket will also be considered to
171 have an exceptional condition pending if an out-of-band data mark is
172 present in the receive queue.
173 A file descriptor for a socket that is listening for connections will
176 indicate that it is ready for reading, when connections are available.
177 A file descriptor for a socket that is connecting asynchronously will
178 indicate that it is ready for writing, when a connection has been
179 established.
180 Selecting true for reading on a socket descriptor upon which a lis‐
183 ten(3XNET) call has been performed indicates that a subsequent
184 accept(3XNET) call on that descriptor will not block.
185 If the timeout argument is not a null pointer, it points to an object
188 of type struct timeval that specifies a maximum interval to wait for
189 the selection to complete. If the timeout argument points to an object
190 of type struct timeval whose members are 0, select() does not block. If
191 the timeout argument is a null pointer, select() blocks until an event
192 causes one of the masks to be returned with a valid (non-zero) value.
193 If the time limit expires before any event occurs that would cause one
194 of the masks to be set to a non-zero value, select() completes success‐
195 fully and returns 0.
196 If the readfs, writefs, and errorfds arguments are all null pointers
199 and the timeout argument is not a null pointer, select() or pselect()
200 blocks for the time specified, or until interrupted by a signal. If the
201 readfs, writefs, and errorfds arguments are all null pointers and the
202 timeout argument is a null pointer, select() blocks until interrupted
203 by a signal.
204 File descriptors associated with regular files always select true for
207 ready to read, ready to write, and error conditions.
208 On failure, the objects pointed to by the readfs, writefs, and errorfds
211 arguments are not modified. If the timeout interval expires without
212 the specified condition being true for any of the specified file
213 descriptors, the objects pointed to by the readfs, writefs, and
214 errorfds arguments have all bits set to 0.
215 File descriptor masks of type fd_set can be initialized and tested with
218 the macros FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO().
219 FD_CLR(fd, &fdset) Clears the bit for the file descriptor fd in
221 the file descriptor set fdset.
222 FD_ISSET(fd, &fdset) Returns a non-zero value if the bit for the
225 file descriptor fd is set in the file descrip‐
226 tor set pointed to by fdset, and 0 otherwise.
227 FD_SET(fd, &fdset) Sets the bit for the file descriptor fd in the
230 file descriptor set fdset.
231 FD_ZERO(&fdset) Initializes the file descriptor set fdset to
234 have zero bits for all file descriptors.
235 The behavior of these macros is undefined if the fd argument is less
239 than 0 or greater than or equal to FD_SETSIZE, or if fd is not a valid
240 file descriptor, or if any of the arguments are expressions with side
241 effects.
242
244 On successful completion, select() and pselect() return the total num‐
245 ber of bits set in the bit masks. Otherwise, −1 is returned and errno
246 is set to indicate the error.
247 The FD_CLR(), FD_SET(), and FD_ZERO() macros return no value. The
250 FD_ISSET() macro returns a non-zero value if the bit for the file
251 descriptor fd is set in the file descriptor set pointed to by fdset,
252 and 0 otherwise.
253
255 The select() and pselect() functions will fail if:
256 EBADF One or more of the file descriptor sets specified a file
258 descriptor that is not a valid open file descriptor.
259 EINTR The function was interrupted before any of the selected
262 events occurred and before the timeout interval expired.
263 If SA_RESTART has been set for the interrupting signal, it is
265 implementation-dependent whether select() restarts or returns
266 with EINTR.
267 EINVAL An invalid timeout interval was specified.
270 EINVAL The nfds argument is less than 0 or greater than FD_SETSIZE.
273 EINVAL One of the specified file descriptors refers to a STREAM or
276 multiplexer that is linked (directly or indirectly) down‐
277 stream from a multiplexer.
278 EINVAL A component of the pointed-to time limit is outside the
281 acceptable range: t_sec must be between 0 and 10^8, inclu‐
282 sive. t_usec must be greater than or equal to 0, and less
283 than 10^6.
284
287 The poll(2) function is preferred over this function. It must be used
288 when the number of file descriptors exceeds FD_SETSIZE.
289 The use of a timeout does not affect any pending timers set up by
292 alarm(2), ualarm(3C) or setitimer(2).
293 On successful completion, the object pointed to by the timeout argument
296 may be modified.
297
299 See attributes(5) for descriptions of the following attributes:
300 ┌─────────────────────────────┬─────────────────────────────┐
305 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
306 ├─────────────────────────────┼─────────────────────────────┤
307 │Interface Stability │Standard │
308 ├─────────────────────────────┼─────────────────────────────┤
309 │MT-Level │MT-Safe │
310 └─────────────────────────────┴─────────────────────────────┘
311
313 alarm(2), fcntl(2), poll(2), read(2), setitimer(2), write(2),
314 accept(3SOCKET), listen(3SOCKET), ualarm(3C), attributes(5), stan‐
315 dards(5)
316
318 The default value for FD_SETSIZE (currently 1024) is larger than the
319 default limit on the number of open files. To accommodate 32-bit appli‐
320 cations that wish to use a larger number of open files with select(),
321 it is possible to increase this size at compile time by providing a
322 larger definition of FD_SETSIZE before the inclusion of any system-sup‐
323 plied header. The maximum supported size for FD_SETSIZE is 65536. The
324 default value is already 65536 for 64-bit applications.
325SunOS 5.11 1 Nov 2004 select(3C)