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