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