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/types.h> 43.Fd #include <sys/socket.h> 44.Fd #include <netinet/in.h> 45.Ft int 46.Fn socket AF_INET SOCK_RAW proto 47.Sh DESCRIPTION 48.Tn IP 49is the transport layer protocol used 50by the Internet protocol family. 51Options may be set at the 52.Tn IP 53level 54when using higher-level protocols that are based on 55.Tn IP 56(such as 57.Tn TCP 58and 59.Tn UDP ) . 60It may also be accessed 61through a 62.Dq raw socket 63when developing new protocols, or 64special-purpose applications. 65.Pp 66There are several 67.Tn IP-level 68.Xr setsockopt 2 69and 70.Xr getsockopt 2 71options. 72.Dv IP_OPTIONS 73may be used to provide 74.Tn IP 75options to be transmitted in the 76.Tn IP 77header of each outgoing packet 78or to examine the header options on incoming packets. 79.Tn IP 80options may be used with any socket type in the Internet family. 81The format of 82.Tn IP 83options to be sent is that specified by the 84.Tn IP 85protocol specification (RFC-791), with one exception: 86the list of addresses for Source Route options must include the first-hop 87gateway at the beginning of the list of gateways. 88The first-hop gateway address will be extracted from the option list 89and the size adjusted accordingly before use. 90To disable previously specified options, 91use a zero-length buffer: 92.Bd -literal 93setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0); 94.Ed 95.Pp 96.Dv IP_TOS 97and 98.Dv IP_TTL 99may be used to set the type-of-service and time-to-live 100fields in the 101.Tn IP 102header for 103.Dv SOCK_STREAM 104and 105.Dv SOCK_DGRAM 106sockets. For example, 107.Bd -literal 108int tos = IPTOS_LOWDELAY; /* see <netinet/in.h> */ 109setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos)); 110 111int ttl = 60; /* max = 255 */ 112setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl)); 113.Ed 114.Pp 115If the 116.Dv IP_RECVDSTADDR 117option is enabled on a 118.Dv SOCK_DGRAM 119socket, 120the 121.Xr recvmsg 2 122call will return the destination 123.Tn IP 124address for a 125.Tn UDP 126datagram. 127The msg_control field in the msghdr structure points to a buffer 128that contains a cmsghdr structure followed by the 129.Tn IP 130address. 131The cmsghdr fields have the following values: 132.Bd -literal 133cmsg_len = sizeof(struct in_addr) 134cmsg_level = IPPROTO_IP 135cmsg_type = IP_RECVDSTADDR 136.Ed 137.Pp 138.Dv IP_PORTRANGE 139may be used to set the port range used for selecting a local port number 140on a socket with an unspecified (zero) port number. It has the following 141possible values: 142.Bl -tag -width IP_PORTRANGE_DEFAULT 143.It Dv IP_PORTRANGE_DEFAULT 144use the default range of values, normally 145.Dv IPPORT_RESERVED 146through 147.Dv IPPORT_USERRESERVED . 148This is adjustable through the sysctl setting: 149.Sy net.inet.ip.portrange.first 150and 151.Sy net.inet.ip.portrange.last . 152.It Dv IP_PORTRANGE_HIGH 153use a high range of values, normally 154.Dv IPPORT_HIFIRSTAUTO 155and 156.Dv IPPORT_HILASTAUTO . 157This is adjustable through the sysctl setting: 158.Sy net.inet.ip.portrange.hifirst 159and 160.Sy net.inet.ip.portrange.hilast . 161.It Dv IP_PORTRANGE_LOW 162use a low range of ports, which are normally restricted to 163privileged processes on 164.Ux 165systems. The range is normally from 166.Dv IPPORT_RESERVED 167down to 168.Li 1 169in descending order. This range is not sysctl configurable. 170.El 171.Ss "Multicast Options" 172.Pp 173.Tn IP 174multicasting is supported only on 175.Dv AF_INET 176sockets of type 177.Dv SOCK_DGRAM 178and 179.Dv SOCK_RAW, 180and only on networks where the interface 181driver supports multicasting. 182.Pp 183The 184.Dv IP_MULTICAST_TTL 185option changes the time-to-live (TTL) 186for outgoing multicast datagrams 187in order to control the scope of the multicasts: 188.Bd -literal 189u_char ttl; /* range: 0 to 255, default = 1 */ 190setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl)); 191.Ed 192.Pp 193Datagrams with a TTL of 1 are not forwarded beyond the local network. 194Multicast datagrams with a TTL of 0 will not be transmitted on any network, 195but may be delivered locally if the sending host belongs to the destination 196group and if multicast loopback has not been disabled on the sending socket 197(see below). Multicast datagrams with TTL greater than 1 may be forwarded 198to other networks if a multicast router is attached to the local network. 199.Pp 200For hosts with multiple interfaces, each multicast transmission is 201sent from the primary network interface. 202The 203.Dv IP_MULTICAST_IF 204option overrides the default for 205subsequent transmissions from a given socket: 206.Bd -literal 207struct in_addr addr; 208setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr)); 209.Ed 210.Pp 211where "addr" is the local 212.Tn IP 213address of the desired interface or 214.Dv INADDR_ANY 215to specify the default interface. 216An interface's local IP address and multicast capability can 217be obtained via the 218.Dv SIOCGIFCONF 219and 220.Dv SIOCGIFFLAGS 221ioctls. 222Normal applications should not need to use this option. 223.Pp 224If a multicast datagram is sent to a group to which the sending host itself 225belongs (on the outgoing interface), a copy of the datagram is, by default, 226looped back by the IP layer for local delivery. 227The 228.Dv IP_MULTICAST_LOOP 229option gives the sender explicit control 230over whether or not subsequent datagrams are looped back: 231.Bd -literal 232u_char loop; /* 0 = disable, 1 = enable (default) */ 233setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop)); 234.Ed 235.Pp 236This option 237improves performance for applications that may have no more than one 238instance on a single host (such as a router demon), by eliminating 239the overhead of receiving their own transmissions. It should generally not 240be used by applications for which there may be more than one instance on a 241single host (such as a conferencing program) or for which the sender does 242not belong to the destination group (such as a time querying program). 243.Pp 244A multicast datagram sent with an initial TTL greater than 1 may be delivered 245to the sending host on a different interface from that on which it was sent, 246if the host belongs to the destination group on that other interface. The 247loopback control option has no effect on such delivery. 248.Pp 249A host must become a member of a multicast group before it can receive 250datagrams sent to the group. To join a multicast group, use the 251.Dv IP_ADD_MEMBERSHIP 252option: 253.Bd -literal 254struct ip_mreq mreq; 255setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq)); 256.Ed 257.Pp 258where 259.Fa mreq 260is the following structure: 261.Bd -literal 262struct ip_mreq { 263 struct in_addr imr_multiaddr; /* IP multicast address of group */ 264 struct in_addr imr_interface; /* local IP address of interface */ 265} 266.Ed 267.Pp 268.Dv imr_interface 269should 270be 271.Dv INADDR_ANY 272to choose the default multicast interface, 273or the 274.Tn IP 275address of a particular multicast-capable interface if 276the host is multihomed. 277Membership is associated with a single interface; 278programs running on multihomed hosts may need to 279join the same group on more than one interface. 280Up to 281.Dv IP_MAX_MEMBERSHIPS 282(currently 20) memberships may be added on a 283single socket. 284.Pp 285To drop a membership, use: 286.Bd -literal 287struct ip_mreq mreq; 288setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq)); 289.Ed 290.Pp 291where 292.Fa mreq 293contains the same values as used to add the membership. 294Memberships are dropped when the socket is closed or the process exits. 295.\"----------------------- 296.Ss "Raw IP Sockets" 297.Pp 298Raw 299.Tn IP 300sockets are connectionless, 301and are normally used with the 302.Xr sendto 2 303and 304.Xr recvfrom 2 305calls, though the 306.Xr connect 2 307call may also be used to fix the destination for future 308packets (in which case the 309.Xr read 2 310or 311.Xr recv 2 312and 313.Xr write 2 314or 315.Xr send 2 316system calls may be used). 317.Pp 318If 319.Fa proto 320is 0, the default protocol 321.Dv IPPROTO_RAW 322is used for outgoing 323packets, and only incoming packets destined for that protocol 324are received. 325If 326.Fa proto 327is non-zero, that protocol number will be used on outgoing packets 328and to filter incoming packets. 329.Pp 330Outgoing packets automatically have an 331.Tn IP 332header prepended to 333them (based on the destination address and the protocol 334number the socket is created with), 335unless 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 344and may be used only with the 345.Dv SOCK_RAW 346type. 347.Bd -literal 348#include <netinet/in_systm.h> 349#include <netinet/ip.h> 350 351int hincl = 1; /* 1 = on, 0 = off */ 352setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl)); 353.Ed 354.Pp 355Unlike previous 356.Tn BSD 357releases, the program must set all 358the fields of the IP header, including the following: 359.Bd -literal 360ip->ip_v = IPVERSION; 361ip->ip_hl = hlen >> 2; 362ip->ip_id = 0; /* 0 means kernel set appropriate value */ 363ip->ip_off = offset; 364.Ed 365.Pp 366If the header source address is set to 367.Dv INADDR_ANY, 368the kernel will choose an appropriate address. 369.Sh DIAGNOSTICS 370A socket operation may fail with one of the following errors returned: 371.Bl -tag -width [EADDRNOTAVAIL] 372.It Bq Er EISCONN 373when trying to establish a connection on a socket which 374already has one, or when trying to send a datagram with the destination 375address specified and the socket is already connected; 376.It Bq Er ENOTCONN 377when trying to send a datagram, but 378no destination address is specified, and the socket hasn't been 379connected; 380.It Bq Er ENOBUFS 381when the system runs out of memory for 382an internal data structure; 383.It Bq Er EADDRNOTAVAIL 384when an attempt is made to create a 385socket with a network address for which no network interface 386exists. 387.It Bq Er EACCES 388when an attempt is made to create 389a raw IP socket by a non-privileged process. 390.El 391.Pp 392The following errors specific to 393.Tn IP 394may occur when setting or getting 395.Tn IP 396options: 397.Bl -tag -width EADDRNOTAVAILxx 398.It Bq Er EINVAL 399An unknown socket option name was given. 400.It Bq Er EINVAL 401The IP option field was improperly formed; 402an option field was shorter than the minimum value 403or longer than the option buffer provided. 404.El 405.Sh SEE ALSO 406.Xr getsockopt 2 , 407.Xr recv 2 , 408.Xr send 2 , 409.Xr icmp 4 , 410.Xr inet 4 , 411.Xr intro 4 412.Sh HISTORY 413The 414.Nm 415protocol appeared in 416.Bx 4.2 . 417