1 GETSOCKOPT(3C) Standard C Library Functions GETSOCKOPT(3C) 2 3 NAME 4 getsockopt, setsockopt - get and set options on sockets 5 6 LIBRARY 7 Standard C Library (libc, -lc) 8 9 SYNOPSIS 10 #include <sys/types.h> 11 #include <sys/socket.h> 12 13 int 14 getsockopt(int s, int level, int optname, void *restrict optval, 15 socklen_t *optlen); 16 17 int 18 setsockopt(int s, int level, int optname, const void *optval, 19 socklen_t optlen); 20 21 DESCRIPTION 22 The getsockopt() and setsockopt() functions manipulate options associated 23 with a socket. Options may exist at multiple protocol levels; they are 24 always present at the uppermost "socket" level. 25 26 The level argument specifies the protocol level at which the option 27 resides. To manipulate options at the socket level, specify the level 28 argument as SOL_SOCKET. To manipulate options at the protocol level, 29 supply the appropriate protocol number for the protocol controlling the 30 option. For example, to indicate that an option will be interpreted by 31 the TCP, set level to the protocol number of TCP, as defined in the 32 <netinet/in.h> header, or as determined by using getprotobyname(3SOCKET). 33 Some socket protocol families may also define additional levels, such as 34 SOL_ROUTE. Only socket-level options are described here. 35 36 The parameters optval and optlen are used to access option values for 37 setsockopt(). For getsockopt(), they identify a buffer in which the 38 value(s) for the requested option(s) are to be returned. For 39 getsockopt(), optlen is a value-result parameter, initially containing 40 the size of the buffer pointed to by optval, and modified on return to 41 indicate the actual size of the value returned. Use a 0 optval if no 42 option value is to be supplied or returned. 43 44 The optname and any specified options are passed uninterpreted to the 45 appropriate protocol module for interpretation. The include file 46 <sys/socket.h> contains definitions for the socket-level options 47 described below. Options at other protocol levels vary in format and 48 name. 49 50 Most socket-level options take an int for optval. For setsockopt(), the 51 optval parameter should be non-zero to enable a boolean option, or zero 52 if the option is to be disabled. SO_LINGER uses a struct linger 53 parameter that specifies the desired state of the option and the linger 54 interval. struct linger is defined in <sys/socket.h>. struct linger 55 contains the following members: 56 57 l_onoff on = 1/off = 0 58 59 l_linger linger time, in seconds 60 61 The following options are recognized at the socket level. Except as 62 noted, each may be examined with getsockopt() and set with setsockopt(). 63 64 SO_DEBUG enable/disable recording of debugging information 65 66 SO_REUSEADDR enable/disable local address reuse 67 68 SO_KEEPALIVE enable/disable keep connections alive 69 70 SO_DONTROUTE enable/disable routing bypass for outgoing messages 71 72 SO_LINGER linger on close if data is present 73 74 SO_BROADCAST enable/disable permission to transmit broadcast messages 75 76 SO_OOBINLINE enable/disable reception of out-of-band data in band 77 78 SO_SNDBUF set buffer size for output 79 80 SO_RCVBUF set buffer size for input 81 82 SO_DGRAM_ERRIND application wants delayed error 83 84 SO_TIMESTAMP enable/disable reception of timestamp with datagrams 85 86 SO_EXCLBIND enable/disable exclusive binding of the socket 87 88 SO_TYPE get the type of the socket (get only) 89 90 SO_ERROR get and clear error on the socket (get only) 91 92 SO_MAC_EXEMPT get or set mandatory access control on the socket. This 93 option is available only when the system is configured 94 with Trusted Extensions. 95 96 SO_ALLZONES bypass zone boundaries (privileged). 97 98 SO_DOMAIN get the domain used in the socket (get only) 99 100 SO_PROTOTYPE for socket in domains PF_INET and PF_INET6, get the 101 underlying protocol number used in the socket. For 102 socket in domain PF_ROUTE, get the address family used 103 in the socket. 104 105 The SO_DEBUG option enables debugging in the underlying protocol modules. 106 The SO_REUSEADDR option indicates that the rules used in validating 107 addresses supplied in a bind(3C) call should allow reuse of local 108 addresses. The SO_KEEPALIVE option enables the periodic transmission of 109 messages on a connected socket. If the connected party fails to respond 110 to these messages, the connection is considered broken and threads using 111 the socket are notified using a SIGPIPE signal. The SO_DONTROUTE option 112 indicates that outgoing messages should bypass the standard routing 113 facilities. Instead, messages are directed to the appropriate network 114 interface according to the network portion of the destination address. 115 116 The SO_LINGER option controls the action taken when unsent messages are 117 queued on a socket and a close(2) is performed. If the socket promises 118 reliable delivery of data and SO_LINGER is set, the system will block the 119 thread on the close(2) attempt until it is able to transmit the data or 120 until it decides it is unable to deliver the information (a timeout 121 period, termed the linger interval, is specified in the setsockopt() call 122 when SO_LINGER is requested). If SO_LINGER is disabled and a close(2) is 123 issued, the system will process the close(2) in a manner that allows the 124 thread to continue as quickly as possible. 125 126 The option SO_BROADCAST requests permission to send broadcast datagrams 127 on the socket. With protocols that support out-of-band data, the 128 SO_OOBINLINE option requests that out-of-band data be placed in the 129 normal data input queue as received; it will then be accessible with 130 recv(3C) or read(2) calls without the MSG_OOB flag. 131 132 The SO_SNDBUF and SO_RCVBUF options adjust the normal buffer sizes 133 allocated for output and input buffers, respectively. The buffer size 134 may be increased for high-volume connections or may be decreased to limit 135 the possible backlog of incoming data. The maximum buffer size for UDP 136 is determined by the value of the ndd(1M) variable udp_max_buf. The 137 maximum buffer size for TCP is determined the value of the ndd(1M) 138 variable tcp_max_buf. Use the ndd(1M) utility to determine the current 139 default values. At present, lowering SO_RCVBUF on a TCP connection after 140 it has been established has no effect. 141 142 By default, delayed errors (such as ICMP "Port Unreachable" packets) are 143 returned only for connected datagram sockets. The SO_DGRAM_ERRIND option 144 makes it possible to receive errors for datagram sockets that are not 145 connected. When this option is set, certain delayed errors received 146 after completion of a sendto(3C) or sendmsg(3C) operation will cause a 147 subsequent sendto(3C) or sendmsg(3C) operation using the same destination 148 address (to parameter) to fail with the appropriate error. See send(3C). 149 150 If the SO_TIMESTAMP option is enabled on a SO_DGRAM or a SO_RAW socket, 151 the recvmsg(3XNET) call will return a timestamp in the native data 152 format, corresponding to when the datagram was received. 153 154 The SO_EXCLBIND option is used to enable or disable the exclusive binding 155 of a socket. It overrides the use of the SO_REUSEADDR option to reuse an 156 address on bind(3C). The actual semantics of the SO_EXCLBIND option 157 depend on the underlying protocol. See tcp(7P) or udp(7P) for more 158 information. 159 160 The SO_TYPE and SO_ERROR options are used only with getsockopt(). The 161 SO_TYPE option returns the type of the socket, for example, SOCK_STREAM. 162 It is useful for servers that inherit sockets on startup. The SO_ERROR 163 option returns any pending error on the socket and clears the error 164 status. It may be used to check for asynchronous errors on connected 165 datagram sockets or for other asynchronous errors. 166 167 The SO_MAC_EXEMPT option is used to toggle socket behavior with unlabeled 168 peers. A socket that has this option enabled can communicate with an 169 unlabeled peer if it is in the global zone or has a label that dominates 170 the default label of the peer. Otherwise, the socket must have a label 171 that is equal to the default label of the unlabeled peer. Calling 172 setsockopt() with this option returns an EACCES error if the process 173 lacks the NET_MAC_AWARE privilege or if the socket is bound. The 174 SO_MAC_EXEMPT option is available only when the system is configured with 175 Trusted Extensions. 176 177 The SO_ALLZONES option can be used to bypass zone boundaries between 178 shared-IP zones. Normally, the system prevents a socket from being bound 179 to an address that is not assigned to the current zone. It also prevents 180 a socket that is bound to a wildcard address from receiving traffic for 181 other zones. However, some daemons which run in the global zone might 182 need to send and receive traffic using addresses that belong to other 183 shared-IP zones. If set before a socket is bound, SO_ALLZONES causes the 184 socket to ignore zone boundaries between shared-IP zones and permits the 185 socket to be bound to any address assigned to the shared-IP zones. If 186 the socket is bound to a wildcard address, it receives traffic intended 187 for all shared-IP zones and behaves as if an equivalent socket were bound 188 in each active shared-IP zone. Applications that use the SO_ALLZONES 189 option to initiate connections or send datagram traffic should specify 190 the source address for outbound traffic by binding to a specific address. 191 There is no effect from setting this option in an exclusive-IP zone. 192 Setting this option requires the sys_net_config privilege. See zones(5). 193 194 RETURN VALUES 195 If successful, getsockopt() and setsockopt() return 0. Otherwise, the 196 functions return -1 and set errno to indicate the error. 197 198 ERRORS 199 The getsockopt() and setsockopt() calls succeed unless: 200 201 [EBADF] The argument s is not a valid file descriptor. 202 203 [ENOMEM] There was insufficient memory available for the 204 operation to complete. 205 206 [ENOPROTOOPT] The option is unknown at the level indicated. 207 208 [ENOSR] There were insufficient STREAMS resources available 209 for the operation to complete. 210 211 [ENOTSOCK] The argument s is not a socket. 212 213 [ENOBUFS] SO_SNDBUF or SO_RCVBUF exceeds a system limit. 214 215 [EINVAL] Invalid length for a given socket option. 216 217 [EHOSTUNREACH] Invalid address for IP_MULTICAST_IF. 218 219 [EINVAL] Not a multicast address for IP_ADD_MEMBERSHIP and 220 IP_DROP_MEMBERSHIP. 221 222 [EADDRNOTAVAIL] Bad interface address for IP_ADD_MEMBERSHIP and 223 IP_DROP_MEMBERSHIP. 224 225 [EADDRINUSE] Address already joined for IP_ADD_MEMBERSHIP. 226 227 [ENOENT] Address not joined for IP_DROP_MEMBERSHIP. 228 229 [EPERM] No permissions. 230 231 [EACCES] Permission denied. 232 233 [EINVAL] The specified option is invalid at the specified 234 socket level, or the socket has been shut down. 235 236 MT-LEVEL 237 Safe 238 239 SEE ALSO 240 ndd(1M), close(2), ioctl(2), read(2), bind(3C), recv(3C), send(3C), 241 socket(3C), socket.h(3HEAD), getprotobyname(3SOCKET), recvmsg(3XNET), 242 attributes(5), zones(5), tcp(7P), udp(7P) 243 244 illumos August 2, 2018 illumos