1.\" $NetBSD: ip.4,v 1.23 2008/09/23 14:58:05 briggs Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)ip.4 8.2 (Berkeley) 11/30/93 31.\" 32.Dd September 23, 2008 33.Dt IP 4 34.Os 35.Sh NAME 36.Nm ip 37.Nd Internet Protocol 38.Sh SYNOPSIS 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 network layer protocol used by the Internet protocol family. 46Options may be set at the 47.Tn IP 48level when using higher-level protocols that are based on 49.Tn IP 50(such as 51.Tn TCP 52and 53.Tn UDP ) . 54It may also be accessed through a 55.Dq raw socket 56when developing new protocols, or special-purpose applications. 57.Pp 58There are several 59.Tn IP-level 60.Xr setsockopt 2 Ns / Ns Xr getsockopt 2 61options. 62.Dv IP_OPTIONS 63may be used to provide 64.Tn IP 65options to be transmitted in the 66.Tn IP 67header of each outgoing packet 68or to examine the header options on incoming packets. 69.Tn IP 70options may be used with any socket type in the Internet family. 71The format of 72.Tn IP 73options to be sent is that specified by the 74.Tn IP 75protocol specification (RFC 791), with one exception: 76the list of addresses for Source Route options must include the first-hop 77gateway at the beginning of the list of gateways. 78The first-hop gateway address will be extracted from the option list 79and the size adjusted accordingly before use. 80To disable previously specified options, use a zero-length buffer: 81.Bd -literal 82setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 83.Ed 84.Pp 85.Dv IP_TOS 86and 87.Dv IP_TTL 88may be used to set the type-of-service and time-to-live fields in the 89.Tn IP 90header for 91.Dv SOCK_STREAM 92and 93.Dv SOCK_DGRAM 94sockets. 95For example, 96.Bd -literal 97int tos = IPTOS_LOWDELAY; /* see \*[Lt]netinet/ip.h\*[Gt] */ 98setsockopt(s, IPPROTO_IP, IP_TOS, \*[Am]tos, sizeof(tos)); 99 100int ttl = 60; /* max = 255 */ 101setsockopt(s, IPPROTO_IP, IP_TTL, \*[Am]ttl, sizeof(ttl)); 102.Ed 103.Pp 104.Dv IP_IPSEC_POLICY 105controls IPSec policy for sockets. 106For example, 107.Bd -literal 108const char *policy = "in ipsec ah/transport//require"; 109char *buf = ipsec_set_policy(policy, strlen(policy)); 110setsockopt(s, IPPROTO_IP, IP_IPSEC_POLICY, buf, ipsec_get_policylen(buf)); 111.Ed 112.Pp 113.Dv IP_PORTRANGE 114controls how ephemeral ports are allocated for 115.Dv SOCK_STREAM 116and 117.Dv SOCK_DGRAM 118sockets. For example, 119.Bd -literal 120int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */ 121setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range)); 122.Ed 123.Pp 124If the 125.Dv IP_RECVDSTADDR 126option is enabled on a 127.Dv SOCK_DGRAM 128or 129.Dv SOCK_RAW 130socket, 131the 132.Xr recvmsg 2 133call will return the destination 134.Tn IP 135address for a 136.Tn UDP 137datagram. 138The msg_control field in the msghdr structure points to a buffer 139that contains a cmsghdr structure followed by the 140.Tn IP 141address. 142The cmsghdr fields have the following values: 143.Bd -literal 144cmsg_len = sizeof(struct in_addr) 145cmsg_level = IPPROTO_IP 146cmsg_type = IP_RECVDSTADDR 147.Ed 148.Pp 149If the 150.Dv IP_RECVIF 151option is enabled on a 152.Dv SOCK_DGRAM 153or 154.Dv SOCK_RAW 155socket, 156the 157.Xr recvmsg 2 158call will return a struct sockaddr_dl corresponding to 159the interface on which the packet was received. 160the msg_control field in the msghdr structure points to a buffer 161that contains a cmsghdr structure followed by the struct sockaddr_dl. 162The cmsghdr fields have the following values: 163.Bd -literal 164cmsg_len = sizeof(struct sockaddr_dl) 165cmsg_level = IPPROTO_IP 166cmsg_type = IP_RECVIF 167.Ed 168.Ss MULTICAST OPTIONS 169.Tn IP 170multicasting is supported only on 171.Dv AF_INET 172sockets of type 173.Dv SOCK_DGRAM 174and 175.Dv SOCK_RAW , 176and only on networks where the interface driver supports multicasting. 177.Pp 178The 179.Dv IP_MULTICAST_TTL 180option changes the time-to-live (TTL) for outgoing multicast datagrams 181in order to control the scope of the multicasts: 182.Bd -literal 183u_char ttl; /* range: 0 to 255, default = 1 */ 184setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl)); 185.Ed 186.Pp 187Datagrams with a TTL of 1 are not forwarded beyond the local network. 188Multicast datagrams with a TTL of 0 will not be transmitted on any network, 189but may be delivered locally if the sending host belongs to the destination 190group and if multicast loopback has not been disabled on the sending socket 191(see below). 192Multicast datagrams with TTL greater than 1 may be forwarded 193to other networks if a multicast router is attached to the local network. 194.Pp 195For hosts with multiple interfaces, each multicast transmission is 196sent from the primary network interface. 197The 198.Dv IP_MULTICAST_IF 199option overrides the default for 200subsequent transmissions from a given socket: 201.Bd -literal 202struct in_addr addr; 203setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr)); 204.Ed 205.Pp 206where "addr" is the local 207.Tn IP 208address of the desired interface or 209.Dv INADDR_ANY 210to specify the default interface. 211An interface's local IP address and multicast capability can 212be obtained via the 213.Dv SIOCGIFCONF 214and 215.Dv SIOCGIFFLAGS 216ioctls. 217An application may also specify an alternative to the default network interface 218by index: 219.Bd -literal 220struct uint32_t idx = htonl(ifindex); 221setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx)); 222.Ed 223.Pp 224where "ifindex" is an interface index as returned by 225.Xr if_nametoindex 3 . 226.Pp 227Normal applications should not need to use 228.Dv IP_MULTICAST_IF . 229.Pp 230If a multicast datagram is sent to a group to which the sending host itself 231belongs (on the outgoing interface), a copy of the datagram is, by default, 232looped back by the IP layer for local delivery. 233The 234.Dv IP_MULTICAST_LOOP 235option gives the sender explicit control 236over whether or not subsequent datagrams are looped back: 237.Bd -literal 238u_char loop; /* 0 = disable, 1 = enable (default) */ 239setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop)); 240.Ed 241.Pp 242This option 243improves performance for applications that may have no more than one 244instance on a single host (such as a router demon), by eliminating 245the overhead of receiving their own transmissions. 246It should generally not be used by applications for which there 247may be more than one instance on a single host (such as a conferencing 248program) or for which the sender does not belong to the destination 249group (such as a time querying program). 250.Pp 251A multicast datagram sent with an initial TTL greater than 1 may be delivered 252to the sending host on a different interface from that on which it was sent, 253if the host belongs to the destination group on that other interface. 254The loopback control option has no effect on such delivery. 255.Pp 256A host must become a member of a multicast group before it can receive 257datagrams sent to the group. 258To join a multicast group, use the 259.Dv IP_ADD_MEMBERSHIP 260option: 261.Bd -literal 262struct ip_mreq mreq; 263setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 264.Ed 265.Pp 266where 267.Fa mreq 268is the following structure: 269.Bd -literal 270struct ip_mreq { 271 struct in_addr imr_multiaddr; /* multicast group to join */ 272 struct in_addr imr_interface; /* interface to join on */ 273} 274.Ed 275.Pp 276.Dv imr_interface 277should be 278.Dv INADDR_ANY 279to choose the default multicast interface, or the 280.Tn IP 281address of a particular multicast-capable interface if 282the host is multihomed. 283Membership is associated with a single interface; 284programs running on multihomed hosts may need to 285join the same group on more than one interface. 286Up to 287.Dv IP_MAX_MEMBERSHIPS 288(currently 20) memberships may be added on a single socket. 289.Pp 290To drop a membership, use: 291.Bd -literal 292struct ip_mreq mreq; 293setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 294.Ed 295.Pp 296where 297.Fa mreq 298contains the same values as used to add the membership. 299Memberships are dropped when the socket is closed or the process exits. 300.\"----------------------- 301.Ss RAW IP SOCKETS 302Raw 303.Tn IP 304sockets are connectionless, and are normally used with the 305.Xr sendto 2 306and 307.Xr recvfrom 2 308calls, though the 309.Xr connect 2 310call may also be used to fix the destination for future 311packets (in which case the 312.Xr read 2 313or 314.Xr recv 2 315and 316.Xr write 2 317or 318.Xr send 2 319system calls may be used). 320.Pp 321If 322.Fa proto 323is 0, the default protocol 324.Dv IPPROTO_RAW 325is used for outgoing packets, and only incoming packets destined 326for that protocol are received. 327If 328.Fa proto 329is non-zero, that protocol number will be used on outgoing packets 330and to filter incoming packets. 331.Pp 332Outgoing packets automatically have an 333.Tn IP 334header prepended to them (based on the destination address and the 335protocol number the socket is created with), unless the 336.Dv IP_HDRINCL 337option has been set. 338Incoming packets are received with 339.Tn IP 340header and options intact. 341.Pp 342.Dv IP_HDRINCL 343indicates the complete IP header is included with the data and may 344be used only with the 345.Dv SOCK_RAW 346type. 347.Bd -literal 348#include \*[Lt]netinet/ip.h\*[Gt] 349 350int hincl = 1; /* 1 = on, 0 = off */ 351setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl)); 352.Ed 353.Pp 354Unlike previous 355.Bx 356releases, the program must set all 357the fields of the IP header, including the following: 358.Bd -literal 359ip-\*[Gt]ip_v = IPVERSION; 360ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2; 361ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */ 362ip-\*[Gt]ip_off = offset; 363.Ed 364.Pp 365If the header source address is set to 366.Dv INADDR_ANY , 367the kernel will choose an appropriate address. 368.Sh DIAGNOSTICS 369A socket operation may fail with one of the following errors returned: 370.Bl -tag -width [EADDRNOTAVAIL] 371.It Bq Er EISCONN 372when trying to establish a connection on a socket which already 373has one, or when trying to send a datagram with the destination 374address specified and the socket is already connected; 375.It Bq Er ENOTCONN 376when trying to send a datagram, but no destination address is 377specified, and the socket hasn't been connected; 378.It Bq Er ENOBUFS 379when the system runs out of memory for an internal data structure; 380.It Bq Er EADDRNOTAVAIL 381when an attempt is made to create a socket with a network address 382for which no network interface exists. 383.It Bq Er EACCES 384when an attempt is made to create a raw IP socket by a non-privileged process. 385.El 386.Pp 387The following errors specific to 388.Tn IP 389may occur when setting or getting 390.Tn IP 391options: 392.Bl -tag -width EADDRNOTAVAILxx 393.It Bq Er EINVAL 394An unknown socket option name was given. 395.It Bq Er EINVAL 396The IP option field was improperly formed; an option field was 397shorter than the minimum value or longer than the option buffer provided. 398.El 399.Sh SEE ALSO 400.Xr getsockopt 2 , 401.Xr recv 2 , 402.Xr send 2 , 403.Xr ipsec_set_policy 3 , 404.Xr icmp 4 , 405.Xr inet 4 , 406.Xr intro 4 407.Rs 408.%R RFC 409.%N 791 410.%D September 1981 411.%T "Internet Protocol" 412.Re 413.Rs 414.%R RFC 415.%N 1112 416.%D August 1989 417.%T "Host Extensions for IP Multicasting" 418.Re 419.Rs 420.%R RFC 421.%N 1122 422.%D October 1989 423.%T "Requirements for Internet Hosts -- Communication Layers" 424.Re 425.Sh HISTORY 426The 427.Nm 428protocol appeared in 429.Bx 4.2 . 430