]>
Commit | Line | Data |
---|---|---|
9bccf70c A |
1 | .\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd Exp $ |
2 | .\" | |
3 | .\" Copyright (c) 1983, 1991, 1993 | |
4 | .\" The Regents of the University of California. All rights reserved. | |
5 | .\" | |
6 | .\" Redistribution and use in source and binary forms, with or without | |
7 | .\" modification, are permitted provided that the following conditions | |
8 | .\" are met: | |
9 | .\" 1. Redistributions of source code must retain the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer. | |
11 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
12 | .\" notice, this list of conditions and the following disclaimer in the | |
13 | .\" documentation and/or other materials provided with the distribution. | |
14 | .\" 3. All advertising materials mentioning features or use of this software | |
15 | .\" must display the following acknowledgement: | |
16 | .\" This product includes software developed by the University of | |
17 | .\" California, Berkeley and its contributors. | |
18 | .\" 4. Neither the name of the University nor the names of its contributors | |
19 | .\" may be used to endorse or promote products derived from this software | |
20 | .\" without specific prior written permission. | |
21 | .\" | |
22 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
23 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
24 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
25 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
26 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
27 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
28 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
29 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
30 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
31 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
32 | .\" SUCH DAMAGE. | |
33 | .\" | |
34 | .\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94 | |
35 | .\" | |
36 | .Dd April 19, 1994 | |
37 | .Dt GETSOCKOPT 2 | |
38 | .Os BSD 4.3r | |
39 | .Sh NAME | |
40 | .Nm getsockopt , | |
41 | .Nm setsockopt | |
42 | .Nd get and set options on sockets | |
43 | .Sh SYNOPSIS | |
9bccf70c A |
44 | .Fd #include <sys/socket.h> |
45 | .Ft int | |
2d21ac55 A |
46 | .Fo getsockopt |
47 | .Fa "int socket" | |
48 | .Fa "int level" | |
49 | .Fa "int option_name" | |
50 | .Fa "void *restrict option_value" | |
51 | .Fa "socklen_t *restrict option_len" | |
52 | .Fc | |
9bccf70c | 53 | .Ft int |
2d21ac55 A |
54 | .Fo setsockopt |
55 | .Fa "int socket" | |
56 | .Fa "int level" | |
57 | .Fa "int option_name" | |
58 | .Fa "const void *option_value" | |
59 | .Fa "socklen_t option_len" | |
60 | .Fc | |
9bccf70c A |
61 | .Sh DESCRIPTION |
62 | .Fn Getsockopt | |
63 | and | |
64 | .Fn setsockopt | |
65 | manipulate the | |
66 | .Em options | |
67 | associated with a socket. Options may exist at multiple | |
68 | protocol levels; they are always present at the uppermost | |
69 | .Dq socket | |
70 | level. | |
71 | .Pp | |
72 | When manipulating socket options the level at which the | |
73 | option resides and the name of the option must be specified. | |
74 | To manipulate options at the socket level, | |
75 | .Fa level | |
76 | is specified as | |
77 | .Dv SOL_SOCKET . | |
78 | To manipulate options at any | |
79 | other level the protocol number of the appropriate protocol | |
80 | controlling the option is supplied. For example, | |
81 | to indicate that an option is to be interpreted by the | |
82 | .Tn TCP | |
83 | protocol, | |
84 | .Fa level | |
85 | should be set to the protocol number of | |
86 | .Tn TCP ; | |
87 | see | |
88 | .Xr getprotoent 3 . | |
89 | .Pp | |
90 | The parameters | |
2d21ac55 | 91 | .Fa option_value |
9bccf70c | 92 | and |
2d21ac55 | 93 | .Fa option_len |
9bccf70c A |
94 | are used to access option values for |
95 | .Fn setsockopt . | |
96 | For | |
97 | .Fn getsockopt | |
98 | they identify a buffer in which the value for the | |
99 | requested option(s) are to be returned. For | |
100 | .Fn getsockopt , | |
2d21ac55 | 101 | .Fa option_len |
9bccf70c A |
102 | is a value-result parameter, initially containing the |
103 | size of the buffer pointed to by | |
2d21ac55 | 104 | .Fa option_value , |
9bccf70c A |
105 | and modified on return to indicate the actual size of |
106 | the value returned. If no option value is | |
107 | to be supplied or returned, | |
2d21ac55 | 108 | .Fa option_value |
9bccf70c A |
109 | may be NULL. |
110 | .Pp | |
2d21ac55 | 111 | .Fa option_name |
9bccf70c A |
112 | and any specified options are passed uninterpreted to the appropriate |
113 | protocol module for interpretation. | |
114 | The include file | |
115 | .Ao Pa sys/socket.h Ac | |
116 | contains definitions for | |
117 | socket level options, described below. | |
118 | Options at other protocol levels vary in format and | |
119 | name; consult the appropriate entries in | |
120 | section | |
121 | 4 of the manual. | |
122 | .Pp | |
123 | Most socket-level options utilize an | |
124 | .Fa int | |
125 | parameter for | |
2d21ac55 | 126 | .Fa option_value . |
9bccf70c A |
127 | For |
128 | .Fn setsockopt , | |
129 | the parameter should be non-zero to enable a boolean option, | |
130 | or zero if the option is to be disabled. | |
131 | .Dv SO_LINGER | |
132 | uses a | |
133 | .Fa struct linger | |
134 | parameter, defined in | |
135 | .Ao Pa sys/socket.h Ac , | |
136 | which specifies the desired state of the option and the | |
137 | linger interval (see below). | |
138 | .Dv SO_SNDTIMEO | |
139 | and | |
140 | .Dv SO_RCVTIMEO | |
141 | use a | |
142 | .Fa struct timeval | |
143 | parameter, defined in | |
144 | .Ao Pa sys/time.h Ac . | |
145 | .Pp | |
146 | The following options are recognized at the socket level. | |
147 | Except as noted, each may be examined with | |
148 | .Fn getsockopt | |
149 | and set with | |
150 | .Fn setsockopt . | |
151 | .Bl -column SO_OOBINLINE -offset indent | |
152 | .It Dv SO_DEBUG Ta "enables recording of debugging information" | |
153 | .It Dv SO_REUSEADDR Ta "enables local address reuse" | |
154 | .It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings" | |
155 | .It Dv SO_KEEPALIVE Ta "enables keep connections alive" | |
156 | .It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" | |
157 | .It Dv SO_LINGER Ta "linger on close if data present" | |
158 | .It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" | |
159 | .It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" | |
160 | .It Dv SO_SNDBUF Ta "set buffer size for output" | |
161 | .It Dv SO_RCVBUF Ta "set buffer size for input" | |
162 | .It Dv SO_SNDLOWAT Ta "set minimum count for output" | |
163 | .It Dv SO_RCVLOWAT Ta "set minimum count for input" | |
164 | .It Dv SO_SNDTIMEO Ta "set timeout value for output" | |
165 | .It Dv SO_RCVTIMEO Ta "set timeout value for input" | |
166 | .It Dv SO_TYPE Ta "get the type of the socket (get only)" | |
167 | .It Dv SO_ERROR Ta "get and clear error on the socket (get only)" | |
168 | .It Dv SO_NOSIGPIPE Ta "do not generate SIGPIPE, instead return EPIPE" | |
169 | .El | |
170 | .Pp | |
171 | .Dv SO_DEBUG | |
172 | enables debugging in the underlying protocol modules. | |
173 | .Dv SO_REUSEADDR | |
174 | indicates that the rules used in validating addresses supplied | |
175 | in a | |
176 | .Xr bind 2 | |
177 | call should allow reuse of local addresses. | |
178 | .Dv SO_REUSEPORT | |
179 | allows completely duplicate bindings by multiple processes | |
180 | if they all set | |
181 | .Dv SO_REUSEPORT | |
182 | before binding the port. | |
183 | This option permits multiple instances of a program to each | |
184 | receive UDP/IP multicast or broadcast datagrams destined for the bound port. | |
185 | .Dv SO_KEEPALIVE | |
186 | enables the | |
187 | periodic transmission of messages on a connected socket. Should the | |
188 | connected party fail to respond to these messages, the connection is | |
189 | considered broken and processes using the socket are notified via a | |
190 | .Dv SIGPIPE | |
191 | signal when attempting to send data. | |
192 | .Dv SO_DONTROUTE | |
193 | indicates that outgoing messages should | |
194 | bypass the standard routing facilities. Instead, messages are directed | |
195 | to the appropriate network interface according to the network portion | |
196 | of the destination address. | |
197 | .Pp | |
198 | .Dv SO_LINGER | |
199 | controls the action taken when unsent messages | |
200 | are queued on socket and a | |
201 | .Xr close 2 | |
202 | is performed. | |
203 | If the socket promises reliable delivery of data and | |
204 | .Dv SO_LINGER is set, | |
205 | the system will block the process on the | |
206 | .Xr close | |
207 | attempt until it is able to transmit the data or until it decides it | |
208 | is unable to deliver the information (a timeout period, termed the | |
209 | linger interval, is specified in the | |
210 | .Fn setsockopt | |
211 | call when | |
212 | .Dv SO_LINGER | |
213 | is requested). | |
214 | If | |
215 | .Dv SO_LINGER | |
216 | is disabled and a | |
217 | .Xr close | |
218 | is issued, the system will process the close in a manner that allows | |
219 | the process to continue as quickly as possible. | |
220 | .Pp | |
221 | The option | |
222 | .Dv SO_BROADCAST | |
223 | requests permission to send broadcast datagrams | |
224 | on the socket. | |
225 | Broadcast was a privileged operation in earlier versions of the system. | |
226 | With protocols that support out-of-band data, the | |
227 | .Dv SO_OOBINLINE | |
228 | option | |
229 | requests that out-of-band data be placed in the normal data input queue | |
230 | as received; it will then be accessible with | |
231 | .Xr recv | |
232 | or | |
233 | .Xr read | |
234 | calls without the | |
235 | .Dv MSG_OOB | |
236 | flag. | |
237 | Some protocols always behave as if this option is set. | |
238 | .Dv SO_SNDBUF | |
239 | and | |
240 | .Dv SO_RCVBUF | |
241 | are options to adjust the normal | |
242 | buffer sizes allocated for output and input buffers, respectively. | |
243 | The buffer size may be increased for high-volume connections, | |
244 | or may be decreased to limit the possible backlog of incoming data. | |
245 | The system places an absolute limit on these values. | |
246 | .Pp | |
247 | .Dv SO_SNDLOWAT | |
248 | is an option to set the minimum count for output operations. | |
2d21ac55 A |
249 | Most output operations process all of the data supplied by the call, |
250 | delivering data to the protocol for transmission | |
9bccf70c A |
251 | and blocking as necessary for flow control. |
252 | Nonblocking output operations will process as much data as permitted | |
2d21ac55 A |
253 | (subject to flow control) without blocking, |
254 | but will process no data if flow control | |
255 | does not allow the smaller of the low-water mark value | |
9bccf70c A |
256 | or the entire request to be processed. |
257 | A | |
258 | .Xr select 2 | |
259 | operation testing the ability to write to a socket will return true | |
2d21ac55 | 260 | only if the low-water mark amount could be processed. |
9bccf70c A |
261 | The default value for |
262 | .Dv SO_SNDLOWAT | |
263 | is set to a convenient size for network efficiency, often 1024. | |
2d21ac55 | 264 | .Pp |
9bccf70c A |
265 | .Dv SO_RCVLOWAT |
266 | is an option to set the minimum count for input operations. | |
267 | In general, receive calls will block until any (non-zero) amount of data | |
2d21ac55 A |
268 | is received, then return with the smaller of the amount available |
269 | or the amount requested. | |
9bccf70c A |
270 | The default value for |
271 | .Dv SO_RCVLOWAT | |
272 | is 1. | |
273 | If | |
274 | .Dv SO_RCVLOWAT | |
2d21ac55 A |
275 | is set to a larger value, blocking receive calls |
276 | normally wait until they have received the smaller | |
277 | of the low-water mark value or the requested amount. | |
278 | Receive calls may still return less than the low-water mark | |
279 | if an error occurs, a signal is caught, | |
280 | or the type of data next in the receive queue | |
9bccf70c A |
281 | is different than that returned. |
282 | .Pp | |
283 | .Dv SO_SNDTIMEO | |
284 | is an option to set a timeout value for output operations. | |
285 | It accepts a | |
286 | .Fa struct timeval | |
287 | parameter with the number of seconds and microseconds | |
288 | used to limit waits for output operations to complete. | |
289 | If a send operation has blocked for this much time, | |
290 | it returns with a partial count | |
291 | or with the error | |
292 | .Er EWOULDBLOCK | |
293 | if no data were sent. | |
294 | In the current implementation, this timer is restarted each time additional | |
295 | data are delivered to the protocol, | |
296 | implying that the limit applies to output portions ranging in size | |
2d21ac55 A |
297 | from the low-water mark to the high-water mark for output. |
298 | .Pp | |
9bccf70c A |
299 | .Dv SO_RCVTIMEO |
300 | is an option to set a timeout value for input operations. | |
301 | It accepts a | |
302 | .Fa struct timeval | |
303 | parameter with the number of seconds and microseconds | |
304 | used to limit waits for input operations to complete. | |
305 | In the current implementation, this timer is restarted each time additional | |
306 | data are received by the protocol, | |
307 | and thus the limit is in effect an inactivity timer. | |
308 | If a receive operation has been blocked for this much time without | |
309 | receiving additional data, it returns with a short count | |
310 | or with the error | |
311 | .Er EWOULDBLOCK | |
2d21ac55 A |
312 | if no data were received. |
313 | The struct timeval parameter must represent a positive time interval; | |
314 | otherwise, | |
55e303ae A |
315 | .Fn setsockopt |
316 | returns with the error | |
317 | .Er EDOM . | |
9bccf70c A |
318 | .Pp |
319 | .Dv SO_NOSIGPIPE is an option that prevents SIGPIPE from being raised | |
320 | when a write fails on a socket to which there is no reader; | |
2d21ac55 | 321 | instead, the write to the socket returns with the error |
9bccf70c A |
322 | .Er EPIPE |
323 | when there is no reader. | |
324 | .Pp | |
325 | Finally, | |
326 | .Dv SO_TYPE | |
327 | and | |
328 | .Dv SO_ERROR | |
329 | are options used only with | |
330 | .Fn getsockopt . | |
331 | .Dv SO_TYPE | |
332 | returns the type of the socket, such as | |
333 | .Dv SOCK_STREAM ; | |
334 | it is useful for servers that inherit sockets on startup. | |
335 | .Dv SO_ERROR | |
336 | returns any pending error on the socket and clears | |
337 | the error status. | |
338 | It may be used to check for asynchronous errors on connected | |
339 | datagram sockets or for other asynchronous errors. | |
340 | .Sh RETURN VALUES | |
2d21ac55 | 341 | .Rv -std |
9bccf70c | 342 | .Sh ERRORS |
2d21ac55 A |
343 | The |
344 | .Fn getsockopt | |
345 | and | |
346 | .Fn setsockopt | |
347 | system calls will succeed unless: | |
9bccf70c | 348 | .Bl -tag -width Er |
2d21ac55 | 349 | .\" ========== |
9bccf70c A |
350 | .It Bq Er EBADF |
351 | The argument | |
2d21ac55 A |
352 | .Fa socket |
353 | is not a valid file descriptor. | |
354 | .\" ========== | |
9bccf70c A |
355 | .It Bq Er EFAULT |
356 | The address pointed to by | |
2d21ac55 | 357 | .Fa option_value |
9bccf70c A |
358 | is not in a valid part of the process address space. |
359 | For | |
360 | .Fn getsockopt , | |
361 | this error may also be returned if | |
2d21ac55 | 362 | .Fa option_len |
9bccf70c | 363 | is not in a valid part of the process address space. |
2d21ac55 A |
364 | .\" ========== |
365 | .It Bq Er EINVAL | |
366 | The option is invalid at the level indicated. | |
367 | .\" ========== | |
368 | .It Bq Er ENOBUFS | |
369 | Insufficient memory buffers are available. | |
370 | .\" ========== | |
371 | .It Bq Er ENOPROTOOPT | |
372 | The option is unknown at the level indicated. | |
373 | .\" ========== | |
374 | .It Bq Er ENOTSOCK | |
375 | The argument | |
376 | .Fa socket | |
377 | is not a socket (e.g., a plain file). | |
378 | .El | |
379 | .Pp | |
380 | The | |
381 | .Fn setsockopt | |
382 | system call will succeed unless: | |
383 | .Bl -tag -width Er | |
384 | .\" ========== | |
55e303ae | 385 | .It Bq Er EDOM |
2d21ac55 A |
386 | The argument |
387 | .Fa option_value | |
388 | is out of bounds. | |
389 | .\" ========== | |
390 | .It Bq Er EISCONN | |
391 | .Fa socket | |
392 | is already connected | |
393 | and a specified option cannot be set | |
394 | while this is the case. | |
9bccf70c | 395 | .El |
2d21ac55 A |
396 | .Sh LEGACY SYNOPSIS |
397 | .Fd #include <sys/types.h> | |
398 | .Fd #include <sys/socket.h> | |
399 | .Pp | |
400 | The include file | |
401 | .In sys/types.h | |
402 | is necessary. | |
9bccf70c A |
403 | .Sh SEE ALSO |
404 | .Xr ioctl 2 , | |
405 | .Xr socket 2 , | |
2d21ac55 | 406 | .Xr getprotoent 3 , |
9bccf70c A |
407 | .Xr protocols 5 |
408 | .Sh BUGS | |
409 | Several of the socket options should be handled at lower levels of the system. | |
410 | .Sh HISTORY | |
411 | The | |
412 | .Fn getsockopt | |
413 | system call appeared in | |
414 | .Bx 4.2 . |