| blob | 2b4b06324ecc64c858c8e6f6e7d0216920f4c7bc |
1 '\" t
2 .\" SPDX-License-Identifier: Linux-man-pages-1-para
3 .\"
4 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
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 <shemminger@vyatta.com>
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 <ehoover@mines.edu>
37 .\"
38 .TH ip 7 (date) "Linux man-pages (unreleased)"
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 .TP
832 .BR IP_RECVERR " (since Linux 2.2)"
833 .\" Precisely: since Linux 2.1.15
834 Enable extended reliable error message passing.
835 When enabled on a datagram socket, all
836 generated errors will be queued in a per-socket error queue.
837 When the user receives an error from a socket operation,
838 the errors can be received by calling
839 .BR recvmsg (2)
840 with the
841 .B MSG_ERRQUEUE
842 flag set.
843 The
844 .I sock_extended_err
845 structure describing the error will be passed in an ancillary message with
846 the type
847 .B IP_RECVERR
848 and the level
849 .BR IPPROTO_IP .
850 .\" or SOL_IP on Linux
851 This is useful for reliable error handling on unconnected sockets.
852 The received data portion of the error queue contains the error packet.
853 .IP
854 The
855 .B IP_RECVERR
856 control message contains a
857 .I sock_extended_err
858 structure:
859 .IP
860 .in +4n
861 .EX
862 #define SO_EE_ORIGIN_NONE 0
863 #define SO_EE_ORIGIN_LOCAL 1
864 #define SO_EE_ORIGIN_ICMP 2
865 #define SO_EE_ORIGIN_ICMP6 3
866 \&
867 struct sock_extended_err {
868 uint32_t ee_errno; /* error number */
869 uint8_t ee_origin; /* where the error originated */
870 uint8_t ee_type; /* type */
871 uint8_t ee_code; /* code */
872 uint8_t ee_pad;
873 uint32_t ee_info; /* additional information */
874 uint32_t ee_data; /* other data */
875 /* More data may follow */
876 };
877 \&
878 struct sockaddr *SO_EE_OFFENDER(struct sock_extended_err *);
879 .EE
880 .in
881 .IP
882 .I ee_errno
883 contains the
884 .I errno
885 number of the queued error.
886 .I ee_origin
887 is the origin code of where the error originated.
888 The other fields are protocol-specific.
889 The macro
890 .B SO_EE_OFFENDER
891 returns a pointer to the address of the network object
892 where the error originated from given a pointer to the ancillary message.
893 If this address is not known, the
894 .I sa_family
895 member of the
896 .I sockaddr
897 contains
898 .B AF_UNSPEC
899 and the other fields of the
900 .I sockaddr
901 are undefined.
902 .IP
903 IP uses the
904 .I sock_extended_err
905 structure as follows:
906 .I ee_origin
907 is set to
908 .B SO_EE_ORIGIN_ICMP
909 for errors received as an ICMP packet, or
910 .B SO_EE_ORIGIN_LOCAL
911 for locally generated errors.
912 Unknown values should be ignored.
913 .I ee_type
914 and
915 .I ee_code
916 are set from the type and code fields of the ICMP header.
917 .I ee_info
918 contains the discovered MTU for
919 .B EMSGSIZE
920 errors.
921 The message also contains the
922 .I sockaddr_in of the node
923 caused the error, which can be accessed with the
924 .B SO_EE_OFFENDER
925 macro.
926 The
927 .I sin_family
928 field of the
929 .B SO_EE_OFFENDER
930 address is
931 .B AF_UNSPEC
932 when the source was unknown.
933 When the error originated from the network, all IP options
934 .RB ( IP_OPTIONS ", " IP_TTL ,
935 etc.) enabled on the socket and contained in the
936 error packet are passed as control messages.
937 The payload of the packet causing the error is returned as normal payload.
938 .\" FIXME . Is it a good idea to document that? It is a dubious feature.
939 .\" On
940 .\" .B SOCK_STREAM
941 .\" sockets,
942 .\" .B IP_RECVERR
943 .\" has slightly different semantics. Instead of
944 .\" saving the errors for the next timeout, it passes all incoming
945 .\" errors immediately to the user.
946 .\" This might be useful for very short-lived TCP connections which
947 .\" need fast error handling. Use this option with care:
948 .\" it makes TCP unreliable
949 .\" by not allowing it to recover properly from routing
950 .\" shifts and other normal
951 .\" conditions and breaks the protocol specification.
952 Note that TCP has no error queue;
953 .B MSG_ERRQUEUE
954 is not permitted on
955 .B SOCK_STREAM
956 sockets.
957 .B IP_RECVERR
958 is valid for TCP, but all errors are returned by socket function return or
959 .B SO_ERROR
960 only.
961 .IP
962 For raw sockets,
963 .B IP_RECVERR
964 enables passing of all received ICMP errors to the
965 application, otherwise errors are reported only on connected sockets
966 .IP
967 It sets or retrieves an integer boolean flag.
968 .B IP_RECVERR
969 defaults to off.
970 .TP
971 .BR IP_RECVOPTS " (since Linux 2.2)"
972 .\" Precisely: since Linux 2.1.15
973 Pass all incoming IP options to the user in a
974 .B IP_OPTIONS
975 control message.
976 The routing header and other options are already filled in
977 for the local host.
978 Not supported for
979 .B SOCK_STREAM
980 sockets.
981 .TP
982 .BR IP_RECVORIGDSTADDR " (since Linux 2.6.29)"
983 .\" commit e8b2dfe9b4501ed0047459b2756ba26e5a940a69
984 This boolean option enables the
985 .B IP_ORIGDSTADDR
986 ancillary message in
987 .BR recvmsg (2),
988 in which the kernel returns the original destination address
989 of the datagram being received.
990 The ancillary message contains a
991 .IR "struct sockaddr_in" .
992 .TP
993 .BR IP_RECVTOS " (since Linux 2.2)"
994 .\" Precisely: since Linux 2.1.68
995 If enabled, the
996 .B IP_TOS
997 ancillary message is passed with incoming packets.
998 It contains a byte which specifies the Type of Service/Precedence
999 field of the packet header.
1000 Expects a boolean integer flag.
1001 .TP
1002 .BR IP_RECVTTL " (since Linux 2.2)"
1003 .\" Precisely: since Linux 2.1.68
1004 When this flag is set, pass a
1005 .B IP_TTL
1006 control message with the time-to-live
1007 field of the received packet as a 32 bit integer.
1008 Not supported for
1009 .B SOCK_STREAM
1010 sockets.
1011 .TP
1012 .BR IP_RETOPTS " (since Linux 2.2)"
1013 .\" Precisely: since Linux 2.1.15
1014 Identical to
1015 .BR IP_RECVOPTS ,
1016 but returns raw unprocessed options with timestamp and route record
1017 options not filled in for this hop.
1018 .TP
1019 .BR IP_ROUTER_ALERT " (since Linux 2.2)"
1020 .\" Precisely: since Linux 2.1.68
1021 Pass all to-be forwarded packets with the
1022 IP Router Alert option set to this socket.
1023 Valid only for raw sockets.
1024 This is useful, for instance, for user-space RSVP daemons.
1025 The tapped packets are not forwarded by the kernel; it is
1026 the user's responsibility to send them out again.
1027 Socket binding is ignored,
1028 such packets are filtered only by protocol.
1029 Expects an integer flag.
1030 .TP
1031 .BR IP_TOS " (since Linux 1.0)"
1032 Set or receive the Type-Of-Service (TOS) field that is sent
1033 with every IP packet originating from this socket.
1034 It is used to prioritize packets on the network.
1035 TOS is a byte.
1036 There are some standard TOS flags defined:
1037 .B IPTOS_LOWDELAY
1038 to minimize delays for interactive traffic,
1039 .B IPTOS_THROUGHPUT
1040 to optimize throughput,
1041 .B IPTOS_RELIABILITY
1042 to optimize for reliability,
1043 .B IPTOS_MINCOST
1044 should be used for "filler data" where slow transmission doesn't matter.
1045 At most one of these TOS values can be specified.
1046 Other bits are invalid and shall be cleared.
1047 Linux sends
1048 .B IPTOS_LOWDELAY
1049 datagrams first by default,
1050 but the exact behavior depends on the configured queueing discipline.
1051 .\" FIXME elaborate on this
1052 Some high-priority levels may require superuser privileges (the
1053 .B CAP_NET_ADMIN
1054 capability).
1055 .\" The priority can also be set in a protocol-independent way by the
1056 .\" .RB ( SOL_SOCKET ", " SO_PRIORITY )
1057 .\" socket option (see
1058 .\" .BR socket (7)).
1059 .TP
1060 .BR IP_TRANSPARENT " (since Linux 2.6.24)"
1061 .\" commit f5715aea4564f233767ea1d944b2637a5fd7cd2e
1062 .\" This patch introduces the IP_TRANSPARENT socket option: enabling that
1063 .\" will make the IPv4 routing omit the non-local source address check on
1064 .\" output. Setting IP_TRANSPARENT requires NET_ADMIN capability.
1065 .\" http://lwn.net/Articles/252545/
1066 Setting this boolean option enables transparent proxying on this socket.
1067 This socket option allows
1068 the calling application to bind to a nonlocal IP address and operate
1069 both as a client and a server with the foreign address as the local endpoint.
1070 NOTE: this requires that routing be set up in a way that
1071 packets going to the foreign address are routed through the TProxy box
1072 (i.e., the system hosting the application that employs the
1073 .B IP_TRANSPARENT
1074 socket option).
1075 Enabling this socket option requires superuser privileges
1076 (the
1077 .B CAP_NET_ADMIN
1078 capability).
1079 .IP
1080 TProxy redirection with the iptables TPROXY target also requires that
1081 this option be set on the redirected socket.
1082 .TP
1083 .BR IP_TTL " (since Linux 1.0)"
1084 Set or retrieve the current time-to-live field that is used in every packet
1085 sent from this socket.
1086 .TP
1087 .BR IP_UNBLOCK_SOURCE " (since Linux 2.4.22 / 2.5.68)"
1088 Unblock previously blocked multicast source.
1089 Returns
1090 .B EADDRNOTAVAIL
1091 when given source is not being blocked.
1092 .IP
1093 Argument is an
1094 .I ip_mreq_source
1095 structure as described under
1096 .BR IP_ADD_SOURCE_MEMBERSHIP .
1097 .TP
1098 .BR SO_PEERSEC " (since Linux 2.6.17)"
1099 If labeled IPSEC or NetLabel is configured on both the sending and
1100 receiving hosts, this read-only socket option returns the security
1101 context of the peer socket connected to this socket.
1102 By default,
1103 this will be the same as the security context of the process that created
1104 the peer socket unless overridden by the policy or by a process with
1105 the required permissions.
1106 .IP
1107 The argument to
1108 .BR getsockopt (2)
1109 is a pointer to a buffer of the specified length in bytes
1110 into which the security context string will be copied.
1111 If the buffer length is less than the length of the security
1112 context string, then
1113 .BR getsockopt (2)
1114 returns \-1, sets
1115 .I errno
1116 to
1117 .BR ERANGE ,
1118 and returns the required length via
1119 .IR optlen .
1120 The caller should allocate at least
1121 .B NAME_MAX
1122 bytes for the buffer initially, although this is not guaranteed
1123 to be sufficient.
1124 Resizing the buffer to the returned length
1125 and retrying may be necessary.
1126 .IP
1127 The security context string may include a terminating null character
1128 in the returned length, but is not guaranteed to do so: a security
1129 context "foo" might be represented as either {'f','o','o'} of length 3
1130 or {'f','o','o','\\0'} of length 4, which are considered to be
1131 interchangeable.
1132 The string is printable, does not contain non-terminating null characters,
1133 and is in an unspecified encoding (in particular, it
1134 is not guaranteed to be ASCII or UTF-8).
1135 .IP
1136 The use of this option for sockets in the
1137 .B AF_INET
1138 address family is supported since Linux 2.6.17
1139 .\" commit 2c7946a7bf45ae86736ab3b43d0085e43947945c
1140 for TCP sockets, and since Linux 4.17
1141 .\" commit d452930fd3b9031e59abfeddb2fa383f1403d61a
1142 for SCTP sockets.
1143 .IP
1144 For SELinux, NetLabel conveys only the MLS portion of the security
1145 context of the peer across the wire, defaulting the rest of the
1146 security context to the values defined in the policy for the
1147 netmsg initial security identifier (SID).
1148 However, NetLabel can
1149 be configured to pass full security contexts over loopback.
1150 Labeled IPSEC always passes full security contexts as part of establishing
1151 the security association (SA) and looks them up based on the association
1152 for each packet.
1153 .\"
1154 .SS /proc interfaces
1155 The IP protocol
1156 supports a set of
1157 .I /proc
1158 interfaces to configure some global parameters.
1159 The parameters can be accessed by reading or writing files in the directory
1160 .IR /proc/sys/net/ipv4/ .
1161 .\" FIXME As at 2.6.12, 14 Jun 2005, the following are undocumented:
1162 .\" ip_queue_maxlen
1163 .\" ip_conntrack_max
1164 Interfaces described as
1165 .I Boolean
1166 take an integer value, with a nonzero value ("true") meaning that
1167 the corresponding option is enabled, and a zero value ("false")
1168 meaning that the option is disabled.
1169 .\"
1170 .TP
1171 .IR ip_always_defrag " (Boolean; since Linux 2.2.13)"
1172 [New with Linux 2.2.13; in earlier kernel versions this feature
1173 was controlled at compile time by the
1174 .B CONFIG_IP_ALWAYS_DEFRAG
1175 option; this option is not present in Linux 2.4.x and later]
1176 .IP
1177 When this boolean flag is enabled (not equal 0), incoming fragments
1178 (parts of IP packets
1179 that arose when some host between origin and destination decided
1180 that the packets were too large and cut them into pieces) will be
1181 reassembled (defragmented) before being processed, even if they are
1182 about to be forwarded.
1183 .IP
1184 Enable only if running either a firewall that is the sole link
1185 to your network or a transparent proxy; never ever use it for a
1186 normal router or host.
1187 Otherwise, fragmented communication can be disturbed
1188 if the fragments travel over different links.
1189 Defragmentation also has a large memory and CPU time cost.
1190 .IP
1191 This is automagically turned on when masquerading or transparent
1192 proxying are configured.
1193 .\"
1194 .TP
1195 .IR ip_autoconfig " (since Linux 2.2 to Linux 2.6.17)"
1196 .\" Precisely: since Linux 2.1.68
1197 .\" FIXME document ip_autoconfig
1198 Not documented.
1199 .\"
1200 .TP
1201 .IR ip_default_ttl " (integer; default: 64; since Linux 2.2)"
1202 .\" Precisely: since Linux 2.1.15
1203 Set the default time-to-live value of outgoing packets.
1204 This can be changed per socket with the
1205 .B IP_TTL
1206 option.
1207 .\"
1208 .TP
1209 .IR ip_dynaddr " (Boolean; default: disabled; since Linux 2.0.31)"
1210 Enable dynamic socket address and masquerading entry rewriting on interface
1211 address change.
1212 This is useful for dialup interface with changing IP addresses.
1213 0 means no rewriting, 1 turns it on and 2 enables verbose mode.
1214 .\"
1215 .TP
1216 .IR ip_forward " (Boolean; default: disabled; since Linux 1.2)"
1217 Enable IP forwarding with a boolean flag.
1218 IP forwarding can be also set on a per-interface basis.
1219 .\"
1220 .TP
1221 .IR ip_local_port_range " (since Linux 2.2)"
1222 .\" Precisely: since Linux 2.1.68
1223 This file contains two integers that define the default local port range
1224 allocated to sockets that are not explicitly bound to a port number\[em]that
1225 is, the range used for
1226 .IR "ephemeral ports" .
1227 An ephemeral port is allocated to a socket in the following circumstances:
1228 .RS
1229 .IP \[bu] 3
1230 the port number in a socket address is specified as 0 when calling
1231 .BR bind (2);
1232 .IP \[bu]
1233 .BR listen (2)
1234 is called on a stream socket that was not previously bound;
1235 .IP \[bu]
1236 .BR connect (2)
1237 was called on a socket that was not previously bound;
1238 .IP \[bu]
1239 .BR sendto (2)
1240 is called on a datagram socket that was not previously bound.
1241 .RE
1242 .IP
1243 Allocation of ephemeral ports starts with the first number in
1244 .I ip_local_port_range
1245 and ends with the second number.
1246 If the range of ephemeral ports is exhausted,
1247 then the relevant system call returns an error (but see BUGS).
1248 .IP
1249 Note that the port range in
1250 .I ip_local_port_range
1251 should not conflict with the ports used by masquerading
1252 (although the case is handled).
1253 Also, arbitrary choices may cause problems with some firewall packet
1254 filters that make assumptions about the local ports in use.
1255 The first number should be at least greater than 1024,
1256 or better, greater than 4096, to avoid clashes
1257 with well known ports and to minimize firewall problems.
1258 .\"
1259 .TP
1260 .IR ip_no_pmtu_disc " (Boolean; default: disabled; since Linux 2.2)"
1261 .\" Precisely: 2.1.15
1262 If enabled, don't do Path MTU Discovery for TCP sockets by default.
1263 Path MTU discovery may fail if misconfigured firewalls (that drop
1264 all ICMP packets) or misconfigured interfaces (e.g., a point-to-point
1265 link where the both ends don't agree on the MTU) are on the path.
1266 It is better to fix the broken routers on the path than to turn off
1267 Path MTU Discovery globally, because not doing it incurs a high cost
1268 to the network.
1269 .\"
1270 .\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt
1271 .TP
1272 .IR ip_nonlocal_bind " (Boolean; default: disabled; since Linux 2.4)"
1273 .\" Precisely: patch-2.4.0-test10
1274 If set, allows processes to
1275 .BR bind (2)
1276 to nonlocal IP addresses,
1277 which can be quite useful, but may break some applications.
1278 .\"
1279 .\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt
1280 .TP
1281 .IR ip6frag_time " (integer; default: 30)"
1282 Time in seconds to keep an IPv6 fragment in memory.
1283 .\"
1284 .\" The following is from Linux 2.6.12: Documentation/networking/ip-sysctl.txt
1285 .TP
1286 .IR ip6frag_secret_interval " (integer; default: 600)"
1287 Regeneration interval (in seconds) of the hash secret (or lifetime
1288 for the hash secret) for IPv6 fragments.
1289 .TP
1290 .IR ipfrag_high_thresh " (integer)"
1291 .TQ
1292 .IR ipfrag_low_thresh " (integer)"
1293 If the amount of queued IP fragments reaches
1294 .IR ipfrag_high_thresh ,
1295 the queue is pruned down to
1296 .IR ipfrag_low_thresh .
1297 Contains an integer with the number of bytes.
1298 .TP
1299 .I neigh/*
1300 See
1301 .BR arp (7).
1302 .\" FIXME Document the conf/*/* interfaces
1303 .\"
1304 .\" FIXME Document the route/* interfaces
1305 .SS Ioctls
1306 All ioctls described in
1307 .BR socket (7)
1308 apply to
1309 .BR ip .
1310 .P
1311 Ioctls to configure generic device parameters are described in
1312 .BR netdevice (7).
1313 .\" FIXME Add a discussion of multicasting
1314 .SH ERRORS
1315 .\" FIXME document all errors.
1316 .\" We should really fix the kernels to give more uniform
1317 .\" error returns (ENOMEM vs ENOBUFS, EPERM vs EACCES etc.)
1318 .TP
1319 .B EACCES
1320 The user tried to execute an operation without the necessary permissions.
1321 These include:
1322 sending a packet to a broadcast address without having the
1323 .B SO_BROADCAST
1324 flag set;
1325 sending a packet via a
1326 .I prohibit
1327 route;
1328 modifying firewall settings without superuser privileges (the
1329 .B CAP_NET_ADMIN
1330 capability);
1331 binding to a privileged port without superuser privileges (the
1332 .B CAP_NET_BIND_SERVICE
1333 capability).
1334 .TP
1335 .B EADDRINUSE
1336 Tried to bind to an address already in use.
1337 .TP
1338 .B EADDRNOTAVAIL
1339 A nonexistent interface was requested or the requested source
1340 address was not local.
1341 .TP
1342 .B EAGAIN
1343 Operation on a nonblocking socket would block.
1344 .TP
1345 .B EALREADY
1346 A connection operation on a nonblocking socket is already in progress.
1347 .TP
1348 .B ECONNABORTED
1349 A connection was closed during an
1350 .BR accept (2).
1351 .TP
1352 .B EHOSTUNREACH
1353 No valid routing table entry matches the destination address.
1354 This error can be caused by an ICMP message from a remote router or
1355 for the local routing table.
1356 .TP
1357 .B EINVAL
1358 Invalid argument passed.
1359 For send operations this can be caused by sending to a
1360 .I blackhole
1361 route.
1362 .TP
1363 .B EISCONN
1364 .BR connect (2)
1365 was called on an already connected socket.
1366 .TP
1367 .B EMSGSIZE
1368 Datagram is bigger than an MTU on the path and it cannot be fragmented.
1369 .TP
1370 .B ENOBUFS
1371 .TQ
1372 .B ENOMEM
1373 Not enough free memory.
1374 This often means that the memory allocation is limited by the socket
1375 buffer limits, not by the system memory, but this is not 100% consistent.
1376 .TP
1377 .B ENOENT
1378 .B SIOCGSTAMP
1379 was called on a socket where no packet arrived.
1380 .TP
1381 .B ENOPKG
1382 A kernel subsystem was not configured.
1383 .TP
1384 .BR ENOPROTOOPT " and " EOPNOTSUPP
1385 Invalid socket option passed.
1386 .TP
1387 .B ENOTCONN
1388 The operation is defined only on a connected socket, but the socket wasn't
1389 connected.
1390 .TP
1391 .B EPERM
1392 User doesn't have permission to set high priority, change configuration,
1393 or send signals to the requested process or group.
1394 .TP
1395 .B EPIPE
1396 The connection was unexpectedly closed or shut down by the other end.
1397 .TP
1398 .B ESOCKTNOSUPPORT
1399 The socket is not configured or an unknown socket type was requested.
1400 .P
1401 Other errors may be generated by the overlaying protocols; see
1402 .BR tcp (7),
1403 .BR raw (7),
1404 .BR udp (7),
1405 and
1406 .BR socket (7).
1407 .SH NOTES
1408 .BR IP_FREEBIND ,
1409 .BR IP_MSFILTER ,
1410 .BR IP_MTU ,
1411 .BR IP_MTU_DISCOVER ,
1412 .BR IP_RECVORIGDSTADDR ,
1413 .BR IP_PASSSEC ,
1414 .BR IP_PKTINFO ,
1415 .BR IP_RECVERR ,
1416 .BR IP_ROUTER_ALERT ,
1417 and
1418 .B IP_TRANSPARENT
1419 are Linux-specific.
1420 .\" IP_XFRM_POLICY is Linux-specific
1421 .\" IP_IPSEC_POLICY is a nonstandard extension, also present on some BSDs
1422 .P
1423 Be very careful with the
1424 .B SO_BROADCAST
1425 option \- it is not privileged in Linux.
1426 It is easy to overload the network
1427 with careless broadcasts.
1428 For new application protocols
1429 it is better to use a multicast group instead of broadcasting.
1430 Broadcasting is discouraged.
1431 See RFC 6762 for an example of a protocol (mDNS)
1432 using the more modern multicast approach
1433 to communicating with an open-ended
1434 group of hosts on the local network.
1435 .P
1436 Some other BSD sockets implementations provide
1437 .B IP_RCVDSTADDR
1438 and
1439 .B IP_RECVIF
1440 socket options to get the destination address and the interface of
1441 received datagrams.
1442 Linux has the more general
1443 .B IP_PKTINFO
1444 for the same task.
1445 .P
1446 Some BSD sockets implementations also provide an
1447 .B IP_RECVTTL
1448 option, but an ancillary message with type
1449 .B IP_RECVTTL
1450 is passed with the incoming packet.
1451 This is different from the
1452 .B IP_TTL
1453 option used in Linux.
1454 .P
1455 Using the
1456 .B SOL_IP
1457 socket options level isn't portable; BSD-based stacks use the
1458 .B IPPROTO_IP
1459 level.
1460 .P
1461 .B INADDR_ANY
1462 (0.0.0.0) and
1463 .B INADDR_BROADCAST
1464 (255.255.255.255) are byte-order-neutral.
1465 This means
1466 .BR htonl (3)
1467 has no effect on them.
1468 .SS Compatibility
1469 For compatibility with Linux 2.0, the obsolete
1470 .BI "socket(AF_INET, SOCK_PACKET, " protocol )
1471 syntax is still supported to open a
1472 .BR packet (7)
1473 socket.
1474 This is deprecated and should be replaced by
1475 .BI "socket(AF_PACKET, SOCK_RAW, " protocol )
1476 instead.
1477 The main difference is the new
1478 .I sockaddr_ll
1479 address structure for generic link layer information instead of the old
1480 .BR sockaddr_pkt .
1481 .SH BUGS
1482 There are too many inconsistent error values.
1483 .P
1484 The error used to diagnose exhaustion of the ephemeral port range differs
1485 across the various system calls
1486 .RB ( connect (2),
1487 .BR bind (2),
1488 .BR listen (2),
1489 .BR sendto (2))
1490 that can assign ephemeral ports.
1491 .P
1492 The ioctls to configure IP-specific interface options and ARP tables are
1493 not described.
1494 .\" .P
1495 .\" Some versions of glibc forget to declare
1496 .\" .IR in_pktinfo .
1497 .\" Workaround currently is to copy it into your program from this man page.
1498 .P
1499 Receiving the original destination address with
1500 .B MSG_ERRQUEUE
1501 in
1502 .I msg_name
1503 by
1504 .BR recvmsg (2)
1505 does not work in some Linux 2.2 kernels.
1506 .\" .SH AUTHORS
1507 .\" This man page was written by Andi Kleen.
1508 .SH SEE ALSO
1509 .BR recvmsg (2),
1510 .BR sendmsg (2),
1511 .BR byteorder (3),
1512 .BR capabilities (7),
1513 .BR icmp (7),
1514 .BR ipv6 (7),
1515 .BR netdevice (7),
1516 .BR netlink (7),
1517 .BR raw (7),
1518 .BR socket (7),
1519 .BR tcp (7),
1520 .BR udp (7),
1521 .BR ip (8)
1522 .P
1523 The kernel source file
1524 .IR Documentation/networking/ip\-sysctl.txt .
1525 .P
1526 RFC\ 791 for the original IP specification.
1527 RFC\ 1122 for the IPv4 host requirements.
1528 RFC\ 1812 for the IPv4 router requirements.