| blob | d4cafb31b8127cbf47e13d987880c09ee8d33098 |
1 .\" $OpenBSD: getsockopt.2,v 1.50 2016/06/13 21:24:43 bluhm Exp $
2 .\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd Exp $
3 .\"
4 .\" Copyright (c) 1983, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94
32 .\"
33 .Dd October 24, 2016
34 .Dt GETSOCKOPT 2
35 .Os
36 .Sh NAME
37 .Nm getsockopt ,
38 .Nm setsockopt
39 .Nd get and set options on sockets
40 .Sh SYNOPSIS
41 .In sys/socket.h
42 .Ft int
43 .Fn getsockopt "int s" "int level" "int optname" "void *optval" "socklen_t *optlen"
44 .Ft int
45 .Fn setsockopt "int s" "int level" "int optname" "const void *optval" "socklen_t optlen"
46 .Sh DESCRIPTION
47 .Fn getsockopt
48 and
49 .Fn setsockopt
50 manipulate the
51 .Em options
52 associated with a socket.
53 Options may exist at multiple protocol levels;
54 they are always present at the uppermost
55 .Dq socket
56 level.
57 .Pp
58 When manipulating socket options the level at which the
59 option resides and the name of the option must be specified.
60 To manipulate options at the socket level,
61 .Fa level
62 is specified as
63 .Dv SOL_SOCKET .
64 To manipulate options at any other level the protocol number of the
65 appropriate protocol controlling the option is supplied.
66 For example, to indicate that an option is to be interpreted by the
67 TCP protocol,
68 .Fa level
69 should be set to the protocol number of TCP; see
70 .Xr getprotoent 3 .
71 .Pp
72 The parameters
73 .Fa optval
74 and
75 .Fa optlen
76 are used to access option values for
77 .Fn setsockopt .
78 For
79 .Fn getsockopt
80 they identify a buffer in which the value for the
81 requested option(s) are to be returned.
82 For
83 .Fn getsockopt ,
84 .Fa optlen
85 is a value-result parameter, initially containing the
86 size of the buffer pointed to by
87 .Fa optval ,
88 and modified on return to indicate the actual size of the value returned.
89 If no option value is to be supplied or returned,
90 .Fa optval
91 may be
92 .Dv NULL .
93 .Pp
94 .Fa optname
95 and any specified options are passed uninterpreted to the appropriate
96 protocol module for interpretation.
97 The include file
98 .In sys/socket.h
99 contains definitions for socket level options, described below.
100 Options at other protocol levels vary in format and name.
101 consult the appropriate entries in section 7P of the manual.
102 .Pp
103 Most socket-level options utilize an
104 .Li int
105 parameter for
106 .Fa optval .
107 For
108 .Fn setsockopt ,
109 the parameter should be non-zero to enable a boolean option,
110 or zero if the option is to be disabled.
111 .Dv SO_LINGER
112 uses a
113 .Li struct linger
114 parameter, defined in
115 .In sys/socket.h ,
116 which specifies the desired state of the option and the
117 linger interval (see below).
118 .Dv SO_SNDTIMEO
119 and
120 .Dv SO_RCVTIMEO
121 use a
122 .Li struct timeval
123 parameter, defined in
124 .In sys/time.h .
125 .Pp
126 The following options are recognized at the socket level.
127 Except as noted, each may be examined with
128 .Fn getsockopt
129 and set with
130 .Fn setsockopt .
131 .Pp
132 .Bl -tag -width SO_OOBINLINE -offset indent -compact
133 .It Dv SO_DEBUG
134 enables recording of debugging information
135 .It Dv SO_REUSEADDR
136 enables local address reuse
137 .It Dv SO_KEEPALIVE
138 enables keep connections alive
139 .It Dv SO_DONTROUTE
140 enables routing bypass for outgoing messages
141 .It Dv SO_LINGER
142 linger on close if data present
143 .It Dv SO_BROADCAST
144 enables permission to transmit broadcast messages
145 .It Dv SO_OOBINLINE
146 enables reception of out-of-band data in band
147 .It Dv SO_SNDBUF
148 set buffer size for output
149 .It Dv SO_RCVBUF
150 set buffer size for input
151 .It Dv SO_SNDTIMEO
152 set timeout value for output
153 .It Dv SO_RCVTIMEO
154 set timeout value for input
155 .It Dv SO_TIMESTAMP
156 enables reception of a timestamp with datagrams
157 .It Dv SO_DGRAM_ERRIND
158 application wants delayed error
159 .It Dv SO_EXCLBIND
160 enables exclusive binding of the socket
161 .It Dv SO_ALLZONES
162 bypass zone boundaries (privileged)
163 .It Dv SO_TYPE
164 get the type of the socket (get only)
165 .It Dv SO_ERROR
166 get and clear error on the socket (get only)
167 .It Dv SO_DOMAIN
168 get the domain used in the socket (get only)
169 .It Dv SO_PROTOTYPE
170 get the protocol type of the socket (get only)
171 .El
172 .Pp
173 .Dv SO_DEBUG
174 enables debugging in the underlying protocol modules.
175 .Dv SO_REUSEADDR
176 indicates that the rules used in validating addresses supplied in a
177 .Xr bind 2
178 call should allow reuse of local addresses.
179 .Dv SO_KEEPALIVE
180 enables the periodic transmission of messages on a connected socket.
181 Should the connected party fail to respond to these messages, the connection
182 is considered broken and processes using the socket are notified via a
183 .Dv SIGPIPE
184 signal when attempting to send data.
185 The
186 .Dv SO_DONTROUTE
187 option indicates that outgoing messages should bypass the standard
188 routing facilities. Messages are directed to the appropriate network
189 interface according to the destination address.
190 .Pp
191 .Dv SO_LINGER
192 controls the action taken when unsent messages
193 are queued on socket and a
194 .Xr close 2
195 is performed.
196 If the socket promises reliable delivery of data and
197 .Dv SO_LINGER
198 is set, the system will block the process on the
199 .Xr close 2
200 attempt until it is able to transmit the data or until it decides it
201 is unable to deliver the information (a timeout period measured in seconds,
202 termed the linger interval, is specified in the
203 .Fn setsockopt
204 call when
205 .Dv SO_LINGER
206 is requested).
207 If
208 .Dv SO_LINGER
209 is disabled and a
210 .Xr close 2
211 is issued, the system will process the close in a manner that allows
212 the process to continue as quickly as possible.
213 .Pp
214 The option
215 .Dv SO_BROADCAST
216 requests permission to send broadcast datagrams
217 on the socket.
218 Broadcast was a privileged operation in earlier versions of the system.
219 With protocols that support out-of-band data, the
220 .Dv SO_OOBINLINE
221 option requests that out-of-band data be placed in the normal data input
222 queue as received; it will then be accessible with
223 .Xr recv 2
224 or
225 .Xr read 2
226 calls without the
227 .Dv MSG_OOB
228 flag.
229 Some protocols always behave as if this option is set.
230 .Pp
231 .Dv SO_SNDBUF
232 and
233 .Dv SO_RCVBUF
234 are options to adjust the normal
235 buffer sizes allocated for output and input buffers, respectively.
236 The buffer size may be increased for high-volume connections,
237 or may be decreased to limit the possible backlog of incoming data.
238 The system places an absolute limit on these values.
239 .Pp
240 .Dv SO_SNDTIMEO
241 is an option to set a timeout value for output operations.
242 It accepts a
243 .Li struct timeval
244 parameter with the number of seconds and microseconds
245 used to limit waits for output operations to complete.
246 If a send operation has blocked for this much time,
247 it returns with a partial count or with the error
248 .Er EWOULDBLOCK
249 if no data was sent.
250 In the current implementation, this timer is restarted each time additional
251 data are delivered to the protocol,
252 implying that the limit applies to output portions ranging in size
253 from the low water mark to the high water mark for output.
254 .Dv SO_RCVTIMEO
255 is an option to set a timeout value for input operations.
256 It accepts a
257 .Li struct timeval
258 parameter with the number of seconds and microseconds
259 used to limit waits for input operations to complete.
260 In the current implementation, this timer is restarted each time additional
261 data are received by the protocol,
262 and thus the limit is in effect an inactivity timer.
263 If a receive operation has been blocked for this much time without
264 receiving additional data, it returns with a short count
265 or with the error
266 .Er EWOULDBLOCK
267 if no data were received.
268 .Pp
269 If the
270 .Dv SO_TIMESTAMP
271 option is enabled on a
272 .Dv SOCK_DGRAM
273 socket, the
274 .Xr recvmsg 2
275 call will return a timestamp corresponding to when the datagram was
276 received.
277 The msg_control field in the msghdr structure points to a buffer
278 that contains a cmsghdr structure followed by a struct timeval.
279 The cmsghdr fields have the following values:
280 .Bd -literal -offset indent
281 cmsg_len = CMSG_LEN(sizeof(struct timeval))
282 cmsg_level = SOL_SOCKET
283 cmsg_type = SCM_TIMESTAMP
284 .Ed
285 .Pp
286 If
287 .Dv SO_DGRAM_ERRIND
288 is set, certain delayed errors (such as ICMP port unreachable packets)
289 received after completion of
290 .Fn sendto
291 or
292 .Fn sendmsg
293 will cause a subsequent
294 .Fn sendto
295 or
296 .Fn sendmsg
297 with the same destination address to fail with the appropriate error.
298 .Pp
299 .Dv SO_EXCLBIND
300 enables the exclusive binding of a socket, overriding the use of
301 .Dv SO_REUSEADDR .
302 The actual semantics of
303 .Dv SO_EXCLBIND
304 depend on the underlying protocol; see
305 .Xr tcp 7P
306 or
307 .Xr udp 7P
308 for more information.
309 .Pp
310 .Dv SO_ALLZONES
311 can be used to bypass zone boundaries between shared-IP zones.
312 Normally, the system prevents a socket from being bound to an address
313 that is not assigned to the current zone. It also prevents a socket
314 that is bound to a wildcard address from receiving traffic for other
315 zones. However, some daemons which run in the global zone might need
316 to send and receive traffic using addresses that belong to other
317 shared-IP zones. If set before a socket is bound,
318 .Dv SO_ALLZONES
319 causes the socket to ignore zone boundaries between shared-IP zones
320 and permits the socket to be bound to any address assigned to the
321 shared-IP zones. If the socket is bound to a wildcard address, it
322 receives traffic intended for all shared-IP zones and behaves as if an
323 equivalent socket were bound in each active shared-IP zone.
324 Applications that use the
325 .Dv SO_ALLZONES
326 option to initiate connections or send datagram traffic should specify
327 the source address for outbound traffic by binding to a specific
328 address. There is no effect from setting this option in an
329 exclusive-IP zone. Setting this option requires the
330 .Dv sys_net_config
331 privilege. See
332 .Xr zones 5 .
333 .Pp
334 Finally,
335 .Dv SO_TYPE ,
336 .Dv SO_ERROR ,
337 .Dv SO_DOMAIN
338 and
339 .Dv SO_PROTOTYPE
340 are options used only with
341 .Fn getsockopt .
342 .Dv SO_TYPE
343 returns the type of the socket, such as
344 .Dv SOCK_STREAM ;
345 it is useful for servers that inherit sockets on startup.
346 .Dv SO_ERROR
347 returns any pending error on the socket and clears the error status.
348 It may be used to check for asynchronous errors on connected
349 datagram sockets or for other asynchronous errors.
350 .Dv SO_DOMAIN
351 returns the address family of the socket, such as
352 .Dv AF_INET .
353 .Dv SO_PROTOTYPE
354 returns the underlying protocol number for the socket if it is in the
355 .Dv PF_INET
356 or
357 .Dv PF_INET6
358 domains, or the address family used if the socket is in the
359 .Dv PF_ROUTE
360 domain.
361 .Sh RETURN VALUES
362 .Rv -std
363 .Sh ERRORS
364 The call succeeds unless:
365 .Bl -tag -width Er
366 .It Bq Er EBADF
367 The argument
368 .Fa s
369 is not a valid descriptor.
370 .It Bq Er ENOTSOCK
371 The argument
372 .Fa s
373 is a file, not a socket.
374 .It Bq Er ENOPROTOOPT
375 The option is unknown at the level indicated.
376 .It Bq Er EOPNOTSUPP
377 The option is unsupported.
378 .It Bq Er EFAULT
379 The address pointed to by
380 .Fa optval
381 is not in a valid part of the process address space.
382 For
383 .Fn getsockopt ,
384 this error may also be returned if
385 .Fa optlen
386 is not in a valid part of the process address space.
387 .It Bq Er ENOBUFS
388 Insufficient resources are available in the system to complete the
389 call.
390 .It Bq Er ENOPROTOOPT
391 The option is unknown at the level indicated.
392 .It Bq Er EINVAL
393 The specified option is invalid at the specified socket level or the
394 socket has been shut down.
395 .It Bq Er EACCES
396 The calling process does not have the appropriate privileges.
397 .El
398 .Sh SEE ALSO
399 .Xr connect 2 ,
400 .Xr ioctl 2 ,
401 .Xr poll 2 ,
402 .Xr select 2 ,
403 .Xr socket 2 ,
404 .Xr getprotoent 3 ,
405 .Xr protocols 4 ,
406 .Xr zones 5 ,
407 .Xr tcp 7P ,
408 .Xr udp 7P
409 .Sh STANDARDS
410 The
411 .Fn getsockopt
412 and
413 .Fn setsockopt
414 functions conform to
415 .St -p1003.1-2008 .
416 .Sh HISTORY
417 The
418 .Fn getsockopt
419 system call appeared in
420 .Bx 4.2 .
421 .Sh BUGS
422 Several of the socket options should be handled at lower levels of the system.