1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getsockopt.2 8.3 (Berkeley) 04/19/94 7.\" 8.Dd 9.Dt GETSOCKOPT 2 10.Os BSD 4.3r 11.Sh NAME 12.Nm getsockopt , 13.Nm setsockopt 14.Nd get and set options on sockets 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <sys/socket.h> 18.Ft int 19.Fn getsockopt "int s" "int level" "int optname" "void *optval" "int *optlen" 20.Ft int 21.Fn setsockopt "int s" "int level" "int optname" "const void *optval" "int optlen" 22.Sh DESCRIPTION 23.Fn Getsockopt 24and 25.Fn setsockopt 26manipulate the 27.Em options 28associated with a socket. Options may exist at multiple 29protocol levels; they are always present at the uppermost 30.Dq socket 31level. 32.Pp 33When manipulating socket options the level at which the 34option resides and the name of the option must be specified. 35To manipulate options at the socket level, 36.Fa level 37is specified as 38.Dv SOL_SOCKET . 39To manipulate options at any 40other level the protocol number of the appropriate protocol 41controlling the option is supplied. For example, 42to indicate that an option is to be interpreted by the 43.Tn TCP 44protocol, 45.Fa level 46should be set to the protocol number of 47.Tn TCP ; 48see 49.Xr getprotoent 3 . 50.Pp 51The parameters 52.Fa optval 53and 54.Fa optlen 55are used to access option values for 56.Fn setsockopt . 57For 58.Fn getsockopt 59they identify a buffer in which the value for the 60requested option(s) are to be returned. For 61.Fn getsockopt , 62.Fa optlen 63is a value-result parameter, initially containing the 64size of the buffer pointed to by 65.Fa optval , 66and modified on return to indicate the actual size of 67the value returned. If no option value is 68to be supplied or returned, 69.Fa optval 70may be NULL. 71.Pp 72.Fa Optname 73and any specified options are passed uninterpreted to the appropriate 74protocol module for interpretation. 75The include file 76.Ao Pa sys/socket.h Ac 77contains definitions for 78socket level options, described below. 79Options at other protocol levels vary in format and 80name; consult the appropriate entries in 81section 824 of the manual. 83.Pp 84Most socket-level options utilize an 85.Fa int 86parameter for 87.Fa optval . 88For 89.Fn setsockopt , 90the parameter should be non-zero to enable a boolean option, 91or zero if the option is to be disabled. 92.Dv SO_LINGER 93uses a 94.Fa struct linger 95parameter, defined in 96.Ao Pa sys/socket.h Ac , 97which specifies the desired state of the option and the 98linger interval (see below). 99.Dv SO_SNDTIMEO 100and 101.Dv SO_RCVTIMEO 102use a 103.Fa struct timeval 104parameter, defined in 105.Ao Pa sys/time.h Ac . 106.Pp 107The following options are recognized at the socket level. 108Except as noted, each may be examined with 109.Fn getsockopt 110and set with 111.Fn setsockopt . 112.Bl -column SO_OOBINLINE -offset indent 113.It Dv SO_DEBUG Ta "enables recording of debugging information" 114.It Dv SO_REUSEADDR Ta "enables local address reuse" 115.It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings" 116.It Dv SO_KEEPALIVE Ta "enables keep connections alive" 117.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" 118.It Dv SO_LINGER Ta "linger on close if data present" 119.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" 120.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" 121.It Dv SO_SNDBUF Ta "set buffer size for output" 122.It Dv SO_RCVBUF Ta "set buffer size for input" 123.It Dv SO_SNDLOWAT Ta "set minimum count for output" 124.It Dv SO_RCVLOWAT Ta "set minimum count for input" 125.It Dv SO_SNDTIMEO Ta "set timeout value for output" 126.It Dv SO_RCVTIMEO Ta "set timeout value for input" 127.It Dv SO_TYPE Ta "get the type of the socket (get only)" 128.It Dv SO_ERROR Ta "get and clear error on the socket (get only)" 129.El 130.Pp 131.Dv SO_DEBUG 132enables debugging in the underlying protocol modules. 133.Dv SO_REUSEADDR 134indicates that the rules used in validating addresses supplied 135in a 136.Xr bind 2 137call should allow reuse of local addresses. 138.Dv SO_REUSEPORT 139allows completely duplicate bindings by multiple processes 140if they all set 141.Dv SO_REUSEPORT 142before binding the port. 143This option permits multiple instances of a program to each 144receive UDP/IP multicast or broadcast datagrams destined for the bound port. 145.Dv SO_KEEPALIVE 146enables the 147periodic transmission of messages on a connected socket. Should the 148connected party fail to respond to these messages, the connection is 149considered broken and processes using the socket are notified via a 150.Dv SIGPIPE 151signal when attempting to send data. 152.Dv SO_DONTROUTE 153indicates that outgoing messages should 154bypass the standard routing facilities. Instead, messages are directed 155to the appropriate network interface according to the network portion 156of the destination address. 157.Pp 158.Dv SO_LINGER 159controls the action taken when unsent messages 160are queued on socket and a 161.Xr close 2 162is performed. 163If the socket promises reliable delivery of data and 164.Dv SO_LINGER is set, 165the system will block the process on the 166.Xr close 167attempt until it is able to transmit the data or until it decides it 168is unable to deliver the information (a timeout period, termed the 169linger interval, is specified in the 170.Fn setsockopt 171call when 172.Dv SO_LINGER 173is requested). 174If 175.Dv SO_LINGER 176is disabled and a 177.Xr close 178is issued, the system will process the close in a manner that allows 179the process to continue as quickly as possible. 180.Pp 181The option 182.Dv SO_BROADCAST 183requests permission to send broadcast datagrams 184on the socket. 185Broadcast was a privileged operation in earlier versions of the system. 186With protocols that support out-of-band data, the 187.Dv SO_OOBINLINE 188option 189requests that out-of-band data be placed in the normal data input queue 190as received; it will then be accessible with 191.Xr recv 192or 193.Xr read 194calls without the 195.Dv MSG_OOB 196flag. 197Some protocols always behave as if this option is set. 198.Dv SO_SNDBUF 199and 200.Dv SO_RCVBUF 201are options to adjust the normal 202buffer sizes allocated for output and input buffers, respectively. 203The buffer size may be increased for high-volume connections, 204or may be decreased to limit the possible backlog of incoming data. 205The system places an absolute limit on these values. 206.Pp 207.Dv SO_SNDLOWAT 208is an option to set the minimum count for output operations. 209Most output operations process all of the data supplied 210by the call, delivering data to the protocol for transmission 211and blocking as necessary for flow control. 212Nonblocking output operations will process as much data as permitted 213subject to flow control without blocking, but will process no data 214if flow control does not allow the smaller of the low water mark value 215or the entire request to be processed. 216A 217.Xr select 2 218operation testing the ability to write to a socket will return true 219only if the low water mark amount could be processed. 220The default value for 221.Dv SO_SNDLOWAT 222is set to a convenient size for network efficiency, often 1024. 223.Dv SO_RCVLOWAT 224is an option to set the minimum count for input operations. 225In general, receive calls will block until any (non-zero) amount of data 226is received, then return with the smaller of the amount available or the amount 227requested. 228The default value for 229.Dv SO_RCVLOWAT 230is 1. 231If 232.Dv SO_RCVLOWAT 233is set to a larger value, blocking receive calls normally 234wait until they have received the smaller of the low water mark value 235or the requested amount. 236Receive calls may still return less than the low water mark if an error 237occurs, a signal is caught, or the type of data next in the receive queue 238is different than that returned. 239.Pp 240.Dv SO_SNDTIMEO 241is an option to set a timeout value for output operations. 242It accepts a 243.Fa struct timeval 244parameter with the number of seconds and microseconds 245used to limit waits for output operations to complete. 246If a send operation has blocked for this much time, 247it returns with a partial count 248or with the error 249.Er EWOULDBLOCK 250if no data were sent. 251In the current implementation, this timer is restarted each time additional 252data are delivered to the protocol, 253implying that the limit applies to output portions ranging in size 254from the low water mark to the high water mark for output. 255.Dv SO_RCVTIMEO 256is an option to set a timeout value for input operations. 257It accepts a 258.Fa struct timeval 259parameter with the number of seconds and microseconds 260used to limit waits for input operations to complete. 261In the current implementation, this timer is restarted each time additional 262data are received by the protocol, 263and thus the limit is in effect an inactivity timer. 264If a receive operation has been blocked for this much time without 265receiving additional data, it returns with a short count 266or with the error 267.Er EWOULDBLOCK 268if no data were received. 269.Pp 270Finally, 271.Dv SO_TYPE 272and 273.Dv SO_ERROR 274are options used only with 275.Fn getsockopt . 276.Dv SO_TYPE 277returns the type of the socket, such as 278.Dv SOCK_STREAM ; 279it is useful for servers that inherit sockets on startup. 280.Dv SO_ERROR 281returns any pending error on the socket and clears 282the error status. 283It may be used to check for asynchronous errors on connected 284datagram sockets or for other asynchronous errors. 285.Sh RETURN VALUES 286A 0 is returned if the call succeeds, -1 if it fails. 287.Sh ERRORS 288The call succeeds unless: 289.Bl -tag -width ENOPROTOOPTAA 290.It Bq Er EBADF 291The argument 292.Fa s 293is not a valid descriptor. 294.It Bq Er ENOTSOCK 295The argument 296.Fa s 297is a file, not a socket. 298.It Bq Er ENOPROTOOPT 299The option is unknown at the level indicated. 300.It Bq Er EFAULT 301The address pointed to by 302.Fa optval 303is not in a valid part of the process address space. 304For 305.Fn getsockopt , 306this error may also be returned if 307.Fa optlen 308is not in a valid part of the process address space. 309.El 310.Sh SEE ALSO 311.Xr ioctl 2 , 312.Xr socket 2 , 313.Xr getprotoent 3 314.Xr protocols 5 315.Sh BUGS 316Several of the socket options should be handled at lower levels of the system. 317.Sh HISTORY 318The 319.Nm 320system call appeared in 321.Bx 4.2 . 322