1 SELECT(3C) Standard C Library Functions SELECT(3C) 2 3 NAME 4 select, pselect, FD_SET, FD_CLR, FD_ISSET, FD_ZERO - synchronous I/O 5 multiplexing 6 7 SYNOPSIS 8 #include <sys/time.h> 9 10 int 11 select(int nfds, fd_set *restrict readfds, fd_set *restrict writefds, 12 fd_set *restrict errorfds, struct timeval *restrict timeout); 13 14 int 15 pselect(int nfds, fd_set *restrict readfds, fd_set *restrict writefds, 16 fd_set *restrict errorfds, const struct timespec *restrict timeout, 17 const sigset_t *restrict sigmask); 18 19 void 20 FD_SET(int fd, fd_set *fdset); 21 22 void 23 FD_CLR(int fd, fd_set *fdset); 24 25 int 26 FD_ISSET(int fd, fd_set *fd_set); 27 28 void 29 FD_ZERO(fd_set *fdset); 30 31 DESCRIPTION 32 The pselect() function examines the file descriptor sets whose addresses 33 are passed in the readfds, writefds, and errorfds parameters to see if 34 some of their descriptors are ready for reading, are ready for writing, 35 or have an exceptional condition pending, respectively. 36 37 The select() function is equivalent to the pselect() function, except as 38 follows: 39 40 o For the select() function, the timeout period is given in seconds and 41 microseconds in an argument of type struct timeval, whereas for the 42 pselect() function the timeout period is given in seconds and 43 nanoseconds in an argument of type struct timespec 44 45 o The select() function has no sigmask argument. It behaves as 46 pselect() does when sigmask is a null pointer. 47 48 o Upon successful completion, the select() function might modify the 49 object pointed to by the Itimeout argument. 50 51 The select() and pselect() functions support regular files, terminal and 52 pseudo-terminal devices, STREAMS-based files, FIFOs, pipes, and sockets. 53 The behavior of select() and pselect() on file descriptors that refer to 54 other types of file is unspecified. 55 56 The nfds argument specifies the range of file descriptors to be tested. 57 The first nfds descriptors are checked in each set; that is, the 58 descriptors from zero through ``nfds - 1'' in the descriptor sets are 59 examined. 60 61 If the readfds argument is not a null pointer, it points to an object of 62 type fd_set that on input specifies the file descriptors to be checked 63 for being ready to read, and on output indicates which file descriptors 64 are ready to read. 65 66 If the writefds argument is not a null pointer, it points to an object of 67 type fd_set that on input specifies the file descriptors to be checked 68 for being ready to write, and on output indicates which file descriptors 69 are ready to write. 70 71 If the errorfds argument is not a null pointer, it points to an object of 72 type fd_set that on input specifies the file descriptors to be checked 73 for error conditions pending, and on output indicates which file 74 descriptors have error conditions pending. 75 76 Upon successful completion, the objects pointed to by the readfds, 77 writefds, and errorfds arguments are modified to indicate which file 78 descriptors are ready for reading, ready for writing, or have an error 79 condition pending, respectively, and return the total number of ready 80 descriptors in all the output sets. For each file descriptor less than 81 nfds, the corresponding bit will be set on successful completion if it 82 was set on input and the associated condition is true for that file 83 descriptor. 84 85 If none of the selected descriptors are ready for the requested 86 operation, the select() or pselect() function blocks 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 select() or pselect() function takes before timing out. If the 90 timeout parameter is not a null pointer, it specifies a maximum interval 91 to wait for the selection to complete. If the specified time interval 92 expires without any requested operation becoming ready, the function 93 returns. If the timeout parameter is a null pointer, then the call to 94 select() or pselect() blocks indefinitely until at least one descriptor 95 meets the specified criteria. To effect a poll, the timeout parameter 96 should not be a null pointer, and should point to a zero-valued timespec 97 structure. 98 99 The use of a timeout does not affect any pending timers set up by 100 alarm(2), ualarm(3C), or setitimer(2). 101 102 If sigmask is not a null pointer, then the pselect() function replaces 103 the signal mask of the process by the set of signals pointed to by 104 sigmask before examining the descriptors, and restores the signal mask of 105 the process before returning. 106 107 A descriptor is considered ready for reading when a call to an input 108 function with O_NONBLOCK clear would not block, whether or not the 109 function would transfer data successfully. (The function might return 110 data, an end-of-file indication, or an error other than one indicating 111 that it is blocked, and in each of these cases the descriptor will be 112 considered ready for reading.) 113 114 A descriptor is considered ready for writing when a call to an output 115 function with O_NONBLOCK clear would not block, whether or not the 116 function would transfer data successfully. 117 118 If a socket has a pending error, it is considered to have an exceptional 119 condition pending. Otherwise, what constitutes an exceptional condition 120 is file type-specific. For a file descriptor for use with a socket, it 121 is protocol-specific except as noted below. For other file types, if the 122 operation is meaningless for a particular file type, select() or 123 pselect() indicates that the descriptor is ready for read or write 124 operations and indicates that the descriptor has no exceptional condition 125 pending. 126 127 If a descriptor refers to a socket, the implied input function is the 128 recvmsg(3XNET) function with parameters requesting normal and ancillary 129 data, such that the presence of either type causes the socket to be 130 marked as readable. The presence of out-of-band data is checked if the 131 socket option SO_OOBINLINE has been enabled, as out-of-band data is 132 enqueued with normal data. If the socket is currently listening, then it 133 is marked as readable if an incoming connection request has been 134 received, and a call to the accept function completes without blocking. 135 136 If a descriptor refers to a socket, the implied output function is the 137 sendmsg(3XNET) function supplying an amount of normal data equal to the 138 current value of the SO_SNDLOWAT option for the socket. If a non- 139 blocking call to the connect function has been made for a socket, and the 140 connection attempt has either succeeded or failed leaving a pending 141 error, the socket is marked as writable. 142 143 A socket is considered to have an exceptional condition pending if a 144 receive operation with O_NONBLOCK clear for the open file description and 145 with the MSG_OOB flag set would return out-of-band data without blocking. 146 (It is protocol-specific whether the MSG_OOB flag would be used to read 147 out-of-band data.) A socket will also be considered to have an 148 exceptional condition pending if an out-of-band data mark is present in 149 the receive queue. 150 151 A file descriptor for a socket that is listening for connections will 152 indicate that it is ready for reading, when connections are available. A 153 file descriptor for a socket that is connecting asynchronously will 154 indicate that it is ready for writing, when a connection has been 155 established. 156 157 Selecting true for reading on a socket descriptor upon which a 158 listen(3XNET) call has been performed indicates that a subsequent 159 accept(3XNET) call on that descriptor will not block. 160 161 If the timeout argument is not a null pointer, it points to an object of 162 type struct timeval that specifies a maximum interval to wait for the 163 selection to complete. If the timeout argument points to an object of 164 type struct timeval whose members are 0, select() does not block. If the 165 timeout argument is a null pointer, select() blocks until an event causes 166 one of the masks to be returned with a valid (non-zero) value. If the 167 time limit expires before any event occurs that would cause one of the 168 masks to be set to a non-zero value, select() completes successfully and 169 returns 0. 170 171 If the readfds, writefds, and errorfds arguments are all null pointers 172 and the timeout argument is not a null pointer, select() or pselect() 173 blocks for the time specified, or until interrupted by a signal. If the 174 readfds, writefds, and errorfds arguments are all null pointers and the 175 timeout argument is a null pointer, select() blocks until interrupted by 176 a signal. 177 178 File descriptors associated with regular files always select true for 179 ready to read, ready to write, and error conditions. 180 181 On failure, the objects pointed to by the readfds, writefds, and errorfds 182 arguments are not modified. If the timeout interval expires without the 183 specified condition being true for any of the specified file descriptors, 184 the objects pointed to by the readfds, writefds, and errorfds arguments 185 have all bits set to 0. 186 187 File descriptor masks of type fd_set can be initialized and tested with 188 the macros FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO(). 189 190 FD_CLR(fd, &fdset) 191 Clears the bit for the file descriptor fd in the file descriptor 192 set fdset. 193 194 FD_ISSET(fd, &fdset) 195 Returns a non-zero value if the bit for the file descriptor fd is 196 set in the file descriptor set pointed to by fdset, and 0 197 otherwise. 198 199 FD_SET(fd, &fdset) 200 Sets the bit for the file descriptor fd in the file descriptor 201 set fdset 202 203 FD_ZERO(&fdset) 204 Initializes the file descriptor set fdset to have zero bits for 205 all file descriptors. 206 207 The behavior of these macros is undefined if the fd argument is less than 208 0 or greater than or equal to FD_SETSIZE, or if fd is not a valid file 209 descriptor, or if any of the arguments are expressions with side effects. 210 211 RETURN VALUES 212 On successful completion, select() and pselect() return the total number 213 of bits set in the bit masks. Otherwise, 1 is returned and errno is set 214 to indicate the error. 215 216 The FD_CLR(), FD_SET(), and FD_ZERO(), macros return no value. The 217 FD_ISSET() macro returns a non-zero value if the bit for the file 218 descriptor fd is set in the file descriptor set pointed to by fdset, and 219 0 otherwise. 220 221 ERRORS 222 The select() and pselect() functions will fail if: 223 224 EBADF One or more of the file descriptor sets specified a file 225 descriptor that is not a valid open file descriptor. 226 227 EINTR The function was interrupted before any of the selected events 228 occurred and before the timeout interval expired. 229 230 If SA_RESTART has been set for the interrupting signal, it is 231 implementation-dependent whether select() restarts or returns 232 with EINTR 233 234 EINVAL An invalid timeout interval was specified. 235 236 EINVAL The nfds argument is less than 0 or greater than FD_SETSIZE. 237 238 EINVAL One of the specified file descriptors refers to a STREAM or 239 multiplexer that is linked (directly or indirectly) downstream 240 from a multiplexer. 241 242 EINVAL A component of the pointed-to time limit is outside the 243 acceptable range: t_sec must be between 0 and 10^8, inclusive. 244 t_usec must be greater than or equal to 0, and less than 10^6. 245 246 USAGE 247 The poll(2) function is preferred over this function. 248 249 The use of a timeout does not affect any pending timers set up by 250 alarm(2), ualarm(3C), or setitimer(2). 251 252 On successful completion, the object pointed to by the timeout argument 253 may be modified. 254 255 INTERFACE STABILITY 256 Standard 257 258 MT Level 259 MT-Safe 260 261 SEE ALSO 262 alarm(2), fcntl(2), poll(2), read(2), setitimer(2), write(2), ualarm(3C), 263 accept(3SOCKET), listen(3SOCKET), attributes(5), standards(5) 264 265 illumos December 28, 2016 illumos