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