1 .\" $NetBSD: getsockopt.2,v 1.7 1995/02/27 12:33:29 cgd Exp $
3 .\" Copyright (c) 1983, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
34 .\" @(#)getsockopt.2 8.3 (Berkeley) 4/19/94
42 .Nd get and set options on sockets
44 .Fd #include <sys/socket.h>
50 .Fa "void *restrict option_value"
51 .Fa "socklen_t *restrict option_len"
58 .Fa "const void *option_value"
59 .Fa "socklen_t option_len"
67 associated with a socket. Options may exist at multiple
68 protocol levels; they are always present at the uppermost
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,
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
85 should be set to the protocol number of
94 are used to access option values for
98 they identify a buffer in which the value for the
99 requested option(s) are to be returned. For
102 is a value-result parameter, initially containing the
103 size of the buffer pointed to by
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,
112 and any specified options are passed uninterpreted to the appropriate
113 protocol module for interpretation.
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
123 Most socket-level options utilize an
129 the parameter should be non-zero to enable a boolean option,
130 or zero if the option is to be disabled.
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).
143 parameter, defined in
144 .Ao Pa sys/time.h Ac .
146 The following options are recognized at the socket level.
147 Except as noted, each may be examined with
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"
175 enables debugging in the underlying protocol modules.
178 indicates that the rules used in validating addresses supplied
181 call should allow reuse of local addresses.
184 allows completely duplicate bindings by multiple processes
187 before binding the port.
188 This option permits multiple instances of a program to each
189 receive UDP/IP multicast or broadcast datagrams destined for the bound port.
193 periodic transmission of messages on a connected socket. Should the
194 connected party fail to respond to these messages, the connection is
195 considered broken and processes using the socket are notified via a
197 signal when attempting to send data.
200 indicates that outgoing messages should
201 bypass the standard routing facilities. Instead, messages are directed
202 to the appropriate network interface according to the network portion
203 of the destination address.
206 controls the action taken when unsent messages
207 are queued on socket and a
210 If the socket promises reliable delivery of data and
211 .Dv SO_LINGER is set,
212 the system will block the process on the
214 attempt until it is able to transmit the data or until it decides it
215 is unable to deliver the information (a timeout period, termed the
216 linger interval, is specified in the
225 is issued, the system will process the close in a manner that allows
226 the process to continue as quickly as possible.
229 is the same option as
231 except the linger time is in seconds for
236 requests permission to send broadcast datagrams
238 Broadcast was a privileged operation in earlier versions of the system.
240 With protocols that support out-of-band data, the
243 requests that out-of-band data be placed in the normal data input queue
244 as received; it will then be accessible with
251 Some protocols always behave as if this option is set.
256 are options to adjust the normal
257 buffer sizes allocated for output and input buffers, respectively.
258 The buffer size may be increased for high-volume connections,
259 or may be decreased to limit the possible backlog of incoming data.
260 The system places an absolute limit on these values.
263 is an option to set the minimum count for output operations.
264 Most output operations process all of the data supplied by the call,
265 delivering data to the protocol for transmission
266 and blocking as necessary for flow control.
267 Nonblocking output operations will process as much data as permitted
268 (subject to flow control) without blocking,
269 but will process no data if flow control
270 does not allow the smaller of the low-water mark value
271 or the entire request to be processed.
274 operation testing the ability to write to a socket will return true
275 only if the low-water mark amount could be processed.
276 The default value for
278 is set to a convenient size for network efficiency, often 2048.
281 is an option to set the minimum count for input operations.
282 In general, receive calls will block until any (non-zero) amount of data
283 is received, then return with the smaller of the amount available
284 or the amount requested.
285 The default value for
290 is set to a larger value, blocking receive calls
291 normally wait until they have received the smaller
292 of the low-water mark value or the requested amount.
293 Receive calls may still return less than the low-water mark
294 if an error occurs, a signal is caught,
295 or the type of data next in the receive queue
296 is different than that returned.
299 is an option to set a timeout value for output operations.
302 parameter with the number of seconds and microseconds
303 used to limit waits for output operations to complete.
304 If a send operation has blocked for this much time,
305 it returns with a partial count
308 if no data were sent.
309 In the current implementation, this timer is restarted each time additional
310 data are delivered to the protocol,
311 implying that the limit applies to output portions ranging in size
312 from the low-water mark to the high-water mark for output.
315 is an option to set a timeout value for input operations.
318 parameter with the number of seconds and microseconds
319 used to limit waits for input operations to complete.
320 In the current implementation, this timer is restarted each time additional
321 data are received by the protocol,
322 and thus the limit is in effect an inactivity timer.
323 If a receive operation has been blocked for this much time without
324 receiving additional data, it returns with a short count
327 if no data were received.
328 The struct timeval parameter must represent a positive time interval;
331 returns with the error
334 .Dv SO_NOSIGPIPE is an option that prevents SIGPIPE from being raised
335 when a write fails on a socket to which there is no reader;
336 instead, the write to the socket returns with the error
338 when there is no reader.
345 are options used only with
349 returns the type of the socket, such as
351 it is useful for servers that inherit sockets on startup.
354 returns any pending error on the socket and clears
356 It may be used to check for asynchronous errors on connected
357 datagram sockets or for other asynchronous errors.
360 returns the amount of data in the input buffer that is available to be received.
361 For datagram oriented sockets,
363 returns the size of the first packet -- this differs from the
367 that returns the total amount of data available.
370 returns the amount of data in the output buffer not yet sent by the protocol.
378 system calls will succeed unless:
384 is not a valid file descriptor.
387 The address pointed to by
389 is not in a valid part of the process address space.
392 this error may also be returned if
394 is not in a valid part of the process address space.
397 The option is invalid at the level indicated.
400 Insufficient system resources available for the call to complete.
403 Insufficient memory available for the system call to complete.
405 .It Bq Er ENOPROTOOPT
406 The option is unknown at the level indicated.
411 is not a socket (e.g., a plain file).
416 system call will succeed unless:
427 and a specified option cannot be set
428 while this is the case.
431 The socket has been shut down.
434 .Fd #include <sys/types.h>
435 .Fd #include <sys/socket.h>
447 Several of the socket options should be handled at lower levels of the system.
451 system call appeared in
projects / apple / xnu.git / blob