1.\" Copyright (c) 1983, 1991 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)getsockopt.2 6.11 (Berkeley) 04/29/92 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_KEEPALIVE Ta "enables keep connections alive" 116.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" 117.It Dv SO_LINGER Ta "linger on close if data present" 118.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" 119.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" 120.It Dv SO_SNDBUF Ta "set buffer size for output" 121.It Dv SO_RCVBUF Ta "set buffer size for input" 122.It Dv SO_SNDLOWAT Ta "set minimum count for output" 123.It Dv SO_RCVLOWAT Ta "set minimum count for input" 124.It Dv SO_SNDTIMEO Ta "set timeout value for output" 125.It Dv SO_RCVTIMEO Ta "set timeout value for input" 126.It Dv SO_TYPE Ta "get the type of the socket (get only)" 127.It Dv SO_ERROR Ta "get and clear error on the socket (get only)" 128.El 129.Pp 130.Dv SO_DEBUG 131enables debugging in the underlying protocol modules. 132.Dv SO_REUSEADDR 133indicates that the rules used in validating addresses supplied 134in a 135.Xr bind 2 136call should allow reuse of local addresses. 137.Dv SO_KEEPALIVE 138enables the 139periodic transmission of messages on a connected socket. Should the 140connected party fail to respond to these messages, the connection is 141considered broken and processes using the socket are notified via a 142.Dv SIGPIPE 143signal when attempting to send data. 144.Dv SO_DONTROUTE 145indicates that outgoing messages should 146bypass the standard routing facilities. Instead, messages are directed 147to the appropriate network interface according to the network portion 148of the destination address. 149.Pp 150.Dv SO_LINGER 151controls the action taken when unsent messags 152are queued on socket and a 153.Xr close 2 154is performed. 155If the socket promises reliable delivery of data and 156.Dv SO_LINGER is set, 157the system will block the process on the 158.Xr close 159attempt until it is able to transmit the data or until it decides it 160is unable to deliver the information (a timeout period, termed the 161linger interval, is specified in the 162.Fn setsockopt 163call when 164.Dv SO_LINGER 165is requested). 166If 167.Dv SO_LINGER 168is disabled and a 169.Xr close 170is issued, the system will process the close in a manner that allows 171the process to continue as quickly as possible. 172.Pp 173The option 174.Dv SO_BROADCAST 175requests permission to send broadcast datagrams 176on the socket. 177Broadcast was a privileged operation in earlier versions of the system. 178With protocols that support out-of-band data, the 179.Dv SO_OOBINLINE 180option 181requests that out-of-band data be placed in the normal data input queue 182as received; it will then be accessible with 183.Xr recv 184or 185.Xr read 186calls without the 187.Dv MSG_OOB 188flag. 189Some protocols always behave as if this option is set. 190.Dv SO_SNDBUF 191and 192.Dv SO_RCVBUF 193are options to adjust the normal 194buffer sizes allocated for output and input buffers, respectively. 195The buffer size may be increased for high-volume connections, 196or may be decreased to limit the possible backlog of incoming data. 197The system places an absolute limit on these values. 198.Pp 199.Dv SO_SNDLOWAT 200is an option to set the minimum count for output operations. 201Most output operations process all of the data supplied 202by the call, delivering data to the protocol for transmission 203and blocking as necessary for flow control. 204Nonblocking output operations will process as much data as permitted 205subject to flow control without blocking, but will process no data 206if flow control does not allow the smaller of the low water mark value 207or the entire request to be processed. 208A 209.Xr select 2 210operation testing the ability to write to a socket will return true 211only if the low water mark amount could be processed. 212The default value for 213.Dv SO_SNDLOWAT 214is set to a convenient size for network efficiency, often 1024. 215.Dv SO_RCVLOWAT 216is an option to set the minimum count for input operations. 217In general, receive calls will block until any (non-zero) amount of data 218is received, then return with smaller of the amount available or the amount 219requested. 220The default value for 221.Dv SO_SNDLOWAT 222is 1. 223If 224.Dv SO_SNDLOWAT 225is set to a larger value, blocking receive calls normally 226wait until they have received the smaller of the low water mark value 227or the requested amount. 228Receive calls may still return less than the low water mark if an error 229occurs, a signal is caught, or the type of data next in the receive queue 230is different than that returned. 231.Pp 232.Dv SO_SNDTIMEO 233is an option to set a timeout value for output operations. 234It accepts a 235.Fa struct timeval 236parameter with the number of seconds and microseconds 237used to limit waits for output operations to complete. 238If a send operation has blocked for this much time, 239it returns with a partial count 240or with the error 241.Er EWOULDBLOCK 242if no data were sent. 243In the current implementation, this timer is restarted each time additional 244data are delivered to the protocol, 245implying that the limit applies to output portions ranging in size 246from the low water mark to the high water mark for output. 247.Dv SO_RCVTIMEO 248is an option to set a timeout value for input operations. 249It accepts a 250.Fa struct timeval 251parameter with the number of seconds and microseconds 252used to limit waits for input operations to complete. 253In the current implementation, this timer is restarted each time additional 254data are received by the protocol, 255and thus the limit is in effect an inactivity timer. 256If a receive operation has been blocked for this much time without 257receiving additional data, it returns with a short count 258or with the error 259.Er EWOULDBLOCK 260if no data were received. 261.Pp 262Finally, 263.Dv SO_TYPE 264and 265.Dv SO_ERROR 266are options used only with 267.Fn getsockopt . 268.Dv SO_TYPE 269returns the type of the socket, such as 270.Dv SOCK_STREAM ; 271it is useful for servers that inherit sockets on startup. 272.Dv SO_ERROR 273returns any pending error on the socket and clears 274the error status. 275It may be used to check for asynchronous errors on connected 276datagram sockets or for other asynchronous errors. 277.Sh RETURN VALUES 278A 0 is returned if the call succeeds, -1 if it fails. 279.Sh ERRORS 280The call succeeds unless: 281.Bl -tag -width ENOPROTOOPTAA 282.It Bq Er EBADF 283The argument 284.Fa s 285is not a valid descriptor. 286.It Bq Er ENOTSOCK 287The argument 288.Fa s 289is a file, not a socket. 290.It Bq Er ENOPROTOOPT 291The option is unknown at the level indicated. 292.It Bq Er EFAULT 293The address pointed to by 294.Fa optval 295is not in a valid part of the process address space. 296For 297.Fn getsockopt , 298this error may also be returned if 299.Fa optlen 300is not in a valid part of the process address space. 301.El 302.Sh SEE ALSO 303.Xr ioctl 2 , 304.Xr socket 2 , 305.Xr getprotoent 3 306.Xr protocols 5 307.Sh BUGS 308Several of the socket options should be handled at lower levels of the system. 309.Sh HISTORY 310The 311.Nm 312system call appeared in 313.Bx 4.2 . 314