bsd/man/man2/getsockopt.2

   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
  63 and
  64 .Fn setsockopt
  65 manipulate the
  66 .Em options
  67 associated with a socket.  Options may exist at multiple
  68 protocol levels; they are always present at the uppermost
  69 .Dq socket
  70 level.
  71 .Pp
  72 When manipulating socket options the level at which the
  73 option resides and the name of the option must be specified.
  74 To manipulate options at the socket level,
  75 .Fa level
  76 is specified as
  77 .Dv SOL_SOCKET .
  78 To manipulate options at any
  79 other level the protocol number of the appropriate protocol
  80 controlling the option is supplied.  For example,
  81 to indicate that an option is to be interpreted by the
  82 .Tn TCP
  83 protocol,
  84 .Fa level
  85 should be set to the protocol number of
  86 .Tn TCP ;
  87 see
  88 .Xr getprotoent 3 .
  89 .Pp
  90 The parameters
  91 .Fa option_value
  92 and
  93 .Fa option_len
  94 are used to access option values for
  95 .Fn setsockopt .
  96 For
  97 .Fn getsockopt
  98 they identify a buffer in which the value for the
  99 requested option(s) are to be returned.  For
 100 .Fn getsockopt ,
 101 .Fa option_len
 102 is a value-result parameter, initially containing the
 103 size of the buffer pointed to by
 104 .Fa option_value ,
 105 and modified on return to indicate the actual size of
 106 the value returned.  If no option value is
 107 to be supplied or returned,
 108 .Fa option_value
 109 may be NULL.
 110 .Pp
 111 .Fa option_name
 112 and any specified options are passed uninterpreted to the appropriate
 113 protocol module for interpretation.
 114 The include file
 115 .Ao Pa sys/socket.h Ac
 116 contains definitions for
 117 socket level options, described below.
 118 Options at other protocol levels vary in format and
 119 name; consult the appropriate entries in
 120 section
 121 4 of the manual.
 122 .Pp
 123 Most socket-level options utilize an
 124 .Fa int
 125 parameter for
 126 .Fa option_value .
 127 For
 128 .Fn setsockopt ,
 129 the parameter should be non-zero to enable a boolean option,
 130 or zero if the option is to be disabled.
 131 .Dv SO_LINGER
 132 uses a
 133 .Fa struct linger
 134 parameter, defined in
 135 .Ao Pa sys/socket.h Ac ,
 136 which specifies the desired state of the option and the
 137 linger interval (see below).
 138 .Dv SO_SNDTIMEO
 139 and
 140 .Dv SO_RCVTIMEO
 141 use a
 142 .Fa struct timeval
 143 parameter, defined in
 144 .Ao Pa sys/time.h Ac .
 145 .Pp
 146 The following options are recognized at the socket level.
 147 Except as noted, each may be examined with
 148 .Fn getsockopt
 149 and 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 .El
 170 .Pp
 171 .Dv SO_DEBUG
 172 enables debugging in the underlying protocol modules.
 173 .Dv SO_REUSEADDR
 174 indicates that the rules used in validating addresses supplied
 175 in a
 176 .Xr bind 2
 177 call should allow reuse of local addresses.
 178 .Dv SO_REUSEPORT
 179 allows completely duplicate bindings by multiple processes
 180 if they all set
 181 .Dv SO_REUSEPORT
 182 before binding the port.
 183 This option permits multiple instances of a program to each
 184 receive UDP/IP multicast or broadcast datagrams destined for the bound port.
 185 .Dv SO_KEEPALIVE
 186 enables the
 187 periodic transmission of messages on a connected socket.  Should the
 188 connected party fail to respond to these messages, the connection is
 189 considered broken and processes using the socket are notified via a
 190 .Dv SIGPIPE
 191 signal when attempting to send data.
 192 .Dv SO_DONTROUTE
 193 indicates that outgoing messages should
 194 bypass the standard routing facilities.  Instead, messages are directed
 195 to the appropriate network interface according to the network portion
 196 of the destination address.
 197 .Pp
 198 .Dv SO_LINGER
 199 controls the action taken when unsent messages
 200 are queued on socket and a
 201 .Xr close 2
 202 is performed.
 203 If the socket promises reliable delivery of data and
 204 .Dv SO_LINGER is set,
 205 the system will block the process on the
 206 .Xr close
 207 attempt until it is able to transmit the data or until it decides it
 208 is unable to deliver the information (a timeout period, termed the
 209 linger interval, is specified in the
 210 .Fn setsockopt
 211 call when
 212 .Dv SO_LINGER
 213 is requested).
 214 If
 215 .Dv SO_LINGER
 216 is disabled and a
 217 .Xr close
 218 is issued, the system will process the close in a manner that allows
 219 the process to continue as quickly as possible.
 220 .Pp
 221 The option
 222 .Dv SO_BROADCAST
 223 requests permission to send broadcast datagrams
 224 on the socket.
 225 Broadcast was a privileged operation in earlier versions of the system.
 226 With protocols that support out-of-band data, the
 227 .Dv SO_OOBINLINE
 228 option
 229 requests that out-of-band data be placed in the normal data input queue
 230 as received; it will then be accessible with
 231 .Xr recv
 232 or
 233 .Xr read
 234 calls without the
 235 .Dv MSG_OOB
 236 flag.
 237 Some protocols always behave as if this option is set.
 238 .Dv SO_SNDBUF
 239 and
 240 .Dv SO_RCVBUF
 241 are options to adjust the normal
 242 buffer sizes allocated for output and input buffers, respectively.
 243 The buffer size may be increased for high-volume connections,
 244 or may be decreased to limit the possible backlog of incoming data.
 245 The system places an absolute limit on these values.
 246 .Pp
 247 .Dv SO_SNDLOWAT
 248 is an option to set the minimum count for output operations.
 249 Most output operations process all of the data supplied by the call,
 250 delivering data to the protocol for transmission
 251 and blocking as necessary for flow control.
 252 Nonblocking output operations will process as much data as permitted
 253 (subject to flow control) without blocking,
 254 but will process no data if flow control
 255 does not allow the smaller of the low-water mark value
 256 or the entire request to be processed.
 257 A
 258 .Xr select 2
 259 operation testing the ability to write to a socket will return true
 260 only if the low-water mark amount could be processed.
 261 The default value for
 262 .Dv SO_SNDLOWAT
 263 is set to a convenient size for network efficiency, often 1024.
 264 .Pp
 265 .Dv SO_RCVLOWAT
 266 is an option to set the minimum count for input operations.
 267 In general, receive calls will block until any (non-zero) amount of data
 268 is received, then return with the smaller of the amount available
 269 or the amount requested.
 270 The default value for
 271 .Dv SO_RCVLOWAT
 272 is 1.
 273 If
 274 .Dv SO_RCVLOWAT
 275 is set to a larger value, blocking receive calls
 276 normally wait until they have received the smaller
 277 of the low-water mark value or the requested amount.
 278 Receive calls may still return less than the low-water mark
 279 if an error occurs, a signal is caught,
 280 or the type of data next in the receive queue
 281 is different than that returned.
 282 .Pp
 283 .Dv SO_SNDTIMEO
 284 is an option to set a timeout value for output operations.
 285 It accepts a
 286 .Fa struct timeval
 287 parameter with the number of seconds and microseconds
 288 used to limit waits for output operations to complete.
 289 If a send operation has blocked for this much time,
 290 it returns with a partial count
 291 or with the error
 292 .Er EWOULDBLOCK
 293 if no data were sent.
 294 In the current implementation, this timer is restarted each time additional
 295 data are delivered to the protocol,
 296 implying that the limit applies to output portions ranging in size
 297 from the low-water mark to the high-water mark for output.
 298 .Pp
 299 .Dv SO_RCVTIMEO
 300 is an option to set a timeout value for input operations.
 301 It accepts a
 302 .Fa struct timeval
 303 parameter with the number of seconds and microseconds
 304 used to limit waits for input operations to complete.
 305 In the current implementation, this timer is restarted each time additional
 306 data are received by the protocol,
 307 and thus the limit is in effect an inactivity timer.
 308 If a receive operation has been blocked for this much time without
 309 receiving additional data, it returns with a short count
 310 or with the error
 311 .Er EWOULDBLOCK
 312 if no data were received.
 313 The struct timeval parameter must represent a positive time interval;
 314 otherwise,
 315 .Fn setsockopt
 316 returns with the error
 317 .Er EDOM .
 318 .Pp
 319 .Dv SO_NOSIGPIPE is an option that prevents SIGPIPE from being raised
 320 when a write fails on a socket to which there is no reader;
 321 instead, the write to the socket returns with the error
 322 .Er EPIPE
 323 when there is no reader.
 324 .Pp
 325 Finally,
 326 .Dv SO_TYPE
 327 and
 328 .Dv SO_ERROR
 329 are options used only with
 330 .Fn getsockopt .
 331 .Dv SO_TYPE
 332 returns the type of the socket, such as
 333 .Dv SOCK_STREAM ;
 334 it is useful for servers that inherit sockets on startup.
 335 .Dv SO_ERROR
 336 returns any pending error on the socket and clears
 337 the error status.
 338 It may be used to check for asynchronous errors on connected
 339 datagram sockets or for other asynchronous errors.
 340 .Sh RETURN VALUES
 341 .Rv -std
 342 .Sh ERRORS
 343 The
 344 .Fn getsockopt
 345 and
 346 .Fn setsockopt
 347 system calls will succeed unless:
 348 .Bl -tag -width Er
 349 .\" ==========
 350 .It Bq Er EBADF
 351 The argument
 352 .Fa socket
 353 is not a valid file descriptor.
 354 .\" ==========
 355 .It Bq Er EFAULT
 356 The address pointed to by
 357 .Fa option_value
 358 is not in a valid part of the process address space.
 359 For
 360 .Fn getsockopt ,
 361 this error may also be returned if
 362 .Fa option_len
 363 is not in a valid part of the process address space.
 364 .\" ==========
 365 .It Bq Er EINVAL
 366 The option is invalid at the level indicated.
 367 .\" ==========
 368 .It Bq Er ENOBUFS
 369 Insufficient memory buffers are available.
 370 .\" ==========
 371 .It Bq Er ENOPROTOOPT
 372 The option is unknown at the level indicated.
 373 .\" ==========
 374 .It Bq Er ENOTSOCK
 375 The argument
 376 .Fa socket
 377 is not a socket (e.g., a plain file).
 378 .El
 379 .Pp
 380 The
 381 .Fn setsockopt
 382 system call will succeed unless:
 383 .Bl -tag -width Er
 384 .\" ==========
 385 .It Bq Er EDOM
 386 The argument
 387 .Fa option_value
 388 is out of bounds.
 389 .\" ==========
 390 .It Bq Er EISCONN
 391 .Fa socket
 392 is already connected
 393 and a specified option cannot be set
 394 while this is the case.
 395 .El
 396 .Sh LEGACY SYNOPSIS
 397 .Fd #include <sys/types.h>
 398 .Fd #include <sys/socket.h>
 399 .Pp
 400 The include file
 401 .In sys/types.h
 402 is necessary.
 403 .Sh SEE ALSO
 404 .Xr ioctl 2 ,
 405 .Xr socket 2 ,
 406 .Xr getprotoent 3 ,
 407 .Xr protocols 5
 408 .Sh BUGS
 409 Several of the socket options should be handled at lower levels of the system.
 410 .Sh HISTORY
 411 The
 412 .Fn getsockopt
 413 system call appeared in
 414 .Bx 4.2 .