Debian Codegraph @

upstream/debian-trixie/man7/ip.7

raw
1 '\" t
2 .\" SPDX-License-Identifier: Linux-man-pages-1-para
3 .\"
4 .\" This man page is Copyright (C) 1999 Andi Kleen <[email protected]>.
5 .\"
6 .\" $Id: ip.7,v 1.19 2000/12/20 18:10:31 ak Exp $
7 .\"
8 .\" FIXME The following socket options are yet to be documented
9 .\"
10 .\" IP_XFRM_POLICY (2.5.48)
11 .\" Needs CAP_NET_ADMIN
12 .\"
13 .\" IP_IPSEC_POLICY (2.5.47)
14 .\" Needs CAP_NET_ADMIN
15 .\"
16 .\" IP_MINTTL (2.6.34)
17 .\" commit d218d11133d888f9745802146a50255a4781d37a
18 .\" Author: Stephen Hemminger <[email protected]>
19 .\"
20 .\" MCAST_JOIN_GROUP (2.4.22 / 2.6)
21 .\"
22 .\" MCAST_BLOCK_SOURCE (2.4.22 / 2.6)
23 .\"
24 .\" MCAST_UNBLOCK_SOURCE (2.4.22 / 2.6)
25 .\"
26 .\" MCAST_LEAVE_GROUP (2.4.22 / 2.6)
27 .\"
28 .\" MCAST_JOIN_SOURCE_GROUP (2.4.22 / 2.6)
29 .\"
30 .\" MCAST_LEAVE_SOURCE_GROUP (2.4.22 / 2.6)
31 .\"
32 .\" MCAST_MSFILTER (2.4.22 / 2.6)
33 .\"
34 .\" IP_UNICAST_IF (3.4)
35 .\" commit 76e21053b5bf33a07c76f99d27a74238310e3c71
36 .\" Author: Erich E. Hoover <[email protected]>
37 .\"
38 .TH ip 7 2024-05-02 "Linux man-pages 6.9.1"
39 .SH NAME
40 ip \- Linux IPv4 protocol implementation
41 .SH SYNOPSIS
42 .nf
43 .B #include <sys/socket.h>
44 .\" .B #include <net/netinet.h> -- does not exist anymore
45 .\" .B #include <linux/errqueue.h> -- never include <linux/foo.h>
46 .B #include <netinet/in.h>
47 .B #include <netinet/ip.h> \fR/* superset of previous */
48 .P
49 .IB tcp_socket " = socket(AF_INET, SOCK_STREAM, 0);"
50 .IB udp_socket " = socket(AF_INET, SOCK_DGRAM, 0);"
51 .IB raw_socket " = socket(AF_INET, SOCK_RAW, " protocol ");"
52 .fi
53 .SH DESCRIPTION
54 Linux implements the Internet Protocol, version 4,
55 described in RFC\ 791 and RFC\ 1122.
56 .B ip
57 contains a level 2 multicasting implementation conforming to RFC\ 1112.
58 It also contains an IP router including a packet filter.
59 .P
60 The programming interface is BSD-sockets compatible.
61 For more information on sockets, see
62 .BR socket (7).
63 .P
64 An IP socket is created using
65 .BR socket (2):
66 .P
67 .in +4n
68 .EX
69 socket(AF_INET, socket_type, protocol);
70 .EE
71 .in
72 .P
73 Valid socket types include
74 .B SOCK_STREAM
75 to open a stream socket,
76 .B SOCK_DGRAM
77 to open a datagram socket, and
78 .B SOCK_RAW
79 to open a
80 .BR raw (7)
81 socket to access the IP protocol directly.
82 .P
83 .I protocol
84 is the IP protocol in the IP header to be received or sent.
85 Valid values for
86 .I protocol
87 include:
88 .IP \[bu] 3
89 0 and
90 .B IPPROTO_TCP
91 for
92 .BR tcp (7)
93 stream sockets;
94 .IP \[bu]
95 0 and
96 .B IPPROTO_UDP
97 for
98 .BR udp (7)
99 datagram sockets;
100 .IP \[bu]
101 .B IPPROTO_SCTP
102 for
103 .BR sctp (7)
104 stream sockets; and
105 .IP \[bu]
106 .B IPPROTO_UDPLITE
107 for
108 .BR udplite (7)
109 datagram sockets.
110 .P
111 For
112 .B SOCK_RAW
113 you may specify a valid IANA IP protocol defined in
114 RFC\ 1700 assigned numbers.
115 .P
116 When a process wants to receive new incoming packets or connections, it
117 should bind a socket to a local interface address using
118 .BR bind (2).
119 In this case, only one IP socket may be bound to any given local
120 (address, port) pair.
121 When
122 .B INADDR_ANY
123 is specified in the bind call, the socket will be bound to
124 .I all
125 local interfaces.
126 When
127 .BR listen (2)
128 is called on an unbound socket, the socket is automatically bound
129 to a random free port with the local address set to
130 .BR INADDR_ANY .
131 When
132 .BR connect (2)
133 is called on an unbound socket, the socket is automatically bound
134 to a random free port or to a usable shared port with the local address
135 set to
136 .BR INADDR_ANY .
137 .P
138 A TCP local socket address that has been bound is unavailable for
139 some time after closing, unless the
140 .B SO_REUSEADDR
141 flag has been set.
142 Care should be taken when using this flag as it makes TCP less reliable.
143 .SS Address format
144 An IP socket address is defined as a combination of an IP interface
145 address and a 16-bit port number.
146 The basic IP protocol does not supply port numbers, they
147 are implemented by higher level protocols like
148 .BR udp (7)
149 and
150 .BR tcp (7).
151 On raw sockets
152 .I sin_port
153 is set to the IP protocol.
154 .P
155 .in +4n
156 .EX
157 struct sockaddr_in {
158 sa_family_t sin_family; /* address family: AF_INET */
159 in_port_t sin_port; /* port in network byte order */
160 struct in_addr sin_addr; /* internet address */
161 };
162 \&
163 /* Internet address */
164 struct in_addr {
165 uint32_t s_addr; /* address in network byte order */
166 };
167 .EE
168 .in
169 .P
170 .I sin_family
171 is always set to
172 .BR AF_INET .
173 This is required; in Linux 2.2 most networking functions return
174 .B EINVAL
175 when this setting is missing.
176 .I sin_port
177 contains the port in network byte order.
178 The port numbers below 1024 are called
179 .I privileged ports
180 (or sometimes:
181 .IR "reserved ports" ).
182 Only a privileged process
183 (on Linux: a process that has the
184 .B CAP_NET_BIND_SERVICE
185 capability in the user namespace governing its network namespace) may
186 .BR bind (2)
187 to these sockets.
188 Note that the raw IPv4 protocol as such has no concept of a
189 port, they are implemented only by higher protocols like
190 .BR tcp (7)
191 and
192 .BR udp (7).
193 .P
194 .I sin_addr
195 is the IP host address.
196 The
197 .I s_addr
198 member of
199 .I struct in_addr
200 contains the host interface address in network byte order.
201 .I in_addr
202 should be assigned one of the
203 .B INADDR_*
204 values
205 (e.g.,
206 .BR INADDR_LOOPBACK )
207 using
208 .BR htonl (3)
209 or set using the
210 .BR inet_aton (3),
211 .BR inet_addr (3),
212 .BR inet_makeaddr (3)
213 library functions or directly with the name resolver (see
214 .BR gethostbyname (3)).
215 .P
216 IPv4 addresses are divided into unicast, broadcast,
217 and multicast addresses.
218 Unicast addresses specify a single interface of a host,
219 broadcast addresses specify all hosts on a network, and multicast
220 addresses address all hosts in a multicast group.
221 Datagrams to broadcast addresses can be sent or received only when the
222 .B SO_BROADCAST
223 socket flag is set.
224 In the current implementation, connection-oriented sockets are allowed
225 to use only unicast addresses.
226 .\" Leave a loophole for XTP @)
227 .P
228 Note that the address and the port are always stored in
229 network byte order.
230 In particular, this means that you need to call
231 .BR htons (3)
232 on the number that is assigned to a port.
233 All address/port manipulation
234 functions in the standard library work in network byte order.
235 .SS Special and reserved addresses
236 There are several special addresses:
237 .TP
238 .BR INADDR_LOOPBACK " (127.0.0.1)"
239 always refers to the local host via the loopback device;
240 .TP
241 .BR INADDR_ANY " (0.0.0.0)"
242 means any address for socket binding;
243 .TP
244 .BR INADDR_BROADCAST " (255.255.255.255)"
245 has the same effect on
246 .BR bind (2)
247 as
248 .B INADDR_ANY
249 for historical reasons.
250 A packet addressed to
251 .B INADDR_BROADCAST
252 through a socket which has
253 .B SO_BROADCAST
254 set will be broadcast to all hosts on the local network segment,
255 as long as the link is broadcast-capable.
256 .TP
257 Highest-numbered address
258 .TQ
259 Lowest-numbered address
260 On any locally-attached non-point-to-point IP subnet
261 with a link type that supports broadcasts,
262 the highest-numbered address
263 (e.g., the .255 address on a subnet with netmask 255.255.255.0)
264 is designated as a broadcast address.
265 It cannot usefully be assigned to an individual interface,
266 and can only be addressed with a socket on which the
267 .B SO_BROADCAST
268 option has been set.
269 Internet standards have historically
270 also reserved the lowest-numbered address
271 (e.g., the .0 address on a subnet with netmask 255.255.255.0)
272 for broadcast, though they call it "obsolete" for this purpose.
273 (Some sources also refer to this as the "network address.")
274 Since Linux 5.14,
275 .\" commit 58fee5fc83658aaacf60246aeab738946a9ba516
276 it is treated as an ordinary unicast address
277 and can be assigned to an interface.
278 .P
279 Internet standards have traditionally also reserved various addresses
280 for particular uses, though Linux no longer treats
281 some of these specially.
282 .TP
283 [0.0.0.1, 0.255.255.255]
284 .TQ
285 [240.0.0.0, 255.255.255.254]
286 Addresses in these ranges (0/8 and 240/4) are reserved globally.
287 Since Linux 5.3
288 .\" commit 96125bf9985a75db00496dd2bc9249b777d2b19b
289 and Linux 2.6.25,
290 .\" commit 1e637c74b0f84eaca02b914c0b8c6f67276e9697
291 respectively,
292 the 0/8 and 240/4 addresses, other than
293 .B INADDR_ANY
294 and
295 .BR INADDR_BROADCAST ,
296 are treated as ordinary unicast addresses.
297 Systems that follow the traditional behaviors may not
298 interoperate with these historically reserved addresses.
299 .TP
300 [127.0.0.1, 127.255.255.254]
301 Addresses in this range (127/8) are treated as loopback addresses
302 akin to the standardized local loopback address
303 .B INADDR_LOOPBACK
304 (127.0.0.1);
305 .TP
306 [224.0.0.0, 239.255.255.255]
307 Addresses in this range (224/4) are dedicated to multicast use.
308 .SS Socket options
309 IP supports some protocol-specific socket options that can be set with
310 .BR setsockopt (2)
311 and read with
312 .BR getsockopt (2).
313 The socket option level for IP is
314 .BR IPPROTO_IP .
315 .\" or SOL_IP on Linux
316 A boolean integer flag is zero when it is false, otherwise true.
317 .P
318 When an invalid socket option is specified,
319 .BR getsockopt (2)
320 and
321 .BR setsockopt (2)
322 fail with the error
323 .BR ENOPROTOOPT .
324 .TP
325 .BR IP_ADD_MEMBERSHIP " (since Linux 1.2)"
326 Join a multicast group.
327 Argument is an
328 .I ip_mreqn
329 structure.
330 .IP
331 .in +4n
332 .EX
333 struct ip_mreqn {
334 struct in_addr imr_multiaddr; /* IP multicast group
335 address */
336 struct in_addr imr_address; /* IP address of local
337 interface */
338 int imr_ifindex; /* interface index */
339 };
340 .EE
341 .in
342 .IP
343 .I imr_multiaddr
344 contains the address of the multicast group the application
345 wants to join or leave.
346 It must be a valid multicast address
347 .\" (i.e., within the 224.0.0.0-239.255.255.255 range)
348 (or
349 .BR setsockopt (2)
350 fails with the error
351 .BR EINVAL ).
352 .I imr_address
353 is the address of the local interface with which the system
354 should join the multicast group; if it is equal to
355 .BR INADDR_ANY ,
356 an appropriate interface is chosen by the system.
357 .I imr_ifindex
358 is the interface index of the interface that should join/leave the
359 .I imr_multiaddr
360 group, or 0 to indicate any interface.
361 .IP
362 The
363 .I ip_mreqn
364 structure is available only since Linux 2.2.
365 For compatibility, the old
366 .I ip_mreq
367 structure (present since Linux 1.2) is still supported;
368 it differs from
369 .I ip_mreqn
370 only by not including the
371 .I imr_ifindex
372 field.
373 (The kernel determines which structure is being passed based
374 on the size passed in
375 .IR optlen .)
376 .IP
377 .B IP_ADD_MEMBERSHIP
378 is valid only for
379 .BR setsockopt (2).
380 .\"
381 .TP
382 .BR IP_ADD_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / Linux 2.5.68)"
383 Join a multicast group and allow receiving data only
384 from a specified source.
385 Argument is an
386 .I ip_mreq_source
387 structure.
388 .IP
389 .in +4n
390 .EX
391 struct ip_mreq_source {
392 struct in_addr imr_multiaddr; /* IP multicast group
393 address */
394 struct in_addr imr_interface; /* IP address of local
395 interface */
396 struct in_addr imr_sourceaddr; /* IP address of
397 multicast source */
398 };
399 .EE
400 .in
401 .IP
402 The
403 .I ip_mreq_source
404 structure is similar to
405 .I ip_mreqn
406 described under
407 .BR IP_ADD_MEMBERSHIP .
408 The
409 .I imr_multiaddr
410 field contains the address of the multicast group the application
411 wants to join or leave.
412 The
413 .I imr_interface
414 field is the address of the local interface with which
415 the system should join the multicast group.
416 Finally, the
417 .I imr_sourceaddr
418 field contains the address of the source the
419 application wants to receive data from.
420 .IP
421 This option can be used multiple times to allow
422 receiving data from more than one source.
423 .TP
424 .BR IP_BIND_ADDRESS_NO_PORT " (since Linux 4.2)"
425 .\" commit 90c337da1524863838658078ec34241f45d8394d
426 Inform the kernel to not reserve an ephemeral port when using
427 .BR bind (2)
428 with a port number of 0.
429 The port will later be automatically chosen at
430 .BR connect (2)
431 time,
432 in a way that allows sharing a source port as long as the 4-tuple is unique.
433 .TP
434 .BR IP_BLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)"
435 Stop receiving multicast data from a specific source in a given group.
436 This is valid only after the application has subscribed
437 to the multicast group using either
438 .B IP_ADD_MEMBERSHIP
439 or
440 .BR IP_ADD_SOURCE_MEMBERSHIP .
441 .IP
442 Argument is an
443 .I ip_mreq_source
444 structure as described under
445 .BR IP_ADD_SOURCE_MEMBERSHIP .
446 .TP
447 .BR IP_DROP_MEMBERSHIP " (since Linux 1.2)"
448 Leave a multicast group.
449 Argument is an
450 .I ip_mreqn
451 or
452 .I ip_mreq
453 structure similar to
454 .BR IP_ADD_MEMBERSHIP .
455 .TP
456 .BR IP_DROP_SOURCE_MEMBERSHIP " (since Linux 2.4.22 / 2.5.68)"
457 Leave a source-specific group\[em]that is, stop receiving data from
458 a given multicast group that come from a given source.
459 If the application has subscribed to multiple sources within
460 the same group, data from the remaining sources will still be delivered.
461 To stop receiving data from all sources at once, use
462 .BR IP_DROP_MEMBERSHIP .
463 .IP
464 Argument is an
465 .I ip_mreq_source
466 structure as described under
467 .BR IP_ADD_SOURCE_MEMBERSHIP .
468 .TP
469 .BR IP_FREEBIND " (since Linux 2.4)"
470 .\" Precisely: since Linux 2.4.0-test10
471 If enabled, this boolean option allows binding to an IP address
472 that is nonlocal or does not (yet) exist.
473 This permits listening on a socket,
474 without requiring the underlying network interface or the
475 specified dynamic IP address to be up at the time that
476 the application is trying to bind to it.
477 This option is the per-socket equivalent of the
478 .I ip_nonlocal_bind
479 .I /proc
480 interface described below.
481 .TP
482 .BR IP_HDRINCL " (since Linux 2.0)"
483 If enabled,
484 the user supplies an IP header in front of the user data.
485 Valid only for
486 .B SOCK_RAW
487 sockets; see
488 .BR raw (7)
489 for more information.
490 When this flag is enabled, the values set by
491 .BR IP_OPTIONS ,
492 .BR IP_TTL ,
493 and
494 .B IP_TOS
495 are ignored.
496 .TP
497 .BR IP_LOCAL_PORT_RANGE " (since Linux 6.3)"
498 Set or get the per-socket default local port range.
499 This option can be used to clamp down the global local port range,
500 defined by the
501 .I ip_local_port_range
502 .I /proc
503 interface described below, for a given socket.
504 .IP
505 The option takes an
506 .I uint32_t
507 value with
508 the high 16 bits set to the upper range bound,
509 and the low 16 bits set to the lower range bound.
510 Range bounds are inclusive.
511 The 16-bit values should be in host byte order.
512 .IP
513 The lower bound has to be less than the upper bound
514 when both bounds are not zero.
515 Otherwise, setting the option fails with EINVAL.
516 .IP
517 If either bound is outside of the global local port range, or is zero,
518 then that bound has no effect.
519 .IP
520 To reset the setting,
521 pass zero as both the upper and the lower bound.
522 .TP
523 .BR IP_MSFILTER " (since Linux 2.4.22 / 2.5.68)"
524 This option provides access to the advanced full-state filtering API.
525 Argument is an
526 .I ip_msfilter
527 structure.
528 .IP
529 .in +4n
530 .EX
531 struct ip_msfilter {
532 struct in_addr imsf_multiaddr; /* IP multicast group
533 address */
534 struct in_addr imsf_interface; /* IP address of local
535 interface */
536 uint32_t imsf_fmode; /* Filter\-mode */
537 \&
538 uint32_t imsf_numsrc; /* Number of sources in
539 the following array */
540 struct in_addr imsf_slist[1]; /* Array of source
541 addresses */
542 };
543 .EE
544 .in
545 .IP
546 There are two macros,
547 .B MCAST_INCLUDE
548 and
549 .BR MCAST_EXCLUDE ,
550 which can be used to specify the filtering mode.
551 Additionally, the
552 .BR IP_MSFILTER_SIZE (n)
553 macro exists to determine how much memory is needed to store
554 .I ip_msfilter
555 structure with
556 .I n
557 sources in the source list.
558 .IP
559 For the full description of multicast source filtering
560 refer to RFC 3376.
561 .TP
562 .BR IP_MTU " (since Linux 2.2)"
563 .\" Precisely: since Linux 2.1.124
564 Retrieve the current known path MTU of the current socket.
565 Returns an integer.
566 .IP
567 .B IP_MTU
568 is valid only for
569 .BR getsockopt (2)
570 and can be employed only when the socket has been connected.
571 .TP
572 .BR IP_MTU_DISCOVER " (since Linux 2.2)"
573 .\" Precisely: since Linux 2.1.124
574 Set or receive the Path MTU Discovery setting for a socket.
575 When enabled, Linux will perform Path MTU Discovery
576 as defined in RFC\ 1191 on
577 .B SOCK_STREAM
578 sockets.
579 For
580 .RB non- SOCK_STREAM
581 sockets,
582 .B IP_PMTUDISC_DO
583 forces the don't-fragment flag to be set on all outgoing packets.
584 It is the user's responsibility to packetize the data
585 in MTU-sized chunks and to do the retransmits if necessary.
586 The kernel will reject (with
587 .BR EMSGSIZE )
588 datagrams that are bigger than the known path MTU.
589 .B IP_PMTUDISC_WANT
590 will fragment a datagram if needed according to the path MTU,
591 or will set the don't-fragment flag otherwise.
592 .IP
593 The system-wide default can be toggled between
594 .B IP_PMTUDISC_WANT
595 and
596 .B IP_PMTUDISC_DONT
597 by writing (respectively, zero and nonzero values) to the
598 .I /proc/sys/net/ipv4/ip_no_pmtu_disc
599 file.
600 .TS
601 tab(:);
602 c l
603 l l.
604 Path MTU discovery value:Meaning
605 IP_PMTUDISC_WANT:Use per-route settings.
606 IP_PMTUDISC_DONT:Never do Path MTU Discovery.
607 IP_PMTUDISC_DO:Always do Path MTU Discovery.
608 IP_PMTUDISC_PROBE:Set DF but ignore Path MTU.
609 .TE
610 .IP
611 When PMTU discovery is enabled, the kernel automatically keeps track of
612 the path MTU per destination host.
613 When it is connected to a specific peer with
614 .BR connect (2),
615 the currently known path MTU can be retrieved conveniently using the
616 .B IP_MTU
617 socket option (e.g., after an
618 .B EMSGSIZE
619 error occurred).
620 The path MTU may change over time.
621 For connectionless sockets with many destinations,
622 the new MTU for a given destination can also be accessed using the
623 error queue (see
624 .BR IP_RECVERR ).
625 A new error will be queued for every incoming MTU update.
626 .IP
627 While MTU discovery is in progress, initial packets from datagram sockets
628 may be dropped.
629 Applications using UDP should be aware of this and not
630 take it into account for their packet retransmit strategy.
631 .IP
632 To bootstrap the path MTU discovery process on unconnected sockets, it
633 is possible to start with a big datagram size
634 (headers up to 64 kilobytes long) and let it shrink by updates of the path MTU.
635 .IP
636 To get an initial estimate of the
637 path MTU, connect a datagram socket to the destination address using
638 .BR connect (2)
639 and retrieve the MTU by calling
640 .BR getsockopt (2)
641 with the
642 .B IP_MTU
643 option.
644 .IP
645 It is possible to implement RFC 4821 MTU probing with
646 .B SOCK_DGRAM
647 or
648 .B SOCK_RAW
649 sockets by setting a value of
650 .B IP_PMTUDISC_PROBE
651 (available since Linux 2.6.22).
652 This is also particularly useful for diagnostic tools such as
653 .BR tracepath (8)
654 that wish to deliberately send probe packets larger than
655 the observed Path MTU.
656 .TP
657 .BR IP_MULTICAST_ALL " (since Linux 2.6.31)"
658 This option can be used to modify the delivery policy of multicast messages.
659 The argument is a boolean integer (defaults to 1).
660 If set to 1,
661 the socket will receive messages from all the groups that have been joined
662 globally on the whole system.
663 Otherwise, it will deliver messages only from
664 the groups that have been explicitly joined (for example via the
665 .B IP_ADD_MEMBERSHIP
666 option) on this particular socket.
667 .TP
668 .BR IP_MULTICAST_IF " (since Linux 1.2)"
669 Set the local device for a multicast socket.
670 The argument for
671 .BR setsockopt (2)
672 is an
673 .I ip_mreqn
674 or
675 .\" net: IP_MULTICAST_IF setsockopt now recognizes struct mreq
676 .\" Commit: 3a084ddb4bf299a6e898a9a07c89f3917f0713f7
677 (since Linux 3.5)
678 .I ip_mreq
679 structure similar to
680 .BR IP_ADD_MEMBERSHIP ,
681 or an
682 .I in_addr
683 structure.
684 (The kernel determines which structure is being passed based
685 on the size passed in
686 .IR optlen .)
687 For
688 .BR getsockopt (2),
689 the argument is an
690 .I in_addr
691 structure.
692 .TP
693 .BR IP_MULTICAST_LOOP " (since Linux 1.2)"
694 Set or read a boolean integer argument that determines whether
695 sent multicast packets should be looped back to the local sockets.
696 .TP
697 .BR IP_MULTICAST_TTL " (since Linux 1.2)"
698 Set or read the time-to-live value of outgoing multicast packets for this
699 socket.
700 It is very important for multicast packets to set the smallest TTL possible.
701 The default is 1 which means that multicast packets don't leave the local
702 network unless the user program explicitly requests it.
703 Argument is an integer.
704 .TP
705 .BR IP_NODEFRAG " (since Linux 2.6.36)"
706 If enabled (argument is nonzero),
707 the reassembly of outgoing packets is disabled in the netfilter layer.
708 The argument is an integer.
709 .IP
710 This option is valid only for
711 .B SOCK_RAW
712 sockets.
713 .TP
714 .BR IP_OPTIONS " (since Linux 2.0)"
715 .\" Precisely: since Linux 1.3.30
716 Set or get the IP options to be sent with every packet from this socket.
717 The arguments are a pointer to a memory buffer containing the options
718 and the option length.
719 The
720 .BR setsockopt (2)
721 call sets the IP options associated with a socket.
722 The maximum option size for IPv4 is 40 bytes.
723 See RFC\ 791 for the allowed options.
724 When the initial connection request packet for a
725 .B SOCK_STREAM
726 socket contains IP options, the IP options will be set automatically
727 to the options from the initial packet with routing headers reversed.
728 Incoming packets are not allowed to change options after the connection
729 is established.
730 The processing of all incoming source routing options
731 is disabled by default and can be enabled by using the
732 .I accept_source_route
733 .I /proc
734 interface.
735 Other options like timestamps are still handled.
736 For datagram sockets, IP options can be set only by the local user.
737 Calling
738 .BR getsockopt (2)
739 with
740 .B IP_OPTIONS
741 puts the current IP options used for sending into the supplied buffer.
742 .TP
743 .BR IP_PASSSEC " (since Linux 2.6.17)"
744 .\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
745 If labeled IPSEC or NetLabel is configured on the sending and receiving
746 hosts, this option enables receiving of the security context of the peer
747 socket in an ancillary message of type
748 .B SCM_SECURITY
749 retrieved using
750 .BR recvmsg (2).
751 This option is supported only for UDP sockets; for TCP or SCTP sockets,
752 see the description of the
753 .B SO_PEERSEC
754 option below.
755 .IP
756 The value given as an argument to
757 .BR setsockopt (2)
758 and returned as the result of
759 .BR getsockopt (2)
760 is an integer boolean flag.
761 .IP
762 The security context returned in the
763 .B SCM_SECURITY
764 ancillary message
765 is of the same format as the one described under the
766 .B SO_PEERSEC
767 option below.
768 .IP
769 Note: the reuse of the
770 .B SCM_SECURITY
771 message type for the
772 .B IP_PASSSEC
773 socket option was likely a mistake, since other IP control messages use
774 their own numbering scheme in the IP namespace and often use the
775 socket option value as the message type.
776 There is no conflict currently since the IP option with the same value as
777 .B SCM_SECURITY
778 is
779 .B IP_HDRINCL
780 and this is never used for a control message type.
781 .TP
782 .BR IP_PKTINFO " (since Linux 2.2)"
783 .\" Precisely: since Linux 2.1.68
784 Pass an
785 .B IP_PKTINFO
786 ancillary message that contains a
787 .I pktinfo
788 structure that supplies some information about the incoming packet.
789 This works only for datagram oriented sockets.
790 The argument is a flag that tells the socket whether the
791 .B IP_PKTINFO
792 message should be passed or not.
793 The message itself can be sent/retrieved
794 only as a control message with a packet using
795 .BR recvmsg (2)
796 or
797 .BR sendmsg (2).
798 .IP
799 .in +4n
800 .EX
801 struct in_pktinfo {
802 unsigned int ipi_ifindex; /* Interface index */
803 struct in_addr ipi_spec_dst; /* Local address */
804 struct in_addr ipi_addr; /* Header Destination
805 address */
806 };
807 .EE
808 .in
809 .IP
810 .I ipi_ifindex
811 is the unique index of the interface the packet was received on.
812 .I ipi_spec_dst
813 is the local address of the packet and
814 .I ipi_addr
815 is the destination address in the packet header.
816 If
817 .B IP_PKTINFO
818 is passed to
819 .BR sendmsg (2)
820 and
821 .\" This field is grossly misnamed
822 .I ipi_spec_dst
823 is not zero, then it is used as the local source address for the routing
824 table lookup and for setting up IP source route options.
825 When
826 .I ipi_ifindex
827 is not zero, the primary local address of the interface specified by the
828 index overwrites
829 .I ipi_spec_dst
830 for the routing table lookup.
831 .IP
832 Not supported for
833 .B SOCK_STREAM
834 sockets.
835 .TP
836 .BR IP_RECVERR " (since Linux 2.2)"
837 .\" Precisely: since Linux 2.1.15
838 Enable extended reliable error message passing.
839 When enabled on a datagram socket, all
840 generated errors will be queued in a per-socket error queue.
841 When the user receives an error from a socket operation,
842 the errors can be received by calling
843 .BR recvmsg (2)
844 with the
845 .B MSG_ERRQUEUE
846 flag set.
847 The
848 .I sock_extended_err
849 structure describing the error will be passed in an ancillary message with
850 the type
851 .B IP_RECVERR
852 and the level
853 .BR IPPROTO_IP .
854 .\" or SOL_IP on Linux
855 This is useful for reliable error handling on unconnected sockets.
856 The received data portion of the error queue contains the error packet.
857 .IP
858 The
859 .B IP_RECVERR
860 control message contains a
861 .I sock_extended_err
862 structure:
863 .IP
864 .in +4n
865 .EX
866 #define SO_EE_ORIGIN_NONE 0
867 #define SO_EE_ORIGIN_LOCAL 1
868 #define SO_EE_ORIGIN_ICMP 2
869 #define SO_EE_ORIGIN_ICMP6 3
870 \&
871 struct sock_extended_err {
872 uint32_t ee_errno; /* error number */
873 uint8_t ee_origin; /* where the error originated */
874 uint8_t ee_type; /* type */
875 uint8_t ee_code; /* code */
876 uint8_t ee_pad;
877 uint32_t ee_info; /* additional information */
878 uint32_t ee_data; /* other data */
879 /* More data may follow */
880 };
881 \&
882 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
883 .EE
884 .in
885 .IP
886 .I ee_errno
887 contains the
888 .I errno
889 number of the queued error.
890 .I ee_origin
891 is the origin code of where the error originated.
892 The other fields are protocol-specific.
893 The macro
894 .B SO_EE_OFFENDER
895 returns a pointer to the address of the network object
896 where the error originated from given a pointer to the ancillary message.
897 If this address is not known, the
898 .I sa_family
899 member of the
900 .I sockaddr
901 contains
902 .B AF_UNSPEC
903 and the other fields of the
904 .I sockaddr
905 are undefined.
906 .IP
907 IP uses the
908 .I sock_extended_err
909 structure as follows:
910 .I ee_origin
911 is set to
912 .B SO_EE_ORIGIN_ICMP
913 for errors received as an ICMP packet, or
914 .B SO_EE_ORIGIN_LOCAL
915 for locally generated errors.
916 Unknown values should be ignored.
917 .I ee_type
918 and
919 .I ee_code
920 are set from the type and code fields of the ICMP header.
921 .I ee_info
922 contains the discovered MTU for
923 .B EMSGSIZE
924 errors.
925 The message also contains the
926 .I sockaddr_in of the node
927 caused the error, which can be accessed with the
928 .B SO_EE_OFFENDER
929 macro.
930 The
931 .I sin_family
932 field of the
933 .B SO_EE_OFFENDER
934 address is
935 .B AF_UNSPEC
936 when the source was unknown.
937 When the error originated from the network, all IP options
938 .RB ( IP_OPTIONS ", " IP_TTL ,
939 etc.) enabled on the socket and contained in the
940 error packet are passed as control messages.
941 The payload of the packet causing the error is returned as normal payload.
942 .\" FIXME . Is it a good idea to document that? It is a dubious feature.
943 .\" On
944 .\" .B SOCK_STREAM
945 .\" sockets,
946 .\" .B IP_RECVERR
947 .\" has slightly different semantics. Instead of
948 .\" saving the errors for the next timeout, it passes all incoming
949 .\" errors immediately to the user.
950 .\" This might be useful for very short-lived TCP connections which
951 .\" need fast error handling. Use this option with care:
952 .\" it makes TCP unreliable
953 .\" by not allowing it to recover properly from routing
954 .\" shifts and other normal
955 .\" conditions and breaks the protocol specification.
956 Note that TCP has no error queue;
957 .B MSG_ERRQUEUE
958 is not permitted on
959 .B SOCK_STREAM
960 sockets.
961 .B IP_RECVERR
962 is valid for TCP, but all errors are returned by socket function return or
963 .B SO_ERROR
964 only.
965 .IP
966 For raw sockets,
967 .B IP_RECVERR
968 enables passing of all received ICMP errors to the
969 application, otherwise errors are reported only on connected sockets
970 .IP
971 It sets or retrieves an integer boolean flag.
972 .B IP_RECVERR
973 defaults to off.
974 .TP
975 .BR IP_RECVOPTS " (since Linux 2.2)"
976 .\" Precisely: since Linux 2.1.15
977 Pass all incoming IP options to the user in a
978 .B IP_OPTIONS
979 control message.
980 The routing header and other options are already filled in
981 for the local host.
982 Not supported for
983 .B SOCK_STREAM
984 sockets.
985 .TP
986 .BR IP_RECVORIGDSTADDR " (since Linux 2.6.29)"
987 .\" commit e8b2dfe9b4501ed0047459b2756ba26e5a940a69
988 This boolean option enables the
989 .B IP_ORIGDSTADDR
990 ancillary message in
991 .BR recvmsg (2),
992 in which the kernel returns the original destination address
993 of the datagram being received.
994 The ancillary message contains a
995 .IR "struct sockaddr_in" .
996 Not supported for
997 .B SOCK_STREAM
998 sockets.
999 .TP
1000 .BR IP_RECVTOS " (since Linux 2.2)"
1001 .\" Precisely: since Linux 2.1.68
1002 If enabled, the
1003 .B IP_TOS
1004 ancillary message is passed with incoming packets.
1005 It contains a byte which specifies the Type of Service/Precedence
1006 field of the packet header.
1007 Expects a boolean integer flag.
1008 Not supported for
1009 .B SOCK_STREAM
1010 sockets.
1011 .TP
1012 .BR IP_RECVTTL " (since Linux 2.2)"
1013 .\" Precisely: since Linux 2.1.68
1014 When this flag is set, pass a
1015 .B IP_TTL
1016 control message with the time-to-live
1017 field of the received packet as a 32 bit integer.
1018 Not supported for
1019 .B SOCK_STREAM
1020 sockets.
1021 .TP
1022 .BR IP_RETOPTS " (since Linux 2.2)"
1023 .\" Precisely: since Linux 2.1.15
1024 Identical to
1025 .BR IP_RECVOPTS ,
1026 but returns raw unprocessed options with timestamp and route record
1027 options not filled in for this hop.
1028 Not supported for
1029 .B SOCK_STREAM
1030 sockets.
1031 .TP
1032 .BR IP_ROUTER_ALERT " (since Linux 2.2)"
1033 .\" Precisely: since Linux 2.1.68
1034 Pass all to-be forwarded packets with the
1035 IP Router Alert option set to this socket.
1036 Valid only for raw sockets.
1037 This is useful, for instance, for user-space RSVP daemons.
1038 The tapped packets are not forwarded by the kernel; it is
1039 the user's responsibility to send them out again.
1040 Socket binding is ignored,
1041 such packets are filtered only by protocol.
1042 Expects an integer flag.
1043 .TP
1044 .BR IP_TOS " (since Linux 1.0)"
1045 Set or receive the Type-Of-Service (TOS) field that is sent
1046 with every IP packet originating from this socket.
1047 It is used to prioritize packets on the network.
1048 TOS is a byte.
1049 There are some standard TOS flags defined:
1050 .B IPTOS_LOWDELAY
1051 to minimize delays for interactive traffic,
1052 .B IPTOS_THROUGHPUT
1053 to optimize throughput,
1054 .B IPTOS_RELIABILITY
1055 to optimize for reliability,
1056 .B IPTOS_MINCOST
1057 should be used for "filler data" where slow transmission doesn't matter.
1058 At most one of these TOS values can be specified.
1059 Other bits are invalid and shall be cleared.
1060 Linux sends
1061 .B IPTOS_LOWDELAY
1062 datagrams first by default,
1063 but the exact behavior depends on the configured queueing discipline.
1064 .\" FIXME elaborate on this
1065 Some high-priority levels may require superuser privileges (the
1066 .B CAP_NET_ADMIN
1067 capability).
1068 .\" The priority can also be set in a protocol-independent way by the
1069 .\" .RB ( SOL_SOCKET ", " SO_PRIORITY )
1070 .\" socket option (see
1071 .\" .BR socket (7)).
1072 .TP
1073 .BR IP_TRANSPARENT " (since Linux 2.6.24)"
1074 .\" commit f5715aea4564f233767ea1d944b2637a5fd7cd2e
1075 .\" This patch introduces the IP_TRANSPARENT socket option: enabling that
1076 .\" will make the IPv4 routing omit the non-local source address check on
1077 .\" output. Setting IP_TRANSPARENT requires NET_ADMIN capability.
1078 .\" http://lwn.net/Articles/252545/
1079 Setting this boolean option enables transparent proxying on this socket.
1080 This socket option allows
1081 the calling application to bind to a nonlocal IP address and operate
1082 both as a client and a server with the foreign address as the local endpoint.
1083 NOTE: this requires that routing be set up in a way that
1084 packets going to the foreign address are routed through the TProxy box
1085 (i.e., the system hosting the application that employs the
1086 .B IP_TRANSPARENT
1087 socket option).
1088 Enabling this socket option requires superuser privileges
1089 (the
1090 .B CAP_NET_ADMIN
1091 capability).
1092 .IP
1093 TProxy redirection with the iptables TPROXY target also requires that
1094 this option be set on the redirected socket.
1095 .TP
1096 .BR IP_TTL " (since Linux 1.0)"
1097 Set or retrieve the current time-to-live field that is used in every packet
1098 sent from this socket.
1099 .TP
1100 .BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)"
1101 Unblock previously blocked multicast source.
1102 Returns
1103 .B EADDRNOTAVAIL
1104 when given source is not being blocked.
1105 .IP
1106 Argument is an
1107 .I ip_mreq_source
1108 structure as described under
1109 .BR IP_ADD_SOURCE_MEMBERSHIP .
1110 .TP
1111 .BR SO_PEERSEC " (since Linux 2.6.17)"
1112 If labeled IPSEC or NetLabel is configured on both the sending and
1113 receiving hosts, this read-only socket option returns the security
1114 context of the peer socket connected to this socket.
1115 By default,
1116 this will be the same as the security context of the process that created
1117 the peer socket unless overridden by the policy or by a process with
1118 the required permissions.
1119 .IP
1120 The argument to
1121 .BR getsockopt (2)
1122 is a pointer to a buffer of the specified length in bytes
1123 into which the security context string will be copied.
1124 If the buffer length is less than the length of the security
1125 context string, then
1126 .BR getsockopt (2)
1127 returns \-1, sets
1128 .I errno
1129 to
1130 .BR ERANGE ,
1131 and returns the required length via
1132 .IR optlen .
1133 The caller should allocate at least
1134 .B NAME_MAX
1135 bytes for the buffer initially, although this is not guaranteed
1136 to be sufficient.
1137 Resizing the buffer to the returned length
1138 and retrying may be necessary.
1139 .IP
1140 The security context string may include a terminating null character
1141 in the returned length, but is not guaranteed to do so: a security
1142 context "foo" might be represented as either {'f','o','o'} of length 3
1143 or {'f','o','o','\\0'} of length 4, which are considered to be
1144 interchangeable.
1145 The string is printable, does not contain non-terminating null characters,
1146 and is in an unspecified encoding (in particular, it
1147 is not guaranteed to be ASCII or UTF-8).
1148 .IP
1149 The use of this option for sockets in the
1150 .B AF_INET
1151 address family is supported since Linux 2.6.17
1152 .\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
1153 for TCP sockets, and since Linux 4.17
1154 .\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a
1155 for SCTP sockets.
1156 .IP
1157 For SELinux, NetLabel conveys only the MLS portion of the security
1158 context of the peer across the wire, defaulting the rest of the
1159 security context to the values defined in the policy for the
1160 netmsg initial security identifier (SID).
1161 However, NetLabel can
1162 be configured to pass full security contexts over loopback.
1163 Labeled IPSEC always passes full security contexts as part of establishing
1164 the security association (SA) and looks them up based on the association
1165 for each packet.
1166 .\"
1167 .SS /proc interfaces
1168 The IP protocol
1169 supports a set of
1170 .I /proc
1171 interfaces to configure some global parameters.
1172 The parameters can be accessed by reading or writing files in the directory
1173 .IR /proc/sys/net/ipv4/ .
1174 .\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented:
1175 .\" ip_queue_maxlen
1176 .\" ip_conntrack_max
1177 Interfaces described as
1178 .I Boolean
1179 take an integer value, with a nonzero value ("true") meaning that
1180 the corresponding option is enabled, and a zero value ("false")
1181 meaning that the option is disabled.
1182 .\"
1183 .TP
1184 .IR ip_always_defrag " (Boolean; since Linux 2.2.13)"
1185 [New with Linux 2.2.13; in earlier kernel versions this feature
1186 was controlled at compile time by the
1187 .B CONFIG_IP_ALWAYS_DEFRAG
1188 option; this option is not present in Linux 2.4.x and later]
1189 .IP
1190 When this boolean flag is enabled (not equal 0), incoming fragments
1191 (parts of IP packets
1192 that arose when some host between origin and destination decided
1193 that the packets were too large and cut them into pieces) will be
1194 reassembled (defragmented) before being processed, even if they are
1195 about to be forwarded.
1196 .IP
1197 Enable only if running either a firewall that is the sole link
1198 to your network or a transparent proxy; never ever use it for a
1199 normal router or host.
1200 Otherwise, fragmented communication can be disturbed
1201 if the fragments travel over different links.
1202 Defragmentation also has a large memory and CPU time cost.
1203 .IP
1204 This is automagically turned on when masquerading or transparent
1205 proxying are configured.
1206 .\"
1207 .TP
1208 .IR ip_autoconfig " (since Linux 2.2 to Linux 2.6.17)"
1209 .\" Precisely: since Linux 2.1.68
1210 .\" FIXME document ip_autoconfig
1211 Not documented.
1212 .\"
1213 .TP
1214 .IR ip_default_ttl " (integer; default: 64; since Linux 2.2)"
1215 .\" Precisely: since Linux 2.1.15
1216 Set the default time-to-live value of outgoing packets.
1217 This can be changed per socket with the
1218 .B IP_TTL
1219 option.
1220 .\"
1221 .TP
1222 .IR ip_dynaddr " (Boolean; default: disabled; since Linux 2.0.31)"
1223 Enable dynamic socket address and masquerading entry rewriting on interface
1224 address change.
1225 This is useful for dialup interface with changing IP addresses.
1226 0 means no rewriting, 1 turns it on and 2 enables verbose mode.
1227 .\"
1228 .TP
1229 .IR ip_forward " (Boolean; default: disabled; since Linux 1.2)"
1230 Enable IP forwarding with a boolean flag.
1231 IP forwarding can be also set on a per-interface basis.
1232 .\"
1233 .TP
1234 .IR ip_local_port_range " (since Linux 2.2)"
1235 .\" Precisely: since Linux 2.1.68
1236 This file contains two integers that define the default local port range
1237 allocated to sockets that are not explicitly bound to a port number\[em]that
1238 is, the range used for
1239 .IR "ephemeral ports" .
1240 An ephemeral port is allocated to a socket in the following circumstances:
1241 .RS
1242 .IP \[bu] 3
1243 the port number in a socket address is specified as 0 when calling
1244 .BR bind (2);
1245 .IP \[bu]
1246 .BR listen (2)
1247 is called on a stream socket that was not previously bound;
1248 .IP \[bu]
1249 .BR connect (2)
1250 was called on a socket that was not previously bound;
1251 .IP \[bu]
1252 .BR sendto (2)
1253 is called on a datagram socket that was not previously bound.
1254 .RE
1255 .IP
1256 Allocation of ephemeral ports starts with the first number in
1257 .I ip_local_port_range
1258 and ends with the second number.
1259 If the range of ephemeral ports is exhausted,
1260 then the relevant system call returns an error (but see BUGS).
1261 .IP
1262 Note that the port range in
1263 .I ip_local_port_range
1264 should not conflict with the ports used by masquerading
1265 (although the case is handled).
1266 Also, arbitrary choices may cause problems with some firewall packet
1267 filters that make assumptions about the local ports in use.
1268 The first number should be at least greater than 1024,
1269 or better, greater than 4096, to avoid clashes
1270 with well known ports and to minimize firewall problems.
1271 .\"
1272 .TP
1273 .IR ip_no_pmtu_disc " (Boolean; default: disabled; since Linux 2.2)"
1274 .\" Precisely: 2.1.15
1275 If enabled, don't do Path MTU Discovery for TCP sockets by default.
1276 Path MTU discovery may fail if misconfigured firewalls (that drop
1277 all ICMP packets) or misconfigured interfaces (e.g., a point-to-point
1278 link where the both ends don't agree on the MTU) are on the path.
1279 It is better to fix the broken routers on the path than to turn off
1280 Path MTU Discovery globally, because not doing it incurs a high cost
1281 to the network.
1282 .\"
1283 .\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt
1284 .TP
1285 .IR ip_nonlocal_bind " (Boolean; default: disabled; since Linux 2.4)"
1286 .\" Precisely: patch-2.4.0-test10
1287 If set, allows processes to
1288 .BR bind (2)
1289 to nonlocal IP addresses,
1290 which can be quite useful, but may break some applications.
1291 .\"
1292 .\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt
1293 .TP
1294 .IR ip6frag_time " (integer; default: 30)"
1295 Time in seconds to keep an IPv6 fragment in memory.
1296 .\"
1297 .\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt
1298 .TP
1299 .IR ip6frag_secret_interval " (integer; default: 600)"
1300 Regeneration interval (in seconds) of the hash secret (or lifetime
1301 for the hash secret) for IPv6 fragments.
1302 .TP
1303 .IR ipfrag_high_thresh " (integer)"
1304 .TQ
1305 .IR ipfrag_low_thresh " (integer)"
1306 If the amount of queued IP fragments reaches
1307 .IR ipfrag_high_thresh ,
1308 the queue is pruned down to
1309 .IR ipfrag_low_thresh .
1310 Contains an integer with the number of bytes.
1311 .TP
1312 .I neigh/*
1313 See
1314 .BR arp (7).
1315 .\" FIXME Document the conf/*/* interfaces
1316 .\"
1317 .\" FIXME Document the route/* interfaces
1318 .SS Ioctls
1319 All ioctls described in
1320 .BR socket (7)
1321 apply to
1322 .BR ip .
1323 .P
1324 Ioctls to configure generic device parameters are described in
1325 .BR netdevice (7).
1326 .\" FIXME Add a discussion of multicasting
1327 .SH ERRORS
1328 .\" FIXME document all errors.
1329 .\" We should really fix the kernels to give more uniform
1330 .\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.)
1331 .TP
1332 .B EACCES
1333 The user tried to execute an operation without the necessary permissions.
1334 These include:
1335 sending a packet to a broadcast address without having the
1336 .B SO_BROADCAST
1337 flag set;
1338 sending a packet via a
1339 .I prohibit
1340 route;
1341 modifying firewall settings without superuser privileges (the
1342 .B CAP_NET_ADMIN
1343 capability);
1344 binding to a privileged port without superuser privileges (the
1345 .B CAP_NET_BIND_SERVICE
1346 capability).
1347 .TP
1348 .B EADDRINUSE
1349 Tried to bind to an address already in use.
1350 .TP
1351 .B EADDRNOTAVAIL
1352 A nonexistent interface was requested or the requested source
1353 address was not local.
1354 .TP
1355 .B EAGAIN
1356 Operation on a nonblocking socket would block.
1357 .TP
1358 .B EALREADY
1359 A connection operation on a nonblocking socket is already in progress.
1360 .TP
1361 .B ECONNABORTED
1362 A connection was closed during an
1363 .BR accept (2).
1364 .TP
1365 .B EHOSTUNREACH
1366 No valid routing table entry matches the destination address.
1367 This error can be caused by an ICMP message from a remote router or
1368 for the local routing table.
1369 .TP
1370 .B EINVAL
1371 Invalid argument passed.
1372 For send operations this can be caused by sending to a
1373 .I blackhole
1374 route.
1375 .TP
1376 .B EISCONN
1377 .BR connect (2)
1378 was called on an already connected socket.
1379 .TP
1380 .B EMSGSIZE
1381 Datagram is bigger than an MTU on the path and it cannot be fragmented.
1382 .TP
1383 .B ENOBUFS
1384 .TQ
1385 .B ENOMEM
1386 Not enough free memory.
1387 This often means that the memory allocation is limited by the socket
1388 buffer limits, not by the system memory, but this is not 100% consistent.
1389 .TP
1390 .B ENOENT
1391 .B SIOCGSTAMP
1392 was called on a socket where no packet arrived.
1393 .TP
1394 .B ENOPKG
1395 A kernel subsystem was not configured.
1396 .TP
1397 .BR ENOPROTOOPT " and " EOPNOTSUPP
1398 Invalid socket option passed.
1399 .TP
1400 .B ENOTCONN
1401 The operation is defined only on a connected socket, but the socket wasn't
1402 connected.
1403 .TP
1404 .B EPERM
1405 User doesn't have permission to set high priority, change configuration,
1406 or send signals to the requested process or group.
1407 .TP
1408 .B EPIPE
1409 The connection was unexpectedly closed or shut down by the other end.
1410 .TP
1411 .B ESOCKTNOSUPPORT
1412 The socket is not configured or an unknown socket type was requested.
1413 .P
1414 Other errors may be generated by the overlaying protocols; see
1415 .BR tcp (7),
1416 .BR raw (7),
1417 .BR udp (7),
1418 and
1419 .BR socket (7).
1420 .SH NOTES
1421 .BR IP_FREEBIND ,
1422 .BR IP_MSFILTER ,
1423 .BR IP_MTU ,
1424 .BR IP_MTU_DISCOVER ,
1425 .BR IP_RECVORIGDSTADDR ,
1426 .BR IP_PASSSEC ,
1427 .BR IP_PKTINFO ,
1428 .BR IP_RECVERR ,
1429 .BR IP_ROUTER_ALERT ,
1430 and
1431 .B IP_TRANSPARENT
1432 are Linux-specific.
1433 .\" IP_XFRM_POLICY is Linux-specific
1434 .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs
1435 .P
1436 Be very careful with the
1437 .B SO_BROADCAST
1438 option \- it is not privileged in Linux.
1439 It is easy to overload the network
1440 with careless broadcasts.
1441 For new application protocols
1442 it is better to use a multicast group instead of broadcasting.
1443 Broadcasting is discouraged.
1444 See RFC 6762 for an example of a protocol (mDNS)
1445 using the more modern multicast approach
1446 to communicating with an open-ended
1447 group of hosts on the local network.
1448 .P
1449 Some other BSD sockets implementations provide
1450 .B IP_RCVDSTADDR
1451 and
1452 .B IP_RECVIF
1453 socket options to get the destination address and the interface of
1454 received datagrams.
1455 Linux has the more general
1456 .B IP_PKTINFO
1457 for the same task.
1458 .P
1459 Some BSD sockets implementations also provide an
1460 .B IP_RECVTTL
1461 option, but an ancillary message with type
1462 .B IP_RECVTTL
1463 is passed with the incoming packet.
1464 This is different from the
1465 .B IP_TTL
1466 option used in Linux.
1467 .P
1468 Using the
1469 .B SOL_IP
1470 socket options level isn't portable; BSD-based stacks use the
1471 .B IPPROTO_IP
1472 level.
1473 .P
1474 .B INADDR_ANY
1475 (0.0.0.0) and
1476 .B INADDR_BROADCAST
1477 (255.255.255.255) are byte-order-neutral.
1478 This means
1479 .BR htonl (3)
1480 has no effect on them.
1481 .SS Compatibility
1482 For compatibility with Linux 2.0, the obsolete
1483 .BI "socket(AF_INET, SOCK_PACKET, " protocol )
1484 syntax is still supported to open a
1485 .BR packet (7)
1486 socket.
1487 This is deprecated and should be replaced by
1488 .BI "socket(AF_PACKET, SOCK_RAW, " protocol )
1489 instead.
1490 The main difference is the new
1491 .I sockaddr_ll
1492 address structure for generic link layer information instead of the old
1493 .BR sockaddr_pkt .
1494 .SH BUGS
1495 There are too many inconsistent error values.
1496 .P
1497 The error used to diagnose exhaustion of the ephemeral port range differs
1498 across the various system calls
1499 .RB ( connect (2),
1500 .BR bind (2),
1501 .BR listen (2),
1502 .BR sendto (2))
1503 that can assign ephemeral ports.
1504 .P
1505 The ioctls to configure IP-specific interface options and ARP tables are
1506 not described.
1507 .\" .P
1508 .\" Some versions of glibc forget to declare
1509 .\" .IR in_pktinfo .
1510 .\" Workaround currently is to copy it into your program from this man page.
1511 .P
1512 Receiving the original destination address with
1513 .B MSG_ERRQUEUE
1514 in
1515 .I msg_name
1516 by
1517 .BR recvmsg (2)
1518 does not work in some Linux 2.2 kernels.
1519 .\" .SH AUTHORS
1520 .\" This man page was written by Andi Kleen.
1521 .SH SEE ALSO
1522 .BR recvmsg (2),
1523 .BR sendmsg (2),
1524 .BR byteorder (3),
1525 .BR capabilities (7),
1526 .BR icmp (7),
1527 .BR ipv6 (7),
1528 .BR netdevice (7),
1529 .BR netlink (7),
1530 .BR raw (7),
1531 .BR socket (7),
1532 .BR tcp (7),
1533 .BR udp (7),
1534 .BR ip (8)
1535 .P
1536 The kernel source file
1537 .IR Documentation/networking/ip\-sysctl.txt .
1538 .P
1539 RFC\ 791 for the original IP specification.
1540 RFC\ 1122 for the IPv4 host requirements.
1541 RFC\ 1812 for the IPv4 router requirements.