| 1 | .\" Copyright (c) 1983 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" %sccs.include.redist.man% |
| 5 | .\" |
| 6 | .\" @(#)getsockopt.2 6.6 (Berkeley) %G% |
| 7 | .\" |
| 8 | .TH GETSOCKOPT 2 "" |
| 9 | .UC 5 |
| 10 | .SH NAME |
| 11 | getsockopt, setsockopt \- get and set options on sockets |
| 12 | .SH SYNOPSIS |
| 13 | .nf |
| 14 | .ft B |
| 15 | #include <sys/types.h> |
| 16 | #include <sys/socket.h> |
| 17 | .PP |
| 18 | .ft B |
| 19 | getsockopt(s, level, optname, optval, optlen) |
| 20 | int s, level, optname; |
| 21 | char *optval; |
| 22 | int *optlen; |
| 23 | .sp |
| 24 | setsockopt(s, level, optname, optval, optlen) |
| 25 | int s, level, optname; |
| 26 | char *optval; |
| 27 | int optlen; |
| 28 | .fi |
| 29 | .SH DESCRIPTION |
| 30 | .I Getsockopt |
| 31 | and |
| 32 | .I setsockopt |
| 33 | manipulate |
| 34 | .I options |
| 35 | associated with a socket. Options may exist at multiple |
| 36 | protocol levels; they are always present at the uppermost |
| 37 | ``socket'' level. |
| 38 | .PP |
| 39 | When manipulating socket options the level at which the |
| 40 | option resides and the name of the option must be specified. |
| 41 | To manipulate options at the ``socket'' level, |
| 42 | .I level |
| 43 | is specified as SOL_SOCKET. To manipulate options at any |
| 44 | other level the protocol number of the appropriate protocol |
| 45 | controlling the option is supplied. For example, |
| 46 | to indicate that an option is to be interpreted by the TCP protocol, |
| 47 | .I level |
| 48 | should be set to the protocol number of TCP; see |
| 49 | .IR getprotoent (3N). |
| 50 | .PP |
| 51 | The parameters |
| 52 | .I optval |
| 53 | and |
| 54 | .I optlen |
| 55 | are used to access option values for |
| 56 | .IR setsockopt . |
| 57 | For |
| 58 | .I getsockopt |
| 59 | they identify a buffer in which the value for the |
| 60 | requested option(s) are to be returned. For |
| 61 | .IR getsockopt , |
| 62 | .I optlen |
| 63 | is a value-result parameter, initially containing the |
| 64 | size of the buffer pointed to by |
| 65 | .IR optval , |
| 66 | and modified on return to indicate the actual size of |
| 67 | the value returned. If no option value is |
| 68 | to be supplied or returned, |
| 69 | .I optval |
| 70 | may be supplied as 0. |
| 71 | .PP |
| 72 | .I Optname |
| 73 | and any specified options are passed uninterpreted to the appropriate |
| 74 | protocol module for interpretation. |
| 75 | The include file |
| 76 | .RI < sys/socket.h > |
| 77 | contains definitions for ``socket'' level options, described below. |
| 78 | Options at other protocol levels vary in format and |
| 79 | name; consult the appropriate entries in section (4P). |
| 80 | .PP |
| 81 | Most socket-level options take an |
| 82 | .I int |
| 83 | parameter for |
| 84 | .IR optval . |
| 85 | For |
| 86 | .IR setsockopt , |
| 87 | the parameter should non-zero to enable a boolean option, |
| 88 | or zero if the option is to be disabled. |
| 89 | SO_LINGER uses a |
| 90 | .I struct linger |
| 91 | parameter, defined in |
| 92 | .RI < sys/socket.h >, |
| 93 | which specifies the desired state of the option and the |
| 94 | linger interval (see below). |
| 95 | .PP |
| 96 | The following options are recognized at the socket level. |
| 97 | Except as noted, each may be examined with |
| 98 | .I getsockopt |
| 99 | and set with |
| 100 | .IR setsockopt . |
| 101 | .PP |
| 102 | .RS |
| 103 | .ta \w'SO_BROADCAST\ \ \ \ 'u |
| 104 | .nf |
| 105 | SO_DEBUG toggle recording of debugging information |
| 106 | SO_REUSEADDR toggle local address reuse |
| 107 | SO_KEEPALIVE toggle keep connections alive |
| 108 | SO_DONTROUTE toggle routing bypass for outgoing messages |
| 109 | SO_LINGER linger on close if data present |
| 110 | SO_BROADCAST toggle permission to transmit broadcast messages |
| 111 | SO_OOBINLINE toggle reception of out-of-band data in band |
| 112 | SO_SNDBUF set buffer size for output |
| 113 | SO_RCVBUF set buffer size for input |
| 114 | SO_TYPE get the type of the socket (get only) |
| 115 | SO_ERROR get and clear error on the socket (get only) |
| 116 | .fi |
| 117 | .RE |
| 118 | .PP |
| 119 | SO_DEBUG enables debugging in the underlying protocol modules. |
| 120 | SO_REUSEADDR indicates that the rules used in validating addresses supplied |
| 121 | in a |
| 122 | .IR bind (2) |
| 123 | call should allow reuse of local addresses. SO_KEEPALIVE enables the |
| 124 | periodic transmission of messages on a connected socket. Should the |
| 125 | connected party fail to respond to these messages, the connection is |
| 126 | considered broken and processes using the socket are notified via a |
| 127 | SIGPIPE signal. SO_DONTROUTE indicates that outgoing messages should |
| 128 | bypass the standard routing facilities. Instead, messages are directed |
| 129 | to the appropriate network interface according to the network portion |
| 130 | of the destination address. |
| 131 | .PP |
| 132 | SO_LINGER controls the action taken when unsent messags |
| 133 | are queued on socket and a |
| 134 | .IR close (2) |
| 135 | is performed. |
| 136 | If the socket promises reliable delivery of data and SO_LINGER is set, |
| 137 | the system will block the process on the |
| 138 | .I close |
| 139 | attempt until it is able to transmit the data or until it decides it |
| 140 | is unable to deliver the information (a timeout period, termed the |
| 141 | linger interval, is specified in the |
| 142 | .IR setsockopt |
| 143 | call when SO_LINGER is requested). |
| 144 | If SO_LINGER is disabled and a |
| 145 | .I close |
| 146 | is issued, the system will process the close in a manner that allows |
| 147 | the process to continue as quickly as possible. |
| 148 | .PP |
| 149 | The option SO_BROADCAST requests permission to send broadcast datagrams |
| 150 | on the socket. |
| 151 | Broadcast was a privileged operation in earlier versions of the system. |
| 152 | With protocols that support out-of-band data, the SO_OOBINLINE option |
| 153 | requests that out-of-band data be placed in the normal data input queue |
| 154 | as received; it will then be accessible with |
| 155 | .I recv |
| 156 | or |
| 157 | .I read |
| 158 | calls without the MSG_OOB flag. |
| 159 | SO_SNDBUF and SO_RCVBUF are options to adjust the normal |
| 160 | buffer sizes allocated for output and input buffers, respectively. |
| 161 | The buffer size may be increased for high-volume connections, |
| 162 | or may be decreased to limit the possible backlog of incoming data. |
| 163 | The system places an absolute limit on these values. |
| 164 | Finally, SO_TYPE and SO_ERROR are options used only with |
| 165 | .IR setsockopt . |
| 166 | SO_TYPE returns the type of the socket, such as SOCK_STREAM; |
| 167 | it is useful for servers that inherit sockets on startup. |
| 168 | SO_ERROR returns any pending error on the socket and clears |
| 169 | the error status. |
| 170 | It may be used to check for asynchronous errors on connected |
| 171 | datagram sockets or for other asynchronous errors. |
| 172 | .SH "RETURN VALUE" |
| 173 | A 0 is returned if the call succeeds, \-1 if it fails. |
| 174 | .SH ERRORS |
| 175 | The call succeeds unless: |
| 176 | .TP 20 |
| 177 | [EBADF] |
| 178 | The argument \fIs\fP is not a valid descriptor. |
| 179 | .TP 20 |
| 180 | [ENOTSOCK] |
| 181 | The argument \fIs\fP is a file, not a socket. |
| 182 | .TP 20 |
| 183 | [ENOPROTOOPT] |
| 184 | The option is unknown at the level indicated. |
| 185 | .TP 20 |
| 186 | [EFAULT] |
| 187 | The address pointed to by |
| 188 | .I optval |
| 189 | is not in a valid part of the process address space. |
| 190 | For |
| 191 | .IR getsockopt , |
| 192 | this error may also be returned if |
| 193 | .I optlen |
| 194 | is not in a valid part of the process address space. |
| 195 | .SH "SEE ALSO" |
| 196 | ioctl(2), socket(2), getprotoent(3N) |
| 197 | .SH BUGS |
| 198 | Several of the socket options should be handled at lower levels of the system. |