man7/ip.7

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