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