1PSELECT(3P) POSIX Programmer's Manual PSELECT(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 pselect, select — synchronous I/O multiplexing
13
15 #include <sys/select.h>
16 int pselect(int nfds, fd_set *restrict readfds,
18 fd_set *restrict writefds, fd_set *restrict errorfds,
19 const struct timespec *restrict timeout,
20 const sigset_t *restrict sigmask);
21 int select(int nfds, fd_set *restrict readfds,
22 fd_set *restrict writefds, fd_set *restrict errorfds,
23 struct timeval *restrict timeout);
24 void FD_CLR(int fd, fd_set *fdset);
25 int FD_ISSET(int fd, fd_set *fdset);
26 void FD_SET(int fd, fd_set *fdset);
27 void FD_ZERO(fd_set *fdset);
28
30 The pselect() function shall examine the file descriptor sets whose
31 addresses are passed in the readfds, writefds, and errorfds parameters
32 to see whether some of their descriptors are ready for reading, are
33 ready for writing, or have an exceptional condition pending, respec‐
34 tively.
35 The select() function shall be equivalent to the pselect() function,
37 except as follows:
38 * For the select() function, the timeout period is given in seconds
40 and microseconds in an argument of type struct timeval, whereas for
41 the pselect() function the timeout period is given in seconds and
42 nanoseconds in an argument of type struct timespec.
43 * The select() function has no sigmask argument; it shall behave as
45 pselect() does when sigmask is a null pointer.
46 * Upon successful completion, the select() function may modify the
48 object pointed to by the timeout argument.
49 The pselect() and select() functions shall support regular files, ter‐
51 minal and pseudo-terminal devices, STREAMS-based files, FIFOs, pipes,
52 and sockets. The behavior of pselect() and select() on file descriptors
53 that refer to other types of file is unspecified.
54 The nfds argument specifies the range of descriptors to be tested. The
56 first nfds descriptors shall be checked in each set; that is, the
57 descriptors from zero through nfds-1 in the descriptor sets shall be
58 examined.
59 If the readfds 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 read, and on output indicates which file
63 descriptors are ready to read.
64 If the writefds 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 being ready to write, and on output indicates which file
68 descriptors are ready to write.
69 If the errorfds argument is not a null pointer, it points to an object
71 of type fd_set that on input specifies the file descriptors to be
72 checked for error conditions pending, and on output indicates which
73 file descriptors have error conditions pending.
74 Upon successful completion, the pselect() or select() function shall
76 modify the objects pointed to by the readfds, writefds, and errorfds
77 arguments to indicate which file descriptors are ready for reading,
78 ready for writing, or have an error condition pending, respectively,
79 and shall return the total number of ready descriptors in all the out‐
80 put sets. For each file descriptor less than nfds, the corresponding
81 bit shall be set upon successful completion if it was set on input and
82 the associated condition is true for that file descriptor.
83 If none of the selected descriptors are ready for the requested opera‐
85 tion, the pselect() or select() function shall block until at least one
86 of the requested operations becomes ready, until the timeout occurs, or
87 until interrupted by a signal. The timeout parameter controls how long
88 the pselect() or select() function shall take before timing out. If the
89 timeout parameter is not a null pointer, it specifies a maximum inter‐
90 val to wait for the selection to complete. If the specified time inter‐
91 val expires without any requested operation becoming ready, the func‐
92 tion shall return. If the timeout parameter is a null pointer, then the
93 call to pselect() or select() shall block indefinitely until at least
94 one descriptor meets the specified criteria. To effect a poll, the
95 timeout parameter should not be a null pointer, and should point to a
96 zero-valued timespec structure.
97 The use of a timeout does not affect any pending timers set up by
99 alarm() or setitimer().
100 Implementations may place limitations on the maximum timeout interval
102 supported. All implementations shall support a maximum timeout interval
103 of at least 31 days. If the timeout argument specifies a timeout inter‐
104 val greater than the implementation-defined maximum value, the maximum
105 value shall be used as the actual timeout value. Implementations may
106 also place limitations on the granularity of timeout intervals. If the
107 requested timeout interval requires a finer granularity than the imple‐
108 mentation supports, the actual timeout interval shall be rounded up to
109 the next supported value.
110 If sigmask is not a null pointer, then the pselect() function shall
112 replace the signal mask of the caller by the set of signals pointed to
113 by sigmask before examining the descriptors, and shall restore the sig‐
114 nal mask of the calling thread before returning.
115 A descriptor shall be considered ready for reading when a call to an
117 input function with O_NONBLOCK clear would not block, whether or not
118 the function would transfer data successfully. (The function might
119 return data, an end-of-file indication, or an error other than one
120 indicating that it is blocked, and in each of these cases the descrip‐
121 tor shall be considered ready for reading.)
122 A descriptor shall be considered ready for writing when a call to an
124 output function with O_NONBLOCK clear would not block, whether or not
125 the function would transfer data successfully.
126 If a socket has a pending error, it shall be considered to have an
128 exceptional condition pending. Otherwise, what constitutes an excep‐
129 tional condition is file type-specific. For a file descriptor for use
130 with a socket, it is protocol-specific except as noted below. For other
131 file types it is implementation-defined. If the operation is meaning‐
132 less for a particular file type, pselect() or select() shall indicate
133 that the descriptor is ready for read or write operations, and shall
134 indicate that the descriptor has no exceptional condition pending.
135 If a descriptor refers to a socket, the implied input function is the
137 recvmsg() function with parameters requesting normal and ancillary
138 data, such that the presence of either type shall cause the socket to
139 be marked as readable. The presence of out-of-band data shall be
140 checked if the socket option SO_OOBINLINE has been enabled, as out-of-
141 band data is enqueued with normal data. If the socket is currently lis‐
142 tening, then it shall be marked as readable if an incoming connection
143 request has been received, and a call to the accept() function shall
144 complete without blocking.
145 If a descriptor refers to a socket, the implied output function is the
147 sendmsg() function supplying an amount of normal data equal to the cur‐
148 rent value of the SO_SNDLOWAT option for the socket. If a non-blocking
149 call to the connect() function has been made for a socket, and the con‐
150 nection attempt has either succeeded or failed leaving a pending error,
151 the socket shall be marked as writable.
152 A socket shall be considered to have an exceptional condition pending
154 if a receive operation with O_NONBLOCK clear for the open file descrip‐
155 tion and with the MSG_OOB flag set would return out-of-band data with‐
156 out blocking. (It is protocol-specific whether the MSG_OOB flag would
157 be used to read out-of-band data.) A socket shall also be considered to
158 have an exceptional condition pending if an out-of-band data mark is
159 present in the receive queue. Other circumstances under which a socket
160 may be considered to have an exceptional condition pending are proto‐
161 col-specific and implementation-defined.
162 If the readfds, writefds, and errorfds arguments are all null pointers
164 and the timeout argument is not a null pointer, the pselect() or
165 select() function shall block for the time specified, or until inter‐
166 rupted by a signal. If the readfds, writefds, and errorfds arguments
167 are all null pointers and the timeout argument is a null pointer, the
168 pselect() or select() function shall block until interrupted by a sig‐
169 nal.
170 File descriptors associated with regular files shall always select true
172 for ready to read, ready to write, and error conditions.
173 On failure, the objects pointed to by the readfds, writefds, and
175 errorfds arguments shall not be modified. If the timeout interval
176 expires without the specified condition being true for any of the spec‐
177 ified file descriptors, the objects pointed to by the readfds,
178 writefds, and errorfds arguments shall have all bits set to 0.
179 File descriptor masks of type fd_set can be initialized and tested with
181 FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO(). It is unspecified
182 whether each of these is a macro or a function. If a macro definition
183 is suppressed in order to access an actual function, or a program
184 defines an external identifier with any of these names, the behavior is
185 undefined.
186 FD_CLR(fd, fdsetp) shall remove the file descriptor fd from the set
188 pointed to by fdsetp. If fd is not a member of this set, there shall
189 be no effect on the set, nor will an error be returned.
190 FD_ISSET(fd, fdsetp) shall evaluate to non-zero if the file descriptor
192 fd is a member of the set pointed to by fdsetp, and shall evaluate to
193 zero otherwise.
194 FD_SET(fd, fdsetp) shall add the file descriptor fd to the set pointed
196 to by fdsetp. If the file descriptor fd is already in this set, there
197 shall be no effect on the set, nor will an error be returned.
198 FD_ZERO(fdsetp) shall initialize the descriptor set pointed to by
200 fdsetp to the null set. No error is returned if the set is not empty at
201 the time FD_ZERO() is invoked.
202 The behavior of these macros is undefined if the fd argument is less
204 than 0 or greater than or equal to FD_SETSIZE, or if fd is not a valid
205 file descriptor, or if any of the arguments are expressions with side-
206 effects.
207 If a thread gets canceled during a pselect() call, the signal mask in
209 effect when executing the registered cleanup functions is either the
210 original signal mask or the signal mask installed as part of the pse‐
211 lect() call.
212
214 Upon successful completion, the pselect() and select() functions shall
215 return the total number of bits set in the bit masks. Otherwise, -1
216 shall be returned, and errno shall be set to indicate the error.
217 FD_CLR(), FD_SET(), and FD_ZERO() do not return a value. FD_ISSET()
219 shall return a non-zero value if the bit for the file descriptor fd is
220 set in the file descriptor set pointed to by fdset, and 0 otherwise.
221
223 Under the following conditions, pselect() and select() shall fail and
224 set errno to:
225 EBADF One or more of the file descriptor sets specified a file
227 descriptor that is not a valid open file descriptor.
228 EINTR The function was interrupted while blocked waiting for any of
230 the selected descriptors to become ready and before the timeout
231 interval expired.
232 If SA_RESTART has been set for the interrupting signal, it
234 is implementation-defined whether the function restarts or
235 returns with [EINTR].
236 EINVAL An invalid timeout interval was specified.
238 EINVAL The nfds argument is less than 0 or greater than FD_SETSIZE.
240 EINVAL One of the specified file descriptors refers to a STREAM or mul‐
242 tiplexer that is linked (directly or indirectly) downstream from
243 a multiplexer.
244 The following sections are informative.
246
248 None.
249
251 None.
252
254 In earlier versions of the Single UNIX Specification, the select()
255 function was defined in the <sys/time.h> header. This is now changed to
256 <sys/select.h>. The rationale for this change was as follows: the
257 introduction of the pselect() function included the <sys/select.h>
258 header and the <sys/select.h> header defines all the related defini‐
259 tions for the pselect() and select() functions. Backwards-compatibility
260 to existing XSI implementations is handled by allowing <sys/time.h> to
261 include <sys/select.h>.
262 Code which wants to avoid the ambiguity of the signal mask for thread
264 cancellation handlers can install an additional cancellation handler
265 which resets the signal mask to the expected value.
266 void cleanup(void *arg)
269 {
270 sigset_t *ss = (sigset_t *) arg;
271 pthread_sigmask(SIG_SETMASK, ss, NULL);
272 }
273 int call_pselect(int nfds, fd_set *readfds, fd_set *writefds,
275 fd_set errorfds, const struct timespec *timeout,
276 const sigset_t *sigmask)
277 {
278 sigset_t oldmask;
279 int result;
280 pthread_sigmask(SIG_SETMASK, NULL, &oldmask);
281 pthread_cleanup_push(cleanup, &oldmask);
282 result = pselect(nfds, readfds, writefds, errorfds, timeout, sigmask);
283 pthread_cleanup_pop(0);
284 return result;
285 }
286
288 None.
289
291 accept(), alarm(), connect(), fcntl(), getitimer(), poll(), read(),
292 recvmsg(), sendmsg(), write()
293 The Base Definitions volume of POSIX.1‐2017, <sys_select.h>,
295 <sys_time.h>
296
298 Portions of this text are reprinted and reproduced in electronic form
299 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
300 table Operating System Interface (POSIX), The Open Group Base Specifi‐
301 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
302 Electrical and Electronics Engineers, Inc and The Open Group. In the
303 event of any discrepancy between this version and the original IEEE and
304 The Open Group Standard, the original IEEE and The Open Group Standard
305 is the referee document. The original Standard can be obtained online
306 at http://www.opengroup.org/unix/online.html .
307 Any typographical or formatting errors that appear in this page are
309 most likely to have been introduced during the conversion of the source
310 files to man page format. To report such errors, see https://www.ker‐
311 nel.org/doc/man-pages/reporting_bugs.html .
312IEEE/The Open Group 2017 PSELECT(3P)