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