| 1 |
'\" t |
| 2 |
.\" Copyright 1999, Andi Kleen <[email protected]> |
| 3 |
.\" Copyright 1999, Matthew Wilcox <[email protected]> |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: Linux-man-pages-1-para |
| 7 |
.\" |
| 8 |
.\" FIXME |
| 9 |
.\" The following are not yet documented: |
| 10 |
.\" |
| 11 |
.\" SO_PEERNAME (2.4?) |
| 12 |
.\" get only |
| 13 |
.\" Seems to do something similar to getpeername(), but then |
| 14 |
.\" why is it necessary / how does it differ? |
| 15 |
.\" |
| 16 |
.\" SO_TIMESTAMPING (2.6.30) |
| 17 |
.\" Documentation/networking/timestamping.rst |
| 18 |
.\" commit cb9eff097831007afb30d64373f29d99825d0068 |
| 19 |
.\" Author: Patrick Ohly <[email protected]> |
| 20 |
.\" |
| 21 |
.\" SO_WIFI_STATUS (3.3) |
| 22 |
.\" commit 6e3e939f3b1bf8534b32ad09ff199d88800835a0 |
| 23 |
.\" Author: Johannes Berg <[email protected]> |
| 24 |
.\" Also: SCM_WIFI_STATUS |
| 25 |
.\" |
| 26 |
.\" SO_NOFCS (3.4) |
| 27 |
.\" commit 3bdc0eba0b8b47797f4a76e377dd8360f317450f |
| 28 |
.\" Author: Ben Greear <[email protected]> |
| 29 |
.\" |
| 30 |
.\" SO_GET_FILTER (3.8) |
| 31 |
.\" commit a8fc92778080c845eaadc369a0ecf5699a03bef0 |
| 32 |
.\" Author: Pavel Emelyanov <[email protected]> |
| 33 |
.\" |
| 34 |
.\" SO_MAX_PACING_RATE (3.13) |
| 35 |
.\" commit 62748f32d501f5d3712a7c372bbb92abc7c62bc7 |
| 36 |
.\" Author: Eric Dumazet <[email protected]> |
| 37 |
.\" |
| 38 |
.\" SO_BPF_EXTENSIONS (3.14) |
| 39 |
.\" commit ea02f9411d9faa3553ed09ce0ec9f00ceae9885e |
| 40 |
.\" Author: Michal Sekletar <[email protected]> |
| 41 |
.\" |
| 42 |
.TH socket 7 2026-02-08 "Linux man-pages 6.18" |
| 43 |
.SH NAME |
| 44 |
socket \- Linux socket interface |
| 45 |
.SH SYNOPSIS |
| 46 |
.nf |
| 47 |
.B #include <sys/socket.h> |
| 48 |
.P |
| 49 |
.IB sockfd " = socket(int " socket_family ", int " socket_type ", int " protocol ); |
| 50 |
.fi |
| 51 |
.SH DESCRIPTION |
| 52 |
This manual page describes the Linux networking socket layer user |
| 53 |
interface. |
| 54 |
The BSD compatible sockets |
| 55 |
are the uniform interface |
| 56 |
between the user process and the network protocol stacks in the kernel. |
| 57 |
The protocol modules are grouped into |
| 58 |
.I protocol families |
| 59 |
such as |
| 60 |
.BR AF_INET ", " AF_IPX ", and " AF_PACKET , |
| 61 |
and |
| 62 |
.I socket types |
| 63 |
such as |
| 64 |
.B SOCK_STREAM |
| 65 |
or |
| 66 |
.BR SOCK_DGRAM . |
| 67 |
See |
| 68 |
.BR socket (2) |
| 69 |
for more information on families and types. |
| 70 |
.SS Socket-layer functions |
| 71 |
These functions are used by the user process to send or receive packets |
| 72 |
and to do other socket operations. |
| 73 |
For more information, see their respective manual pages. |
| 74 |
.P |
| 75 |
.BR socket (2) |
| 76 |
creates a socket, |
| 77 |
.BR connect (2) |
| 78 |
connects a socket to a remote socket address, |
| 79 |
the |
| 80 |
.BR bind (2) |
| 81 |
function binds a socket to a local socket address, |
| 82 |
.BR listen (2) |
| 83 |
tells the socket that new connections shall be accepted, and |
| 84 |
.BR accept (2) |
| 85 |
is used to get a new socket with a new incoming connection. |
| 86 |
.BR socketpair (2) |
| 87 |
returns two connected anonymous sockets (implemented only for a few |
| 88 |
local families like |
| 89 |
.BR AF_UNIX ) |
| 90 |
.P |
| 91 |
.BR send (2), |
| 92 |
.BR sendto (2), |
| 93 |
and |
| 94 |
.BR sendmsg (2) |
| 95 |
send data over a socket, and |
| 96 |
.BR recv (2), |
| 97 |
.BR recvfrom (2), |
| 98 |
.BR recvmsg (2) |
| 99 |
receive data from a socket. |
| 100 |
.BR poll (2) |
| 101 |
and |
| 102 |
.BR select (2) |
| 103 |
wait for arriving data or a readiness to send data. |
| 104 |
In addition, the standard I/O operations like |
| 105 |
.BR write (2), |
| 106 |
.BR writev (2), |
| 107 |
.BR sendfile (2), |
| 108 |
.BR read (2), |
| 109 |
and |
| 110 |
.BR readv (2) |
| 111 |
can be used to read and write data. |
| 112 |
.P |
| 113 |
.BR getsockname (2) |
| 114 |
returns the local socket address and |
| 115 |
.BR getpeername (2) |
| 116 |
returns the remote socket address. |
| 117 |
.BR getsockopt (2) |
| 118 |
and |
| 119 |
.BR setsockopt (2) |
| 120 |
are used to set or get socket layer or protocol options. |
| 121 |
.BR ioctl (2) |
| 122 |
can be used to set or read some other options. |
| 123 |
.P |
| 124 |
.BR close (2) |
| 125 |
is used to close a socket. |
| 126 |
.BR shutdown (2) |
| 127 |
closes parts of a full-duplex socket connection. |
| 128 |
.P |
| 129 |
Seeking, or calling |
| 130 |
.BR pread (2) |
| 131 |
or |
| 132 |
.BR pwrite (2) |
| 133 |
with a nonzero position is not supported on sockets. |
| 134 |
.P |
| 135 |
It is possible to do nonblocking I/O on sockets by setting the |
| 136 |
.B O_NONBLOCK |
| 137 |
flag on a socket file descriptor using |
| 138 |
.BR fcntl (2). |
| 139 |
Then all operations that would block will (usually) |
| 140 |
return with |
| 141 |
.B EAGAIN |
| 142 |
(operation should be retried later); |
| 143 |
.BR connect (2) |
| 144 |
will return |
| 145 |
.B EINPROGRESS |
| 146 |
error. |
| 147 |
The user can then wait for various events via |
| 148 |
.BR poll (2) |
| 149 |
or |
| 150 |
.BR select (2). |
| 151 |
.TS |
| 152 |
tab(:) allbox; |
| 153 |
c s s |
| 154 |
l l lx. |
| 155 |
I/O events |
| 156 |
Event:Poll flag:Occurrence |
| 157 |
Read:POLLIN:T{ |
| 158 |
New data arrived. |
| 159 |
T} |
| 160 |
Read:POLLIN:T{ |
| 161 |
A connection setup has been completed |
| 162 |
(for connection-oriented sockets) |
| 163 |
T} |
| 164 |
Read:POLLHUP:T{ |
| 165 |
A disconnection request has been initiated by the other end. |
| 166 |
T} |
| 167 |
Read:POLLHUP:T{ |
| 168 |
A connection is broken (only for connection-oriented protocols). |
| 169 |
When the socket is written |
| 170 |
.B SIGPIPE |
| 171 |
is also sent. |
| 172 |
T} |
| 173 |
Write:POLLOUT:T{ |
| 174 |
Socket has enough send buffer space for writing new data. |
| 175 |
T} |
| 176 |
Read/Write:T{ |
| 177 |
POLLIN | |
| 178 |
.br |
| 179 |
POLLOUT |
| 180 |
T}:T{ |
| 181 |
An outgoing |
| 182 |
.BR connect (2) |
| 183 |
finished. |
| 184 |
T} |
| 185 |
Read/Write:POLLERR:T{ |
| 186 |
An asynchronous error occurred. |
| 187 |
T} |
| 188 |
Read/Write:POLLHUP:T{ |
| 189 |
The other end has shut down one direction. |
| 190 |
T} |
| 191 |
Exception:POLLPRI:T{ |
| 192 |
Urgent data arrived. |
| 193 |
.B SIGURG |
| 194 |
is sent then. |
| 195 |
T} |
| 196 |
.\" FIXME . The following is not true currently: |
| 197 |
.\" It is no I/O event when the connection |
| 198 |
.\" is broken from the local end using |
| 199 |
.\" .BR shutdown (2) |
| 200 |
.\" or |
| 201 |
.\" .BR close (2). |
| 202 |
.TE |
| 203 |
.P |
| 204 |
An alternative to |
| 205 |
.BR poll (2) |
| 206 |
and |
| 207 |
.BR select (2) |
| 208 |
is to let the kernel inform the application about events |
| 209 |
via a |
| 210 |
.B SIGIO |
| 211 |
signal. |
| 212 |
For that the |
| 213 |
.B O_ASYNC |
| 214 |
flag must be set on a socket file descriptor via |
| 215 |
.BR fcntl (2) |
| 216 |
and a valid signal handler for |
| 217 |
.B SIGIO |
| 218 |
must be installed via |
| 219 |
.BR sigaction (2). |
| 220 |
See the |
| 221 |
.I Signals |
| 222 |
discussion below. |
| 223 |
.SS Socket address structures |
| 224 |
Each socket domain has its own format for socket addresses, |
| 225 |
with a domain-specific address structure. |
| 226 |
Each of these structures begins with an |
| 227 |
integer "family" field (typed as |
| 228 |
.IR sa_family_t ) |
| 229 |
that indicates the type of the address structure. |
| 230 |
This allows |
| 231 |
the various system calls (e.g., |
| 232 |
.BR connect (2), |
| 233 |
.BR bind (2), |
| 234 |
.BR accept (2), |
| 235 |
.BR getsockname (2), |
| 236 |
.BR getpeername (2)), |
| 237 |
which are generic to all socket domains, |
| 238 |
to determine the domain of a particular socket address. |
| 239 |
.P |
| 240 |
To allow any type of socket address to be passed to |
| 241 |
interfaces in the sockets API, |
| 242 |
the type |
| 243 |
.I struct sockaddr |
| 244 |
is defined. |
| 245 |
The purpose of this type is purely to allow casting of |
| 246 |
domain-specific socket address types to a "generic" type, |
| 247 |
so as to avoid compiler warnings about type mismatches in |
| 248 |
calls to the sockets API. |
| 249 |
.P |
| 250 |
In addition, the sockets API provides the data type |
| 251 |
.IR "struct sockaddr_storage". |
| 252 |
This type is suitable to accommodate |
| 253 |
all supported domain-specific socket address structures; |
| 254 |
it is large enough and is aligned properly. |
| 255 |
(In particular, it is large enough to hold |
| 256 |
IPv6 socket addresses.) |
| 257 |
The structure includes the following field, which can be used to identify |
| 258 |
the type of socket address actually stored in the structure: |
| 259 |
.P |
| 260 |
.in +4n |
| 261 |
.EX |
| 262 |
sa_family_t ss_family; |
| 263 |
.EE |
| 264 |
.in |
| 265 |
.P |
| 266 |
The |
| 267 |
.I sockaddr_storage |
| 268 |
structure is useful in programs that must handle socket addresses |
| 269 |
in a generic way |
| 270 |
(e.g., programs that must deal with both IPv4 and IPv6 socket addresses). |
| 271 |
.SS Socket options |
| 272 |
The socket options listed below can be set by using |
| 273 |
.BR setsockopt (2) |
| 274 |
and read with |
| 275 |
.BR getsockopt (2) |
| 276 |
with the socket level set to |
| 277 |
.B SOL_SOCKET |
| 278 |
for all sockets. |
| 279 |
Unless otherwise noted, |
| 280 |
.I optval |
| 281 |
is a pointer to an |
| 282 |
.IR int . |
| 283 |
.\" FIXME . |
| 284 |
.\" In the list below, the text used to describe argument types |
| 285 |
.\" for each socket option should be more consistent |
| 286 |
.\" |
| 287 |
.\" SO_ACCEPTCONN is in POSIX.1-2001, and its origin is explained in |
| 288 |
.\" W R Stevens, UNPv1 |
| 289 |
.TP |
| 290 |
.B SO_ACCEPTCONN |
| 291 |
Returns a value indicating whether or not this socket has been marked |
| 292 |
to accept connections with |
| 293 |
.BR listen (2). |
| 294 |
The value 0 indicates that this is not a listening socket, |
| 295 |
the value 1 indicates that this is a listening socket. |
| 296 |
This socket option is read-only. |
| 297 |
.TP |
| 298 |
.BR SO_ATTACH_FILTER " (since Linux 2.2)" |
| 299 |
.TQ |
| 300 |
.BR SO_ATTACH_BPF " (since Linux 3.19)" |
| 301 |
Attach a classic BPF |
| 302 |
.RB ( SO_ATTACH_FILTER ) |
| 303 |
or an extended BPF |
| 304 |
.RB ( SO_ATTACH_BPF ) |
| 305 |
program to the socket for use as a filter of incoming packets. |
| 306 |
A packet will be dropped if the filter program returns zero. |
| 307 |
If the filter program returns a |
| 308 |
nonzero value which is less than the packet's data size, |
| 309 |
the packet will be truncated to the size returned. |
| 310 |
If the value returned by the filter is greater than or equal to the |
| 311 |
packet's data size, the packet is allowed to proceed unmodified. |
| 312 |
.IP |
| 313 |
The argument for |
| 314 |
.B SO_ATTACH_FILTER |
| 315 |
is a |
| 316 |
.I sock_fprog |
| 317 |
structure, defined in |
| 318 |
.IR <linux/filter.h> : |
| 319 |
.IP |
| 320 |
.in +4n |
| 321 |
.EX |
| 322 |
struct sock_fprog { |
| 323 |
unsigned short len; |
| 324 |
struct sock_filter *filter; |
| 325 |
}; |
| 326 |
.EE |
| 327 |
.in |
| 328 |
.IP |
| 329 |
The argument for |
| 330 |
.B SO_ATTACH_BPF |
| 331 |
is a file descriptor returned by the |
| 332 |
.BR bpf (2) |
| 333 |
system call and must refer to a program of type |
| 334 |
.BR BPF_PROG_TYPE_SOCKET_FILTER . |
| 335 |
.IP |
| 336 |
These options may be set multiple times for a given socket, |
| 337 |
each time replacing the previous filter program. |
| 338 |
The classic and extended versions may be called on the same socket, |
| 339 |
but the previous filter will always be replaced such that a socket |
| 340 |
never has more than one filter defined. |
| 341 |
.IP |
| 342 |
Both classic and extended BPF are explained in the kernel source file |
| 343 |
.I Documentation/networking/filter.rst |
| 344 |
.TP |
| 345 |
.B SO_ATTACH_REUSEPORT_CBPF |
| 346 |
.TQ |
| 347 |
.B SO_ATTACH_REUSEPORT_EBPF |
| 348 |
For use with the |
| 349 |
.B SO_REUSEPORT |
| 350 |
option, these options allow the user to set a classic BPF |
| 351 |
.RB ( SO_ATTACH_REUSEPORT_CBPF ) |
| 352 |
or an extended BPF |
| 353 |
.RB ( SO_ATTACH_REUSEPORT_EBPF ) |
| 354 |
program which defines how packets are assigned to |
| 355 |
the sockets in the reuseport group (that is, all sockets which have |
| 356 |
.B SO_REUSEPORT |
| 357 |
set and are using the same local address to receive packets). |
| 358 |
.IP |
| 359 |
The classic BPF program must return an index between 0 and N\-1 representing |
| 360 |
the socket which should receive the packet |
| 361 |
(where N is the number of sockets in the group). |
| 362 |
If the BPF program returns an invalid index, |
| 363 |
socket selection will fall back to the plain |
| 364 |
.B SO_REUSEPORT |
| 365 |
mechanism. |
| 366 |
.IP |
| 367 |
Sockets are numbered in the order in which they are added to the group |
| 368 |
(that is, the order of |
| 369 |
.BR bind (2) |
| 370 |
calls for UDP sockets or the order of |
| 371 |
.BR listen (2) |
| 372 |
calls for TCP sockets). |
| 373 |
.IP |
| 374 |
The extended BPF program can be of two types: |
| 375 |
.RS |
| 376 |
.TP |
| 377 |
.B BPF_PROG_TYPE_SOCKET_FILTER |
| 378 |
In this case, |
| 379 |
the extended BPF program must return an index between 0 and N\-1, |
| 380 |
like a classic BPF program. |
| 381 |
.TP |
| 382 |
.BR BPF_PROG_TYPE_SK_REUSEPORT " (since Linux 4.19)" |
| 383 |
In this case, |
| 384 |
it must return an action |
| 385 |
.RB ( SK_PASS |
| 386 |
or |
| 387 |
.BR SK_DROP ) |
| 388 |
and the |
| 389 |
.B bpf_sk_select_reuseport |
| 390 |
helper can be used to select the socket which should receive the packet. |
| 391 |
.RE |
| 392 |
.IP |
| 393 |
New sockets added to a reuseport group will inherit the BPF program. |
| 394 |
When a socket is removed from a reuseport group (via |
| 395 |
.BR close (2)), |
| 396 |
the last socket in the group will be moved into the closed socket's |
| 397 |
position. |
| 398 |
.IP |
| 399 |
These options may be set repeatedly at any time on any socket in the group |
| 400 |
to replace the current BPF program used by all sockets in the group. |
| 401 |
.IP |
| 402 |
.B SO_ATTACH_REUSEPORT_CBPF |
| 403 |
takes the same argument type as |
| 404 |
.B SO_ATTACH_FILTER |
| 405 |
and |
| 406 |
.B SO_ATTACH_REUSEPORT_EBPF |
| 407 |
takes the same argument type as |
| 408 |
.BR SO_ATTACH_BPF . |
| 409 |
.IP |
| 410 |
UDP support for this feature is available since Linux 4.5; |
| 411 |
TCP support is available since Linux 4.6. |
| 412 |
.TP |
| 413 |
.B SO_BINDTODEVICE |
| 414 |
Bind this socket to a particular device like \[lq]eth0\[rq], |
| 415 |
as specified in the passed interface name. |
| 416 |
If the |
| 417 |
name is an empty string or the option size is zero, the socket device |
| 418 |
binding is removed. |
| 419 |
The passed option is a variable-size null-terminated |
| 420 |
interface name string with the maximum size of |
| 421 |
.BR IFNAMSIZ . |
| 422 |
If a socket is bound to an interface, |
| 423 |
only packets received from that particular interface are processed by the |
| 424 |
socket. |
| 425 |
Note that this works only for some socket types, particularly |
| 426 |
.B AF_INET |
| 427 |
sockets. |
| 428 |
It is not supported for packet sockets (use normal |
| 429 |
.BR bind (2) |
| 430 |
there). |
| 431 |
.IP |
| 432 |
Before Linux 3.8, |
| 433 |
this socket option could be set, but could not retrieved with |
| 434 |
.BR getsockopt (2). |
| 435 |
Since Linux 3.8, it is readable. |
| 436 |
The |
| 437 |
.I optlen |
| 438 |
argument should contain the buffer size available |
| 439 |
to receive the device name and is recommended to be |
| 440 |
.B IFNAMSIZ |
| 441 |
bytes. |
| 442 |
The real device name length is reported back in the |
| 443 |
.I optlen |
| 444 |
argument. |
| 445 |
.TP |
| 446 |
.B SO_BROADCAST |
| 447 |
Set or get the broadcast flag. |
| 448 |
When enabled, datagram sockets are allowed to send |
| 449 |
packets to a broadcast address. |
| 450 |
This option has no effect on stream-oriented sockets. |
| 451 |
.TP |
| 452 |
.B SO_BSDCOMPAT |
| 453 |
Enable BSD bug-to-bug compatibility. |
| 454 |
This is used by the UDP protocol module in Linux 2.0 and 2.2. |
| 455 |
If enabled, ICMP errors received for a UDP socket will not be passed |
| 456 |
to the user program. |
| 457 |
In later kernel versions, support for this option has been phased out: |
| 458 |
Linux 2.4 silently ignores it, and Linux 2.6 generates a kernel warning |
| 459 |
(printk()) if a program uses this option. |
| 460 |
Linux 2.0 also enabled BSD bug-to-bug compatibility |
| 461 |
options (random header changing, skipping of the broadcast flag) for raw |
| 462 |
sockets with this option, but that was removed in Linux 2.2. |
| 463 |
.TP |
| 464 |
.B SO_DEBUG |
| 465 |
Enable socket debugging. |
| 466 |
Allowed only for processes with the |
| 467 |
.B CAP_NET_ADMIN |
| 468 |
capability or an effective user ID of 0. |
| 469 |
.TP |
| 470 |
.BR SO_DETACH_FILTER " (since Linux 2.2)" |
| 471 |
.TQ |
| 472 |
.BR SO_DETACH_BPF " (since Linux 3.19)" |
| 473 |
These two options, which are synonyms, |
| 474 |
may be used to remove the classic or extended BPF |
| 475 |
program attached to a socket with either |
| 476 |
.B SO_ATTACH_FILTER |
| 477 |
or |
| 478 |
.BR SO_ATTACH_BPF . |
| 479 |
The option value is ignored. |
| 480 |
.TP |
| 481 |
.BR SO_DOMAIN " (since Linux 2.6.32)" |
| 482 |
Retrieves the socket domain as an integer, returning a value such as |
| 483 |
.BR AF_INET6 . |
| 484 |
See |
| 485 |
.BR socket (2) |
| 486 |
for details. |
| 487 |
This socket option is read-only. |
| 488 |
.TP |
| 489 |
.B SO_ERROR |
| 490 |
Get and clear the pending socket error. |
| 491 |
This socket option is read-only. |
| 492 |
Expects an integer. |
| 493 |
.TP |
| 494 |
.B SO_DONTROUTE |
| 495 |
Don't send via a gateway, send only to directly connected hosts. |
| 496 |
The same effect can be achieved by setting the |
| 497 |
.B MSG_DONTROUTE |
| 498 |
flag on a socket |
| 499 |
.BR send (2) |
| 500 |
operation. |
| 501 |
Expects an integer boolean flag. |
| 502 |
.TP |
| 503 |
.BR SO_INCOMING_CPU " (gettable since Linux 3.19, settable since Linux 4.4)" |
| 504 |
.\" getsockopt 2c8c56e15df3d4c2af3d656e44feb18789f75837 |
| 505 |
.\" setsockopt 70da268b569d32a9fddeea85dc18043de9d89f89 |
| 506 |
Sets or gets the CPU affinity of a socket. |
| 507 |
Expects an integer flag. |
| 508 |
.IP |
| 509 |
.in +4n |
| 510 |
.EX |
| 511 |
int cpu = 1; |
| 512 |
setsockopt(fd, SOL_SOCKET, SO_INCOMING_CPU, &cpu, |
| 513 |
sizeof(cpu)); |
| 514 |
.EE |
| 515 |
.in |
| 516 |
.IP |
| 517 |
Because all of the packets for a single stream |
| 518 |
(i.e., all packets for the same 4-tuple) |
| 519 |
arrive on the single RX queue that is associated with a particular CPU, |
| 520 |
the typical use case is to employ one listening process per RX queue, |
| 521 |
with the incoming flow being handled by a listener |
| 522 |
on the same CPU that is handling the RX queue. |
| 523 |
This provides optimal NUMA behavior and keeps CPU caches hot. |
| 524 |
.\" |
| 525 |
.\" From an email conversation with Eric Dumazet: |
| 526 |
.\" >> Note that setting the option is not supported if SO_REUSEPORT is used. |
| 527 |
.\" > |
| 528 |
.\" > Please define "not supported". Does this yield an API diagnostic? |
| 529 |
.\" > If so, what is it? |
| 530 |
.\" > |
| 531 |
.\" >> Socket will be selected from an array, either by a hash or BPF program |
| 532 |
.\" >> that has no access to this information. |
| 533 |
.\" > |
| 534 |
.\" > Sorry -- I'm lost here. How does this comment relate to the proposed |
| 535 |
.\" > man page text above? |
| 536 |
.\" |
| 537 |
.\" Simply that : |
| 538 |
.\" |
| 539 |
.\" If an application uses both SO_INCOMING_CPU and SO_REUSEPORT, then |
| 540 |
.\" SO_REUSEPORT logic, selecting the socket to receive the packet, ignores |
| 541 |
.\" SO_INCOMING_CPU setting. |
| 542 |
.TP |
| 543 |
.BR SO_INCOMING_NAPI_ID " (gettable since Linux 4.12)" |
| 544 |
.\" getsockopt 6d4339028b350efbf87c61e6d9e113e5373545c9 |
| 545 |
Returns a system-level unique ID called NAPI ID that is associated |
| 546 |
with a RX queue on which the last packet associated with that |
| 547 |
socket is received. |
| 548 |
.IP |
| 549 |
This can be used by an application to split the incoming flows among worker |
| 550 |
threads based on the RX queue on which the packets associated with the |
| 551 |
flows are received. |
| 552 |
It allows each worker thread to be associated with |
| 553 |
a NIC HW receive queue and service all the connection |
| 554 |
requests received on that RX queue. |
| 555 |
This mapping between an app thread and |
| 556 |
a HW NIC queue streamlines the |
| 557 |
flow of data from the NIC to the application. |
| 558 |
.TP |
| 559 |
.B SO_KEEPALIVE |
| 560 |
Enable sending of keep-alive messages on connection-oriented sockets. |
| 561 |
Expects an integer boolean flag. |
| 562 |
.TP |
| 563 |
.B SO_LINGER |
| 564 |
Sets or gets the |
| 565 |
.B SO_LINGER |
| 566 |
option. |
| 567 |
The argument is a |
| 568 |
.I linger |
| 569 |
structure. |
| 570 |
.IP |
| 571 |
.in +4n |
| 572 |
.EX |
| 573 |
struct linger { |
| 574 |
int l_onoff; /* linger active */ |
| 575 |
int l_linger; /* how many seconds to linger for */ |
| 576 |
}; |
| 577 |
.EE |
| 578 |
.in |
| 579 |
.IP |
| 580 |
When enabled, a |
| 581 |
.BR close (2) |
| 582 |
or |
| 583 |
.BR shutdown (2) |
| 584 |
will not return until all queued messages for the socket have been |
| 585 |
successfully sent or the linger timeout has been reached. |
| 586 |
Otherwise, |
| 587 |
the call returns immediately and the closing is done in the background. |
| 588 |
When the socket is closed as part of |
| 589 |
.BR exit (2), |
| 590 |
it always lingers in the background. |
| 591 |
.TP |
| 592 |
.B SO_LOCK_FILTER |
| 593 |
.\" commit d59577b6ffd313d0ab3be39cb1ab47e29bdc9182 |
| 594 |
When set, this option will prevent |
| 595 |
changing the filters associated with the socket. |
| 596 |
These filters include any set using the socket options |
| 597 |
.BR SO_ATTACH_FILTER , |
| 598 |
.BR SO_ATTACH_BPF , |
| 599 |
.BR SO_ATTACH_REUSEPORT_CBPF , |
| 600 |
and |
| 601 |
.BR SO_ATTACH_REUSEPORT_EBPF . |
| 602 |
.IP |
| 603 |
The typical use case is for a privileged process to set up a raw socket |
| 604 |
(an operation that requires the |
| 605 |
.B CAP_NET_RAW |
| 606 |
capability), apply a restrictive filter, set the |
| 607 |
.B SO_LOCK_FILTER |
| 608 |
option, |
| 609 |
and then either drop its privileges or pass the socket file descriptor |
| 610 |
to an unprivileged process via a UNIX domain socket. |
| 611 |
.IP |
| 612 |
Once the |
| 613 |
.B SO_LOCK_FILTER |
| 614 |
option has been enabled, attempts to change or remove the filter |
| 615 |
attached to a socket, or to disable the |
| 616 |
.B SO_LOCK_FILTER |
| 617 |
option will fail with the error |
| 618 |
.BR EPERM . |
| 619 |
.TP |
| 620 |
.BR SO_MARK " (since Linux 2.6.25)" |
| 621 |
.\" commit 4a19ec5800fc3bb64e2d87c4d9fdd9e636086fe0 |
| 622 |
.\" and 914a9ab386a288d0f22252fc268ecbc048cdcbd5 |
| 623 |
Set the mark for each packet sent through this socket |
| 624 |
(similar to the netfilter MARK target but socket-based). |
| 625 |
Changing the mark can be used for mark-based |
| 626 |
routing without netfilter or for packet filtering. |
| 627 |
Setting this option requires the |
| 628 |
.B CAP_NET_ADMIN |
| 629 |
or |
| 630 |
.B CAP_NET_RAW |
| 631 |
(since Linux 5.17) capability. |
| 632 |
.TP |
| 633 |
.B SO_OOBINLINE |
| 634 |
If this option is enabled, |
| 635 |
out-of-band data is directly placed into the receive data stream. |
| 636 |
Otherwise, out-of-band data is passed only when the |
| 637 |
.B MSG_OOB |
| 638 |
flag is set during receiving. |
| 639 |
.\" don't document it because it can do too much harm. |
| 640 |
.\".B SO_NO_CHECK |
| 641 |
.\" The kernel has support for the SO_NO_CHECK socket |
| 642 |
.\" option (boolean: 0 == default, calculate checksum on xmit, |
| 643 |
.\" 1 == do not calculate checksum on xmit). |
| 644 |
.\" Additional note from Andi Kleen on SO_NO_CHECK (2010-08-30) |
| 645 |
.\" On Linux UDP checksums are essentially free and there's no reason |
| 646 |
.\" to turn them off and it would disable another safety line. |
| 647 |
.\" That is why I didn't document the option. |
| 648 |
.TP |
| 649 |
.B SO_PASSCRED |
| 650 |
Enable or disable the receiving of the |
| 651 |
.B SCM_CREDENTIALS |
| 652 |
control message. |
| 653 |
For more information, see |
| 654 |
.BR unix (7). |
| 655 |
.TP |
| 656 |
.B SO_PASSSEC |
| 657 |
Enable or disable the receiving of the |
| 658 |
.B SCM_SECURITY |
| 659 |
control message. |
| 660 |
For more information, see |
| 661 |
.BR unix (7). |
| 662 |
.TP |
| 663 |
.BR SO_PEEK_OFF " (since Linux 3.4)" |
| 664 |
.\" commit ef64a54f6e558155b4f149bb10666b9e914b6c54 |
| 665 |
This option, which is currently supported only for |
| 666 |
.BR unix (7) |
| 667 |
sockets, sets the value of the "peek offset" for the |
| 668 |
.BR recv (2) |
| 669 |
system call when used with |
| 670 |
.B MSG_PEEK |
| 671 |
flag. |
| 672 |
.IP |
| 673 |
When this option is set to a negative value |
| 674 |
(it is set to \-1 for all new sockets), |
| 675 |
traditional behavior is provided: |
| 676 |
.BR recv (2) |
| 677 |
with the |
| 678 |
.B MSG_PEEK |
| 679 |
flag will peek data from the front of the queue. |
| 680 |
.IP |
| 681 |
When the option is set to a value greater than or equal to zero, |
| 682 |
then the next peek at data queued in the socket will occur at |
| 683 |
the byte offset specified by the option value. |
| 684 |
At the same time, the "peek offset" will be |
| 685 |
incremented by the number of bytes that were peeked from the queue, |
| 686 |
so that a subsequent peek will return the next data in the queue. |
| 687 |
.IP |
| 688 |
If data is removed from the front of the queue via a call to |
| 689 |
.BR recv (2) |
| 690 |
(or similar) without the |
| 691 |
.B MSG_PEEK |
| 692 |
flag, the "peek offset" will be decreased by the number of bytes removed. |
| 693 |
In other words, receiving data without the |
| 694 |
.B MSG_PEEK |
| 695 |
flag will cause the "peek offset" to be adjusted to maintain |
| 696 |
the correct relative position in the queued data, |
| 697 |
so that a subsequent peek will retrieve the data that would have been |
| 698 |
retrieved had the data not been removed. |
| 699 |
.IP |
| 700 |
For datagram sockets, if the "peek offset" points to the middle of a packet, |
| 701 |
the data returned will be marked with the |
| 702 |
.B MSG_TRUNC |
| 703 |
flag. |
| 704 |
.IP |
| 705 |
The following example serves to illustrate the use of |
| 706 |
.BR SO_PEEK_OFF . |
| 707 |
Suppose a stream socket has the following queued input data: |
| 708 |
.IP |
| 709 |
.in +4n |
| 710 |
.EX |
| 711 |
aabbccddeeff |
| 712 |
.EE |
| 713 |
.in |
| 714 |
.IP |
| 715 |
The following sequence of |
| 716 |
.BR recv (2) |
| 717 |
calls would have the effect noted in the comments: |
| 718 |
.IP |
| 719 |
.in +4n |
| 720 |
.EX |
| 721 |
int ov = 4; // Set peek offset to 4 |
| 722 |
setsockopt(fd, SOL_SOCKET, SO_PEEK_OFF, &ov, sizeof(ov)); |
| 723 |
\& |
| 724 |
recv(fd, buf, 2, MSG_PEEK); // Peeks "cc"; offset set to 6 |
| 725 |
recv(fd, buf, 2, MSG_PEEK); // Peeks "dd"; offset set to 8 |
| 726 |
recv(fd, buf, 2, 0); // Reads "aa"; offset set to 6 |
| 727 |
recv(fd, buf, 2, MSG_PEEK); // Peeks "ee"; offset set to 8 |
| 728 |
.EE |
| 729 |
.in |
| 730 |
.TP |
| 731 |
.B SO_PEERCRED |
| 732 |
Return the credentials of the peer process connected to this socket. |
| 733 |
For further details, see |
| 734 |
.BR unix (7). |
| 735 |
.TP |
| 736 |
.BR SO_PEERSEC (2const) |
| 737 |
.TP |
| 738 |
.B SO_PRIORITY |
| 739 |
Set the protocol-defined priority for all packets to be sent on |
| 740 |
this socket. |
| 741 |
Linux uses this value to order the networking queues: |
| 742 |
packets with a higher priority may be processed first depending |
| 743 |
on the selected device queueing discipline. |
| 744 |
.\" For |
| 745 |
.\" .BR ip (7), |
| 746 |
.\" this also sets the IP type-of-service (TOS) field for outgoing packets. |
| 747 |
Setting a priority outside the range 0 to 6 requires the |
| 748 |
.B CAP_NET_ADMIN |
| 749 |
capability. |
| 750 |
.TP |
| 751 |
.BR SO_PROTOCOL " (since Linux 2.6.32)" |
| 752 |
Retrieves the socket protocol as an integer, returning a value such as |
| 753 |
.BR IPPROTO_SCTP . |
| 754 |
See |
| 755 |
.BR socket (2) |
| 756 |
for details. |
| 757 |
This socket option is read-only. |
| 758 |
.TP |
| 759 |
.B SO_RCVBUF |
| 760 |
Sets or gets the maximum socket receive buffer in bytes. |
| 761 |
The kernel doubles this value (to allow space for bookkeeping overhead) |
| 762 |
when it is set using |
| 763 |
.\" Most (all?) other implementations do not do this -- MTK, Dec 05 |
| 764 |
.BR setsockopt (2), |
| 765 |
and this doubled value is returned by |
| 766 |
.BR getsockopt (2). |
| 767 |
.\" The following thread on LMKL is quite informative: |
| 768 |
.\" getsockopt/setsockopt with SO_RCVBUF and SO_SNDBUF "non-standard" behavior |
| 769 |
.\" 17 July 2012 |
| 770 |
.\" http://thread.gmane.org/gmane.linux.kernel/1328935 |
| 771 |
The default value is set by the |
| 772 |
.I /proc/sys/net/core/rmem_default |
| 773 |
file, and the maximum allowed value is set by the |
| 774 |
.I /proc/sys/net/core/rmem_max |
| 775 |
file. |
| 776 |
The minimum (doubled) value for this option is 256. |
| 777 |
.TP |
| 778 |
.BR SO_RCVBUFFORCE " (since Linux 2.6.14)" |
| 779 |
Using this socket option, a privileged |
| 780 |
.RB ( CAP_NET_ADMIN ) |
| 781 |
process can perform the same task as |
| 782 |
.BR SO_RCVBUF , |
| 783 |
but the |
| 784 |
.I rmem_max |
| 785 |
limit can be overridden. |
| 786 |
.TP |
| 787 |
.B SO_RCVLOWAT |
| 788 |
.TQ |
| 789 |
.B SO_SNDLOWAT |
| 790 |
Specify the minimum number of bytes in the buffer until the socket layer |
| 791 |
will pass the data to the protocol |
| 792 |
.RB ( SO_SNDLOWAT ) |
| 793 |
or the user on receiving |
| 794 |
.RB ( SO_RCVLOWAT ). |
| 795 |
These two values are initialized to 1. |
| 796 |
.B SO_SNDLOWAT |
| 797 |
is not changeable on Linux |
| 798 |
.RB ( setsockopt (2) |
| 799 |
fails with the error |
| 800 |
.BR ENOPROTOOPT ). |
| 801 |
.B SO_RCVLOWAT |
| 802 |
is changeable |
| 803 |
only since Linux 2.4. |
| 804 |
.IP |
| 805 |
Before Linux 2.6.28 |
| 806 |
.\" Tested on kernel 2.6.14 -- mtk, 30 Nov 05 |
| 807 |
.BR select (2), |
| 808 |
.BR poll (2), |
| 809 |
and |
| 810 |
.BR epoll (7) |
| 811 |
did not respect the |
| 812 |
.B SO_RCVLOWAT |
| 813 |
setting on Linux, |
| 814 |
and indicated a socket as readable when even a single byte of data |
| 815 |
was available. |
| 816 |
A subsequent read from the socket would then block until |
| 817 |
.B SO_RCVLOWAT |
| 818 |
bytes are available. |
| 819 |
Since Linux 2.6.28, |
| 820 |
.\" commit c7004482e8dcb7c3c72666395cfa98a216a4fb70 |
| 821 |
.BR select (2), |
| 822 |
.BR poll (2), |
| 823 |
and |
| 824 |
.BR epoll (7) |
| 825 |
indicate a socket as readable only if at least |
| 826 |
.B SO_RCVLOWAT |
| 827 |
bytes are available. |
| 828 |
.TP |
| 829 |
.B SO_RCVTIMEO |
| 830 |
.TQ |
| 831 |
.B SO_SNDTIMEO |
| 832 |
.\" Not implemented in Linux 2.0. |
| 833 |
.\" Implemented in Linux 2.1.11 for getsockopt: always return a zero struct. |
| 834 |
.\" Implemented in Linux 2.3.41 for setsockopt, and actually used. |
| 835 |
Specify the receiving or sending timeouts until reporting an error. |
| 836 |
The argument is a |
| 837 |
.IR "struct timeval" . |
| 838 |
If an input or output function blocks for this period of time, and |
| 839 |
data has been sent or received, the return value of that function |
| 840 |
will be the amount of data transferred; |
| 841 |
if no data has been transferred |
| 842 |
and the timeout has been reached, |
| 843 |
then \-1 is returned with |
| 844 |
.I errno |
| 845 |
set to |
| 846 |
.B EAGAIN |
| 847 |
or |
| 848 |
.BR EWOULDBLOCK , |
| 849 |
.\" in fact to EAGAIN |
| 850 |
or |
| 851 |
.B EINPROGRESS |
| 852 |
(for |
| 853 |
.BR connect (2)) |
| 854 |
just as if the socket was specified to be nonblocking. |
| 855 |
If the timeout is set to zero (the default), |
| 856 |
then the operation will never timeout. |
| 857 |
Timeouts only have effect for system calls that perform socket I/O (e.g., |
| 858 |
.BR accept (2), |
| 859 |
.BR connect (2), |
| 860 |
.BR read (2), |
| 861 |
.BR recvmsg (2), |
| 862 |
.BR send (2), |
| 863 |
.BR sendmsg (2)); |
| 864 |
timeouts have no effect for |
| 865 |
.BR select (2), |
| 866 |
.BR poll (2), |
| 867 |
.BR epoll_wait (2), |
| 868 |
and so on. |
| 869 |
.TP |
| 870 |
.B SO_REUSEADDR |
| 871 |
.\" commit c617f398edd4db2b8567a28e899a88f8f574798d |
| 872 |
.\" https://lwn.net/Articles/542629/ |
| 873 |
Indicates that the rules used in validating addresses supplied in a |
| 874 |
.BR bind (2) |
| 875 |
call should allow reuse of local addresses. |
| 876 |
For |
| 877 |
.B AF_INET |
| 878 |
sockets this |
| 879 |
means that a socket may bind, except when there |
| 880 |
is an active listening socket bound to the address. |
| 881 |
When the listening socket is bound to |
| 882 |
.B INADDR_ANY |
| 883 |
with a specific port then it is not possible |
| 884 |
to bind to this port for any local address. |
| 885 |
Argument is an integer boolean flag. |
| 886 |
.TP |
| 887 |
.BR SO_REUSEPORT " (since Linux 3.9)" |
| 888 |
Permits multiple |
| 889 |
.B AF_INET |
| 890 |
or |
| 891 |
.B AF_INET6 |
| 892 |
sockets to be bound to an identical socket address. |
| 893 |
This option must be set on each socket (including the first socket) |
| 894 |
prior to calling |
| 895 |
.BR bind (2) |
| 896 |
on the socket. |
| 897 |
To prevent port hijacking, |
| 898 |
all of the processes binding to the same address must have the same |
| 899 |
effective UID. |
| 900 |
This option can be employed with both TCP and UDP sockets. |
| 901 |
.IP |
| 902 |
For TCP sockets, this option allows |
| 903 |
.BR accept (2) |
| 904 |
load distribution in a multi-threaded server to be improved by |
| 905 |
using a distinct listener socket for each thread. |
| 906 |
This provides improved load distribution as compared |
| 907 |
to traditional techniques such using a single |
| 908 |
.BR accept (2)ing |
| 909 |
thread that distributes connections, |
| 910 |
or having multiple threads that compete to |
| 911 |
.BR accept (2) |
| 912 |
from the same socket. |
| 913 |
.IP |
| 914 |
For UDP sockets, |
| 915 |
the use of this option can provide better distribution |
| 916 |
of incoming datagrams to multiple processes (or threads) as compared |
| 917 |
to the traditional technique of having multiple processes |
| 918 |
compete to receive datagrams on the same socket. |
| 919 |
.TP |
| 920 |
.BR SO_RXQ_OVFL " (since Linux 2.6.33)" |
| 921 |
.\" commit 3b885787ea4112eaa80945999ea0901bf742707f |
| 922 |
Indicates that an unsigned 32-bit value ancillary message (cmsg) |
| 923 |
should be attached to received skbs indicating |
| 924 |
the number of packets dropped by the socket since its creation. |
| 925 |
.TP |
| 926 |
.BR SO_SELECT_ERR_QUEUE " (since Linux 3.10)" |
| 927 |
.\" commit 7d4c04fc170087119727119074e72445f2bb192b |
| 928 |
.\" Author: Keller, Jacob E <[email protected]> |
| 929 |
When this option is set on a socket, |
| 930 |
an error condition on a socket causes notification not only via the |
| 931 |
.I exceptfds |
| 932 |
set of |
| 933 |
.BR select (2). |
| 934 |
Similarly, |
| 935 |
.BR poll (2) |
| 936 |
also returns a |
| 937 |
.B POLLPRI |
| 938 |
whenever an |
| 939 |
.B POLLERR |
| 940 |
event is returned. |
| 941 |
.\" It does not affect wake up. |
| 942 |
.IP |
| 943 |
Background: this option was added when waking up on an error condition |
| 944 |
occurred only via the |
| 945 |
.I readfds |
| 946 |
and |
| 947 |
.I writefds |
| 948 |
sets of |
| 949 |
.BR select (2). |
| 950 |
The option was added to allow monitoring for error conditions via the |
| 951 |
.I exceptfds |
| 952 |
argument without simultaneously having to receive notifications (via |
| 953 |
.IR readfds ) |
| 954 |
for regular data that can be read from the socket. |
| 955 |
After changes in Linux 4.16, |
| 956 |
.\" commit 6e5d58fdc9bedd0255a8 |
| 957 |
.\" ("skbuff: Fix not waking applications when errors are enqueued") |
| 958 |
the use of this flag to achieve the desired notifications |
| 959 |
is no longer necessary. |
| 960 |
This option is nevertheless retained for backwards compatibility. |
| 961 |
.TP |
| 962 |
.B SO_SNDBUF |
| 963 |
Sets or gets the maximum socket send buffer in bytes. |
| 964 |
The kernel doubles this value (to allow space for bookkeeping overhead) |
| 965 |
when it is set using |
| 966 |
.\" Most (all?) other implementations do not do this -- MTK, Dec 05 |
| 967 |
.\" See also the comment to SO_RCVBUF (17 Jul 2012 LKML mail) |
| 968 |
.BR setsockopt (2), |
| 969 |
and this doubled value is returned by |
| 970 |
.BR getsockopt (2). |
| 971 |
The default value is set by the |
| 972 |
.I /proc/sys/net/core/wmem_default |
| 973 |
file and the maximum allowed value is set by the |
| 974 |
.I /proc/sys/net/core/wmem_max |
| 975 |
file. |
| 976 |
The minimum (doubled) value for this option is 2048. |
| 977 |
.TP |
| 978 |
.BR SO_SNDBUFFORCE " (since Linux 2.6.14)" |
| 979 |
Using this socket option, a privileged |
| 980 |
.RB ( CAP_NET_ADMIN ) |
| 981 |
process can perform the same task as |
| 982 |
.BR SO_SNDBUF , |
| 983 |
but the |
| 984 |
.I wmem_max |
| 985 |
limit can be overridden. |
| 986 |
.TP |
| 987 |
.B SO_TIMESTAMP |
| 988 |
Enable or disable the receiving of the |
| 989 |
.B SO_TIMESTAMP |
| 990 |
control message. |
| 991 |
The timestamp control message is sent with level |
| 992 |
.B SOL_SOCKET |
| 993 |
and a |
| 994 |
.I cmsg_type |
| 995 |
of |
| 996 |
.BR SCM_TIMESTAMP . |
| 997 |
The |
| 998 |
.I cmsg_data |
| 999 |
field is a |
| 1000 |
.I "struct timeval" |
| 1001 |
indicating the |
| 1002 |
reception time of the last packet passed to the user in this call. |
| 1003 |
See |
| 1004 |
.BR cmsg (3) |
| 1005 |
for details on control messages. |
| 1006 |
.TP |
| 1007 |
.BR SO_TIMESTAMPNS " (since Linux 2.6.22)" |
| 1008 |
.\" commit 92f37fd2ee805aa77925c1e64fd56088b46094fc |
| 1009 |
Enable or disable the receiving of the |
| 1010 |
.B SO_TIMESTAMPNS |
| 1011 |
control message. |
| 1012 |
The timestamp control message is sent with level |
| 1013 |
.B SOL_SOCKET |
| 1014 |
and a |
| 1015 |
.I cmsg_type |
| 1016 |
of |
| 1017 |
.BR SCM_TIMESTAMPNS . |
| 1018 |
The |
| 1019 |
.I cmsg_data |
| 1020 |
field is a |
| 1021 |
.I "struct timespec" |
| 1022 |
indicating the |
| 1023 |
reception time of the last packet passed to the user in this call. |
| 1024 |
The clock used for the timestamp is |
| 1025 |
.BR CLOCK_REALTIME . |
| 1026 |
See |
| 1027 |
.BR cmsg (3) |
| 1028 |
for details on control messages. |
| 1029 |
.IP |
| 1030 |
A socket cannot mix |
| 1031 |
.B SO_TIMESTAMP |
| 1032 |
and |
| 1033 |
.BR SO_TIMESTAMPNS : |
| 1034 |
the two modes are mutually exclusive. |
| 1035 |
.TP |
| 1036 |
.B SO_TYPE |
| 1037 |
Gets the socket type as an integer (e.g., |
| 1038 |
.BR SOCK_STREAM ). |
| 1039 |
This socket option is read-only. |
| 1040 |
.TP |
| 1041 |
.BR SO_BUSY_POLL " (since Linux 3.11)" |
| 1042 |
Sets the approximate time in microseconds to busy poll on a blocking receive |
| 1043 |
when there is no data. |
| 1044 |
Increasing this value requires |
| 1045 |
.BR CAP_NET_ADMIN . |
| 1046 |
The default for this option is controlled by the |
| 1047 |
.I /proc/sys/net/core/busy_read |
| 1048 |
file. |
| 1049 |
.IP |
| 1050 |
The value in the |
| 1051 |
.I /proc/sys/net/core/busy_poll |
| 1052 |
file determines how long |
| 1053 |
.BR select (2) |
| 1054 |
and |
| 1055 |
.BR poll (2) |
| 1056 |
will busy poll when they operate on sockets with |
| 1057 |
.B SO_BUSY_POLL |
| 1058 |
set and no events to report are found. |
| 1059 |
.IP |
| 1060 |
In both cases, |
| 1061 |
busy polling will only be done when the socket last received data |
| 1062 |
from a network device that supports this option. |
| 1063 |
.IP |
| 1064 |
While busy polling may improve latency of some applications, |
| 1065 |
care must be taken when using it since this will increase |
| 1066 |
both CPU utilization and power usage. |
| 1067 |
.SS Signals |
| 1068 |
When writing onto a connection-oriented socket that has been shut down |
| 1069 |
(by the local or the remote end) |
| 1070 |
.B SIGPIPE |
| 1071 |
is sent to the writing process and |
| 1072 |
.B EPIPE |
| 1073 |
is returned. |
| 1074 |
The signal is not sent when the write call |
| 1075 |
specified the |
| 1076 |
.B MSG_NOSIGNAL |
| 1077 |
flag. |
| 1078 |
.P |
| 1079 |
When requested with the |
| 1080 |
.B FIOSETOWN |
| 1081 |
.BR fcntl (2) |
| 1082 |
or |
| 1083 |
.B SIOCSPGRP |
| 1084 |
.BR ioctl (2), |
| 1085 |
.B SIGIO |
| 1086 |
is sent when an I/O event occurs. |
| 1087 |
It is possible to use |
| 1088 |
.BR poll (2) |
| 1089 |
or |
| 1090 |
.BR select (2) |
| 1091 |
in the signal handler to find out which socket the event occurred on. |
| 1092 |
An alternative (in Linux 2.2) is to set a real-time signal using the |
| 1093 |
.B F_SETSIG |
| 1094 |
.BR fcntl (2); |
| 1095 |
the handler of the real time signal will be called with |
| 1096 |
the file descriptor in the |
| 1097 |
.I si_fd |
| 1098 |
field of its |
| 1099 |
.IR siginfo_t . |
| 1100 |
See |
| 1101 |
.BR fcntl (2) |
| 1102 |
for more information. |
| 1103 |
.P |
| 1104 |
Under some circumstances (e.g., multiple processes accessing a |
| 1105 |
single socket), the condition that caused the |
| 1106 |
.B SIGIO |
| 1107 |
may have already disappeared when the process reacts to the signal. |
| 1108 |
If this happens, the process should wait again because Linux |
| 1109 |
will resend the signal later. |
| 1110 |
.\" .SS Ancillary messages |
| 1111 |
.SS /proc interfaces |
| 1112 |
The core socket networking parameters can be accessed |
| 1113 |
via files in the directory |
| 1114 |
.IR /proc/sys/net/core/ . |
| 1115 |
.TP |
| 1116 |
.I rmem_default |
| 1117 |
contains the default setting in bytes of the socket receive buffer. |
| 1118 |
.TP |
| 1119 |
.I rmem_max |
| 1120 |
contains the maximum socket receive buffer size in bytes which a user may |
| 1121 |
set by using the |
| 1122 |
.B SO_RCVBUF |
| 1123 |
socket option. |
| 1124 |
.TP |
| 1125 |
.I wmem_default |
| 1126 |
contains the default setting in bytes of the socket send buffer. |
| 1127 |
.TP |
| 1128 |
.I wmem_max |
| 1129 |
contains the maximum socket send buffer size in bytes which a user may |
| 1130 |
set by using the |
| 1131 |
.B SO_SNDBUF |
| 1132 |
socket option. |
| 1133 |
.TP |
| 1134 |
.I message_cost |
| 1135 |
.TQ |
| 1136 |
.I message_burst |
| 1137 |
configure the token bucket filter used to load limit warning messages |
| 1138 |
caused by external network events. |
| 1139 |
.TP |
| 1140 |
.I netdev_max_backlog |
| 1141 |
Maximum number of packets in the global input queue. |
| 1142 |
.TP |
| 1143 |
.I optmem_max |
| 1144 |
Maximum size of ancillary data and user control data like the iovecs |
| 1145 |
per socket. |
| 1146 |
.\" netdev_fastroute is not documented because it is experimental |
| 1147 |
.SS Ioctls |
| 1148 |
These operations can be accessed using |
| 1149 |
.BR ioctl (2): |
| 1150 |
.P |
| 1151 |
.in +4n |
| 1152 |
.EX |
| 1153 |
.IB error " = ioctl(" ip_socket ", " ioctl_type ", " &value_result ");" |
| 1154 |
.EE |
| 1155 |
.in |
| 1156 |
.TP |
| 1157 |
.B SIOCGSTAMP |
| 1158 |
Return a |
| 1159 |
.I struct timeval |
| 1160 |
with the receive timestamp of the last packet passed to the user. |
| 1161 |
This is useful for accurate round trip time measurements. |
| 1162 |
See |
| 1163 |
.BR setitimer (2) |
| 1164 |
for a description of |
| 1165 |
.IR "struct timeval" . |
| 1166 |
.\" |
| 1167 |
This ioctl should be used only if the socket options |
| 1168 |
.B SO_TIMESTAMP |
| 1169 |
and |
| 1170 |
.B SO_TIMESTAMPNS |
| 1171 |
are not set on the socket. |
| 1172 |
Otherwise, it returns the timestamp of the |
| 1173 |
last packet that was received while |
| 1174 |
.B SO_TIMESTAMP |
| 1175 |
and |
| 1176 |
.B SO_TIMESTAMPNS |
| 1177 |
were not set, or it fails if no such packet has been received, |
| 1178 |
(i.e., |
| 1179 |
.BR ioctl (2) |
| 1180 |
returns \-1 with |
| 1181 |
.I errno |
| 1182 |
set to |
| 1183 |
.BR ENOENT ). |
| 1184 |
.TP |
| 1185 |
.B SIOCSPGRP |
| 1186 |
Set the process or process group that is to receive |
| 1187 |
.B SIGIO |
| 1188 |
or |
| 1189 |
.B SIGURG |
| 1190 |
signals when I/O becomes possible or urgent data is available. |
| 1191 |
The argument is a pointer to a |
| 1192 |
.IR pid_t . |
| 1193 |
For further details, see the description of |
| 1194 |
.B F_SETOWN |
| 1195 |
in |
| 1196 |
.BR fcntl (2). |
| 1197 |
.TP |
| 1198 |
.B FIOASYNC |
| 1199 |
Change the |
| 1200 |
.B O_ASYNC |
| 1201 |
flag to enable or disable asynchronous I/O mode of the socket. |
| 1202 |
Asynchronous I/O mode means that the |
| 1203 |
.B SIGIO |
| 1204 |
signal or the signal set with |
| 1205 |
.B F_SETSIG |
| 1206 |
is raised when a new I/O event occurs. |
| 1207 |
.IP |
| 1208 |
Argument is an integer boolean flag. |
| 1209 |
(This operation is synonymous with the use of |
| 1210 |
.BR fcntl (2) |
| 1211 |
to set the |
| 1212 |
.B O_ASYNC |
| 1213 |
flag.) |
| 1214 |
.\" |
| 1215 |
.TP |
| 1216 |
.B SIOCGPGRP |
| 1217 |
Get the current process or process group that receives |
| 1218 |
.B SIGIO |
| 1219 |
or |
| 1220 |
.B SIGURG |
| 1221 |
signals, |
| 1222 |
or 0 |
| 1223 |
when none is set. |
| 1224 |
.P |
| 1225 |
Valid |
| 1226 |
.BR fcntl (2) |
| 1227 |
operations: |
| 1228 |
.TP |
| 1229 |
.B FIOGETOWN |
| 1230 |
The same as the |
| 1231 |
.B SIOCGPGRP |
| 1232 |
.BR ioctl (2). |
| 1233 |
.TP |
| 1234 |
.B FIOSETOWN |
| 1235 |
The same as the |
| 1236 |
.B SIOCSPGRP |
| 1237 |
.BR ioctl (2). |
| 1238 |
.SH VERSIONS |
| 1239 |
.B SO_BINDTODEVICE |
| 1240 |
was introduced in Linux 2.0.30. |
| 1241 |
.B SO_PASSCRED |
| 1242 |
is new in Linux 2.2. |
| 1243 |
The |
| 1244 |
.I /proc |
| 1245 |
interfaces were introduced in Linux 2.2. |
| 1246 |
.B SO_RCVTIMEO |
| 1247 |
and |
| 1248 |
.B SO_SNDTIMEO |
| 1249 |
are supported since Linux 2.3.41. |
| 1250 |
Earlier, timeouts were fixed to |
| 1251 |
a protocol-specific setting, and could not be read or written. |
| 1252 |
.SH NOTES |
| 1253 |
Linux assumes that |
| 1254 |
half of the send/receive buffer is used for internal kernel structures; |
| 1255 |
thus the values in the corresponding |
| 1256 |
.I /proc |
| 1257 |
files are twice what can be observed on the wire. |
| 1258 |
.P |
| 1259 |
Linux will allow port reuse only with the |
| 1260 |
.B SO_REUSEADDR |
| 1261 |
option |
| 1262 |
when this option was set both in the previous program that performed a |
| 1263 |
.BR bind (2) |
| 1264 |
to the port and in the program that wants to reuse the port. |
| 1265 |
This differs from some implementations (e.g., FreeBSD) |
| 1266 |
where only the later program needs to set the |
| 1267 |
.B SO_REUSEADDR |
| 1268 |
option. |
| 1269 |
Typically this difference is invisible, since, for example, a server |
| 1270 |
program is designed to always set this option. |
| 1271 |
.\" .SH AUTHORS |
| 1272 |
.\" This man page was written by Andi Kleen. |
| 1273 |
.SH SEE ALSO |
| 1274 |
.BR wireshark (1), |
| 1275 |
.BR bpf (2), |
| 1276 |
.BR connect (2), |
| 1277 |
.BR getsockopt (2), |
| 1278 |
.BR setsockopt (2), |
| 1279 |
.BR socket (2), |
| 1280 |
.BR pcap (3), |
| 1281 |
.BR address_families (7), |
| 1282 |
.BR capabilities (7), |
| 1283 |
.BR ddp (7), |
| 1284 |
.BR ip (7), |
| 1285 |
.BR ipv6 (7), |
| 1286 |
.BR packet (7), |
| 1287 |
.BR tcp (7), |
| 1288 |
.BR udp (7), |
| 1289 |
.BR unix (7), |
| 1290 |
.BR tcpdump (8) |