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