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