1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)ip.4 8.2 (Berkeley) 11/30/93 29.\" $FreeBSD$ 30.\" 31.Dd September 1, 2014 32.Dt IP 4 33.Os 34.Sh NAME 35.Nm ip 36.Nd Internet Protocol 37.Sh SYNOPSIS 38.In sys/types.h 39.In sys/socket.h 40.In netinet/in.h 41.Ft int 42.Fn socket AF_INET SOCK_RAW proto 43.Sh DESCRIPTION 44.Tn IP 45is the transport layer protocol used 46by the Internet protocol family. 47Options may be set at the 48.Tn IP 49level 50when using higher-level protocols that are based on 51.Tn IP 52(such as 53.Tn TCP 54and 55.Tn UDP ) . 56It may also be accessed 57through a 58.Dq raw socket 59when developing new protocols, or 60special-purpose applications. 61.Pp 62There are several 63.Tn IP-level 64.Xr setsockopt 2 65and 66.Xr getsockopt 2 67options. 68.Dv IP_OPTIONS 69may be used to provide 70.Tn IP 71options to be transmitted in the 72.Tn IP 73header of each outgoing packet 74or to examine the header options on incoming packets. 75.Tn IP 76options may be used with any socket type in the Internet family. 77The format of 78.Tn IP 79options to be sent is that specified by the 80.Tn IP 81protocol specification (RFC-791), with one exception: 82the list of addresses for Source Route options must include the first-hop 83gateway at the beginning of the list of gateways. 84The first-hop gateway address will be extracted from the option list 85and the size adjusted accordingly before use. 86To disable previously specified options, 87use a zero-length buffer: 88.Bd -literal 89setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 90.Ed 91.Pp 92.Dv IP_TOS 93and 94.Dv IP_TTL 95may be used to set the type-of-service and time-to-live 96fields in the 97.Tn IP 98header for 99.Dv SOCK_STREAM , SOCK_DGRAM , 100and certain types of 101.Dv SOCK_RAW 102sockets. 103For example, 104.Bd -literal 105int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */ 106setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); 107 108int ttl = 60; /* max = 255 */ 109setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); 110.Ed 111.Pp 112.Dv IP_MINTTL 113may be used to set the minimum acceptable TTL a packet must have when 114received on a socket. 115All packets with a lower TTL are silently dropped. 116This option is only really useful when set to 255, preventing packets 117from outside the directly connected networks reaching local listeners 118on sockets. 119.Pp 120.Dv IP_DONTFRAG 121may be used to set the Don't Fragment flag on IP packets. 122Currently this option is respected only on 123.Xr udp 4 124and raw 125.Nm 126sockets, unless the 127.Dv IP_HDRINCL 128option has been set. 129On 130.Xr tcp 4 131sockets, the Don't Fragment flag is controlled by the Path 132MTU Discovery option. 133Sending a packet larger than the MTU size of the egress interface, 134determined by the destination address, returns an 135.Er EMSGSIZE 136error. 137.Pp 138If the 139.Dv IP_ORIGDSTADDR 140option is enabled on a 141.Dv SOCK_DGRAM 142socket, 143the 144.Xr recvmsg 2 145call will return the destination 146.Tn IP 147address and destination port or a 148.Tn UDP 149datagram. 150The 151.Vt msg_control 152field in the 153.Vt msghdr 154structure points to a buffer 155that contains a 156.Vt cmsghdr 157structure followed by the 158.Tn in_sockkaddr 159structre. 160The 161.Vt cmsghdr 162fields have the following values: 163.Bd -literal 164cmsg_len = CMSG_LEN(sizeof(struct in_sockaddr)) 165cmsg_level = IPPROTO_IP 166cmsg_type = IP_ORIGDSTADDR 167.Ed 168.Pp 169If the 170.Dv IP_RECVDSTADDR 171option is enabled on a 172.Dv SOCK_DGRAM 173socket, 174the 175.Xr recvmsg 2 176call will return the destination 177.Tn IP 178address for a 179.Tn UDP 180datagram. 181The 182.Vt msg_control 183field in the 184.Vt msghdr 185structure points to a buffer 186that contains a 187.Vt cmsghdr 188structure followed by the 189.Tn IP 190address. 191The 192.Vt cmsghdr 193fields have the following values: 194.Bd -literal 195cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 196cmsg_level = IPPROTO_IP 197cmsg_type = IP_RECVDSTADDR 198.Ed 199.Pp 200The source address to be used for outgoing 201.Tn UDP 202datagrams on a socket can be specified as ancillary data with a type code of 203.Dv IP_SENDSRCADDR . 204The msg_control field in the msghdr structure should point to a buffer 205that contains a 206.Vt cmsghdr 207structure followed by the 208.Tn IP 209address. 210The cmsghdr fields should have the following values: 211.Bd -literal 212cmsg_len = CMSG_LEN(sizeof(struct in_addr)) 213cmsg_level = IPPROTO_IP 214cmsg_type = IP_SENDSRCADDR 215.Ed 216.Pp 217The socket should be either bound to 218.Dv INADDR_ANY 219and a local port, and the address supplied with 220.Dv IP_SENDSRCADDR 221should't be 222.Dv INADDR_ANY , 223or the socket should be bound to a local address and the address supplied with 224.Dv IP_SENDSRCADDR 225should be 226.Dv INADDR_ANY . 227In the latter case bound address is overriden via generic source address 228selection logic, which would choose IP address of interface closest to 229destination. 230.Pp 231For convenience, 232.Dv IP_SENDSRCADDR 233is defined to have the same value as 234.Dv IP_RECVDSTADDR , 235so the 236.Dv IP_RECVDSTADDR 237control message from 238.Xr recvmsg 2 239can be used directly as a control message for 240.Xr sendmsg 2 . 241.\" 242.Pp 243If the 244.Dv IP_ONESBCAST 245option is enabled on a 246.Dv SOCK_DGRAM 247or a 248.Dv SOCK_RAW 249socket, the destination address of outgoing 250broadcast datagrams on that socket will be forced 251to the undirected broadcast address, 252.Dv INADDR_BROADCAST , 253before transmission. 254This is in contrast to the default behavior of the 255system, which is to transmit undirected broadcasts 256via the first network interface with the 257.Dv IFF_BROADCAST 258flag set. 259.Pp 260This option allows applications to choose which 261interface is used to transmit an undirected broadcast 262datagram. 263For example, the following code would force an 264undirected broadcast to be transmitted via the interface 265configured with the broadcast address 192.168.2.255: 266.Bd -literal 267char msg[512]; 268struct sockaddr_in sin; 269int onesbcast = 1; /* 0 = disable (default), 1 = enable */ 270 271setsockopt(s, IPPROTO_IP, IP_ONESBCAST, &onesbcast, sizeof(onesbcast)); 272sin.sin_addr.s_addr = inet_addr("192.168.2.255"); 273sin.sin_port = htons(1234); 274sendto(s, msg, sizeof(msg), 0, &sin, sizeof(sin)); 275.Ed 276.Pp 277It is the application's responsibility to set the 278.Dv IP_TTL 279option 280to an appropriate value in order to prevent broadcast storms. 281The application must have sufficient credentials to set the 282.Dv SO_BROADCAST 283socket level option, otherwise the 284.Dv IP_ONESBCAST 285option has no effect. 286.Pp 287If the 288.Dv IP_BINDANY 289option is enabled on a 290.Dv SOCK_STREAM , 291.Dv SOCK_DGRAM 292or a 293.Dv SOCK_RAW 294socket, one can 295.Xr bind 2 296to any address, even one not bound to any available network interface in the 297system. 298This functionality (in conjunction with special firewall rules) can be used for 299implementing a transparent proxy. 300The 301.Dv PRIV_NETINET_BINDANY 302privilege is needed to set this option. 303.Pp 304If the 305.Dv IP_RECVTTL 306option is enabled on a 307.Dv SOCK_DGRAM 308socket, the 309.Xr recvmsg 2 310call will return the 311.Tn IP 312.Tn TTL 313(time to live) field for a 314.Tn UDP 315datagram. 316The msg_control field in the msghdr structure points to a buffer 317that contains a cmsghdr structure followed by the 318.Tn TTL . 319The cmsghdr fields have the following values: 320.Bd -literal 321cmsg_len = CMSG_LEN(sizeof(u_char)) 322cmsg_level = IPPROTO_IP 323cmsg_type = IP_RECVTTL 324.Ed 325.\" 326.Pp 327If the 328.Dv IP_RECVTOS 329option is enabled on a 330.Dv SOCK_DGRAM 331socket, the 332.Xr recvmsg 2 333call will return the 334.Tn IP 335.Tn TOS 336(type of service) field for a 337.Tn UDP 338datagram. 339The msg_control field in the msghdr structure points to a buffer 340that contains a cmsghdr structure followed by the 341.Tn TOS . 342The cmsghdr fields have the following values: 343.Bd -literal 344cmsg_len = CMSG_LEN(sizeof(u_char)) 345cmsg_level = IPPROTO_IP 346cmsg_type = IP_RECVTOS 347.Ed 348.\" 349.Pp 350If the 351.Dv IP_RECVIF 352option is enabled on a 353.Dv SOCK_DGRAM 354socket, the 355.Xr recvmsg 2 356call returns a 357.Vt "struct sockaddr_dl" 358corresponding to the interface on which the 359packet was received. 360The 361.Va msg_control 362field in the 363.Vt msghdr 364structure points to a buffer that contains a 365.Vt cmsghdr 366structure followed by the 367.Vt "struct sockaddr_dl" . 368The 369.Vt cmsghdr 370fields have the following values: 371.Bd -literal 372cmsg_len = CMSG_LEN(sizeof(struct sockaddr_dl)) 373cmsg_level = IPPROTO_IP 374cmsg_type = IP_RECVIF 375.Ed 376.Pp 377.Dv IP_PORTRANGE 378may be used to set the port range used for selecting a local port number 379on a socket with an unspecified (zero) port number. 380It has the following 381possible values: 382.Bl -tag -width IP_PORTRANGE_DEFAULT 383.It Dv IP_PORTRANGE_DEFAULT 384use the default range of values, normally 385.Dv IPPORT_HIFIRSTAUTO 386through 387.Dv IPPORT_HILASTAUTO . 388This is adjustable through the sysctl setting: 389.Va net.inet.ip.portrange.first 390and 391.Va net.inet.ip.portrange.last . 392.It Dv IP_PORTRANGE_HIGH 393use a high range of values, normally 394.Dv IPPORT_HIFIRSTAUTO 395and 396.Dv IPPORT_HILASTAUTO . 397This is adjustable through the sysctl setting: 398.Va net.inet.ip.portrange.hifirst 399and 400.Va net.inet.ip.portrange.hilast . 401.It Dv IP_PORTRANGE_LOW 402use a low range of ports, which are normally restricted to 403privileged processes on 404.Ux 405systems. 406The range is normally from 407.Dv IPPORT_RESERVED 408\- 1 down to 409.Li IPPORT_RESERVEDSTART 410in descending order. 411This is adjustable through the sysctl setting: 412.Va net.inet.ip.portrange.lowfirst 413and 414.Va net.inet.ip.portrange.lowlast . 415.El 416.Pp 417The range of privileged ports which only may be opened by 418root-owned processes may be modified by the 419.Va net.inet.ip.portrange.reservedlow 420and 421.Va net.inet.ip.portrange.reservedhigh 422sysctl settings. 423The values default to the traditional range, 4240 through 425.Dv IPPORT_RESERVED 426\- 1 427(0 through 1023), respectively. 428Note that these settings do not affect and are not accounted for in the 429use or calculation of the other 430.Va net.inet.ip.portrange 431values above. 432Changing these values departs from 433.Ux 434tradition and has security 435consequences that the administrator should carefully evaluate before 436modifying these settings. 437.Pp 438Ports are allocated at random within the specified port range in order 439to increase the difficulty of random spoofing attacks. 440In scenarios such as benchmarking, this behavior may be undesirable. 441In these cases, 442.Va net.inet.ip.portrange.randomized 443can be used to toggle randomization off. 444If more than 445.Va net.inet.ip.portrange.randomcps 446ports have been allocated in the last second, then return to sequential 447port allocation. 448Return to random allocation only once the current port allocation rate 449drops below 450.Va net.inet.ip.portrange.randomcps 451for at least 452.Va net.inet.ip.portrange.randomtime 453seconds. 454The default values for 455.Va net.inet.ip.portrange.randomcps 456and 457.Va net.inet.ip.portrange.randomtime 458are 10 port allocations per second and 45 seconds correspondingly. 459.Ss "Multicast Options" 460.Tn IP 461multicasting is supported only on 462.Dv AF_INET 463sockets of type 464.Dv SOCK_DGRAM 465and 466.Dv SOCK_RAW , 467and only on networks where the interface 468driver supports multicasting. 469.Pp 470The 471.Dv IP_MULTICAST_TTL 472option changes the time-to-live (TTL) 473for outgoing multicast datagrams 474in order to control the scope of the multicasts: 475.Bd -literal 476u_char ttl; /* range: 0 to 255, default = 1 */ 477setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 478.Ed 479.Pp 480Datagrams with a TTL of 1 are not forwarded beyond the local network. 481Multicast datagrams with a TTL of 0 will not be transmitted on any network, 482but may be delivered locally if the sending host belongs to the destination 483group and if multicast loopback has not been disabled on the sending socket 484(see below). 485Multicast datagrams with TTL greater than 1 may be forwarded 486to other networks if a multicast router is attached to the local network. 487.Pp 488For hosts with multiple interfaces, where an interface has not 489been specified for a multicast group membership, 490each multicast transmission is sent from the primary network interface. 491The 492.Dv IP_MULTICAST_IF 493option overrides the default for 494subsequent transmissions from a given socket: 495.Bd -literal 496struct in_addr addr; 497setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 498.Ed 499.Pp 500where "addr" is the local 501.Tn IP 502address of the desired interface or 503.Dv INADDR_ANY 504to specify the default interface. 505.Pp 506To specify an interface by index, an instance of 507.Vt ip_mreqn 508may be passed instead. 509The 510.Vt imr_ifindex 511member should be set to the index of the desired interface, 512or 0 to specify the default interface. 513The kernel differentiates between these two structures by their size. 514.Pp 515The use of 516.Vt IP_MULTICAST_IF 517is 518.Em not recommended , 519as multicast memberships are scoped to each 520individual interface. 521It is supported for legacy use only by applications, 522such as routing daemons, which expect to 523be able to transmit link-local IPv4 multicast datagrams (224.0.0.0/24) 524on multiple interfaces, 525without requesting an individual membership for each interface. 526.Pp 527.\" 528An interface's local IP address and multicast capability can 529be obtained via the 530.Dv SIOCGIFCONF 531and 532.Dv SIOCGIFFLAGS 533ioctls. 534Normal applications should not need to use this option. 535.Pp 536If a multicast datagram is sent to a group to which the sending host itself 537belongs (on the outgoing interface), a copy of the datagram is, by default, 538looped back by the IP layer for local delivery. 539The 540.Dv IP_MULTICAST_LOOP 541option gives the sender explicit control 542over whether or not subsequent datagrams are looped back: 543.Bd -literal 544u_char loop; /* 0 = disable, 1 = enable (default) */ 545setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 546.Ed 547.Pp 548This option 549improves performance for applications that may have no more than one 550instance on a single host (such as a routing daemon), by eliminating 551the overhead of receiving their own transmissions. 552It should generally not 553be used by applications for which there may be more than one instance on a 554single host (such as a conferencing program) or for which the sender does 555not belong to the destination group (such as a time querying program). 556.Pp 557The sysctl setting 558.Va net.inet.ip.mcast.loop 559controls the default setting of the 560.Dv IP_MULTICAST_LOOP 561socket option for new sockets. 562.Pp 563A multicast datagram sent with an initial TTL greater than 1 may be delivered 564to the sending host on a different interface from that on which it was sent, 565if the host belongs to the destination group on that other interface. 566The loopback control option has no effect on such delivery. 567.Pp 568A host must become a member of a multicast group before it can receive 569datagrams sent to the group. 570To join a multicast group, use the 571.Dv IP_ADD_MEMBERSHIP 572option: 573.Bd -literal 574struct ip_mreq mreq; 575setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 576.Ed 577.Pp 578where 579.Fa mreq 580is the following structure: 581.Bd -literal 582struct ip_mreq { 583 struct in_addr imr_multiaddr; /* IP multicast address of group */ 584 struct in_addr imr_interface; /* local IP address of interface */ 585} 586.Ed 587.Pp 588.Va imr_interface 589should be set to the 590.Tn IP 591address of a particular multicast-capable interface if 592the host is multihomed. 593It may be set to 594.Dv INADDR_ANY 595to choose the default interface, although this is not recommended; 596this is considered to be the first interface corresponding 597to the default route. 598Otherwise, the first multicast-capable interface 599configured in the system will be used. 600.Pp 601Prior to 602.Fx 7.0 , 603if the 604.Va imr_interface 605member is within the network range 606.Li 0.0.0.0/8 , 607it is treated as an interface index in the system interface MIB, 608as per the RIP Version 2 MIB Extension (RFC-1724). 609In versions of 610.Fx 611since 7.0, this behavior is no longer supported. 612Developers should 613instead use the RFC 3678 multicast source filter APIs; in particular, 614.Dv MCAST_JOIN_GROUP . 615.Pp 616Up to 617.Dv IP_MAX_MEMBERSHIPS 618memberships may be added on a single socket. 619Membership is associated with a single interface; 620programs running on multihomed hosts may need to 621join the same group on more than one interface. 622.Pp 623To drop a membership, use: 624.Bd -literal 625struct ip_mreq mreq; 626setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 627.Ed 628.Pp 629where 630.Fa mreq 631contains the same values as used to add the membership. 632Memberships are dropped when the socket is closed or the process exits. 633.\" TODO: Update this piece when IPv4 source-address selection is implemented. 634.Pp 635The IGMP protocol uses the primary IP address of the interface 636as its identifier for group membership. 637This is the first IP address configured on the interface. 638If this address is removed or changed, the results are 639undefined, as the IGMP membership state will then be inconsistent. 640If multiple IP aliases are configured on the same interface, 641they will be ignored. 642.Pp 643This shortcoming was addressed in IPv6; MLDv2 requires 644that the unique link-local address for an interface is 645used to identify an MLDv2 listener. 646.Ss "Source-Specific Multicast Options" 647Since 648.Fx 8.0 , 649the use of Source-Specific Multicast (SSM) is supported. 650These extensions require an IGMPv3 multicast router in order to 651make best use of them. 652If a legacy multicast router is present on the link, 653.Fx 654will simply downgrade to the version of IGMP spoken by the router, 655and the benefits of source filtering on the upstream link 656will not be present, although the kernel will continue to 657squelch transmissions from blocked sources. 658.Pp 659Each group membership on a socket now has a filter mode: 660.Bl -tag -width MCAST_EXCLUDE 661.It Dv MCAST_EXCLUDE 662Datagrams sent to this group are accepted, 663unless the source is in a list of blocked source addresses. 664.It Dv MCAST_INCLUDE 665Datagrams sent to this group are accepted 666only if the source is in a list of accepted source addresses. 667.El 668.Pp 669Groups joined using the legacy 670.Dv IP_ADD_MEMBERSHIP 671option are placed in exclusive-mode, 672and are able to request that certain sources are blocked or allowed. 673This is known as the 674.Em delta-based API . 675.Pp 676To block a multicast source on an existing group membership: 677.Bd -literal 678struct ip_mreq_source mreqs; 679setsockopt(s, IPPROTO_IP, IP_BLOCK_SOURCE, &mreqs, sizeof(mreqs)); 680.Ed 681.Pp 682where 683.Fa mreqs 684is the following structure: 685.Bd -literal 686struct ip_mreq_source { 687 struct in_addr imr_multiaddr; /* IP multicast address of group */ 688 struct in_addr imr_sourceaddr; /* IP address of source */ 689 struct in_addr imr_interface; /* local IP address of interface */ 690} 691.Ed 692.Va imr_sourceaddr 693should be set to the address of the source to be blocked. 694.Pp 695To unblock a multicast source on an existing group: 696.Bd -literal 697struct ip_mreq_source mreqs; 698setsockopt(s, IPPROTO_IP, IP_UNBLOCK_SOURCE, &mreqs, sizeof(mreqs)); 699.Ed 700.Pp 701The 702.Dv IP_BLOCK_SOURCE 703and 704.Dv IP_UNBLOCK_SOURCE 705options are 706.Em not permitted 707for inclusive-mode group memberships. 708.Pp 709To join a multicast group in 710.Dv MCAST_INCLUDE 711mode with a single source, 712or add another source to an existing inclusive-mode membership: 713.Bd -literal 714struct ip_mreq_source mreqs; 715setsockopt(s, IPPROTO_IP, IP_ADD_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); 716.Ed 717.Pp 718To leave a single source from an existing group in inclusive mode: 719.Bd -literal 720struct ip_mreq_source mreqs; 721setsockopt(s, IPPROTO_IP, IP_DROP_SOURCE_MEMBERSHIP, &mreqs, sizeof(mreqs)); 722.Ed 723If this is the last accepted source for the group, the membership 724will be dropped. 725.Pp 726The 727.Dv IP_ADD_SOURCE_MEMBERSHIP 728and 729.Dv IP_DROP_SOURCE_MEMBERSHIP 730options are 731.Em not accepted 732for exclusive-mode group memberships. 733However, both exclusive and inclusive mode memberships 734support the use of the 735.Em full-state API 736documented in RFC 3678. 737For management of source filter lists using this API, 738please refer to 739.Xr sourcefilter 3 . 740.Pp 741The sysctl settings 742.Va net.inet.ip.mcast.maxsocksrc 743and 744.Va net.inet.ip.mcast.maxgrpsrc 745are used to specify an upper limit on the number of per-socket and per-group 746source filter entries which the kernel may allocate. 747.\"----------------------- 748.Ss "Raw IP Sockets" 749Raw 750.Tn IP 751sockets are connectionless, 752and are normally used with the 753.Xr sendto 2 754and 755.Xr recvfrom 2 756calls, though the 757.Xr connect 2 758call may also be used to fix the destination for future 759packets (in which case the 760.Xr read 2 761or 762.Xr recv 2 763and 764.Xr write 2 765or 766.Xr send 2 767system calls may be used). 768.Pp 769If 770.Fa proto 771is 0, the default protocol 772.Dv IPPROTO_RAW 773is used for outgoing 774packets, and only incoming packets destined for that protocol 775are received. 776If 777.Fa proto 778is non-zero, that protocol number will be used on outgoing packets 779and to filter incoming packets. 780.Pp 781Outgoing packets automatically have an 782.Tn IP 783header prepended to 784them (based on the destination address and the protocol 785number the socket is created with), 786unless the 787.Dv IP_HDRINCL 788option has been set. 789Unlike in previous 790.Bx 791releases, incoming packets are received with 792.Tn IP 793header and options intact, leaving all fields in network byte order. 794.Pp 795.Dv IP_HDRINCL 796indicates the complete IP header is included with the data 797and may be used only with the 798.Dv SOCK_RAW 799type. 800.Bd -literal 801#include <netinet/in_systm.h> 802#include <netinet/ip.h> 803 804int hincl = 1; /* 1 = on, 0 = off */ 805setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 806.Ed 807.Pp 808Unlike previous 809.Bx 810releases, the program must set all 811the fields of the IP header, including the following: 812.Bd -literal 813ip->ip_v = IPVERSION; 814ip->ip_hl = hlen >> 2; 815ip->ip_id = 0; /* 0 means kernel set appropriate value */ 816ip->ip_off = htons(offset); 817ip->ip_len = htons(len); 818.Ed 819.Pp 820The packet should be provided as is to be sent over wire. 821This implies all fields, including 822.Va ip_len 823and 824.Va ip_off 825to be in network byte order. 826See 827.Xr byteorder 3 828for more information on network byte order. 829If the 830.Va ip_id 831field is set to 0 then the kernel will choose an 832appropriate value. 833If the header source address is set to 834.Dv INADDR_ANY , 835the kernel will choose an appropriate address. 836.Sh ERRORS 837A socket operation may fail with one of the following errors returned: 838.Bl -tag -width Er 839.It Bq Er EISCONN 840when trying to establish a connection on a socket which 841already has one, or when trying to send a datagram with the destination 842address specified and the socket is already connected; 843.It Bq Er ENOTCONN 844when trying to send a datagram, but 845no destination address is specified, and the socket has not been 846connected; 847.It Bq Er ENOBUFS 848when the system runs out of memory for 849an internal data structure; 850.It Bq Er EADDRNOTAVAIL 851when an attempt is made to create a 852socket with a network address for which no network interface 853exists. 854.It Bq Er EACCES 855when an attempt is made to create 856a raw IP socket by a non-privileged process. 857.El 858.Pp 859The following errors specific to 860.Tn IP 861may occur when setting or getting 862.Tn IP 863options: 864.Bl -tag -width Er 865.It Bq Er EINVAL 866An unknown socket option name was given. 867.It Bq Er EINVAL 868The IP option field was improperly formed; 869an option field was shorter than the minimum value 870or longer than the option buffer provided. 871.El 872.Pp 873The following errors may occur when attempting to send 874.Tn IP 875datagrams via a 876.Dq raw socket 877with the 878.Dv IP_HDRINCL 879option set: 880.Bl -tag -width Er 881.It Bq Er EINVAL 882The user-supplied 883.Va ip_len 884field was not equal to the length of the datagram written to the socket. 885.El 886.Sh SEE ALSO 887.Xr getsockopt 2 , 888.Xr recv 2 , 889.Xr send 2 , 890.Xr byteorder 3 , 891.Xr sourcefilter 3 , 892.Xr icmp 4 , 893.Xr igmp 4 , 894.Xr inet 4 , 895.Xr intro 4 , 896.Xr multicast 4 897.Rs 898.%A D. Thaler 899.%A B. Fenner 900.%A B. Quinn 901.%T "Socket Interface Extensions for Multicast Source Filters" 902.%N RFC 3678 903.%D Jan 2004 904.Re 905.Sh HISTORY 906The 907.Nm 908protocol appeared in 909.Bx 4.2 . 910The 911.Vt ip_mreqn 912structure appeared in 913.Tn Linux 2.4 . 914.Sh BUGS 915Before 916.Fx 10.0 917packets received on raw IP sockets had the 918.Va ip_hl 919subtracted from the 920.Va ip_len 921field. 922.Pp 923Before 924.Fx 11.0 925packets received on raw IP sockets had the 926.Va ip_len 927and 928.Va ip_off 929fields converted to host byte order. 930Packets written to raw IP sockets were expected to have 931.Va ip_len 932and 933.Va ip_off 934in host byte order. 935