Print this page
Clearview IPMP manpages
| Split |
Close |
| Expand all |
| Collapse all |
--- old/./getsockopt.3socket.txt
+++ new/./getsockopt.3socket.txt
1 1 Sockets Library Functions getsockopt(3SOCKET)
2 2
3 3
4 4
5 5 NAME
6 6 getsockopt, setsockopt - get and set options on sockets
7 7
8 8 SYNOPSIS
9 9 cc [ flag ... ] file ... -lsocket -lnsl [ library ... ]
10 10 #include <sys/types.h>
11 11 #include <sys/socket.h>
12 12
13 13 int getsockopt(int s, int level, int optname, void *optval,
14 14 int *optlen);
15 15
16 16
17 17 int setsockopt(int s, int level, int optname, const void *optval,
|
↓ open down ↓ |
17 lines elided |
↑ open up ↑ |
18 18 int optlen);
19 19
20 20
21 21 DESCRIPTION
22 22 The getsockopt() and setsockopt() functions manipulate
23 23 options associated with a socket. Options may exist at mul-
24 24 tiple protocol levels; they are always present at the upper-
25 25 most "socket" level.
26 26
27 27
28 - When manipulating socket options, the level at which the
29 - option resides and the name of the option must be specified.
30 - To manipulate options at the "socket" level, level is speci-
31 - fied as SOL_SOCKET. To manipulate options at any other
32 - level, level is the protocol number of the protocol that
33 - controls the option. For example, to indicate that an option
34 - is to be interpreted by the TCP protocol, level is set to
35 - the TCP protocol number. See getprotobyname(3SOCKET).
28 + The *level* argument specifies the protocol level at which
29 + the option resides. To manipulate options at the socket
30 + level, specify the *level* argument as *SOL_SOCKET*. To
31 + manipulate options at the protocol level, supply the
32 + appropriate protocol number for the protocol controlling the
33 + option. For example, to indicate that an option will be
34 + interpreted by TCP, set *level* to the protocol number of
35 + TCP, as defined in the *<netinet/in.h>* header, or as
36 + determined by using *getprotobyname(3SOCKET)*. Some socket
37 + protocol families may also define additional levels, such as
38 + *SOL_ROUTE*. Only socket-level options are described here.
36 39
37 40
38 41 The parameters optval and optlen are used to access option
39 42 values for setsockopt(). For getsockopt(), they identify a
40 43 buffer in which the value(s) for the requested option(s) are
41 44 to be returned. For getsockopt(), optlen is a value-result
42 45 parameter, initially containing the size of the buffer
43 46 pointed to by optval, and modified on return to indicate the
44 47 actual size of the value returned. Use a 0 optval if no
45 48 option value is to be supplied or returned.
46 49
47 50
48 51 The optname and any specified options are passed uninter-
49 52 preted to the appropriate protocol module for interpreta-
50 53 tion. The include file <sys/socket.h> contains definitions
51 54 for the socket-level options described below. Options at
52 55 other protocol levels vary in format and name.
53 56
54 57
55 58 Most socket-level options take an int for optval. For set-
56 59 sockopt(), the optval parameter should be non-zero to enable
57 60
58 61
59 62
60 63 SunOS 5.11 Last change: 7 Aug 2008 1
61 64
62 65
63 66
64 67
65 68
66 69
67 70 Sockets Library Functions getsockopt(3SOCKET)
68 71
69 72
70 73
71 74 a boolean option, or zero if the option is to be disabled.
72 75 SO_LINGER uses a struct linger parameter that specifies the
73 76 desired state of the option and the linger interval. struct
74 77 linger is defined in <sys/socket.h>. struct linger contains
75 78 the following members:
76 79
77 80 l_onoff on = 1/off = 0
78 81
79 82
80 83 l_linger linger time, in seconds
81 84
82 85
83 86
84 87 The following options are recognized at the socket level.
85 88 Except as noted, each may be examined with getsockopt() and
86 89 set with setsockopt().
87 90
88 91 SO_DEBUG enable/disable recording of debugging
89 92 information
90 93
91 94
92 95 SO_REUSEADDR enable/disable local address reuse
93 96
94 97
95 98 SO_KEEPALIVE enable/disable keep connections alive
96 99
97 100
98 101 SO_DONTROUTE enable/disable routing bypass for outgo-
99 102 ing messages
100 103
101 104
102 105 SO_LINGER linger on close if data is present
103 106
104 107
105 108 SO_BROADCAST enable/disable permission to transmit
106 109 broadcast messages
107 110
108 111
109 112 SO_OOBINLINE enable/disable reception of out-of-band
110 113 data in band
111 114
112 115
113 116 SO_SNDBUF set buffer size for output
114 117
115 118
116 119 SO_RCVBUF set buffer size for input
117 120
118 121
119 122 SO_DGRAM_ERRIND application wants delayed error
120 123
121 124
122 125
123 126
124 127
125 128
126 129 SunOS 5.11 Last change: 7 Aug 2008 2
127 130
128 131
129 132
130 133
131 134
132 135
133 136 Sockets Library Functions getsockopt(3SOCKET)
134 137
135 138
136 139
137 140 SO_TIMESTAMP enable/disable reception of timestamp
138 141 with datagrams
139 142
140 143
141 144 SO_EXCLBIND enable/disable exclusive binding of the
142 145 socket
143 146
144 147
145 148 SO_TYPE get the type of the socket (get only)
146 149
147 150
148 151 SO_ERROR get and clear error on the socket (get
149 152 only)
150 153
151 154
152 155 SO_MAC_EXEMPT get or set mandatory access control on
153 156 the socket. This option is available only
154 157 when the system is configured with
155 158 Trusted Extensions.
156 159
157 160
158 161 SO_ALLZONES bypass zone boundaries (privileged).
159 162
160 163
161 164 SO_DOMAIN get the domain used in the socket (get
162 165 only)
163 166
164 167
165 168 SO_PROTOTYPE for socket in domains PF_INET and
166 169 PF_INET6, get the underlying protocol
167 170 number used in the socket. For socket in
168 171 domain PF_ROUTE, get the address family
169 172 used in the socket.
170 173
171 174
172 175
173 176 The SO_DEBUG option enables debugging in the underlying pro-
174 177 tocol modules. The SO_REUSEADDR option indicates that the
175 178 rules used in validating addresses supplied in a
176 179 bind(3SOCKET) call should allow reuse of local addresses.
177 180 The SO_KEEPALIVE option enables the periodic transmission of
178 181 messages on a connected socket. If the connected party fails
179 182 to respond to these messages, the connection is considered
180 183 broken and threads using the socket are notified using a
181 184 SIGPIPE signal. The SO_DONTROUTE option indicates that out-
182 185 going messages should bypass the standard routing facili-
183 186 ties. Instead, messages are directed to the appropriate net-
184 187 work interface according to the network portion of the des-
185 188 tination address.
186 189
187 190
188 191
189 192
190 193
191 194
192 195 SunOS 5.11 Last change: 7 Aug 2008 3
193 196
194 197
195 198
196 199
197 200
198 201
199 202 Sockets Library Functions getsockopt(3SOCKET)
200 203
201 204
202 205
203 206 The SO_LINGER option controls the action taken when unsent
204 207 messages are queued on a socket and a close(2) is performed.
205 208 If the socket promises reliable delivery of data and
206 209 SO_LINGER is set, the system will block the thread on the
207 210 close() attempt until it is able to transmit the data or
208 211 until it decides it is unable to deliver the information (a
209 212 timeout period, termed the linger interval, is specified in
210 213 the setsockopt() call when SO_LINGER is requested). If
211 214 SO_LINGER is disabled and a close() is issued, the system
212 215 will process the close() in a manner that allows the thread
213 216 to continue as quickly as possible.
214 217
215 218
216 219 The option SO_BROADCAST requests permission to send broad-
217 220 cast datagrams on the socket. With protocols that support
218 221 out-of-band data, the SO_OOBINLINE option requests that
219 222 out-of-band data be placed in the normal data input queue as
220 223 received; it will then be accessible with recv() or read()
221 224 calls without the MSG_OOB flag.
222 225
223 226
224 227 The SO_SNDBUF and SO_RCVBUF options adjust the normal buffer
225 228 sizes allocated for output and input buffers, respectively.
226 229 The buffer size may be increased for high-volume connections
227 230 or may be decreased to limit the possible backlog of incom-
228 231 ing data. The maximum buffer size for UDP is determined by
229 232 the value of the ndd variable udp_max_buf. The maximum
230 233 buffer size for TCP is determined the value of the ndd vari-
231 234 able tcp_max_buf. Use the ndd(1M) utility to determine the
232 235 current default values. See the Solaris Tunable Parameters
233 236 Reference Manual for information on setting the values of
234 237 udp_max_buf and tcp_max_buf. At present, lowering SO_RCVBUF
235 238 on a TCP connection after it has been established has no
236 239 effect.
237 240
238 241
239 242 By default, delayed errors (such as ICMP port unreachable
240 243 packets) are returned only for connected datagram sockets.
241 244 The SO_DGRAM_ERRIND option makes it possible to receive
242 245 errors for datagram sockets that are not connected. When
243 246 this option is set, certain delayed errors received after
244 247 completion of a sendto() or sendmsg() operation will cause a
245 248 subsequent sendto() or sendmsg() operation using the same
246 249 destination address (to parameter) to fail with the
247 250 appropriate error. See send(3SOCKET).
248 251
249 252
250 253 If the SO_TIMESTAMP option is enabled on a SO_DGRAM or a
251 254 SO_RAW socket, the recvmsg(3XNET) call will return a times-
252 255 tamp in the native data format, corresponding to when the
253 256 datagram was received.
254 257
255 258
256 259
257 260
258 261 SunOS 5.11 Last change: 7 Aug 2008 4
259 262
260 263
261 264
262 265
263 266
264 267
265 268 Sockets Library Functions getsockopt(3SOCKET)
266 269
267 270
268 271
269 272 The SO_EXCLBIND option is used to enable or disable the
270 273 exclusive binding of a socket. It overrides the use of the
271 274 SO_REUSEADDR option to reuse an address on bind(3SOCKET).
272 275 The actual semantics of the SO_EXCLBIND option depend on the
273 276 underlying protocol. See tcp(7P) or udp(7P) for more infor-
274 277 mation.
275 278
276 279
277 280 The SO_TYPE and SO_ERROR options are used only with get-
278 281 sockopt(). The SO_TYPE option returns the type of the
279 282 socket, for example, SOCK_STREAM. It is useful for servers
280 283 that inherit sockets on startup. The SO_ERROR option
281 284 returns any pending error on the socket and clears the error
282 285 status. It may be used to check for asynchronous errors on
283 286 connected datagram sockets or for other asynchronous errors.
284 287
285 288
286 289 The SO_MAC_EXEMPT option is used to toggle socket behavior
287 290 with unlabeled peers. A socket that has this option enabled
288 291 can communicate with an unlabeled peer if it is in the glo-
289 292 bal zone or has a label that dominates the default label of
290 293 the peer. Otherwise, the socket must have a label that is
291 294 equal to the default label of the unlabeled peer. Calling
292 295 setsockopt() with this option returns an EACCES error if the
293 296 process lacks the NET_MAC_AWARE privilege or if the socket
294 297 is bound. The SO_MAC_EXEMPT option is available only when
295 298 the system is configured with Trusted Extensions.
296 299
297 300
298 301 The SO_ALLZONES option can be used to bypass zone boundaries
299 302 between shared-IP zones. Normally, the system prevents a
300 303 socket from being bound to an address that is not assigned
301 304 to the current zone. It also prevents a socket that is bound
302 305 to a wildcard address from receiving traffic for other
303 306 zones. However, some daemons which run in the global zone
304 307 might need to send and receive traffic using addresses that
305 308 belong to other shared-IP zones. If set before a socket is
306 309 bound, SO_ALLZONES causes the socket to ignore zone boun-
307 310 daries between shared-IP zones and permits the socket to be
308 311 bound to any address assigned to the shared-IP zones. If the
309 312 socket is bound to a wildcard address, it receives traffic
310 313 intended for all shared-IP zones and behaves as if an
311 314 equivalent socket were bound in each active shared-IP zone.
312 315 Applications that use the SO_ALLZONES option to initiate
313 316 connections or send datagram traffic should specify the
314 317 source address for outbound traffic by binding to a specific
315 318 address. There is no effect from setting this option in an
316 319 exclusive-IP zone. Setting this option requires the
317 320 sys_net_config privilege. See zones(5).
318 321
319 322 RETURN VALUES
320 323
321 324
322 325
323 326
324 327 SunOS 5.11 Last change: 7 Aug 2008 5
325 328
326 329
327 330
328 331
329 332
330 333
331 334 Sockets Library Functions getsockopt(3SOCKET)
332 335
333 336
334 337
335 338 If successful, getsockopt() and setsockopt() return 0. Oth-
336 339 erwise, the functions return -1 and set errno to indicate
337 340 the error.
338 341
339 342 ERRORS
340 343 The getsockopt() and setsockopt() calls succeed unless:
341 344
342 345 EBADF The argument s is not a valid file descrip-
343 346 tor.
344 347
345 348
346 349 ENOMEM There was insufficient memory available for
347 350 the operation to complete.
348 351
349 352
350 353 ENOPROTOOPT The option is unknown at the level indi-
351 354 cated.
352 355
353 356
354 357 ENOSR There were insufficient STREAMS resources
355 358 available for the operation to complete.
356 359
357 360
358 361 ENOTSOCK The argument s is not a socket.
359 362
360 363
361 364 ENOBUFS SO_SNDBUF or SO_RCVBUF exceeds a system
362 365 limit.
363 366
364 367
365 368 EINVAL Invalid length for IP_OPTIONS.
366 369
367 370
368 371 EHOSTUNREACH Invalid address for IP_MULTICAST_IF.
369 372
370 373
371 374 EINVAL Not a multicast address for
372 375 IP_ADD_MEMBERSHIP and IP_DROP_MEMBERSHIP.
373 376
374 377
375 378 EADDRNOTAVAIL Bad interface address for IP_ADD_MEMBERSHIP
376 379 and IP_DROP_MEMBERSHIP.
377 380
378 381
379 382 EADDRINUSE Address already joined for
380 383 IP_ADD_MEMBERSHIP.
381 384
382 385
383 386 ENOENT Address not joined for IP_DROP_MEMBERSHIP.
384 387
385 388
386 389
387 390
388 391
389 392
390 393 SunOS 5.11 Last change: 7 Aug 2008 6
391 394
392 395
393 396
394 397
395 398
396 399
397 400 Sockets Library Functions getsockopt(3SOCKET)
398 401
399 402
400 403
401 404 EPERM No permissions.
402 405
403 406
404 407 EACCES Permission denied.
405 408
406 409
407 410 EINVAL The specified option is invalid at the
408 411 specified socket level, or the socket has
409 412 been shut down.
410 413
411 414
412 415 ATTRIBUTES
413 416 See attributes(5) for descriptions of the following attri-
414 417 butes:
415 418
416 419
417 420
418 421 ____________________________________________________________
419 422 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
420 423 |_____________________________|_____________________________|
421 424 | MT-Level | Safe |
422 425 |_____________________________|_____________________________|
423 426
424 427
425 428 SEE ALSO
426 429 ndd(1M), close(2), ioctl(2), read(2), bind(3SOCKET),
427 430 getprotobyname(3SOCKET), recv(3SOCKET), recvmsg(3XNET),
428 431 send(3SOCKET), socket(3SOCKET), socket.h(3HEAD), attri-
429 432 butes(5), zones(5), tcp(7P), udp(7P)
430 433
431 434
432 435 Solaris Tunable Parameters Reference Manual
433 436
434 437
435 438
436 439
437 440
438 441
439 442
440 443
441 444
442 445
443 446
444 447
445 448
446 449
447 450
448 451
449 452
450 453
451 454
452 455
453 456
454 457
455 458
456 459 SunOS 5.11 Last change: 7 Aug 2008 7
457 460
458 461
459 462
|
↓ open down ↓ |
414 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX