Debian Codegraph @

upstream/debian-unstable/man7/socket.7

raw
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)