2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
25 .\" This notice shall appear on any product containing this material.
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
43 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
56 .Nd synchronous I/O multiplexing
62 .Fa "fd_set *restrict readfds"
63 .Fa "fd_set *restrict writefds"
64 .Fa "fd_set *restrict errorfds"
65 .Fa "struct timeval *restrict timeout"
70 .Fa "fd_set *restrict readfds"
71 .Fa "fd_set *restrict writefds"
72 .Fa "fd_set *restrict errorfds"
73 .Fa "const struct timespec *restrict timeout"
74 .Fa "const sigset_t *restrict sigmask"
98 function examines the file descriptor sets whose addresses
104 parameters to see if some of their descriptors are ready for reading,
105 are ready for writing, or have an exceptional condition pending,
110 function is equivalent to the
112 function, except as follows:
117 function, the timeout period is given in seconds and
118 microseconds in an argument of type
122 function the timeout period is given in seconds and nanoseconds
123 in an argument of type
137 Upon successful completion, the
139 function might modify the object pointed to by the
148 functions support regular files, terminal and pseudo-terminal devices,
149 STREAMS-based files, FIFOs, pipes, and sockets.
154 on file descriptors that refer to other types of file is unspecified.
158 argument specifies the range of file descriptors to be tested.
161 descriptors are checked in each set; that is, the
162 descriptors from zero through
164 in the descriptor sets are examined.
168 argument is not a null pointer, it points to an object of
171 that on input specifies the file descriptors to be checked
172 for being ready to read, and on output indicates which file descriptors are
177 argument is not a null pointer, it points to an object of
180 that on input specifies the file descriptors to be checked
181 for being ready to write, and on output indicates which file descriptors are
186 argument is not a null pointer, it points to an object of
189 that on input specifies the file descriptors to be checked
190 for error conditions pending, and on output indicates which file descriptors
191 have error conditions pending.
193 Upon successful completion, the objects pointed to by the
198 arguments are modified to indicate which file descriptors are ready for reading,
199 ready for writing, or have an error condition pending, respectively, and return
200 the total number of ready descriptors in all the output sets.
201 For each file descriptor less than
203 the corresponding bit will be set on successful completion if it was set on
204 input and the associated condition is true for that file descriptor.
206 If none of the selected descriptors are ready for the requested operation, the
210 function blocks until at least one of the
211 requested operations becomes ready, until the timeout occurs, or until
212 interrupted by a signal.
215 parameter controls how long the
219 function takes before timing out.
222 parameter is not a null pointer, it specifies a maximum interval
223 to wait for the selection to complete.
224 If the specified time interval expires without any requested operation becoming
225 ready, the function returns.
228 parameter is a null pointer, then the call to
232 blocks indefinitely until at least one descriptor meets the
234 To effect a poll, the
236 parameter should not be a null pointer, and should point to a zero-valued
242 does not affect any pending timers set up by
250 is not a null pointer, then the
252 function replaces the signal mask of the process by the set of signals pointed
255 before examining the descriptors, and restores the signal mask of
256 the process before returning.
258 A descriptor is considered ready for reading when a call to an input function
261 clear would not block, whether or not the function would
262 transfer data successfully.
263 (The function might return data, an end-of-file indication, or an error other
264 than one indicating that it is blocked, and in each of these cases the
265 descriptor will be considered ready for reading.)
267 A descriptor is considered ready for writing when a call to an output function
270 clear would not block, whether or not the function would
271 transfer data successfully.
273 If a socket has a pending error, it is considered to have an exceptional
275 Otherwise, what constitutes an exceptional condition is file type-specific.
276 For a file descriptor for use with a socket, it is protocol-specific except as
278 For other file types, if the operation is meaningless for a particular file
283 indicates that the descriptor is ready for read or write operations and
284 indicates that the descriptor has no exceptional condition pending.
286 If a descriptor refers to a socket, the implied input function is the
288 function with parameters requesting normal and ancillary
289 data, such that the presence of either type causes the socket to be marked as
291 The presence of out-of-band data is checked if the socket option
293 has been enabled, as out-of-band data is enqueued with
295 If the socket is currently listening, then it is marked as readable if an
296 incoming connection request has been received, and a call to the accept function
297 completes without blocking.
299 If a descriptor refers to a socket, the implied output function is the
301 function supplying an amount of normal data equal to the
304 option for the socket.
305 If a non-blocking call to the connect function has been made for a socket, and
306 the connection attempt has either succeeded or failed leaving a pending error,
307 the socket is marked as writable.
309 A socket is considered to have an exceptional condition pending if a receive
312 clear for the open file description and with the
314 flag set would return out-of-band data without blocking.
315 (It is protocol-specific whether the
317 flag would be used to read out-of-band data.)
318 A socket will also be considered to have an exceptional condition pending if an
319 out-of-band data mark is present in the receive queue.
321 A file descriptor for a socket that is listening for connections will indicate
322 that it is ready for reading, when connections are available.
323 A file descriptor for a socket that is connecting asynchronously will indicate
324 that it is ready for writing, when a connection has been established.
326 Selecting true for reading on a socket descriptor upon which a
328 call has been performed indicates that a subsequent
330 call on that descriptor will not block.
334 argument is not a null pointer, it points to an object of type
336 that specifies a maximum interval to wait for the
337 selection to complete.
340 argument points to an object of type
347 argument is a null pointer,
349 blocks until an event causes one of the masks to be returned with a valid
351 If the time limit expires before any event occurs that would cause one of the
352 masks to be set to a non-zero value,
354 completes successfully and returns 0.
361 arguments are all null pointers and the
363 argument is not a null pointer,
367 blocks for the time specified, or until interrupted by a
374 arguments are all null pointers and the
376 argument is a null pointer,
378 blocks until interrupted by a signal.
380 File descriptors associated with regular files always select true for ready to
381 read, ready to write, and error conditions.
383 On failure, the objects pointed to by the
388 arguments are not modified.
389 If the timeout interval expires without the specified condition being true for
390 any of the specified file descriptors, the objects pointed to by the
395 arguments have all bits set to 0.
397 File descriptor masks of type
399 can be initialized and tested with the macros
405 .Bl -tag -width indent
406 .It Fn FD_CLR "fd" "&fdset"
407 Clears the bit for the file descriptor
409 in the file descriptor set
411 .It Fn FD_ISSET "fd" "&fdset"
412 Returns a non-zero value if the bit for the file descriptor
415 the file descriptor set pointed to by
418 .It Fn FD_SET "fd" "&fdset"
419 Sets the bit for the file descriptor
421 in the file descriptor set
423 .It Fn FD_ZERO "&fdset"
424 Initializes the file descriptor set \fIfdset\fR to have zero bits for all file
428 The behavior of these macros is undefined if the
430 argument is less than 0 or greater than or equal to
434 is not a valid file descriptor, or if any of the arguments are expressions
437 On successful completion,
442 number of bits set in the bit masks.
447 is set to indicate the error.
454 macros return no value.
457 macro returns a non-zero value if the bit for the file
460 is set in the file descriptor set pointed to by
470 functions will fail if:
471 .Bl -tag -width indent
473 One or more of the file descriptor sets specified a file descriptor that is not
474 a valid open file descriptor.
476 The function was interrupted before any of the selected events occurred and
477 before the timeout interval expired.
481 has been set for the interrupting signal, it is implementation-dependent whether
483 restarts or returns with
486 An invalid timeout interval was specified.
490 argument is less than 0 or greater than
493 One of the specified file descriptors refers to a STREAM or multiplexer that is
494 linked (directly or indirectly) downstream from a multiplexer.
496 A component of the pointed-to time limit is outside the acceptable range:
498 must be between 0 and 10^8, inclusive.
500 must be greater than or equal to 0, and less than 10^6.
505 function is preferred over this function.
507 The use of a timeout does not affect any pending timers set up by
513 On successful completion, the object pointed to by the
515 argument may be modified.
516 .Sh INTERFACE STABILITY