Commit | Line | Data |
---|---|---|
da268306 KB |
1 | .\" Copyright (c) 1983 The Regents of the University of California. |
2 | .\" All rights reserved. | |
efbcfcab | 3 | .\" |
91cff1e1 | 4 | .\" %sccs.include.redist.man% |
da268306 | 5 | .\" |
91cff1e1 | 6 | .\" @(#)getsockopt.2 6.6 (Berkeley) %G% |
efbcfcab | 7 | .\" |
a66e777a | 8 | .TH GETSOCKOPT 2 "" |
efbcfcab KM |
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, | |
ea7101e3 | 46 | to indicate that an option is to be interpreted by the TCP protocol, |
efbcfcab KM |
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 > | |
d25f1c67 | 77 | contains definitions for ``socket'' level options, described below. |
efbcfcab | 78 | Options at other protocol levels vary in format and |
d25f1c67 MK |
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. | |
efbcfcab KM |
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] | |
d25f1c67 | 184 | The option is unknown at the level indicated. |
efbcfcab KM |
185 | .TP 20 |
186 | [EFAULT] | |
fd690c8b KM |
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. | |
efbcfcab | 195 | .SH "SEE ALSO" |
d25f1c67 MK |
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. |