1PSELECT(3P)                POSIX Programmer's Manual               PSELECT(3P)
2
3
4

PROLOG

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
11

NAME

13       pselect, select — synchronous I/O multiplexing
14

SYNOPSIS

16       #include <sys/select.h>
17
18       int pselect(int nfds, fd_set *restrict readfds,
19           fd_set *restrict writefds, fd_set *restrict errorfds,
20           const struct timespec *restrict timeout,
21           const sigset_t *restrict sigmask);
22       int select(int nfds, fd_set *restrict readfds,
23           fd_set *restrict writefds, fd_set *restrict errorfds,
24           struct timeval *restrict timeout);
25       void FD_CLR(int fd, fd_set *fdset);
26       int FD_ISSET(int fd, fd_set *fdset);
27       void FD_SET(int fd, fd_set *fdset);
28       void FD_ZERO(fd_set *fdset);
29

DESCRIPTION

31       The pselect() function shall examine the  file  descriptor  sets  whose
32       addresses  are passed in the readfds, writefds, and errorfds parameters
33       to see whether some of their descriptors are  ready  for  reading,  are
34       ready  for  writing,  or have an exceptional condition pending, respec‐
35       tively.
36
37       The select() function shall be equivalent to  the  pselect()  function,
38       except as follows:
39
40        *  For  the  select() function, the timeout period is given in seconds
41           and microseconds in an argument of type struct timeval, whereas for
42           the  pselect()  function the timeout period is given in seconds and
43           nanoseconds in an argument of type struct timespec.
44
45        *  The select() function has no sigmask argument; it shall  behave  as
46           pselect() does when sigmask is a null pointer.
47
48        *  Upon  successful  completion,  the select() function may modify the
49           object pointed to by the timeout argument.
50
51       The pselect() and select() functions shall support regular files,  ter‐
52       minal  and  pseudo-terminal devices, STREAMS-based files, FIFOs, pipes,
53       and sockets. The behavior of pselect() and select() on file descriptors
54       that refer to other types of file is unspecified.
55
56       The  nfds argument specifies the range of descriptors to be tested. The
57       first nfds descriptors shall be checked  in  each  set;  that  is,  the
58       descriptors  from  zero  through nfds−1 in the descriptor sets shall be
59       examined.
60
61       If the readfds argument is not a null pointer, it points to  an  object
62       of  type  fd_set  that  on  input  specifies the file descriptors to be
63       checked for being ready to read, and on  output  indicates  which  file
64       descriptors are ready to read.
65
66       If  the writefds argument is not a null pointer, it points to an object
67       of type fd_set that on input  specifies  the  file  descriptors  to  be
68       checked  for  being  ready to write, and on output indicates which file
69       descriptors are ready to write.
70
71       If the errorfds argument is not a null pointer, it points to an  object
72       of  type  fd_set  that  on  input  specifies the file descriptors to be
73       checked for error conditions pending, and  on  output  indicates  which
74       file descriptors have error conditions pending.
75
76       Upon  successful  completion,  the pselect() or select() function shall
77       modify the objects pointed to by the readfds,  writefds,  and  errorfds
78       arguments  to  indicate  which  file descriptors are ready for reading,
79       ready for writing, or have an error  condition  pending,  respectively,
80       and  shall return the total number of ready descriptors in all the out‐
81       put sets. For each file descriptor less than  nfds,  the  corresponding
82       bit  shall be set upon successful completion if it was set on input and
83       the associated condition is true for that file descriptor.
84
85       If none of the selected descriptors are ready for the requested  opera‐
86       tion, the pselect() or select() function shall block until at least one
87       of the requested operations becomes ready, until the timeout occurs, or
88       until interrupted by a signal.  The timeout parameter controls how long
89       the pselect() or select() function shall take before timing out. If the
90       timeout  parameter is not a null pointer, it specifies a maximum inter‐
91       val to wait for the selection to complete. If the specified time inter‐
92       val  expires  without any requested operation becoming ready, the func‐
93       tion shall return. If the timeout parameter is a null pointer, then the
94       call  to  pselect() or select() shall block indefinitely until at least
95       one descriptor meets the specified criteria.  To  effect  a  poll,  the
96       timeout  parameter  should not be a null pointer, and should point to a
97       zero-valued timespec structure.
98
99       The use of a timeout does not affect  any  pending  timers  set  up  by
100       alarm() or setitimer().
101
102       Implementations  may  place limitations on the maximum timeout interval
103       supported. All implementations shall support a maximum timeout interval
104       of at least 31 days. If the timeout argument specifies a timeout inter‐
105       val greater than the implementation-defined maximum value, the  maximum
106       value  shall  be  used as the actual timeout value. Implementations may
107       also place limitations on the granularity of timeout intervals. If  the
108       requested timeout interval requires a finer granularity than the imple‐
109       mentation supports, the actual timeout interval shall be rounded up  to
110       the next supported value.
111
112       If  sigmask  is  not  a null pointer, then the pselect() function shall
113       replace the signal mask of the caller by the set of signals pointed  to
114       by sigmask before examining the descriptors, and shall restore the sig‐
115       nal mask of the calling thread before returning.
116
117       A descriptor shall be considered ready for reading when a  call  to  an
118       input  function  with  O_NONBLOCK clear would not block, whether or not
119       the function would transfer  data  successfully.  (The  function  might
120       return  data,  an  end-of-file  indication,  or an error other than one
121       indicating that it is blocked, and in each of these cases the  descrip‐
122       tor shall be considered ready for reading.)
123
124       A  descriptor  shall  be considered ready for writing when a call to an
125       output function with O_NONBLOCK clear would not block, whether  or  not
126       the function would transfer data successfully.
127
128       If  a  socket  has  a  pending error, it shall be considered to have an
129       exceptional condition pending. Otherwise, what  constitutes  an  excep‐
130       tional  condition  is file type-specific. For a file descriptor for use
131       with a socket, it is protocol-specific except as noted below. For other
132       file  types  it is implementation-defined. If the operation is meaning‐
133       less for a particular file type, pselect() or select()  shall  indicate
134       that  the  descriptor  is ready for read or write operations, and shall
135       indicate that the descriptor has no exceptional condition pending.
136
137       If a descriptor refers to a socket, the implied input function  is  the
138       recvmsg()  function  with  parameters  requesting  normal and ancillary
139       data, such that the presence of either type shall cause the  socket  to
140       be  marked  as  readable.  The  presence  of  out-of-band data shall be
141       checked if the socket option SO_OOBINLINE has been enabled, as  out-of-
142       band data is enqueued with normal data. If the socket is currently lis‐
143       tening, then it shall be marked as readable if an  incoming  connection
144       request  has  been  received, and a call to the accept() function shall
145       complete without blocking.
146
147       If a descriptor refers to a socket, the implied output function is  the
148       sendmsg() function supplying an amount of normal data equal to the cur‐
149       rent value of the SO_SNDLOWAT option for the socket. If a  non-blocking
150       call to the connect() function has been made for a socket, and the con‐
151       nection attempt has either succeeded or failed leaving a pending error,
152       the socket shall be marked as writable.
153
154       A  socket  shall be considered to have an exceptional condition pending
155       if a receive operation with O_NONBLOCK clear for the open file descrip‐
156       tion  and with the MSG_OOB flag set would return out-of-band data with‐
157       out blocking. (It is protocol-specific whether the MSG_OOB  flag  would
158       be used to read out-of-band data.) A socket shall also be considered to
159       have an exceptional condition pending if an out-of-band  data  mark  is
160       present  in the receive queue. Other circumstances under which a socket
161       may be considered to have an exceptional condition pending  are  proto‐
162       col-specific and implementation-defined.
163
164       If  the readfds, writefds, and errorfds arguments are all null pointers
165       and the timeout argument is  not  a  null  pointer,  the  pselect()  or
166       select()  function  shall block for the time specified, or until inter‐
167       rupted by a signal. If the readfds, writefds,  and  errorfds  arguments
168       are  all  null pointers and the timeout argument is a null pointer, the
169       pselect() or select() function shall block until interrupted by a  sig‐
170       nal.
171
172       File descriptors associated with regular files shall always select true
173       for ready to read, ready to write, and error conditions.
174
175       On failure, the objects  pointed  to  by  the  readfds,  writefds,  and
176       errorfds  arguments  shall  not  be  modified.  If the timeout interval
177       expires without the specified condition being true for any of the spec‐
178       ified  file  descriptors,  the  objects  pointed  to  by  the  readfds,
179       writefds, and errorfds arguments shall have all bits set to 0.
180
181       File descriptor masks of type fd_set can be initialized and tested with
182       FD_CLR(),  FD_ISSET(),  FD_SET(),  and  FD_ZERO().   It  is unspecified
183       whether each of these is a macro or a function. If a  macro  definition
184       is  suppressed  in  order  to  access  an actual function, or a program
185       defines an external identifier with any of these names, the behavior is
186       undefined.
187
188       FD_CLR(fd,  fdsetp)  shall  remove  the file descriptor fd from the set
189       pointed to by fdsetp.  If fd is not a member of this set,  there  shall
190       be no effect on the set, nor will an error be returned.
191
192       FD_ISSET(fd,  fdsetp) shall evaluate to non-zero if the file descriptor
193       fd is a member of the set pointed to by fdsetp, and shall  evaluate  to
194       zero otherwise.
195
196       FD_SET(fd,  fdsetp) shall add the file descriptor fd to the set pointed
197       to by fdsetp.  If the file descriptor fd is already in this set,  there
198       shall be no effect on the set, nor will an error be returned.
199
200       FD_ZERO(fdsetp)  shall  initialize  the  descriptor  set  pointed to by
201       fdsetp to the null set. No error is returned if the set is not empty at
202       the time FD_ZERO() is invoked.
203
204       The  behavior  of  these macros is undefined if the fd argument is less
205       than 0 or greater than or equal to FD_SETSIZE, or if fd is not a  valid
206       file  descriptor, or if any of the arguments are expressions with side-
207       effects.
208
209       If a thread gets canceled during a pselect() call, the signal  mask  in
210       effect  when  executing  the registered cleanup functions is either the
211       original signal mask or the signal mask installed as part of  the  pse‐
212       lect() call.
213

RETURN VALUE

215       Upon  successful completion, the pselect() and select() functions shall
216       return the total number of bits set in the bit  masks.   Otherwise,  −1
217       shall be returned, and errno shall be set to indicate the error.
218
219       FD_CLR(),  FD_SET(),  and  FD_ZERO() do not return a value.  FD_ISSET()
220       shall return a non-zero value if the bit for the file descriptor fd  is
221       set in the file descriptor set pointed to by fdset, and 0 otherwise.
222

ERRORS

224       Under  the  following conditions, pselect() and select() shall fail and
225       set errno to:
226
227       EBADF  One or more  of  the  file  descriptor  sets  specified  a  file
228              descriptor that is not a valid open file descriptor.
229
230       EINTR  The  function  was interrupted before any of the selected events
231              occurred and before the timeout interval expired.
232
233                   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
237       EINVAL An invalid timeout interval was specified.
238
239       EINVAL The nfds argument is less than 0 or greater than FD_SETSIZE.
240
241       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
245       The following sections are informative.
246

EXAMPLES

248       None.
249

APPLICATION USAGE

251       None.
252

RATIONALE

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
263       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
267           void cleanup(void *arg)
268           {
269               sigset_t *ss = (sigset_t *) arg;
270               pthread_sigmask(SIG_SETMASK, ss, NULL);
271           }
272
273           int call_pselect(int nfds, fd_set *readfds, fd_set *writefds,
274               fd_set errorfds, const struct timespec *timeout,
275               const sigset_t *sigmask)
276           {
277               sigset_t oldmask;
278               int result;
279               pthread_sigmask(SIG_SETMASK, NULL, &oldmask);
280               pthread_cleanup_push(cleanup, &oldmask);
281               result = pselect(nfds, readfds, writefds, errorfds, timeout, sigmask);
282               pthread_cleanup_pop(0);
283               return result;
284           }
285

FUTURE DIRECTIONS

287       None.
288

SEE ALSO

290       accept(),  alarm(),  connect(),  fcntl(),  getitimer(), poll(), read(),
291       recvmsg(), sendmsg(), write()
292
293       The  Base   Definitions   volume   of   POSIX.1‐2008,   <sys_select.h>,
294       <sys_time.h>
295
297       Portions  of  this text are reprinted and reproduced in electronic form
298       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
299       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
300       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
301       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
302       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  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.unix.org/online.html .
307
308       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 .
312
313
314
315IEEE/The Open Group                  2013                          PSELECT(3P)
Impressum