1 .\"
   2 .\" The contents of this file are subject to the terms of the
   3 .\" Common Development and Distribution License (the "License").
   4 .\" You may not use this file except in compliance with the License.
   5 .\"
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   7 .\" or http://www.opensolaris.org/os/licensing.
   8 .\" See the License for the specific language governing permissions
   9 .\" and limitations under the License.
  10 .\"
  11 .\" When distributing Covered Code, include this CDDL HEADER in each
  12 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  13 .\" If applicable, add the following below this CDDL HEADER, with the
  14 .\" fields enclosed by brackets "[]" replaced with your own identifying
  15 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  16 .\"
  17 .\"
  18 .\" Copyright 1989 AT&T
  19 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
  20 .\" Copyright 2018 Nexenta Systems, Inc.
  21 .\"
  22 .Dd August 2, 2018
  23 .Dt GETSOCKOPT 3C
  24 .Os
  25 .Sh NAME
  26 .Nm getsockopt ,
  27 .Nm setsockopt
  28 .Nd get and set options on sockets
  29 .Sh LIBRARY
  30 .Lb libc
  31 .Sh SYNOPSIS
  32 .In sys/types.h
  33 .In sys/socket.h
  34 .Ft int
  35 .Fo getsockopt
  36 .Fa "int s"
  37 .Fa "int level"
  38 .Fa "int optname"
  39 .Fa "void *restrict optval"
  40 .Fa "socklen_t *optlen"
  41 .Fc
  42 .Ft int
  43 .Fo setsockopt
  44 .Fa "int s"
  45 .Fa "int level"
  46 .Fa "int optname"
  47 .Fa "const void *optval"
  48 .Fa "socklen_t optlen"
  49 .Fc
  50 .Sh DESCRIPTION
  51 The
  52 .Fn getsockopt
  53 and
  54 .Fn setsockopt
  55 functions manipulate options associated with a socket.
  56 Options may exist at multiple protocol levels; they are always present at the
  57 uppermost "socket" level.
  58 .Pp
  59 The
  60 .Fa level
  61 argument specifies the protocol level at which the option resides.
  62 To manipulate options at the socket level, specify the
  63 .Fa level
  64 argument as
  65 .Dv SOL_SOCKET .
  66 To manipulate options at the protocol level, supply the appropriate protocol
  67 number for the protocol controlling the option.
  68 For example, to indicate that an option will be interpreted by the TCP, set
  69 .Fa level
  70 to the protocol number of TCP, as defined in the
  71 .In netinet/in.h
  72 header, or as determined by using
  73 .Xr getprotobyname 3SOCKET .
  74 Some socket protocol families may also define additional levels, such as
  75 .Dv SOL_ROUTE .
  76 Only socket-level options are described here.
  77 .Pp
  78 The parameters
  79 .Fa optval
  80 and
  81 .Fa optlen
  82 are used to access option values for
  83 .Fn setsockopt .
  84 For
  85 .Fn getsockopt ,
  86 they identify a buffer in which the value(s) for the requested option(s) are to
  87 be returned.
  88 For
  89 .Fn getsockopt ,
  90 .Fa optlen
  91 is a value-result parameter, initially containing the size of the buffer pointed
  92 to by
  93 .Fa optval ,
  94 and modified on return to indicate the actual size of the value returned.
  95 Use a 0
  96 .Fa optval
  97 if no option value is to be supplied or returned.
  98 .Pp
  99 The
 100 .Fa optname
 101 and any specified options are passed uninterpreted to the appropriate protocol
 102 module for interpretation.
 103 The include file
 104 .In sys/socket.h
 105 contains definitions for the socket-level options described below.
 106 Options at other protocol levels vary in format and name.
 107 .Pp
 108 Most socket-level options take an
 109 .Vt int
 110 for
 111 .Fa optval .
 112 For
 113 .Fn setsockopt ,
 114 the
 115 .Fa optval
 116 parameter should be non-zero to enable a boolean option, or zero if the option
 117 is to be disabled.
 118 .Dv SO_LINGER
 119 uses a
 120 .Vt "struct linger"
 121 parameter that specifies the desired state of the option and the linger
 122 interval.
 123 .Vt "struct linger"
 124 is defined in
 125 .In sys/socket.h .
 126 .Vt "struct linger"
 127 contains the following members:
 128 .Bl -tag -width "l_linger"
 129 .It Va l_onoff
 130 on = 1/off = 0
 131 .It Va l_linger
 132 linger time, in seconds
 133 .El
 134 .Pp
 135 The following options are recognized at the socket level.
 136 Except as noted, each may be examined with
 137 .Fn getsockopt
 138 and set with
 139 .Fn setsockopt .
 140 .Bl -tag -width "SO_DGRAM_ERRIND"
 141 .It Dv SO_DEBUG
 142 enable/disable recording of debugging information
 143 .It Dv SO_REUSEADDR
 144 enable/disable local address reuse
 145 .It Dv SO_KEEPALIVE
 146 enable/disable keep connections alive
 147 .It Dv SO_DONTROUTE
 148 enable/disable routing bypass for outgoing messages
 149 .It Dv SO_LINGER
 150 linger on close if data is present
 151 .It Dv SO_BROADCAST
 152 enable/disable permission to transmit broadcast messages
 153 .It Dv SO_OOBINLINE
 154 enable/disable reception of out-of-band data in band
 155 .It Dv SO_SNDBUF
 156 set buffer size for output
 157 .It Dv SO_RCVBUF
 158 set buffer size for input
 159 .It Dv SO_DGRAM_ERRIND
 160 application wants delayed error
 161 .It Dv SO_TIMESTAMP
 162 enable/disable reception of timestamp with datagrams
 163 .It Dv SO_EXCLBIND
 164 enable/disable exclusive binding of the socket
 165 .It Dv SO_TYPE
 166 get the type of the socket (get only)
 167 .It Dv SO_ERROR
 168 get and clear error on the socket (get only)
 169 .It Dv SO_MAC_EXEMPT
 170 get or set mandatory access control on the socket.
 171 This option is available only when the system is configured with Trusted
 172 Extensions.
 173 .It Dv SO_ALLZONES
 174 bypass zone boundaries (privileged).
 175 .It Dv SO_DOMAIN
 176 get the domain used in the socket (get only)
 177 .It Dv SO_PROTOTYPE
 178 for socket in domains
 179 .Dv PF_INET
 180 and
 181 .Dv PF_INET6 ,
 182 get the underlying protocol number used in the socket.
 183 For socket in domain
 184 .Dv PF_ROUTE ,
 185 get the address family used in the socket.
 186 .El
 187 .Pp
 188 The
 189 .Dv SO_DEBUG
 190 option enables debugging in the underlying protocol modules.
 191 The
 192 .Dv SO_REUSEADDR
 193 option indicates that the rules used in validating addresses supplied in a
 194 .Xr bind 3C
 195 call should allow reuse of local addresses.
 196 The
 197 .Dv SO_KEEPALIVE
 198 option enables the periodic transmission of messages on a connected socket.
 199 If the connected party fails to respond to these messages, the connection is
 200 considered broken and threads using the socket are notified using a
 201 .Dv SIGPIPE
 202 signal.
 203 The
 204 .Dv SO_DONTROUTE
 205 option indicates that outgoing messages should bypass the standard routing
 206 facilities.
 207 Instead, messages are directed to the appropriate network interface according
 208 to the network portion of the destination address.
 209 .Pp
 210 The
 211 .Dv SO_LINGER
 212 option controls the action taken when unsent messages are queued on a socket and
 213 a
 214 .Xr close 2
 215 is performed.
 216 If the socket promises reliable delivery of data and
 217 .Dv SO_LINGER
 218 is set, the system will block the thread on the
 219 .Xr close 2
 220 attempt until it is able to transmit the data or until it decides it is unable
 221 to deliver the information (a timeout period, termed the linger interval, is
 222 specified in the
 223 .Fn setsockopt
 224 call when
 225 .Dv SO_LINGER
 226 is requested).
 227 If
 228 .Dv SO_LINGER
 229 is disabled and a
 230 .Xr close 2
 231 is issued, the system will process the
 232 .Xr close 2
 233 in a manner that allows the thread to continue as quickly as possible.
 234 .Pp
 235 The option
 236 .Dv SO_BROADCAST
 237 requests permission to send broadcast datagrams on the socket.
 238 With protocols that support out-of-band data, the
 239 .Dv SO_OOBINLINE
 240 option requests that out-of-band data be placed in the normal data input queue
 241 as received; it will then be accessible with
 242 .Xr recv 3C
 243 or
 244 .Xr read 2
 245 calls without the
 246 .Dv MSG_OOB
 247 flag.
 248 .Pp
 249 The
 250 .Dv SO_SNDBUF
 251 and
 252 .Dv SO_RCVBUF
 253 options adjust the normal buffer sizes allocated for output and input buffers,
 254 respectively.
 255 The buffer size may be increased for high-volume connections or may be decreased
 256 to limit the possible backlog of incoming data.
 257 The maximum buffer size for UDP is determined by the value of the
 258 .Xr ndd 1M
 259 variable
 260 .Cm udp_max_buf .
 261 The maximum buffer size for TCP is determined the value of the
 262 .Xr ndd 1M
 263 variable
 264 .Cm tcp_max_buf .
 265 Use the
 266 .Xr ndd 1M
 267 utility to determine the current default values.
 268 At present, lowering
 269 .Dv SO_RCVBUF
 270 on a TCP connection after it has been established has no effect.
 271 .Pp
 272 By default, delayed errors (such as ICMP
 273 .Dq Port Unreachable
 274 packets) are returned only for connected datagram sockets.
 275 The
 276 .Dv SO_DGRAM_ERRIND
 277 option makes it possible to receive errors for datagram sockets that are not
 278 connected.
 279 When this option is set, certain delayed errors received after completion of a
 280 .Xr sendto 3C
 281 or
 282 .Xr sendmsg 3C
 283 operation will cause a subsequent
 284 .Xr sendto 3C
 285 or
 286 .Xr sendmsg 3C
 287 operation using the same destination address
 288 .Po Fa to
 289 parameter
 290 .Pc
 291 to fail with the appropriate error.
 292 See
 293 .Xr send 3C .
 294 .Pp
 295 If the
 296 .Dv SO_TIMESTAMP
 297 option is enabled on a
 298 .Dv SO_DGRAM
 299 or a
 300 .Dv SO_RAW
 301 socket, the
 302 .Xr recvmsg 3XNET
 303 call will return a timestamp in the native data format, corresponding to when
 304 the datagram was received.
 305 .Pp
 306 The
 307 .Dv SO_EXCLBIND
 308 option is used to enable or disable the exclusive binding of a socket.
 309 It overrides the use of the
 310 .Dv SO_REUSEADDR
 311 option to reuse an address on
 312 .Xr bind 3C .
 313 The actual semantics of the
 314 .Dv SO_EXCLBIND
 315 option depend on the underlying protocol.
 316 See
 317 .Xr tcp 7P
 318 or
 319 .Xr udp 7P
 320 for more information.
 321 .Pp
 322 The
 323 .Dv SO_TYPE
 324 and
 325 .Dv SO_ERROR
 326 options are used only with
 327 .Fn getsockopt .
 328 The
 329 .Dv SO_TYPE
 330 option returns the type of the socket, for example,
 331 .Dv SOCK_STREAM .
 332 It is useful for servers that inherit sockets on startup.
 333 The
 334 .Dv SO_ERROR
 335 option returns any pending error on the socket and clears the error status.
 336 It may be used to check for asynchronous errors on connected datagram sockets or
 337 for other asynchronous errors.
 338 .Pp
 339 The
 340 .Dv SO_MAC_EXEMPT
 341 option is used to toggle socket behavior with unlabeled peers.
 342 A socket that has this option enabled can communicate with an unlabeled peer if
 343 it is in the global zone or has a label that dominates the default label of the
 344 peer.
 345 Otherwise, the socket must have a label that is equal to the default label of
 346 the unlabeled peer.
 347 Calling
 348 .Fn setsockopt
 349 with this option returns an
 350 .Er EACCES
 351 error if the process lacks the
 352 .Dv NET_MAC_AWARE
 353 privilege or if the socket is bound.
 354 The
 355 .Dv SO_MAC_EXEMPT
 356 option is available only when the system is configured with Trusted Extensions.
 357 .Pp
 358 The
 359 .Dv SO_ALLZONES
 360 option can be used to bypass zone boundaries between shared-IP zones.
 361 Normally, the system prevents a socket from being bound to an address that is
 362 not assigned to the current zone.
 363 It also prevents a socket that is bound to a wildcard address from receiving
 364 traffic for other zones.
 365 However, some daemons which run in the global zone might need to send and
 366 receive traffic using addresses that belong to other shared-IP zones.
 367 If set before a socket is bound,
 368 .Dv SO_ALLZONES
 369 causes the socket to ignore zone boundaries between shared-IP zones and permits
 370 the socket to be bound to any address assigned to the shared-IP zones.
 371 If the socket is bound to a wildcard address, it receives traffic intended for
 372 all shared-IP zones and behaves as if an equivalent socket were bound in each
 373 active shared-IP zone.
 374 Applications that use the
 375 .Dv SO_ALLZONES
 376 option to initiate connections or send datagram traffic should specify the
 377 source address for outbound traffic by binding to a specific address.
 378 There is no effect from setting this option in an exclusive-IP zone.
 379 Setting this option requires the
 380 .Em sys_net_config
 381 privilege.
 382 See
 383 .Xr zones 5 .
 384 .Sh RETURN VALUES
 385 If successful,
 386 .Fn getsockopt
 387 and
 388 .Fn setsockopt
 389 return 0.
 390 Otherwise, the functions return -1 and set
 391 .Va errno
 392 to indicate the error.
 393 .Sh ERRORS
 394 The
 395 .Fn getsockopt
 396 and
 397 .Fn setsockopt
 398 calls succeed unless:
 399 .Bl -tag -width Er
 400 .It Bq Er EBADF
 401 The argument
 402 .Fa s
 403 is not a valid file descriptor.
 404 .It Bq Er ENOMEM
 405 There was insufficient memory available for the operation to complete.
 406 .It Bq Er ENOPROTOOPT
 407 The option is unknown at the level indicated.
 408 .It Bq Er ENOSR
 409 There were insufficient STREAMS resources available for the operation to
 410 complete.
 411 .It Bq Er ENOTSOCK
 412 The argument
 413 .Fa s
 414 is not a socket.
 415 .It Bq Er ENOBUFS
 416 .Dv SO_SNDBUF
 417 or
 418 .Dv SO_RCVBUF
 419 exceeds a system limit.
 420 .It Bq Er EINVAL
 421 Invalid length for a given socket option.
 422 .It Bq Er EHOSTUNREACH
 423 Invalid address for
 424 .Dv IP_MULTICAST_IF .
 425 .It Bq Er EINVAL
 426 Not a multicast address for
 427 .Dv IP_ADD_MEMBERSHIP
 428 and
 429 .Dv IP_DROP_MEMBERSHIP .
 430 .It Bq Er EADDRNOTAVAIL
 431 Bad interface address for
 432 .Dv IP_ADD_MEMBERSHIP
 433 and
 434 .Dv IP_DROP_MEMBERSHIP .
 435 .It Bq Er EADDRINUSE
 436 Address already joined for
 437 .Dv IP_ADD_MEMBERSHIP .
 438 .It Bq Er ENOENT
 439 Address not joined for
 440 .Dv IP_DROP_MEMBERSHIP .
 441 .It Bq Er EPERM
 442 No permissions.
 443 .It Bq Er EACCES
 444 Permission denied.
 445 .It Bq Er EINVAL
 446 The specified option is invalid at the specified socket level, or the socket
 447 has been shut down.
 448 .El
 449 .Sh MT-LEVEL
 450 .Sy Safe
 451 .Sh SEE ALSO
 452 .Xr ndd 1M ,
 453 .Xr close 2 ,
 454 .Xr ioctl 2 ,
 455 .Xr read 2 ,
 456 .Xr bind 3C ,
 457 .Xr recv 3C ,
 458 .Xr send 3C ,
 459 .Xr socket 3C ,
 460 .Xr socket.h 3HEAD ,
 461 .Xr getprotobyname 3SOCKET ,
 462 .Xr recvmsg 3XNET ,
 463 .Xr attributes 5 ,
 464 .Xr zones 5 ,
 465 .Xr tcp 7P ,
 466 .Xr udp 7P