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