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