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.7 (Berkeley) 03/10/91 7.\" 8.\" Copyright (c) 1983, 1991 The Regents of the University of California. 9.\" All rights reserved. 10.\" 11.\" %sccs.include.redist.man% 12.\" 13.\" @(#)getsockopt.2 6.7 (Berkeley) 03/10/91 14.\" 15.Dd 16.Dt GETSOCKOPT 2 17.Os BSD 4.2 18.Sh NAME 19.Nm getsockopt , 20.Nm setsockopt 21.Nd get and set options on sockets 22.Sh SYNOPSIS 23.Fd #include <sys/types.h> 24.Fd #include <sys/socket.h> 25.Ft int 26.Fn getsockopt "int s" "int level" "int optname" "char *optval" "int *optlen" 27.Ft int 28.Fn setsockopt "int s" "int level" "int optname" "char *optval" "int optlen" 29.Sh DESCRIPTION 30.Fn Getsockopt 31and 32.Fn setsockopt 33manipulate the 34.Em options 35associated with a socket. Options may exist at multiple 36protocol levels; they are always present at the uppermost 37.Dq socket 38level. 39.Pp 40When manipulating socket options the level at which the 41option resides and the name of the option must be specified. 42To manipulate options at the socket level, 43.Fa level 44is specified as 45.Dv SOL_SOCKET . 46To manipulate options at any 47other level the protocol number of the appropriate protocol 48controlling the option is supplied. For example, 49to indicate that an option is to be interpreted by the 50.Tn TCP 51protocol, 52.Fa level 53should be set to the protocol number of 54.Tn TCP ; 55see 56.Xr getprotoent 3 . 57.Pp 58The parameters 59.Fa optval 60and 61.Fa optlen 62are used to access option values for 63.Fn setsockopt . 64For 65.Fn getsockopt 66they identify a buffer in which the value for the 67requested option(s) are to be returned. For 68.Fn getsockopt , 69.Fa optlen 70is a value-result parameter, initially containing the 71size of the buffer pointed to by 72.Fa optval , 73and modified on return to indicate the actual size of 74the value returned. If no option value is 75to be supplied or returned, 76.Fa optval 77may be NULL. 78.Pp 79.Fa Optname 80and any specified options are passed uninterpreted to the appropriate 81protocol module for interpretation. 82The include file 83.Ao Pa sys/socket.h Ac 84contains definitions for 85socket level options, described below. 86Options at other protocol levels vary in format and 87name; consult the appropriate entries in 88section 894 of the manual. 90.Pp 91Most socket-level options take an 92.Fa int 93parameter for 94.Fa optval . 95For 96.Fn setsockopt , 97the parameter should be non-zero to enable a boolean option, 98or zero if the option is to be disabled. 99.Dv SO_LINGER 100uses a 101.Fa struct linger 102parameter, defined in 103.Ao Pa sys/socket.h Ac , 104which specifies the desired state of the option and the 105linger interval (see below). 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_TYPE Ta get the type of the socket (get only) 123.It Dv SO_ERROR Ta get and clear error on the socket (get only) 124.El 125.Pp 126.Dv SO_DEBUG 127enables debugging in the underlying protocol modules. 128.Dv SO_REUSEADDR 129indicates that the rules used in validating addresses supplied 130in a 131.Xr bind 2 132call should allow reuse of local addresses. 133.Dv SO_KEEPALIVE 134enables the 135periodic transmission of messages on a connected socket. Should the 136connected party fail to respond to these messages, the connection is 137considered broken and processes using the socket are notified via a 138.Dv SIGPIPE 139signal. 140.Dv SO_DONTROUTE 141indicates that outgoing messages should 142bypass the standard routing facilities. Instead, messages are directed 143to the appropriate network interface according to the network portion 144of the destination address. 145.Pp 146.Dv SO_LINGER 147controls the action taken when unsent messags 148are queued on socket and a 149.Xr close 2 150is performed. 151If the socket promises reliable delivery of data and 152.Dv SO_LINGER is set, 153the system will block the process on the 154.Xr close 155attempt until it is able to transmit the data or until it decides it 156is unable to deliver the information (a timeout period, termed the 157linger interval, is specified in the 158.Fn setsockopt 159call when 160.Dv SO_LINGER 161is requested). 162If 163.Dv SO_LINGER 164is disabled and a 165.Xr close 166is issued, the system will process the close in a manner that allows 167the process to continue as quickly as possible. 168.Pp 169The option 170.Dv SO_BROADCAST 171requests permission to send broadcast datagrams 172on the socket. 173Broadcast was a privileged operation in earlier versions of the system. 174With protocols that support out-of-band data, the 175.Dv SO_OOBINLINE 176option 177requests that out-of-band data be placed in the normal data input queue 178as received; it will then be accessible with 179.Xr recv 180or 181.Xr read 182calls without the 183.Dv MSG_OOB 184flag. 185.Dv SO_SNDBUF 186and 187.Dv SO_RCVBUF 188are options to adjust the normal 189buffer sizes allocated for output and input buffers, respectively. 190The buffer size may be increased for high-volume connections, 191or may be decreased to limit the possible backlog of incoming data. 192The system places an absolute limit on these values. 193Finally, 194.Dv SO_TYPE 195and 196.Dv SO_ERROR 197are options used only with 198.Fn setsockopt . 199.Dv SO_TYPE 200returns the type of the socket, such as 201.Dv SOCK_STREAM ; 202it is useful for servers that inherit sockets on startup. 203.Dv SO_ERROR 204returns any pending error on the socket and clears 205the error status. 206It may be used to check for asynchronous errors on connected 207datagram sockets or for other asynchronous errors. 208.Sh RETURN VALUES 209A 0 is returned if the call succeeds, -1 if it fails. 210.Sh ERRORS 211The call succeeds unless: 212.Bl -tag -width ENOPROTOOPTAA 213.It Bq Er EBADF 214The argument 215.Fa s 216is not a valid descriptor. 217.It Bq Er ENOTSOCK 218The argument 219.Fa s 220is a file, not a socket. 221.It Bq Er ENOPROTOOPT 222The option is unknown at the level indicated. 223.It Bq Er EFAULT 224The address pointed to by 225.Fa optval 226is not in a valid part of the process address space. 227For 228.Fn getsockopt , 229this error may also be returned if 230.Fa optlen 231is not in a valid part of the process address space. 232.El 233.Sh SEE ALSO 234.Xr ioctl 2 , 235.Xr socket 2 , 236.Xr getprotoent 3 237.Xr protocols 5 238.Sh BUGS 239Several of the socket options should be handled at lower levels of the system. 240.Sh HISTORY 241The 242.Nm 243system call appeared in 244.Bx 4.2 . 245