1select(3C)               Standard C Library Functions               select(3C)
2
3
4

NAME

6       select,  pselect,  FD_SET,  FD_CLR, FD_ISSET, FD_ZERO - synchronous I/O
7       multiplexing
8

SYNOPSIS

10       #include <sys/time.h>
11
12       int select(int nfds,
13            fd_set *restrict readfds, fd_set *restrict writefds,
14            fd_set *restrict errorfds,
15            struct timeval *restrict timeout);
16
17
18       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
24
25       void FD_SET(int fd, fd_set *fdset);
26
27
28       void FD_CLR(int fd, fd_set *fdset);
29
30
31       int FD_ISSET(int fd, fd_set *fdset);
32
33
34       void FD_ZERO(fd_set *fdset);
35
36

DESCRIPTION

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
43
44       The  select()  function is equivalent to the pselect() function, except
45       as follows:
46
47           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
53           o      The select() function has no sigmask argument. It behaves as
54                  pselect() does when sigmask is a null pointer.
55
56           o      Upon successful completion, the select() function might mod‐
57                  ify the object pointed to by the timeout argument.
58
59
60       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
65
66       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
71
72       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
77
78       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
83
84       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
89
90       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
99
100       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
114
115       The use of a timeout does not affect  any  pending  timers  set  up  by
116       alarm(2), ualarm(3C), or setitimer(2).
117
118
119       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
124
125       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
132
133       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
137
138       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
147
148       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
157
158       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
165
166       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
174
175       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
181
182       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
186
187       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
197
198       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
205
206       File  descriptors  associated with regular files always select true for
207       ready to read, ready to write, and error conditions.
208
209
210       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
216
217       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
220       FD_CLR(fd, &fdset)      Clears  the  bit  for the file descriptor fd in
221                               the file descriptor set fdset.
222
223
224       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
228
229       FD_SET(fd, &fdset)      Sets the bit for the file descriptor fd in  the
230                               file descriptor set fdset.
231
232
233       FD_ZERO(&fdset)         Initializes  the  file  descriptor set fdset to
234                               have zero bits for all file descriptors.
235
236
237
238       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

RETURN VALUES

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
248
249       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

ERRORS

255       The select() and pselect() functions will fail if:
256
257       EBADF     One or more of the file  descriptor  sets  specified  a  file
258                 descriptor that is not a valid open file descriptor.
259
260
261       EINTR     The  function  was  interrupted  before  any  of the selected
262                 events occurred and before the timeout interval expired.
263
264                 If SA_RESTART has been set for the interrupting signal, it is
265                 implementation-dependent whether select() restarts or returns
266                 with EINTR.
267
268
269       EINVAL    An invalid timeout interval was specified.
270
271
272       EINVAL    The nfds argument is less than 0 or greater than FD_SETSIZE.
273
274
275       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
279
280       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
285

USAGE

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
290
291       The use of a timeout does not affect  any  pending  timers  set  up  by
292       alarm(2), ualarm(3C) or setitimer(2).
293
294
295       On successful completion, the object pointed to by the timeout argument
296       may be modified.
297

ATTRIBUTES

299       See attributes(5) for descriptions of the following attributes:
300
301
302
303
304       ┌─────────────────────────────┬─────────────────────────────┐
305       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
306       ├─────────────────────────────┼─────────────────────────────┤
307       │Interface Stability          │Standard                     │
308       ├─────────────────────────────┼─────────────────────────────┤
309       │MT-Level                     │MT-Safe                      │
310       └─────────────────────────────┴─────────────────────────────┘
311

SEE ALSO

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

NOTES

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.
325
326
327
328SunOS 5.11                        1 Nov 2004                        select(3C)
Impressum