1PSELECT(P) POSIX Programmer's Manual PSELECT(P)
2
6 pselect, select - synchronous I/O multiplexing
7
9 #include <sys/select.h>
10 int pselect(int nfds, fd_set *restrict readfds,
12 fd_set *restrict writefds, fd_set *restrict errorfds,
13 const struct timespec *restrict timeout,
14 const sigset_t *restrict sigmask);
15 int select(int nfds, fd_set *restrict readfds,
16 fd_set *restrict writefds, fd_set *restrict errorfds,
17 struct timeval *restrict timeout);
18 void FD_CLR(int fd, fd_set *fdset);
19 int FD_ISSET(int fd, fd_set *fdset);
20 void FD_SET(int fd, fd_set *fdset);
21 void FD_ZERO(fd_set *fdset);
22
25 The pselect() function shall examine the file descriptor sets whose
26 addresses are passed in the readfds, writefds, and errorfds parameters
27 to see whether some of their descriptors are ready for reading, are
28 ready for writing, or have an exceptional condition pending, respec‐
29 tively.
30 The select() function shall be equivalent to the pselect() function,
32 except as follows:
33 * For the select() function, the timeout period is given in seconds
35 and microseconds in an argument of type struct timeval, whereas for
36 the pselect() function the timeout period is given in seconds and
37 nanoseconds in an argument of type struct timespec.
38 * The select() function has no sigmask argument; it shall behave as
40 pselect() does when sigmask is a null pointer.
41 * Upon successful completion, the select() function may modify the
43 object pointed to by the timeout argument.
44 The pselect() and select() functions shall support regular files, ter‐
46 minal and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes,
47 and sockets. The behavior of pselect() and select() on file descriptors
48 that refer to other types of file is unspecified.
49 The nfds argument specifies the range of descriptors to be tested. The
51 first nfds descriptors shall be checked in each set; that is, the
52 descriptors from zero through nfds-1 in the descriptor sets shall be
53 examined.
54 If the readfds argument is not a null pointer, it points to an object
56 of type fd_set that on input specifies the file descriptors to be
57 checked for being ready to read, and on output indicates which file
58 descriptors are ready to read.
59 If the writefds argument is not a null pointer, it points to an object
61 of type fd_set that on input specifies the file descriptors to be
62 checked for being ready to write, and on output indicates which file
63 descriptors are ready to write.
64 If the errorfds argument is not a null pointer, it points to an object
66 of type fd_set that on input specifies the file descriptors to be
67 checked for error conditions pending, and on output indicates which
68 file descriptors have error conditions pending.
69 Upon successful completion, the pselect() or select() function shall
71 modify the objects pointed to by the readfds, writefds, and errorfds
72 arguments to indicate which file descriptors are ready for reading,
73 ready for writing, or have an error condition pending, respectively,
74 and shall return the total number of ready descriptors in all the out‐
75 put sets. For each file descriptor less than nfds, the corresponding
76 bit shall be set on successful completion if it was set on input and
77 the associated condition is true for that file descriptor.
78 If none of the selected descriptors are ready for the requested opera‐
80 tion, the pselect() or select() function shall block until at least one
81 of the requested operations becomes ready, until the timeout occurs, or
82 until interrupted by a signal. The timeout parameter controls how long
83 the pselect() or select() function shall take before timing out. If the
84 timeout parameter is not a null pointer, it specifies a maximum inter‐
85 val to wait for the selection to complete. If the specified time
86 interval expires without any requested operation becoming ready, the
87 function shall return. If the timeout parameter is a null pointer, then
88 the call to pselect() or select() shall block indefinitely until at
89 least one descriptor meets the specified criteria. To effect a poll,
90 the timeout parameter should not be a null pointer, and should point to
91 a zero-valued timespec structure.
92 The use of a timeout does not affect any pending timers set up by
94 alarm(), ualarm(), or setitimer().
95 Implementations may place limitations on the maximum timeout interval
97 supported. All implementations shall support a maximum timeout interval
98 of at least 31 days. If the timeout argument specifies a timeout inter‐
99 val greater than the implementation-defined maximum value, the maximum
100 value shall be used as the actual timeout value. Implementations may
101 also place limitations on the granularity of timeout intervals. If the
102 requested timeout interval requires a finer granularity than the imple‐
103 mentation supports, the actual timeout interval shall be rounded up to
104 the next supported value.
105 If sigmask is not a null pointer, then the pselect() function shall
107 replace the signal mask of the process by the set of signals pointed to
108 by sigmask before examining the descriptors, and shall restore the sig‐
109 nal mask of the process before returning.
110 A descriptor shall be considered ready for reading when a call to an
112 input function with O_NONBLOCK clear would not block, whether or not
113 the function would transfer data successfully. (The function might
114 return data, an end-of-file indication, or an error other than one
115 indicating that it is blocked, and in each of these cases the descrip‐
116 tor shall be considered ready for reading.)
117 A descriptor shall be considered ready for writing when a call to an
119 output function with O_NONBLOCK clear would not block, whether or not
120 the function would transfer data successfully.
121 If a socket has a pending error, it shall be considered to have an
123 exceptional condition pending. Otherwise, what constitutes an excep‐
124 tional condition is file type-specific. For a file descriptor for use
125 with a socket, it is protocol-specific except as noted below. For other
126 file types it is implementation-defined. If the operation is meaning‐
127 less for a particular file type, pselect() or select() shall indicate
128 that the descriptor is ready for read or write operations, and shall
129 indicate that the descriptor has no exceptional condition pending.
130 If a descriptor refers to a socket, the implied input function is the
132 recvmsg() function with parameters requesting normal and ancillary
133 data, such that the presence of either type shall cause the socket to
134 be marked as readable. The presence of out-of-band data shall be
135 checked if the socket option SO_OOBINLINE has been enabled, as out-of-
136 band data is enqueued with normal data. If the socket is currently lis‐
137 tening, then it shall be marked as readable if an incoming connection
138 request has been received, and a call to the accept() function shall
139 complete without blocking.
140 If a descriptor refers to a socket, the implied output function is the
142 sendmsg() function supplying an amount of normal data equal to the cur‐
143 rent value of the SO_SNDLOWAT option for the socket. If a non-blocking
144 call to the connect() function has been made for a socket, and the con‐
145 nection attempt has either succeeded or failed leaving a pending error,
146 the socket shall be marked as writable.
147 A socket shall be considered to have an exceptional condition pending
149 if a receive operation with O_NONBLOCK clear for the open file descrip‐
150 tion and with the MSG_OOB flag set would return out-of-band data with‐
151 out blocking. (It is protocol-specific whether the MSG_OOB flag would
152 be used to read out-of-band data.) A socket shall also be considered to
153 have an exceptional condition pending if an out-of-band data mark is
154 present in the receive queue. Other circumstances under which a socket
155 may be considered to have an exceptional condition pending are proto‐
156 col-specific and implementation-defined.
157 If the readfds, writefds, and errorfds arguments are all null pointers
159 and the timeout argument is not a null pointer, the pselect() or
160 select() function shall block for the time specified, or until inter‐
161 rupted by a signal. If the readfds, writefds, and errorfds arguments
162 are all null pointers and the timeout argument is a null pointer, the
163 pselect() or select() function shall block until interrupted by a sig‐
164 nal.
165 File descriptors associated with regular files shall always select true
167 for ready to read, ready to write, and error conditions.
168 On failure, the objects pointed to by the readfds, writefds, and
170 errorfds arguments shall not be modified. If the timeout interval
171 expires without the specified condition being true for any of the spec‐
172 ified file descriptors, the objects pointed to by the readfds,
173 writefds, and errorfds arguments shall have all bits set to 0.
174 File descriptor masks of type fd_set can be initialized and tested with
176 FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO(). It is unspecified
177 whether each of these is a macro or a function. If a macro definition
178 is suppressed in order to access an actual function, or a program
179 defines an external identifier with any of these names, the behavior is
180 undefined.
181 FD_CLR(fd, fdsetp) shall remove the file descriptor fd from the set
183 pointed to by fdsetp. If fd is not a member of this set, there shall be
184 no effect on the set, nor will an error be returned.
185 FD_ISSET(fd, fdsetp) shall evaluate to non-zero if the file descriptor
187 fd is a member of the set pointed to by fdsetp, and shall evaluate to
188 zero otherwise.
189 FD_SET(fd, fdsetp) shall add the file descriptor fd to the set pointed
191 to by fdsetp. If the file descriptor fd is already in this set, there
192 shall be no effect on the set, nor will an error be returned.
193 FD_ZERO(fdsetp) shall initialize the descriptor set pointed to by
195 fdsetp to the null set. No error is returned if the set is not empty at
196 the time FD_ZERO() is invoked.
197 The behavior of these macros is undefined if the fd argument is less
199 than 0 or greater than or equal to FD_SETSIZE, or if fd is not a valid
200 file descriptor, or if any of the arguments are expressions with side
201 effects.
202
204 Upon successful completion, the pselect() and select() functions shall
205 return the total number of bits set in the bit masks. Otherwise, -1
206 shall be returned, and errno shall be set to indicate the error.
207 FD_CLR(), FD_SET(), and FD_ZERO() do not return a value. FD_ISSET()
209 shall return a non-zero value if the bit for the file descriptor fd is
210 set in the file descriptor set pointed to by fdset, and 0 otherwise.
211
213 Under the following conditions, pselect() and select() shall fail and
214 set errno to:
215 EBADF One or more of the file descriptor sets specified a file
217 descriptor that is not a valid open file descriptor.
218 EINTR The function was interrupted before any of the selected events
220 occurred and before the timeout interval expired.
221 If SA_RESTART has been set for the interrupting signal, it is implemen‐
223 tation-defined whether the function restarts or returns with [EINTR].
224 EINVAL An invalid timeout interval was specified.
226 EINVAL The nfds argument is less than 0 or greater than FD_SETSIZE.
228 EINVAL One of the specified file descriptors refers to a STREAM or mul‐
230 tiplexer that is linked (directly or indirectly) downstream from
231 a multiplexer.
232 The following sections are informative.
235
237 None.
238
240 None.
241
243 In previous versions of the Single UNIX Specification, the select()
244 function was defined in the <sys/time.h> header. This is now changed to
245 <sys/select.h>. The rationale for this change was as follows: the
246 introduction of the pselect() function included the <sys/select.h>
247 header and the <sys/select.h> header defines all the related defini‐
248 tions for the pselect() and select() functions. Backwards-compatibility
249 to existing XSI implementations is handled by allowing <sys/time.h> to
250 include <sys/select.h>.
251
253 None.
254
256 accept() , alarm() , connect() , fcntl() , poll() , read() , recvmsg()
257 , sendmsg() , setitimer() , ualarm() , write() , the Base Definitions
258 volume of IEEE Std 1003.1-2001, <sys/select.h>, <sys/time.h>
259
261 Portions of this text are reprinted and reproduced in electronic form
262 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
263 -- Portable Operating System Interface (POSIX), The Open Group Base
264 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
265 Electrical and Electronics Engineers, Inc and The Open Group. In the
266 event of any discrepancy between this version and the original IEEE and
267 The Open Group Standard, the original IEEE and The Open Group Standard
268 is the referee document. The original Standard can be obtained online
269 at http://www.opengroup.org/unix/online.html .
270IEEE/The Open Group 2003 PSELECT(P)