1.\" $NetBSD: ip.4,v 1.19 2005/12/12 22:47:36 wiz 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 December 12, 2005 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/in.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_PORTRANGE 105controls how ephemeral ports are allocated for 106.Dv SOCK_STREAM 107and 108.Dv SOCK_DGRAM 109sockets. For example, 110.Bd -literal 111int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */ 112setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range)); 113.Ed 114.Pp 115If the 116.Dv IP_RECVDSTADDR 117option is enabled on a 118.Dv SOCK_DGRAM 119or 120.Dv SOCK_RAW 121socket, 122the 123.Xr recvmsg 2 124call will return the destination 125.Tn IP 126address for a 127.Tn UDP 128datagram. 129The msg_control field in the msghdr structure points to a buffer 130that contains a cmsghdr structure followed by the 131.Tn IP 132address. 133The cmsghdr fields have the following values: 134.Bd -literal 135cmsg_len = sizeof(struct in_addr) 136cmsg_level = IPPROTO_IP 137cmsg_type = IP_RECVDSTADDR 138.Ed 139.Pp 140If the 141.Dv IP_RECVIF 142option is enabled on a 143.Dv SOCK_DGRAM 144or 145.Dv SOCK_RAW 146socket, 147the 148.Xr recvmsg 2 149call will return a struct sockaddr_dl corresponding to 150the interface on which the packet was received. 151the msg_control field in the msghdr structure points to a buffer 152that contains a cmsghdr structure followed by the struct sockaddr_dl. 153The cmsghdr fields have the following values: 154.Bd -literal 155cmsg_len = sizeof(struct sockaddr_dl) 156cmsg_level = IPPROTO_IP 157cmsg_type = IP_RECVIF 158.Ed 159.Ss MULTICAST OPTIONS 160.Tn IP 161multicasting is supported only on 162.Dv AF_INET 163sockets of type 164.Dv SOCK_DGRAM 165and 166.Dv SOCK_RAW , 167and only on networks where the interface driver supports multicasting. 168.Pp 169The 170.Dv IP_MULTICAST_TTL 171option changes the time-to-live (TTL) for outgoing multicast datagrams 172in order to control the scope of the multicasts: 173.Bd -literal 174u_char ttl; /* range: 0 to 255, default = 1 */ 175setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl)); 176.Ed 177.Pp 178Datagrams with a TTL of 1 are not forwarded beyond the local network. 179Multicast datagrams with a TTL of 0 will not be transmitted on any network, 180but may be delivered locally if the sending host belongs to the destination 181group and if multicast loopback has not been disabled on the sending socket 182(see below). 183Multicast datagrams with TTL greater than 1 may be forwarded 184to other networks if a multicast router is attached to the local network. 185.Pp 186For hosts with multiple interfaces, each multicast transmission is 187sent from the primary network interface. 188The 189.Dv IP_MULTICAST_IF 190option overrides the default for 191subsequent transmissions from a given socket: 192.Bd -literal 193struct in_addr addr; 194setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr)); 195.Ed 196.Pp 197where "addr" is the local 198.Tn IP 199address of the desired interface or 200.Dv INADDR_ANY 201to specify the default interface. 202An interface's local IP address and multicast capability can 203be obtained via the 204.Dv SIOCGIFCONF 205and 206.Dv SIOCGIFFLAGS 207ioctls. 208An application may also specify an alternative to the default network interface 209by index: 210.Bd -literal 211struct uint32_t idx = htonl(ifindex); 212setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx)); 213.Ed 214.Pp 215where "ifindex" is an interface index as returned by 216.Xr if_nametoindex 3 . 217.Pp 218Normal applications should not need to use 219.Dv IP_MULTICAST_IF . 220.Pp 221If a multicast datagram is sent to a group to which the sending host itself 222belongs (on the outgoing interface), a copy of the datagram is, by default, 223looped back by the IP layer for local delivery. 224The 225.Dv IP_MULTICAST_LOOP 226option gives the sender explicit control 227over whether or not subsequent datagrams are looped back: 228.Bd -literal 229u_char loop; /* 0 = disable, 1 = enable (default) */ 230setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop)); 231.Ed 232.Pp 233This option 234improves performance for applications that may have no more than one 235instance on a single host (such as a router demon), by eliminating 236the overhead of receiving their own transmissions. 237It should generally not be used by applications for which there 238may be more than one instance on a single host (such as a conferencing 239program) or for which the sender does not belong to the destination 240group (such as a time querying program). 241.Pp 242A multicast datagram sent with an initial TTL greater than 1 may be delivered 243to the sending host on a different interface from that on which it was sent, 244if the host belongs to the destination group on that other interface. 245The loopback control option has no effect on such delivery. 246.Pp 247A host must become a member of a multicast group before it can receive 248datagrams sent to the group. 249To join a multicast group, use the 250.Dv IP_ADD_MEMBERSHIP 251option: 252.Bd -literal 253struct ip_mreq mreq; 254setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 255.Ed 256.Pp 257where 258.Fa mreq 259is the following structure: 260.Bd -literal 261struct ip_mreq { 262 struct in_addr imr_multiaddr; /* multicast group to join */ 263 struct in_addr imr_interface; /* interface to join on */ 264} 265.Ed 266.Pp 267.Dv imr_interface 268should be 269.Dv INADDR_ANY 270to choose the default multicast interface, or the 271.Tn IP 272address of a particular multicast-capable interface if 273the host is multihomed. 274Membership is associated with a single interface; 275programs running on multihomed hosts may need to 276join the same group on more than one interface. 277Up to 278.Dv IP_MAX_MEMBERSHIPS 279(currently 20) memberships may be added on a single socket. 280.Pp 281To drop a membership, use: 282.Bd -literal 283struct ip_mreq mreq; 284setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); 285.Ed 286.Pp 287where 288.Fa mreq 289contains the same values as used to add the membership. 290Memberships are dropped when the socket is closed or the process exits. 291.\"----------------------- 292.Ss RAW IP SOCKETS 293Raw 294.Tn IP 295sockets are connectionless, and are normally used with the 296.Xr sendto 2 297and 298.Xr recvfrom 2 299calls, though the 300.Xr connect 2 301call may also be used to fix the destination for future 302packets (in which case the 303.Xr read 2 304or 305.Xr recv 2 306and 307.Xr write 2 308or 309.Xr send 2 310system calls may be used). 311.Pp 312If 313.Fa proto 314is 0, the default protocol 315.Dv IPPROTO_RAW 316is used for outgoing packets, and only incoming packets destined 317for that protocol are received. 318If 319.Fa proto 320is non-zero, that protocol number will be used on outgoing packets 321and to filter incoming packets. 322.Pp 323Outgoing packets automatically have an 324.Tn IP 325header prepended to them (based on the destination address and the 326protocol number the socket is created with), unless the 327.Dv IP_HDRINCL 328option has been set. 329Incoming packets are received with 330.Tn IP 331header and options intact. 332.Pp 333.Dv IP_HDRINCL 334indicates the complete IP header is included with the data and may 335be used only with the 336.Dv SOCK_RAW 337type. 338.Bd -literal 339#include \*[Lt]netinet/ip.h\*[Gt] 340 341int hincl = 1; /* 1 = on, 0 = off */ 342setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl)); 343.Ed 344.Pp 345Unlike previous 346.Bx 347releases, the program must set all 348the fields of the IP header, including the following: 349.Bd -literal 350ip-\*[Gt]ip_v = IPVERSION; 351ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2; 352ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */ 353ip-\*[Gt]ip_off = offset; 354.Ed 355.Pp 356If the header source address is set to 357.Dv INADDR_ANY , 358the kernel will choose an appropriate address. 359.Sh DIAGNOSTICS 360A socket operation may fail with one of the following errors returned: 361.Bl -tag -width [EADDRNOTAVAIL] 362.It Bq Er EISCONN 363when trying to establish a connection on a socket which already 364has one, or when trying to send a datagram with the destination 365address specified and the socket is already connected; 366.It Bq Er ENOTCONN 367when trying to send a datagram, but no destination address is 368specified, and the socket hasn't been connected; 369.It Bq Er ENOBUFS 370when the system runs out of memory for an internal data structure; 371.It Bq Er EADDRNOTAVAIL 372when an attempt is made to create a socket with a network address 373for which no network interface exists. 374.It Bq Er EACCES 375when an attempt is made to create a raw IP socket by a non-privileged process. 376.El 377.Pp 378The following errors specific to 379.Tn IP 380may occur when setting or getting 381.Tn IP 382options: 383.Bl -tag -width EADDRNOTAVAILxx 384.It Bq Er EINVAL 385An unknown socket option name was given. 386.It Bq Er EINVAL 387The IP option field was improperly formed; an option field was 388shorter than the minimum value or longer than the option buffer provided. 389.El 390.Sh SEE ALSO 391.Xr getsockopt 2 , 392.Xr recv 2 , 393.Xr send 2 , 394.Xr icmp 4 , 395.Xr inet 4 , 396.Xr intro 4 397.Rs 398.%R RFC 399.%N 791 400.%D September 1981 401.%T "Internet Protocol" 402.Re 403.Rs 404.%R RFC 405.%N 1112 406.%D August 1989 407.%T "Host Extensions for IP Multicasting" 408.Re 409.Rs 410.%R RFC 411.%N 1122 412.%D October 1989 413.%T "Requirements for Internet Hosts -- Communication Layers" 414.Re 415.Sh HISTORY 416The 417.Nm 418protocol appeared in 419.Bx 4.2 . 420