1.\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94 35.\" 36.Dd April 19, 1994 37.Dt GETSOCKOPT 2 38.Os BSD 4.3r 39.Sh NAME 40.Nm getsockopt , 41.Nm setsockopt 42.Nd get and set options on sockets 43.Sh SYNOPSIS 44.Fd #include <sys/socket.h> 45.Ft int 46.Fo getsockopt 47.Fa "int socket" 48.Fa "int level" 49.Fa "int option_name" 50.Fa "void *restrict option_value" 51.Fa "socklen_t *restrict option_len" 52.Fc 53.Ft int 54.Fo setsockopt 55.Fa "int socket" 56.Fa "int level" 57.Fa "int option_name" 58.Fa "const void *option_value" 59.Fa "socklen_t option_len" 60.Fc 61.Sh DESCRIPTION 62.Fn getsockopt 63and 64.Fn setsockopt 65manipulate the 66.Em options 67associated with a socket. Options may exist at multiple 68protocol levels; they are always present at the uppermost 69.Dq socket 70level. 71.Pp 72When manipulating socket options the level at which the 73option resides and the name of the option must be specified. 74To manipulate options at the socket level, 75.Fa level 76is specified as 77.Dv SOL_SOCKET . 78To manipulate options at any 79other level the protocol number of the appropriate protocol 80controlling the option is supplied. For example, 81to indicate that an option is to be interpreted by the 82.Tn TCP 83protocol, 84.Fa level 85should be set to the protocol number of 86.Tn TCP ; 87see 88.Xr getprotoent 3 . 89.Pp 90The parameters 91.Fa option_value 92and 93.Fa option_len 94are used to access option values for 95.Fn setsockopt . 96For 97.Fn getsockopt 98they identify a buffer in which the value for the 99requested option(s) are to be returned. For 100.Fn getsockopt , 101.Fa option_len 102is a value-result parameter, initially containing the 103size of the buffer pointed to by 104.Fa option_value , 105and modified on return to indicate the actual size of 106the value returned. If no option value is 107to be supplied or returned, 108.Fa option_value 109may be NULL. 110.Pp 111.Fa option_name 112and any specified options are passed uninterpreted to the appropriate 113protocol module for interpretation. 114The include file 115.Ao Pa sys/socket.h Ac 116contains definitions for 117socket level options, described below. 118Options at other protocol levels vary in format and 119name; consult the appropriate entries in 120section 1214 of the manual. 122.Pp 123Most socket-level options utilize an 124.Fa int 125parameter for 126.Fa option_value . 127For 128.Fn setsockopt , 129the parameter should be non-zero to enable a boolean option, 130or zero if the option is to be disabled. 131.Dv SO_LINGER 132uses a 133.Fa struct linger 134parameter, defined in 135.Ao Pa sys/socket.h Ac , 136which specifies the desired state of the option and the 137linger interval (see below). 138.Dv SO_SNDTIMEO 139and 140.Dv SO_RCVTIMEO 141use a 142.Fa struct timeval 143parameter, defined in 144.Ao Pa sys/time.h Ac . 145.Pp 146The following options are recognized at the socket level. 147Except as noted, each may be examined with 148.Fn getsockopt 149and set with 150.Fn setsockopt . 151.Bl -column SO_OOBINLINE -offset indent 152.It Dv SO_DEBUG Ta "enables recording of debugging information" 153.It Dv SO_REUSEADDR Ta "enables local address reuse" 154.It Dv SO_REUSEPORT Ta "enables duplicate address and port bindings" 155.It Dv SO_KEEPALIVE Ta "enables keep connections alive" 156.It Dv SO_DONTROUTE Ta "enables routing bypass for outgoing messages" 157.It Dv SO_LINGER Ta "linger on close if data present" 158.It Dv SO_BROADCAST Ta "enables permission to transmit broadcast messages" 159.It Dv SO_OOBINLINE Ta "enables reception of out-of-band data in band" 160.It Dv SO_SNDBUF Ta "set buffer size for output" 161.It Dv SO_RCVBUF Ta "set buffer size for input" 162.It Dv SO_SNDLOWAT Ta "set minimum count for output" 163.It Dv SO_RCVLOWAT Ta "set minimum count for input" 164.It Dv SO_SNDTIMEO Ta "set timeout value for output" 165.It Dv SO_RCVTIMEO Ta "set timeout value for input" 166.It Dv SO_TYPE Ta "get the type of the socket (get only)" 167.It Dv SO_ERROR Ta "get and clear error on the socket (get only)" 168.It Dv SO_NOSIGPIPE Ta "do not generate SIGPIPE, instead return EPIPE" 169.It Dv SO_NREAD Ta "number of bytes to be read (get only)" 170.It Dv SO_NWRITE Ta "number of bytes written not yet sent by the protocol (get only)" 171.It Dv SO_LINGER_SEC Ta "linger on close if data present with timeout in seconds" 172.El 173.Pp 174.Dv SO_DEBUG 175enables debugging in the underlying protocol modules. 176.Pp 177.Dv SO_REUSEADDR 178indicates that the rules used in validating addresses supplied 179in a 180.Xr bind 2 181call should allow reuse of local addresses. 182.Pp 183.Dv SO_REUSEPORT 184allows completely duplicate bindings by multiple processes 185if they all set 186.Dv SO_REUSEPORT 187before binding the port. 188This option permits multiple instances of a program to each 189receive UDP/IP multicast or broadcast datagrams destined for the bound port. 190.Pp 191.Dv SO_KEEPALIVE 192enables the 193periodic transmission of messages on a connected socket. Should the 194connected party fail to respond to these messages, the connection is 195considered broken and processes using the socket are notified via a 196.Dv SIGPIPE 197signal when attempting to send data. 198.Pp 199.Dv SO_DONTROUTE 200indicates that outgoing messages should 201bypass the standard routing facilities. Instead, messages are directed 202to the appropriate network interface according to the network portion 203of the destination address. 204.Pp 205.Dv SO_LINGER 206controls the action taken when unsent messages 207are queued on socket and a 208.Xr close 2 209is performed. 210If the socket promises reliable delivery of data and 211.Dv SO_LINGER is set, 212the system will block the process on the 213.Xr close 214attempt until it is able to transmit the data or until it decides it 215is unable to deliver the information (a timeout period, termed the 216linger interval, is specified in the 217.Fn setsockopt 218call when 219.Dv SO_LINGER 220is requested). 221If 222.Dv SO_LINGER 223is disabled and a 224.Xr close 225is issued, the system will process the close in a manner that allows 226the process to continue as quickly as possible. 227.Pp 228.Dv SO_LINGER_SEC 229is the same option as 230.Dv SO_LINGER 231except the linger time is in seconds for 232.Dv SO_LINGER_SEC . 233.Pp 234The option 235.Dv SO_BROADCAST 236requests permission to send broadcast datagrams 237on the socket. 238Broadcast was a privileged operation in earlier versions of the system. 239.Pp 240With protocols that support out-of-band data, the 241.Dv SO_OOBINLINE 242option 243requests that out-of-band data be placed in the normal data input queue 244as received; it will then be accessible with 245.Xr recv 246or 247.Xr read 248calls without the 249.Dv MSG_OOB 250flag. 251Some protocols always behave as if this option is set. 252.Pp 253.Dv SO_SNDBUF 254and 255.Dv SO_RCVBUF 256are options to adjust the normal 257buffer sizes allocated for output and input buffers, respectively. 258The buffer size may be increased for high-volume connections, 259or may be decreased to limit the possible backlog of incoming data. 260The system places an absolute limit on these values. 261.Pp 262.Dv SO_SNDLOWAT 263is an option to set the minimum count for output operations. 264Most output operations process all of the data supplied by the call, 265delivering data to the protocol for transmission 266and blocking as necessary for flow control. 267Nonblocking output operations will process as much data as permitted 268(subject to flow control) without blocking, 269but will process no data if flow control 270does not allow the smaller of the low-water mark value 271or the entire request to be processed. 272A 273.Xr select 2 274operation testing the ability to write to a socket will return true 275only if the low-water mark amount could be processed. 276The default value for 277.Dv SO_SNDLOWAT 278is set to a convenient size for network efficiency, often 2048. 279.Pp 280.Dv SO_RCVLOWAT 281is an option to set the minimum count for input operations. 282In general, receive calls will block until any (non-zero) amount of data 283is received, then return with the smaller of the amount available 284or the amount requested. 285The default value for 286.Dv SO_RCVLOWAT 287is 1. 288If 289.Dv SO_RCVLOWAT 290is set to a larger value, blocking receive calls 291normally wait until they have received the smaller 292of the low-water mark value or the requested amount. 293Receive calls may still return less than the low-water mark 294if an error occurs, a signal is caught, 295or the type of data next in the receive queue 296is different than that returned. 297.Pp 298.Dv SO_SNDTIMEO 299is an option to set a timeout value for output operations. 300It accepts a 301.Fa struct timeval 302parameter with the number of seconds and microseconds 303used to limit waits for output operations to complete. 304If a send operation has blocked for this much time, 305it returns with a partial count 306or with the error 307.Er EWOULDBLOCK 308if no data were sent. 309In the current implementation, this timer is restarted each time additional 310data are delivered to the protocol, 311implying that the limit applies to output portions ranging in size 312from the low-water mark to the high-water mark for output. 313.Pp 314.Dv SO_RCVTIMEO 315is an option to set a timeout value for input operations. 316It accepts a 317.Fa struct timeval 318parameter with the number of seconds and microseconds 319used to limit waits for input operations to complete. 320In the current implementation, this timer is restarted each time additional 321data are received by the protocol, 322and thus the limit is in effect an inactivity timer. 323If a receive operation has been blocked for this much time without 324receiving additional data, it returns with a short count 325or with the error 326.Er EWOULDBLOCK 327if no data were received. 328The struct timeval parameter must represent a positive time interval; 329otherwise, 330.Fn setsockopt 331returns with the error 332.Er EDOM . 333.Pp 334.Dv SO_NOSIGPIPE is an option that prevents SIGPIPE from being raised 335when a write fails on a socket to which there is no reader; 336instead, the write to the socket returns with the error 337.Er EPIPE 338when there is no reader. 339.Pp 340Finally, 341.Dv SO_TYPE , 342.Dv SO_ERROR , 343.Dv SO_NREAD , and 344.Dv SO_NWRITE 345are options used only with 346.Fn getsockopt . 347.Pp 348.Dv SO_TYPE 349returns the type of the socket, such as 350.Dv SOCK_STREAM ; 351it is useful for servers that inherit sockets on startup. 352.Pp 353.Dv SO_ERROR 354returns any pending error on the socket and clears 355the error status. 356It may be used to check for asynchronous errors on connected 357datagram sockets or for other asynchronous errors. 358.Pp 359.Dv SO_NREAD 360returns the amount of data in the input buffer that is available to be received. 361For datagram oriented sockets, 362.Dv SO_NREAD 363returns the size of the first packet -- this differs from the 364.Fn ioctl 365command 366.Dv FIONREAD 367that returns the total amount of data available. 368.Pp 369.Dv SO_NWRITE 370returns the amount of data in the output buffer not yet sent by the protocol. 371.Sh RETURN VALUES 372.Rv -std 373.Sh ERRORS 374The 375.Fn getsockopt 376and 377.Fn setsockopt 378system calls will succeed unless: 379.Bl -tag -width Er 380.\" ========== 381.It Bq Er EBADF 382The argument 383.Fa socket 384is not a valid file descriptor. 385.\" ========== 386.It Bq Er EFAULT 387The address pointed to by 388.Fa option_value 389is not in a valid part of the process address space. 390For 391.Fn getsockopt , 392this error may also be returned if 393.Fa option_len 394is not in a valid part of the process address space. 395.\" ========== 396.It Bq Er EINVAL 397The option is invalid at the level indicated. 398.\" ========== 399.It Bq Er ENOBUFS 400Insufficient system resources available for the call to complete. 401.\" ========== 402.It Bq Er ENOMEM 403Insufficient memory available for the system call to complete. 404.\" ========== 405.It Bq Er ENOPROTOOPT 406The option is unknown at the level indicated. 407.\" ========== 408.It Bq Er ENOTSOCK 409The argument 410.Fa socket 411is not a socket (e.g., a plain file). 412.El 413.Pp 414The 415.Fn setsockopt 416system call will succeed unless: 417.Bl -tag -width Er 418.\" ========== 419.It Bq Er EDOM 420The argument 421.Fa option_value 422is out of bounds. 423.\" ========== 424.It Bq Er EISCONN 425.Fa socket 426is already connected 427and a specified option cannot be set 428while this is the case. 429.\" ========== 430.It Bq Er EINVAL 431The socket has been shut down. 432.El 433.Sh LEGACY SYNOPSIS 434.Fd #include <sys/types.h> 435.Fd #include <sys/socket.h> 436.Pp 437The include file 438.In sys/types.h 439is necessary. 440.Sh SEE ALSO 441.Xr socket 2 , 442.Xr bind 2 , 443.Xr ioctl 2 , 444.Xr getprotoent 3 , 445.Xr protocols 5 446.Sh BUGS 447Several of the socket options should be handled at lower levels of the system. 448.Sh HISTORY 449The 450.Fn getsockopt 451system call appeared in 452.Bx 4.2 . 453