| blob | 48ea7719fe47b0aa4c3255e36df591130a09a324 |
1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH GETSOCKOPT 3XNET "Jan 21, 2007"
11 .SH NAME
12 getsockopt \- get the socket options
13 .SH SYNOPSIS
14 .LP
15 .nf
16 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lxnet\fR [ \fIlibrary\fR... ]
17 #include <sys/socket.h>
19 \fBint\fR \fBgetsockopt\fR(\fBint\fR \fIsocket\fR, \fBint\fR \fIlevel\fR, \fBint\fR \fIoption_name\fR,
20 \fBvoid *restrict\fR \fIoption_value\fR, \fBsocklen_t *restrict\fR \fIoption_len\fR);
21 .fi
23 .SH DESCRIPTION
24 .sp
25 .LP
26 The \fBgetsockopt()\fR function retrieves the value for the option specified by
27 the \fIoption_name\fR argument for the socket specified by the \fIsocket\fR
28 argument. If the size of the option value is greater than \fIoption_len\fR, the
29 value stored in the object pointed to by the \fIoption_value\fR argument will
30 be silently truncated. Otherwise, the object pointed to by the \fIoption_len\fR
31 argument will be modified to indicate the actual length of the value.
32 .sp
33 .LP
34 The \fIlevel\fR argument specifies the protocol level at which the option
35 resides. To retrieve options at the socket level, specify the \fIlevel\fR
36 argument as \fBSOL_SOCKET\fR. To retrieve options at other levels, supply the
37 appropriate protocol number for the protocol controlling the option. For
38 example, to indicate that an option will be interpreted by the \fBTCP\fR
39 (Transport Control Protocol), set \fIlevel\fR to the protocol number of
40 \fBTCP\fR, as defined in the <\fBnetinet/in.h\fR> header, or as determined by
41 using \fBgetprotobyname\fR(3XNET) function.
42 .sp
43 .LP
44 The socket in use might require the process to have appropriate privileges to
45 use the \fBgetsockopt()\fR function.
46 .sp
47 .LP
48 The \fIoption_name\fR argument specifies a single option to be retrieved. It
49 can be one of the following values defined in \fB<sys/socket.h>\fR:
50 .sp
51 .ne 2
52 .na
53 \fB\fBSO_DEBUG\fR\fR
54 .ad
55 .RS 17n
56 Reports whether debugging information is being recorded. This option stores an
57 \fBint\fR value. This is a boolean option.
58 .RE
60 .sp
61 .ne 2
62 .na
63 \fB\fBSO_ACCEPTCONN\fR\fR
64 .ad
65 .RS 17n
66 Reports whether socket listening is enabled. This option stores an \fBint\fR
67 value.
68 .RE
70 .sp
71 .ne 2
72 .na
73 \fB\fBSO_BROADCAST\fR\fR
74 .ad
75 .RS 17n
76 Reports whether transmission of broadcast messages is supported, if this is
77 supported by the protocol. This option stores an \fBint\fR value. This is a
78 boolean option.
79 .RE
81 .sp
82 .ne 2
83 .na
84 \fB\fBSO_REUSEADDR\fR\fR
85 .ad
86 .RS 17n
87 Reports whether the rules used in validating addresses supplied to
88 \fBbind\fR(3XNET) should allow reuse of local addresses, if this is supported
89 by the protocol. This option stores an \fBint\fR value. This is a boolean
90 option.
91 .RE
93 .sp
94 .ne 2
95 .na
96 \fB\fBSO_KEEPALIVE\fR\fR
97 .ad
98 .RS 17n
99 Reports whether connections are kept active with periodic transmission of
100 messages, if this is supported by the protocol.
101 .sp
102 If the connected socket fails to respond to these messages, the connection is
103 broken and threads writing to that socket are notified with a \fBSIGPIPE\fR
104 signal. This option stores an \fBint\fR value.
105 .sp
106 This is a boolean option.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fBSO_LINGER\fR\fR
113 .ad
114 .RS 17n
115 Reports whether the socket lingers on \fBclose\fR(2) if data is present. If
116 \fBSO_LINGER\fR is set, the system blocks the process during \fBclose\fR(2)
117 until it can transmit the data or until the end of the interval indicated by
118 the \fBl_linger\fR member, whichever comes first. If \fBSO_LINGER\fR is not
119 specified, and \fBclose\fR(2) is issued, the system handles the call in a way
120 that allows the process to continue as quickly as possible. This option stores
121 a \fBlinger\fR structure.
122 .RE
124 .sp
125 .ne 2
126 .na
127 \fB\fBSO_OOBINLINE\fR\fR
128 .ad
129 .RS 17n
130 Reports whether the socket leaves received out-of-band data (data marked
131 urgent) in line. This option stores an \fBint\fR value. This is a boolean
132 option.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fBSO_SNDBUF\fR\fR
139 .ad
140 .RS 17n
141 Reports send buffer size information. This option stores an \fBint\fR value.
142 .RE
144 .sp
145 .ne 2
146 .na
147 \fB\fBSO_RCVBUF\fR\fR
148 .ad
149 .RS 17n
150 Reports receive buffer size information. This option stores an \fBint\fR value.
151 .RE
153 .sp
154 .ne 2
155 .na
156 \fB\fBSO_ERROR\fR\fR
157 .ad
158 .RS 17n
159 Reports information about error status and clears it. This option stores an
160 \fBint\fR value.
161 .RE
163 .sp
164 .ne 2
165 .na
166 \fB\fBSO_TYPE\fR\fR
167 .ad
168 .RS 17n
169 Reports the socket type. This option stores an \fBint\fR value.
170 .RE
172 .sp
173 .ne 2
174 .na
175 \fB\fBSO_DONTROUTE\fR\fR
176 .ad
177 .RS 17n
178 Reports whether outgoing messages bypass the standard routing facilities. The
179 destination must be on a directly-connected network, and messages are directed
180 to the appropriate network interface according to the destination address. The
181 effect, if any, of this option depends on what protocol is in use. This option
182 stores an \fBint\fR value. This is a boolean option.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBSO_MAC_EXEMPT\fR\fR
189 .ad
190 .RS 17n
191 Gets the mandatory access control status of the socket. A socket that has this
192 option enabled can communicate with an unlabeled peer if the socket is in the
193 global zone or has a label that dominates the default label of the peer.
194 Otherwise, the socket must have a label that is equal to the default label of
195 the unlabeled peer. \fB\fR\fBSO_MAC_EXEMPT\fR is a boolean option that is
196 available only when the system is configured with Trusted Extensions.
197 .RE
199 .sp
200 .ne 2
201 .na
202 \fB\fBSO_ALLZONES\fR\fR
203 .ad
204 .RS 17n
205 Bypasses zone boundaries (privileged). This option stores an \fBint\fR value.
206 This is a boolean option.
207 .sp
208 The \fBSO_ALLZONES\fR option can be used to bypass zone boundaries between
209 shared-IP zones. Normally, the system prevents a socket from being bound to an
210 address that is not assigned to the current zone. It also prevents a socket
211 that is bound to a wildcard address from receiving traffic for other zones.
212 However, some daemons which run in the global zone might need to send and
213 receive traffic using addresses that belong to other shared-IP zones. If set
214 before a socket is bound, \fBSO_ALLZONES\fR causes the socket to ignore zone
215 boundaries between shared-IP zones and permits the socket to be bound to any
216 address assigned to the shared-IP zones. If the socket is bound to a wildcard
217 address, it receives traffic intended for all shared-IP zones and behaves as if
218 an equivalent socket were bound in each active shared-IP zone. Applications
219 that use the \fBSO_ALLZONES\fR option to initiate connections or send datagram
220 traffic should specify the source address for outbound traffic by binding to a
221 specific address. There is no effect from setting this option in an
222 exclusive-IP zone. Setting this option requires the \fBsys_net_config\fR
223 privilege. See \fBzones\fR(5).
224 .RE
226 .sp
227 .ne 2
228 .na
229 \fB\fBSO_DOMAIN\fR\fR
230 .ad
231 .RS 17n
232 get the domain used in the socket (get only)
233 .RE
235 .sp
236 .ne 2
237 .na
238 \fB\fBSO_PROTOTYPE\fR\fR
239 .ad
240 .RS 17n
241 for socket in domains \fBAF_INET\fR and \fBAF_INET6\fR, get the underlying
242 protocol number used in the socket. For socket in domain \fBAF_ROUTE\fR, get
243 the address family used in the socket.
244 .RE
246 .sp
247 .LP
248 For boolean options, a zero value indicates that the option is disabled and a
249 non-zero value indicates that the option is enabled.
250 .sp
251 .LP
252 Options at other protocol levels vary in format and name.
253 .sp
254 .LP
255 The socket in use may require the process to have appropriate privileges to use
256 the \fBgetsockopt()\fR function.
257 .SH RETURN VALUES
258 .sp
259 .LP
260 Upon successful completion, \fBgetsockopt()\fR returns \fB0\fR. Otherwise,
261 \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
262 .SH ERRORS
263 .sp
264 .LP
265 The \fBgetsockopt()\fR function will fail if:
266 .sp
267 .ne 2
268 .na
269 \fB\fBEBADF\fR\fR
270 .ad
271 .RS 15n
272 The \fIsocket\fR argument is not a valid file descriptor.
273 .RE
275 .sp
276 .ne 2
277 .na
278 \fB\fBEFAULT\fR\fR
279 .ad
280 .RS 15n
281 The \fIoption_value\fR or \fIoption_len\fR parameter can not be accessed or
282 written.
283 .RE
285 .sp
286 .ne 2
287 .na
288 \fB\fBEINVAL\fR\fR
289 .ad
290 .RS 15n
291 The specified option is invalid at the specified socket level.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBENOPROTOOPT\fR\fR
298 .ad
299 .RS 15n
300 The option is not supported by the protocol.
301 .RE
303 .sp
304 .ne 2
305 .na
306 \fB\fBENOTSOCK\fR\fR
307 .ad
308 .RS 15n
309 The \fIsocket\fR argument does not refer to a socket.
310 .RE
312 .sp
313 .LP
314 The \fBgetsockopt()\fR function may fail if:
315 .sp
316 .ne 2
317 .na
318 \fB\fBEACCES\fR\fR
319 .ad
320 .RS 11n
321 The calling process does not have the appropriate privileges.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fB\fBEINVAL\fR\fR
328 .ad
329 .RS 11n
330 The socket has been shut down.
331 .RE
333 .sp
334 .ne 2
335 .na
336 \fB\fBENOBUFS\fR\fR
337 .ad
338 .RS 11n
339 Insufficient resources are available in the system to complete the call.
340 .RE
342 .sp
343 .ne 2
344 .na
345 \fB\fBENOSR\fR\fR
346 .ad
347 .RS 11n
348 There were insufficient STREAMS resources available for the operation to
349 complete.
350 .RE
352 .SH ATTRIBUTES
353 .sp
354 .LP
355 See \fBattributes\fR(5) for descriptions of the following attributes:
356 .sp
358 .sp
359 .TS
360 box;
361 c | c
362 l | l .
363 ATTRIBUTE TYPE ATTRIBUTE VALUE
364 _
365 Interface Stability Standard
366 _
367 MT-Level MT-Safe
368 .TE
370 .SH SEE ALSO
371 .sp
372 .LP
373 \fBclose\fR(2), \fBbind\fR(3XNET), \fBendprotoent\fR(3XNET),
374 \fBsetsockopt\fR(3XNET), \fBsocket\fR(3XNET), \fBattributes\fR,
375 \fBstandards\fR(5)