| blob | 1fc62106c6735d8085618fa47e610d3628b76843 |
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. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
15 .\"
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
26 .\" SUCH DAMAGE.
27 .\"
28 .\" @(#)ip.4 8.2 (Berkeley) 11/30/93
29 .\" $FreeBSD: src/share/man/man4/ip.4,v 1.13.2.9 2002/05/02 02:40:26 silby Exp $
30 .\" $DragonFly: src/share/man/man4/ip.4,v 1.7 2007/12/15 10:23:58 swildner Exp $
31 .\"
32 .Dd March 3, 2001
33 .Dt IP 4
34 .Os
35 .Sh NAME
36 .Nm ip
37 .Nd Internet Protocol
38 .Sh SYNOPSIS
39 .In sys/types.h
40 .In sys/socket.h
41 .In netinet/in.h
42 .Ft int
43 .Fn socket AF_INET SOCK_RAW proto
44 .Sh DESCRIPTION
45 .Tn IP
46 is the transport layer protocol used
47 by the Internet protocol family.
48 Options may be set at the
49 .Tn IP
50 level
51 when using higher-level protocols that are based on
52 .Tn IP
53 (such as
54 .Tn TCP
55 and
56 .Tn UDP ) .
57 It may also be accessed
58 through a
59 .Dq raw socket
60 when developing new protocols, or
61 special-purpose applications.
62 .Pp
63 There are several
64 .Tn IP-level
65 .Xr setsockopt 2
66 and
67 .Xr getsockopt 2
68 options.
69 .Dv IP_OPTIONS
70 may be used to provide
71 .Tn IP
72 options to be transmitted in the
73 .Tn IP
74 header of each outgoing packet
75 or to examine the header options on incoming packets.
76 .Tn IP
77 options may be used with any socket type in the Internet family.
78 The format of
79 .Tn IP
80 options to be sent is that specified by the
81 .Tn IP
82 protocol specification (RFC 791), with one exception:
83 the list of addresses for Source Route options must include the first-hop
84 gateway at the beginning of the list of gateways.
85 The first-hop gateway address will be extracted from the option list
86 and the size adjusted accordingly before use.
87 To disable previously specified options,
88 use a zero-length buffer:
89 .Bd -literal
90 setsockopt(s, IPPROTO_IP, IP_OPTIONS, NULL, 0);
91 .Ed
92 .Pp
93 .Dv IP_TOS
94 and
95 .Dv IP_TTL
96 may be used to set the type-of-service and time-to-live
97 fields in the
98 .Tn IP
99 header for
100 .Dv SOCK_STREAM , SOCK_DGRAM ,
101 and certain types of
102 .Dv SOCK_RAW
103 sockets.
104 For example,
105 .Bd -literal
106 int tos = IPTOS_LOWDELAY; /* see <netinet/ip.h> */
107 setsockopt(s, IPPROTO_IP, IP_TOS, &tos, sizeof(tos));
109 int ttl = 60; /* max = 255 */
110 setsockopt(s, IPPROTO_IP, IP_TTL, &ttl, sizeof(ttl));
111 .Ed
112 .Pp
113 .Dv IP_MINTTL
114 may be used to set the minimum acceptable TTL a packet must have when
115 received on a socket.
116 All packets with a lower TTL are silently dropped.
117 Works on already connected/connecting and listening sockets for RAW/UDP/TCP.
118 It allows to implement security mechanisms described in RFC 3682 (GTSM).
119 .Pp
120 If the
121 .Dv IP_RECVDSTADDR
122 option is enabled on a
123 .Dv SOCK_DGRAM
124 socket,
125 the
126 .Xr recvmsg 2
127 call will return the destination
128 .Tn IP
129 address for a
130 .Tn UDP
131 datagram.
132 The msg_control field in the msghdr structure points to a buffer
133 that contains a cmsghdr structure followed by the
134 .Tn IP
135 address.
136 The cmsghdr fields have the following values:
137 .Bd -literal
138 cmsg_len = sizeof(struct in_addr)
139 cmsg_level = IPPROTO_IP
140 cmsg_type = IP_RECVDSTADDR
141 .Ed
142 .Pp
143 If the
144 .Dv IP_RECVTTL
145 option is enabled on a
146 .Dv SOCK_DGRAM
147 socket, the
148 .Xr recvmsg 2
149 call will return the
150 .Tn IP
151 .Tn TTL
152 (time to live) field for a
153 .Tn UDP
154 datagram.
155 The msg_control field in the msghdr structure points to a buffer
156 that contains a cmsghdr structure followed by the
157 .Tn TTL .
158 The cmsghdr fields have the following values:
159 .Bd -literal
160 cmsg_len = sizeof(u_char)
161 cmsg_level = IPPROTO_IP
162 cmsg_type = IP_RECVTTL
163 .Ed
164 .Pp
165 .Dv IP_PORTRANGE
166 may be used to set the port range used for selecting a local port number
167 on a socket with an unspecified (zero) port number.
168 It has the following
169 possible values:
170 .Bl -tag -width IP_PORTRANGE_DEFAULT
171 .It Dv IP_PORTRANGE_DEFAULT
172 use the default range of values, normally
173 .Dv IPPORT_RESERVED
174 through
175 .Dv IPPORT_USERRESERVED .
176 This is adjustable through the sysctl setting:
177 .Va net.inet.ip.portrange.first
178 and
179 .Va net.inet.ip.portrange.last .
180 .It Dv IP_PORTRANGE_HIGH
181 use a high range of values, normally
182 .Dv IPPORT_HIFIRSTAUTO
183 and
184 .Dv IPPORT_HILASTAUTO .
185 This is adjustable through the sysctl setting:
186 .Va net.inet.ip.portrange.hifirst
187 and
188 .Va net.inet.ip.portrange.hilast .
189 .It Dv IP_PORTRANGE_LOW
190 use a low range of ports, which are normally restricted to
191 privileged processes on
192 .Ux
193 systems. The range is normally from
194 .Dv IPPORT_RESERVED - 1
195 down to
196 .Li IPPORT_RESERVEDSTART
197 in descending order.
198 This is adjustable through the sysctl setting:
199 .Va net.inet.ip.portrange.lowfirst
200 and
201 .Va net.inet.ip.portrange.lowlast .
202 .El
203 .Ss "Multicast Options"
204 .Tn IP
205 multicasting is supported only on
206 .Dv AF_INET
207 sockets of type
208 .Dv SOCK_DGRAM
209 and
210 .Dv SOCK_RAW ,
211 and only on networks where the interface
212 driver supports multicasting.
213 .Pp
214 The
215 .Dv IP_MULTICAST_TTL
216 option changes the time-to-live (TTL)
217 for outgoing multicast datagrams
218 in order to control the scope of the multicasts:
219 .Bd -literal
220 u_char ttl; /* range: 0 to 255, default = 1 */
221 setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, &ttl, sizeof(ttl));
222 .Ed
223 .Pp
224 Datagrams with a TTL of 1 are not forwarded beyond the local network.
225 Multicast datagrams with a TTL of 0 will not be transmitted on any network,
226 but may be delivered locally if the sending host belongs to the destination
227 group and if multicast loopback has not been disabled on the sending socket
228 (see below). Multicast datagrams with TTL greater than 1 may be forwarded
229 to other networks if a multicast router is attached to the local network.
230 .Pp
231 For hosts with multiple interfaces, each multicast transmission is
232 sent from the primary network interface.
233 The
234 .Dv IP_MULTICAST_IF
235 option overrides the default for
236 subsequent transmissions from a given socket:
237 .Bd -literal
238 struct in_addr addr;
239 setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, &addr, sizeof(addr));
240 .Ed
241 .Pp
242 where "addr" is the local
243 .Tn IP
244 address of the desired interface or
245 .Dv INADDR_ANY
246 to specify the default interface.
247 An interface's local IP address and multicast capability can
248 be obtained via the
249 .Dv SIOCGIFCONF
250 and
251 .Dv SIOCGIFFLAGS
252 ioctls.
253 Normal applications should not need to use this option.
254 .Pp
255 If a multicast datagram is sent to a group to which the sending host itself
256 belongs (on the outgoing interface), a copy of the datagram is, by default,
257 looped back by the IP layer for local delivery.
258 The
259 .Dv IP_MULTICAST_LOOP
260 option gives the sender explicit control
261 over whether or not subsequent datagrams are looped back:
262 .Bd -literal
263 u_char loop; /* 0 = disable, 1 = enable (default) */
264 setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, &loop, sizeof(loop));
265 .Ed
266 .Pp
267 This option
268 improves performance for applications that may have no more than one
269 instance on a single host (such as a router daemon), by eliminating
270 the overhead of receiving their own transmissions. It should generally not
271 be used by applications for which there may be more than one instance on a
272 single host (such as a conferencing program) or for which the sender does
273 not belong to the destination group (such as a time querying program).
274 .Pp
275 A multicast datagram sent with an initial TTL greater than 1 may be delivered
276 to the sending host on a different interface from that on which it was sent,
277 if the host belongs to the destination group on that other interface. The
278 loopback control option has no effect on such delivery.
279 .Pp
280 A host must become a member of a multicast group before it can receive
281 datagrams sent to the group. To join a multicast group, use the
282 .Dv IP_ADD_MEMBERSHIP
283 option:
284 .Bd -literal
285 struct ip_mreq mreq;
286 setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, &mreq, sizeof(mreq));
287 .Ed
288 .Pp
289 where
290 .Fa mreq
291 is the following structure:
292 .Bd -literal
293 struct ip_mreq {
294 struct in_addr imr_multiaddr; /* IP multicast address of group */
295 struct in_addr imr_interface; /* local IP address of interface */
296 }
297 .Ed
298 .Pp
299 .Fa imr_interface
300 should
301 be
302 .Dv INADDR_ANY
303 to choose the default multicast interface,
304 or the
305 .Tn IP
306 address of a particular multicast-capable interface if
307 the host is multihomed.
308 Membership is associated with a single interface;
309 programs running on multihomed hosts may need to
310 join the same group on more than one interface.
311 Up to
312 .Dv IP_MAX_MEMBERSHIPS
313 (currently 20) memberships may be added on a
314 single socket.
315 .Pp
316 To drop a membership, use:
317 .Bd -literal
318 struct ip_mreq mreq;
319 setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, &mreq, sizeof(mreq));
320 .Ed
321 .Pp
322 where
323 .Fa mreq
324 contains the same values as used to add the membership.
325 Memberships are dropped when the socket is closed or the process exits.
326 .\"-----------------------
327 .Ss "Raw IP Sockets"
328 Raw
329 .Tn IP
330 sockets are connectionless,
331 and are normally used with the
332 .Xr sendto 2
333 and
334 .Xr recvfrom 2
335 calls, though the
336 .Xr connect 2
337 call may also be used to fix the destination for future
338 packets (in which case the
339 .Xr read 2
340 or
341 .Xr recv 2
342 and
343 .Xr write 2
344 or
345 .Xr send 2
346 system calls may be used).
347 .Pp
348 If
349 .Fa proto
350 is 0, the default protocol
351 .Dv IPPROTO_RAW
352 is used for outgoing
353 packets, and only incoming packets destined for that protocol
354 are received.
355 If
356 .Fa proto
357 is non-zero, that protocol number will be used on outgoing packets
358 and to filter incoming packets.
359 .Pp
360 Outgoing packets automatically have an
361 .Tn IP
362 header prepended to
363 them (based on the destination address and the protocol
364 number the socket is created with),
365 unless the
366 .Dv IP_HDRINCL
367 option has been set.
368 Incoming packets are received with
369 .Tn IP
370 header and options intact.
371 .Pp
372 .Dv IP_HDRINCL
373 indicates the complete IP header is included with the data
374 and may be used only with the
375 .Dv SOCK_RAW
376 type.
377 .Bd -literal
378 #include <netinet/in_systm.h>
379 #include <netinet/ip.h>
381 int hincl = 1; /* 1 = on, 0 = off */
382 setsockopt(s, IPPROTO_IP, IP_HDRINCL, &hincl, sizeof(hincl));
383 .Ed
384 .Pp
385 Unlike previous
386 .Bx
387 releases, the program must set all
388 the fields of the IP header, including the following:
389 .Bd -literal
390 ip->ip_v = IPVERSION;
391 ip->ip_hl = hlen >> 2;
392 ip->ip_id = 0; /* 0 means kernel set appropriate value */
393 ip->ip_off = offset;
394 .Ed
395 .Pp
396 If the header source address is set to
397 .Dv INADDR_ANY ,
398 the kernel will choose an appropriate address.
399 .Sh ERRORS
400 A socket operation may fail with one of the following errors returned:
401 .Bl -tag -width Er
402 .It Bq Er EISCONN
403 when trying to establish a connection on a socket which
404 already has one, or when trying to send a datagram with the destination
405 address specified and the socket is already connected;
406 .It Bq Er ENOTCONN
407 when trying to send a datagram, but
408 no destination address is specified, and the socket hasn't been
409 connected;
410 .It Bq Er ENOBUFS
411 when the system runs out of memory for
412 an internal data structure;
413 .It Bq Er EADDRNOTAVAIL
414 when an attempt is made to create a
415 socket with a network address for which no network interface
416 exists.
417 .It Bq Er EACCES
418 when an attempt is made to create
419 a raw IP socket by a non-privileged process.
420 .El
421 .Pp
422 The following errors specific to
423 .Tn IP
424 may occur when setting or getting
425 .Tn IP
426 options:
427 .Bl -tag -width EADDRNOTAVAILxx
428 .It Bq Er EINVAL
429 An unknown socket option name was given.
430 .It Bq Er EINVAL
431 The IP option field was improperly formed;
432 an option field was shorter than the minimum value
433 or longer than the option buffer provided.
434 .El
435 .Sh SEE ALSO
436 .Xr getsockopt 2 ,
437 .Xr recv 2 ,
438 .Xr send 2 ,
439 .Xr icmp 4 ,
440 .Xr inet 4 ,
441 .Xr intro 4
442 .Sh HISTORY
443 The
444 .Nm
445 protocol appeared in
446 .Bx 4.2 .