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