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