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