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