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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)ip.4 8.2 (Berkeley) 11/30/93 33.\" $FreeBSD$ 34.\" 35.Dd November 30, 1993 36.Dt IP 4 37.Os BSD 4.2 38.Sh NAME 39.Nm ip 40.Nd Internet Protocol 41.Sh SYNOPSIS 42.Fd #include <sys/socket.h> 43.Fd #include <netinet/in.h> 44.Ft int 45.Fn socket AF_INET SOCK_RAW proto 46.Sh DESCRIPTION 47.Tn IP 48is the transport layer protocol used 49by the Internet protocol family. 50Options may be set at the 51.Tn IP 52level 53when using higher-level protocols that are based on 54.Tn IP 55(such as 56.Tn TCP 57and 58.Tn UDP ) . 59It may also be accessed 60through a 61.Dq raw socket 62when developing new protocols, or 63special-purpose applications. 64.Pp 65There are several 66.Tn IP-level 67.Xr setsockopt 2 68and 69.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 2 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 = sizeof(struct in_addr) 133cmsg_level = IPPROTO_IP 134cmsg_type = IP_RECVDSTADDR 135.Ed 136.Pp 137.Dv IP_PORTRANGE 138may be used to set the port range used for selecting a local port number 139on a socket with an unspecified (zero) port number. It has the following 140possible values: 141.Bl -tag -width IP_PORTRANGE_DEFAULT 142.It Dv IP_PORTRANGE_DEFAULT 143use the default range of values, normally 144.Dv IPPORT_RESERVED 145through 146.Dv IPPORT_RESERVED . 147This is adjustable through the sysctl setting: 148.Sy net.inet.ip.portrange.first 149and 150.Sy net.inet.ip.portrange.last . 151.It Dv IP_PORTRANGE_HIGH 152use a high range of values, normally 153.Dv IPPORT_HIFIRSTAUTO 154and 155.Dv IPPORT_HILASTAUTO . 156This is adjustable through the sysctl setting: 157.Sy net.inet.ip.portrange.hifirst 158and 159.Sy net.inet.ip.portrange.hilast . 160.It Dv IP_PORTRANGE_LOW 161use a low range of ports, which are normally restricted to 162privileged processes on 163.Ux 164systems. The range is normally from 165.Dv IPPORT_RESERVED 166down to 167.Li 1 168in descending order. This range is not sysctl configurable. 169.El 170.Ss "Multicast Options" 171.Pp 172.Tn IP 173multicasting is supported only on 174.Dv AF_INET 175sockets of type 176.Dv SOCK_DGRAM 177and 178.Dv SOCK_RAW, 179and only on networks where the interface 180driver supports multicasting. 181.Pp 182The 183.Dv IP_MULTICAST_TTL 184option changes the time-to-live (TTL) 185for outgoing multicast datagrams 186in order to control the scope of the multicasts: 187.Bd -literal 188u_char ttl; /* range: 0 to 255, default = 1 */ 189setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 190.Ed 191.Pp 192Datagrams with a TTL of 1 are not forwarded beyond the local network. 193Multicast datagrams with a TTL of 0 will not be transmitted on any network, 194but may be delivered locally if the sending host belongs to the destination 195group and if multicast loopback has not been disabled on the sending socket 196(see below). Multicast datagrams with TTL greater than 1 may be forwarded 197to other networks if a multicast router is attached to the local network. 198.Pp 199For hosts with multiple interfaces, each multicast transmission is 200sent from the primary network interface. 201The 202.Dv IP_MULTICAST_IF 203option overrides the default for 204subsequent transmissions from a given socket: 205.Bd -literal 206struct in_addr addr; 207setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 208.Ed 209.Pp 210where "addr" is the local 211.Tn IP 212address of the desired interface or 213.Dv INADDR_ANY 214to specify the default interface. 215An interface's local IP address and multicast capability can 216be obtained via the 217.Dv SIOCGIFCONF 218and 219.Dv SIOCGIFFLAGS 220ioctls. 221Normal applications should not need to use this option. 222.Pp 223If a multicast datagram is sent to a group to which the sending host itself 224belongs (on the outgoing interface), a copy of the datagram is, by default, 225looped back by the IP layer for local delivery. 226The 227.Dv IP_MULTICAST_LOOP 228option gives the sender explicit control 229over whether or not subsequent datagrams are looped back: 230.Bd -literal 231u_char loop; /* 0 = disable, 1 = enable (default) */ 232setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 233.Ed 234.Pp 235This option 236improves performance for applications that may have no more than one 237instance on a single host (such as a router demon), by eliminating 238the overhead of receiving their own transmissions. It should generally not 239be used by applications for which there may be more than one instance on a 240single host (such as a conferencing program) or for which the sender does 241not belong to the destination group (such as a time querying program). 242.Pp 243A multicast datagram sent with an initial TTL greater than 1 may be delivered 244to the sending host on a different interface from that on which it was sent, 245if the host belongs to the destination group on that other interface. The 246loopback control option has no effect on such delivery. 247.Pp 248A host must become a member of a multicast group before it can receive 249datagrams sent to the group. To 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, &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; /* IP multicast address of group */ 263 struct in_addr imr_interface; /* local IP address of interface */ 264} 265.Ed 266.Pp 267.Dv imr_interface 268should 269be 270.Dv INADDR_ANY 271to choose the default multicast interface, 272or the 273.Tn IP 274address of a particular multicast-capable interface if 275the host is multihomed. 276Membership is associated with a single interface; 277programs running on multihomed hosts may need to 278join the same group on more than one interface. 279Up to 280.Dv IP_MAX_MEMBERSHIPS 281(currently 20) memberships may be added on a 282single socket. 283.Pp 284To drop a membership, use: 285.Bd -literal 286struct ip_mreq mreq; 287setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 288.Ed 289.Pp 290where 291.Fa mreq 292contains the same values as used to add the membership. 293Memberships are dropped when the socket is closed or the process exits. 294.\"----------------------- 295.Ss "Raw IP Sockets" 296.Pp 297Raw 298.Tn IP 299sockets are connectionless, 300and are normally used with the 301.Xr sendto 2 302and 303.Xr recvfrom 2 304calls, though the 305.Xr connect 2 306call may also be used to fix the destination for future 307packets (in which case the 308.Xr read 2 309or 310.Xr recv 2 311and 312.Xr write 2 313or 314.Xr send 2 315system calls may be used). 316.Pp 317If 318.Fa proto 319is 0, the default protocol 320.Dv IPPROTO_RAW 321is used for outgoing 322packets, and only incoming packets destined for that protocol 323are received. 324If 325.Fa proto 326is non-zero, that protocol number will be used on outgoing packets 327and to filter incoming packets. 328.Pp 329Outgoing packets automatically have an 330.Tn IP 331header prepended to 332them (based on the destination address and the protocol 333number the socket is created with), 334unless the 335.Dv IP_HDRINCL 336option has been set. 337Incoming packets are received with 338.Tn IP 339header and options intact. 340.Pp 341.Dv IP_HDRINCL 342indicates the complete IP header is included with the data 343and may be used only with the 344.Dv SOCK_RAW 345type. 346.Bd -literal 347#include <netinet/ip.h> 348 349int hincl = 1; /* 1 = on, 0 = off */ 350setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 351.Ed 352.Pp 353Unlike previous 354.Tn BSD 355releases, the program must set all 356the fields of the IP header, including the following: 357.Bd -literal 358ip->ip_v = IPVERSION; 359ip->ip_hl = hlen >> 2; 360ip->ip_id = 0; /* 0 means kernel set appropriate value */ 361ip->ip_off = offset; 362.Ed 363.Pp 364If the header source address is set to 365.Dv INADDR_ANY, 366the kernel will choose an appropriate address. 367.Sh DIAGNOSTICS 368A socket operation may fail with one of the following errors returned: 369.Bl -tag -width [EADDRNOTAVAIL] 370.It Bq Er EISCONN 371when trying to establish a connection on a socket which 372already has one, or when trying to send a datagram with the destination 373address specified and the socket is already connected; 374.It Bq Er ENOTCONN 375when trying to send a datagram, but 376no destination address is specified, and the socket hasn't been 377connected; 378.It Bq Er ENOBUFS 379when the system runs out of memory for 380an internal data structure; 381.It Bq Er EADDRNOTAVAIL 382when an attempt is made to create a 383socket with a network address for which no network interface 384exists. 385.It Bq Er EACESS 386when an attempt is made to create 387a raw IP socket by a non-privileged process. 388.El 389.Pp 390The following errors specific to 391.Tn IP 392may occur when setting or getting 393.Tn IP 394options: 395.Bl -tag -width EADDRNOTAVAILxx 396.It Bq Er EINVAL 397An unknown socket option name was given. 398.It Bq Er EINVAL 399The IP option field was improperly formed; 400an option field was shorter than the minimum value 401or longer than the option buffer provided. 402.El 403.Sh SEE ALSO 404.Xr getsockopt 2 , 405.Xr recv 2 , 406.Xr send 2 , 407.Xr icmp 4 , 408.Xr inet 4 , 409.Xr intro 4 410.Sh HISTORY 411The 412.Nm 413protocol appeared in 414.Bx 4.2 . 415