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