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