1 '\" te
   2 .\" Copyright (C) 2009, Sun Microsystems, Inc. All Rights Reserved
   3 .\" Copyright 1989 AT&T
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH GETSOCKOPT 3SOCKET "Jan 27, 2009"
   8 .SH NAME
   9 getsockopt, setsockopt \- get and set options on sockets
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBcc\fR [ \fIflag\fR ... ] \fIfile\fR ... \fB-lsocket\fR \fB -lnsl \fR [ \fIlibrary\fR ... ]
  14 #include <sys/types.h>
  15 #include <sys/socket.h>
  16 
  17 \fBint\fR \fBgetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBvoid *\fR\fIoptval\fR,
  18      \fBint *\fR\fIoptlen\fR);
  19 .fi
  20 
  21 .LP
  22 .nf
  23 \fBint\fR \fBsetsockopt\fR(\fBint\fR \fIs\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoptname\fR, \fBconst void *\fR\fIoptval\fR,
  24      \fBint\fR \fIoptlen\fR);
  25 .fi
  26 
  27 .SH DESCRIPTION
  28 .sp
  29 .LP
  30 The \fBgetsockopt()\fR and \fBsetsockopt()\fR functions manipulate options
  31 associated with a socket. Options may exist at multiple protocol levels; they
  32 are always present at the uppermost "socket" level.
  33 .sp
  34 .LP
  35 The \fIlevel\fR argument specifies the protocol level at which the option
  36 resides. To manipulate options at the socket level, specify the \fIlevel\fR
  37 argument as \fBSOL_SOCKET\fR. To manipulate options at the protocol level,
  38 supply the appropriate protocol number for the protocol controlling the option.
  39 For example, to indicate that an option will be interpreted by the \fBTCP\fR,
  40 set \fIlevel\fR to the protocol number of \fBTCP\fR, as defined in the
  41 \fB<netinet/in.h>\fR header, or as determined by using
  42 \fBgetprotobyname\fR(3SOCKET). Some socket protocol families may also define
  43 additional levels, such as \fBSOL_ROUTE\fR. Only socket-level options are
  44 described here.
  45 .sp
  46 .LP
  47 The parameters \fIoptval\fR and \fIoptlen\fR are used to access option values
  48 for \fBsetsockopt()\fR. For \fBgetsockopt()\fR, they identify a buffer in which
  49 the value(s) for the requested option(s) are to be returned. For
  50 \fBgetsockopt()\fR, \fIoptlen\fR is a value-result parameter, initially
  51 containing the size of the buffer pointed to by \fIoptval\fR, and modified on
  52 return to indicate the actual size of the value returned. Use a 0 \fIoptval\fR
  53 if no option value is to be supplied or returned.
  54 .sp
  55 .LP
  56 The \fIoptname\fR and any specified options are passed uninterpreted to the
  57 appropriate protocol module for interpretation. The include file
  58 <\fBsys/socket.h\fR> contains definitions for the socket-level options
  59 described below. Options at other protocol levels vary in format and name.
  60 .sp
  61 .LP
  62 Most socket-level options take an \fBint\fR for \fIoptval\fR. For
  63 \fBsetsockopt()\fR, the \fIoptval\fR parameter should be non-zero to enable a
  64 boolean option, or zero if the option is to be disabled. \fBSO_LINGER\fR uses a
  65 \fBstruct linger\fR parameter that specifies the desired state of the option
  66 and the linger interval. \fBstruct linger\fR is defined in
  67 <\fBsys/socket.h\fR>. \fBstruct\fR \fBlinger\fR contains the following members:
  68 .sp
  69 .ne 2
  70 .na
  71 \fB\fBl_onoff\fR\fR
  72 .ad
  73 .RS 12n
  74 on = 1/off = 0
  75 .RE
  76 
  77 .sp
  78 .ne 2
  79 .na
  80 \fB\fBl_linger\fR\fR
  81 .ad
  82 .RS 12n
  83 linger time, in seconds
  84 .RE
  85 
  86 .sp
  87 .LP
  88 The following options are recognized at the socket level. Except as noted, each
  89 may be examined with \fBgetsockopt()\fR and set with \fBsetsockopt()\fR.
  90 .sp
  91 .ne 2
  92 .na
  93 \fB\fBSO_DEBUG\fR\fR
  94 .ad
  95 .RS 19n
  96 enable/disable recording of debugging information
  97 .RE
  98 
  99 .sp
 100 .ne 2
 101 .na
 102 \fB\fBSO_REUSEADDR\fR\fR
 103 .ad
 104 .RS 19n
 105 enable/disable local address reuse
 106 .RE
 107 
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBSO_KEEPALIVE\fR\fR
 112 .ad
 113 .RS 19n
 114 enable/disable keep connections alive
 115 .RE
 116 
 117 .sp
 118 .ne 2
 119 .na
 120 \fB\fBSO_DONTROUTE\fR\fR
 121 .ad
 122 .RS 19n
 123 enable/disable routing bypass for outgoing messages
 124 .RE
 125 
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBSO_LINGER\fR\fR
 130 .ad
 131 .RS 19n
 132 linger on close if data is present
 133 .RE
 134 
 135 .sp
 136 .ne 2
 137 .na
 138 \fB\fBSO_BROADCAST\fR\fR
 139 .ad
 140 .RS 19n
 141 enable/disable permission to transmit broadcast messages
 142 .RE
 143 
 144 .sp
 145 .ne 2
 146 .na
 147 \fB\fBSO_OOBINLINE\fR\fR
 148 .ad
 149 .RS 19n
 150 enable/disable reception of out-of-band data in band
 151 .RE
 152 
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fBSO_SNDBUF\fR\fR
 157 .ad
 158 .RS 19n
 159 set buffer size for output
 160 .RE
 161 
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fBSO_RCVBUF\fR\fR
 166 .ad
 167 .RS 19n
 168 set buffer size for input
 169 .RE
 170 
 171 .sp
 172 .ne 2
 173 .na
 174 \fB\fBSO_DGRAM_ERRIND\fR\fR
 175 .ad
 176 .RS 19n
 177 application wants delayed error
 178 .RE
 179 
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fBSO_TIMESTAMP\fR\fR
 184 .ad
 185 .RS 19n
 186 enable/disable reception of timestamp with datagrams
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fBSO_EXCLBIND\fR\fR
 193 .ad
 194 .RS 19n
 195 enable/disable exclusive binding of the socket
 196 .RE
 197 
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBSO_TYPE\fR\fR
 202 .ad
 203 .RS 19n
 204 get the type of the socket (get only)
 205 .RE
 206 
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBSO_ERROR\fR\fR
 211 .ad
 212 .RS 19n
 213 get and clear error on the socket (get only)
 214 .RE
 215 
 216 .sp
 217 .ne 2
 218 .na
 219 \fB\fBSO_MAC_EXEMPT\fR\fR
 220 .ad
 221 .RS 19n
 222 get or set mandatory access control on the socket. This option is available
 223 only when the system is configured with Trusted Extensions.
 224 .RE
 225 
 226 .sp
 227 .ne 2
 228 .na
 229 \fB\fBSO_ALLZONES\fR\fR
 230 .ad
 231 .RS 19n
 232 bypass zone boundaries (privileged).
 233 .RE
 234 
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fBSO_DOMAIN\fR\fR
 239 .ad
 240 .RS 19n
 241 get the domain used in the socket (get only)
 242 .RE
 243 
 244 .sp
 245 .ne 2
 246 .na
 247 \fB\fBSO_PROTOTYPE\fR\fR
 248 .ad
 249 .RS 19n
 250 for socket in domains \fBPF_INET\fR and \fBPF_INET6\fR, get the underlying
 251 protocol number used in the socket. For socket in domain \fBPF_ROUTE\fR, get
 252 the address family used in the socket.
 253 .RE
 254 
 255 .sp
 256 .LP
 257 The \fBSO_DEBUG\fR option enables debugging in the underlying protocol modules.
 258 The \fBSO_REUSEADDR\fR option indicates that the rules used in validating
 259 addresses supplied in a \fBbind\fR(3SOCKET) call should allow reuse of local
 260 addresses. The \fBSO_KEEPALIVE\fR option enables the periodic transmission of
 261 messages on a connected socket. If the connected party fails to respond to
 262 these messages, the connection is considered broken and threads using the
 263 socket are notified using a \fBSIGPIPE\fR signal. The \fBSO_DONTROUTE\fR option
 264 indicates that outgoing messages should bypass the standard routing facilities.
 265 Instead, messages are directed to the appropriate network interface according
 266 to the network portion of the destination address.
 267 .sp
 268 .LP
 269 The \fBSO_LINGER\fR option controls the action taken when unsent messages are
 270 queued on a socket and a \fBclose\fR(2) is performed. If the socket promises
 271 reliable delivery of data and \fBSO_LINGER\fR is set, the system will block the
 272 thread on the \fBclose()\fR attempt until it is able to transmit the data or
 273 until it decides it is unable to deliver the information (a timeout period,
 274 termed the linger interval, is specified in the \fBsetsockopt()\fR call when
 275 \fBSO_LINGER\fR is requested). If \fBSO_LINGER\fR is disabled and a
 276 \fBclose()\fR is issued, the system will process the \fBclose()\fR in a manner
 277 that allows the thread to continue as quickly as possible.
 278 .sp
 279 .LP
 280 The option \fBSO_BROADCAST\fR requests permission to send broadcast datagrams
 281 on the socket. With protocols that support out-of-band data, the
 282 \fBSO_OOBINLINE\fR option requests that out-of-band data be placed in the
 283 normal data input queue as received; it will then be accessible with
 284 \fBrecv()\fR or \fBread()\fR calls without the \fBMSG_OOB\fR flag.
 285 .sp
 286 .LP
 287 The \fBSO_SNDBUF\fR and \fBSO_RCVBUF\fR options adjust the normal buffer sizes
 288 allocated for output and input buffers, respectively. The buffer size may be
 289 increased for high-volume connections or may be decreased to limit the possible
 290 backlog of incoming data. The maximum buffer size for \fBUDP\fR is determined
 291 by the value of the \fBndd\fR variable \fBudp_max_buf\fR. The maximum buffer
 292 size for \fBTCP\fR is determined the value of the \fBndd\fR variable
 293 \fBtcp_max_buf\fR. Use the \fBndd\fR(1M) utility to determine the current
 294 default values. See the \fISolaris Tunable Parameters Reference Manual\fR for
 295 information on setting the values of \fBudp_max_buf\fR and \fBtcp_max_buf\fR.
 296 At present, lowering \fBSO_RCVBUF\fR on a TCP connection after it has been
 297 established has no effect.
 298 .sp
 299 .LP
 300 By default, delayed errors (such as \fBICMP\fR port unreachable packets) are
 301 returned only for connected datagram sockets. The \fBSO_DGRAM_ERRIND\fR option
 302 makes it possible to receive errors for datagram sockets that are not
 303 connected. When this option is set, certain delayed errors received after
 304 completion of a \fBsendto()\fR or \fBsendmsg()\fR operation will cause a
 305 subsequent \fBsendto()\fR or \fBsendmsg()\fR operation using the same
 306 destination address (\fIto\fR parameter) to fail with the appropriate error.
 307 See \fBsend\fR(3SOCKET).
 308 .sp
 309 .LP
 310 If the \fBSO_TIMESTAMP\fR option is enabled on a \fBSO_DGRAM\fR or a
 311 \fBSO_RAW\fR socket, the \fBrecvmsg\fR(3XNET) call will return a timestamp in
 312 the native data format, corresponding to when the datagram was received.
 313 .sp
 314 .LP
 315 The \fBSO_EXCLBIND\fR option is used to enable or disable the exclusive binding
 316 of a socket. It overrides the use of the \fBSO_REUSEADDR\fR option to reuse an
 317 address on \fBbind\fR(3SOCKET). The actual semantics of the \fBSO_EXCLBIND\fR
 318 option depend on the underlying protocol. See \fBtcp\fR(7P) or \fBudp\fR(7P)
 319 for more information.
 320 .sp
 321 .LP
 322 The \fBSO_TYPE\fR and \fBSO_ERROR\fR options are used only with
 323 \fBgetsockopt()\fR. The \fBSO_TYPE\fR option returns the type of the socket,
 324 for example, \fBSOCK_STREAM\fR. It is useful for servers that inherit sockets
 325 on startup. The \fBSO_ERROR\fR option returns any pending error on the socket
 326 and clears the error status. It may be used to check for asynchronous errors on
 327 connected datagram sockets or for other asynchronous errors.
 328 .sp
 329 .LP
 330 The \fBSO_MAC_EXEMPT\fR option is used to toggle socket behavior with unlabeled
 331 peers. A socket that has this option enabled can communicate with an unlabeled
 332 peer if it is in the global zone or has a label that dominates the default
 333 label of the peer. Otherwise, the socket must have a label that is equal to the
 334 default label of the unlabeled peer. Calling \fBsetsockopt()\fR with this
 335 option returns an \fBEACCES\fR error if the process lacks the
 336 \fBNET_MAC_AWARE\fR privilege or if the socket is bound. The
 337 \fBSO_MAC_EXEMPT\fR option is available only when the system is configured with
 338 Trusted Extensions.
 339 .sp
 340 .LP
 341 The \fBSO_ALLZONES\fR option can be used to bypass zone boundaries between
 342 shared-IP zones. Normally, the system prevents a socket from being bound to an
 343 address that is not assigned to the current zone. It also prevents a socket
 344 that is bound to a wildcard address from receiving traffic for other zones.
 345 However, some daemons which run in the global zone might need to send and
 346 receive traffic using addresses that belong to other shared-IP zones. If set
 347 before a socket is bound, \fBSO_ALLZONES\fR causes the socket to ignore zone
 348 boundaries between shared-IP zones and permits the socket to be bound to any
 349 address assigned to the shared-IP zones. If the socket is bound to a wildcard
 350 address, it receives traffic intended for all shared-IP zones and behaves as if
 351 an equivalent socket were bound in each active shared-IP zone. Applications
 352 that use the \fBSO_ALLZONES\fR option to initiate connections or send datagram
 353 traffic should specify the source address for outbound traffic by binding to a
 354 specific address. There is no effect from setting this option in an
 355 exclusive-IP zone. Setting this option requires the \fBsys_net_config\fR
 356 privilege. See \fBzones\fR(5).
 357 .SH RETURN VALUES
 358 .sp
 359 .LP
 360 If successful, \fBgetsockopt()\fR and \fBsetsockopt()\fR return \fB0\fR.
 361 Otherwise, the functions return \fB\(mi1\fR and set \fBerrno\fR to indicate the
 362 error.
 363 .SH ERRORS
 364 .sp
 365 .LP
 366 The \fBgetsockopt()\fR and \fBsetsockopt()\fR calls succeed unless:
 367 .sp
 368 .ne 2
 369 .na
 370 \fB\fBEBADF\fR\fR
 371 .ad
 372 .RS 17n
 373 The argument \fIs\fR is not a valid file descriptor.
 374 .RE
 375 
 376 .sp
 377 .ne 2
 378 .na
 379 \fB\fBENOMEM\fR\fR
 380 .ad
 381 .RS 17n
 382 There was insufficient memory available for the operation to complete.
 383 .RE
 384 
 385 .sp
 386 .ne 2
 387 .na
 388 \fB\fBENOPROTOOPT\fR\fR
 389 .ad
 390 .RS 17n
 391 The option is unknown at the level indicated.
 392 .RE
 393 
 394 .sp
 395 .ne 2
 396 .na
 397 \fB\fBENOSR\fR\fR
 398 .ad
 399 .RS 17n
 400 There were insufficient STREAMS resources available for the operation to
 401 complete.
 402 .RE
 403 
 404 .sp
 405 .ne 2
 406 .na
 407 \fB\fBENOTSOCK\fR\fR
 408 .ad
 409 .RS 17n
 410 The argument \fIs\fR is not a socket.
 411 .RE
 412 
 413 .sp
 414 .ne 2
 415 .na
 416 \fB\fBENOBUFS\fR\fR
 417 .ad
 418 .RS 17n
 419 \fBSO_SNDBUF\fR or \fBSO_RCVBUF\fR exceeds a system limit.
 420 .RE
 421 
 422 .sp
 423 .ne 2
 424 .na
 425 \fB\fBEINVAL\fR\fR
 426 .ad
 427 .RS 17n
 428 Invalid length for a given socket option.
 429 .RE
 430 
 431 .sp
 432 .ne 2
 433 .na
 434 \fB\fBEHOSTUNREACH\fR\fR
 435 .ad
 436 .RS 17n
 437 Invalid address for \fBIP_MULTICAST_IF\fR.
 438 .RE
 439 
 440 .sp
 441 .ne 2
 442 .na
 443 \fB\fBEINVAL\fR\fR
 444 .ad
 445 .RS 17n
 446 Not a multicast address for \fBIP_ADD_MEMBERSHIP\fR and
 447 \fBIP_DROP_MEMBERSHIP\fR.
 448 .RE
 449 
 450 .sp
 451 .ne 2
 452 .na
 453 \fB\fBEADDRNOTAVAIL\fR\fR
 454 .ad
 455 .RS 17n
 456 Bad interface address for \fBIP_ADD_MEMBERSHIP\fR and \fBIP_DROP_MEMBERSHIP\fR.
 457 .RE
 458 
 459 .sp
 460 .ne 2
 461 .na
 462 \fB\fBEADDRINUSE\fR\fR
 463 .ad
 464 .RS 17n
 465 Address already joined for \fBIP_ADD_MEMBERSHIP\fR.
 466 .RE
 467 
 468 .sp
 469 .ne 2
 470 .na
 471 \fB\fBENOENT\fR\fR
 472 .ad
 473 .RS 17n
 474 Address not joined for \fBIP_DROP_MEMBERSHIP\fR.
 475 .RE
 476 
 477 .sp
 478 .ne 2
 479 .na
 480 \fB\fBEPERM\fR\fR
 481 .ad
 482 .RS 17n
 483 No permissions.
 484 .RE
 485 
 486 .sp
 487 .ne 2
 488 .na
 489 \fB\fBEACCES\fR\fR
 490 .ad
 491 .RS 17n
 492 Permission denied.
 493 .RE
 494 
 495 .sp
 496 .ne 2
 497 .na
 498 \fB\fBEINVAL\fR\fR
 499 .ad
 500 .RS 17n
 501 The specified option is invalid at the specified socket level, or the socket
 502 has been shut down.
 503 .RE
 504 
 505 .SH ATTRIBUTES
 506 .sp
 507 .LP
 508 See \fBattributes\fR(5) for descriptions of the following attributes:
 509 .sp
 510 
 511 .sp
 512 .TS
 513 box;
 514 c | c
 515 l | l .
 516 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 517 _
 518 MT-Level        Safe
 519 .TE
 520 
 521 .SH SEE ALSO
 522 .sp
 523 .LP
 524 \fBndd\fR(1M), \fBclose\fR(2), \fBioctl\fR(2), \fBread\fR(2),
 525 \fBbind\fR(3SOCKET), \fBgetprotobyname\fR(3SOCKET), \fBrecv\fR(3SOCKET),
 526 \fBrecvmsg\fR(3XNET), \fBsend\fR(3SOCKET), \fBsocket\fR(3SOCKET),
 527 \fBsocket.h\fR(3HEAD), \fBattributes\fR(5), \fBzones\fR(5), \fBtcp\fR(7P),
 528 \fBudp\fR(7P)
 529 .sp
 530 .LP
 531 \fISolaris Tunable Parameters Reference Manual\fR