| @@ -1,429 +1,429 @@ | | | @@ -1,429 +1,429 @@ |
1 | .\" $NetBSD: ip.4,v 1.22 2006/12/23 06:58:20 wiz Exp $ | | 1 | .\" $NetBSD: ip.4,v 1.23 2008/09/23 14:58:05 briggs 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 December 5, 2006 | | 32 | .Dd September 23, 2008 |
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/in.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. For example, | | 118 | sockets. For example, |
119 | .Bd -literal | | 119 | .Bd -literal |
120 | int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */ | | 120 | int range = IP_PORTRANGE_LOW; /* see \*[Lt]netinet/in.h\*[Gt] */ |
121 | setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range)); | | 121 | setsockopt(s, IPPROTO_IP, IP_PORTRANGE, \*[Am]range, sizeof(range)); |
122 | .Ed | | 122 | .Ed |
123 | .Pp | | 123 | .Pp |
124 | If the | | 124 | If the |
125 | .Dv IP_RECVDSTADDR | | 125 | .Dv IP_RECVDSTADDR |
126 | option is enabled on a | | 126 | option is enabled on a |
127 | .Dv SOCK_DGRAM | | 127 | .Dv SOCK_DGRAM |
128 | or | | 128 | or |
129 | .Dv SOCK_RAW | | 129 | .Dv SOCK_RAW |
130 | socket, | | 130 | socket, |
131 | the | | 131 | the |
132 | .Xr recvmsg 2 | | 132 | .Xr recvmsg 2 |
133 | call will return the destination | | 133 | call will return the destination |
134 | .Tn IP | | 134 | .Tn IP |
135 | address for a | | 135 | address for a |
136 | .Tn UDP | | 136 | .Tn UDP |
137 | datagram. | | 137 | datagram. |
138 | The msg_control field in the msghdr structure points to a buffer | | 138 | The msg_control field in the msghdr structure points to a buffer |
139 | that contains a cmsghdr structure followed by the | | 139 | that contains a cmsghdr structure followed by the |
140 | .Tn IP | | 140 | .Tn IP |
141 | address. | | 141 | address. |
142 | The cmsghdr fields have the following values: | | 142 | The cmsghdr fields have the following values: |
143 | .Bd -literal | | 143 | .Bd -literal |
144 | cmsg_len = sizeof(struct in_addr) | | 144 | cmsg_len = sizeof(struct in_addr) |
145 | cmsg_level = IPPROTO_IP | | 145 | cmsg_level = IPPROTO_IP |
146 | cmsg_type = IP_RECVDSTADDR | | 146 | cmsg_type = IP_RECVDSTADDR |
147 | .Ed | | 147 | .Ed |
148 | .Pp | | 148 | .Pp |
149 | If the | | 149 | If the |
150 | .Dv IP_RECVIF | | 150 | .Dv IP_RECVIF |
151 | option is enabled on a | | 151 | option is enabled on a |
152 | .Dv SOCK_DGRAM | | 152 | .Dv SOCK_DGRAM |
153 | or | | 153 | or |
154 | .Dv SOCK_RAW | | 154 | .Dv SOCK_RAW |
155 | socket, | | 155 | socket, |
156 | the | | 156 | the |
157 | .Xr recvmsg 2 | | 157 | .Xr recvmsg 2 |
158 | call will return a struct sockaddr_dl corresponding to | | 158 | call will return a struct sockaddr_dl corresponding to |
159 | the interface on which the packet was received. | | 159 | the interface on which the packet was received. |
160 | the msg_control field in the msghdr structure points to a buffer | | 160 | the msg_control field in the msghdr structure points to a buffer |
161 | that contains a cmsghdr structure followed by the struct sockaddr_dl. | | 161 | that contains a cmsghdr structure followed by the struct sockaddr_dl. |
162 | The cmsghdr fields have the following values: | | 162 | The cmsghdr fields have the following values: |
163 | .Bd -literal | | 163 | .Bd -literal |
164 | cmsg_len = sizeof(struct sockaddr_dl) | | 164 | cmsg_len = sizeof(struct sockaddr_dl) |
165 | cmsg_level = IPPROTO_IP | | 165 | cmsg_level = IPPROTO_IP |
166 | cmsg_type = IP_RECVIF | | 166 | cmsg_type = IP_RECVIF |
167 | .Ed | | 167 | .Ed |
168 | .Ss MULTICAST OPTIONS | | 168 | .Ss MULTICAST OPTIONS |
169 | .Tn IP | | 169 | .Tn IP |
170 | multicasting is supported only on | | 170 | multicasting is supported only on |
171 | .Dv AF_INET | | 171 | .Dv AF_INET |
172 | sockets of type | | 172 | sockets of type |
173 | .Dv SOCK_DGRAM | | 173 | .Dv SOCK_DGRAM |
174 | and | | 174 | and |
175 | .Dv SOCK_RAW , | | 175 | .Dv SOCK_RAW , |
176 | and only on networks where the interface driver supports multicasting. | | 176 | and only on networks where the interface driver supports multicasting. |
177 | .Pp | | 177 | .Pp |
178 | The | | 178 | The |
179 | .Dv IP_MULTICAST_TTL | | 179 | .Dv IP_MULTICAST_TTL |
180 | option changes the time-to-live (TTL) for outgoing multicast datagrams | | 180 | option changes the time-to-live (TTL) for outgoing multicast datagrams |
181 | in order to control the scope of the multicasts: | | 181 | in order to control the scope of the multicasts: |
182 | .Bd -literal | | 182 | .Bd -literal |
183 | u_char ttl; /* range: 0 to 255, default = 1 */ | | 183 | u_char ttl; /* range: 0 to 255, default = 1 */ |
184 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl)); | | 184 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_TTL, \*[Am]ttl, sizeof(ttl)); |
185 | .Ed | | 185 | .Ed |
186 | .Pp | | 186 | .Pp |
187 | Datagrams with a TTL of 1 are not forwarded beyond the local network. | | 187 | Datagrams with a TTL of 1 are not forwarded beyond the local network. |
188 | Multicast datagrams with a TTL of 0 will not be transmitted on any network, | | 188 | Multicast datagrams with a TTL of 0 will not be transmitted on any network, |
189 | but may be delivered locally if the sending host belongs to the destination | | 189 | but may be delivered locally if the sending host belongs to the destination |
190 | group and if multicast loopback has not been disabled on the sending socket | | 190 | group and if multicast loopback has not been disabled on the sending socket |
191 | (see below). | | 191 | (see below). |
192 | Multicast datagrams with TTL greater than 1 may be forwarded | | 192 | Multicast datagrams with TTL greater than 1 may be forwarded |
193 | to other networks if a multicast router is attached to the local network. | | 193 | to other networks if a multicast router is attached to the local network. |
194 | .Pp | | 194 | .Pp |
195 | For hosts with multiple interfaces, each multicast transmission is | | 195 | For hosts with multiple interfaces, each multicast transmission is |
196 | sent from the primary network interface. | | 196 | sent from the primary network interface. |
197 | The | | 197 | The |
198 | .Dv IP_MULTICAST_IF | | 198 | .Dv IP_MULTICAST_IF |
199 | option overrides the default for | | 199 | option overrides the default for |
200 | subsequent transmissions from a given socket: | | 200 | subsequent transmissions from a given socket: |
201 | .Bd -literal | | 201 | .Bd -literal |
202 | struct in_addr addr; | | 202 | struct in_addr addr; |
203 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr)); | | 203 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]addr, sizeof(addr)); |
204 | .Ed | | 204 | .Ed |
205 | .Pp | | 205 | .Pp |
206 | where "addr" is the local | | 206 | where "addr" is the local |
207 | .Tn IP | | 207 | .Tn IP |
208 | address of the desired interface or | | 208 | address of the desired interface or |
209 | .Dv INADDR_ANY | | 209 | .Dv INADDR_ANY |
210 | to specify the default interface. | | 210 | to specify the default interface. |
211 | An interface's local IP address and multicast capability can | | 211 | An interface's local IP address and multicast capability can |
212 | be obtained via the | | 212 | be obtained via the |
213 | .Dv SIOCGIFCONF | | 213 | .Dv SIOCGIFCONF |
214 | and | | 214 | and |
215 | .Dv SIOCGIFFLAGS | | 215 | .Dv SIOCGIFFLAGS |
216 | ioctls. | | 216 | ioctls. |
217 | An application may also specify an alternative to the default network interface | | 217 | An application may also specify an alternative to the default network interface |
218 | by index: | | 218 | by index: |
219 | .Bd -literal | | 219 | .Bd -literal |
220 | struct uint32_t idx = htonl(ifindex); | | 220 | struct uint32_t idx = htonl(ifindex); |
221 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx)); | | 221 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_IF, \*[Am]idx, sizeof(idx)); |
222 | .Ed | | 222 | .Ed |
223 | .Pp | | 223 | .Pp |
224 | where "ifindex" is an interface index as returned by | | 224 | where "ifindex" is an interface index as returned by |
225 | .Xr if_nametoindex 3 . | | 225 | .Xr if_nametoindex 3 . |
226 | .Pp | | 226 | .Pp |
227 | Normal applications should not need to use | | 227 | Normal applications should not need to use |
228 | .Dv IP_MULTICAST_IF . | | 228 | .Dv IP_MULTICAST_IF . |
229 | .Pp | | 229 | .Pp |
230 | If a multicast datagram is sent to a group to which the sending host itself | | 230 | If a multicast datagram is sent to a group to which the sending host itself |
231 | belongs (on the outgoing interface), a copy of the datagram is, by default, | | 231 | belongs (on the outgoing interface), a copy of the datagram is, by default, |
232 | looped back by the IP layer for local delivery. | | 232 | looped back by the IP layer for local delivery. |
233 | The | | 233 | The |
234 | .Dv IP_MULTICAST_LOOP | | 234 | .Dv IP_MULTICAST_LOOP |
235 | option gives the sender explicit control | | 235 | option gives the sender explicit control |
236 | over whether or not subsequent datagrams are looped back: | | 236 | over whether or not subsequent datagrams are looped back: |
237 | .Bd -literal | | 237 | .Bd -literal |
238 | u_char loop; /* 0 = disable, 1 = enable (default) */ | | 238 | u_char loop; /* 0 = disable, 1 = enable (default) */ |
239 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop)); | | 239 | setsockopt(s, IPPROTO_IP, IP_MULTICAST_LOOP, \*[Am]loop, sizeof(loop)); |
240 | .Ed | | 240 | .Ed |
241 | .Pp | | 241 | .Pp |
242 | This option | | 242 | This option |
243 | improves performance for applications that may have no more than one | | 243 | improves performance for applications that may have no more than one |
244 | instance on a single host (such as a router demon), by eliminating | | 244 | instance on a single host (such as a router demon), by eliminating |
245 | the overhead of receiving their own transmissions. | | 245 | the overhead of receiving their own transmissions. |
246 | It should generally not be used by applications for which there | | 246 | It should generally not be used by applications for which there |
247 | may be more than one instance on a single host (such as a conferencing | | 247 | may be more than one instance on a single host (such as a conferencing |
248 | program) or for which the sender does not belong to the destination | | 248 | program) or for which the sender does not belong to the destination |
249 | group (such as a time querying program). | | 249 | group (such as a time querying program). |
250 | .Pp | | 250 | .Pp |
251 | A multicast datagram sent with an initial TTL greater than 1 may be delivered | | 251 | A multicast datagram sent with an initial TTL greater than 1 may be delivered |
252 | to the sending host on a different interface from that on which it was sent, | | 252 | to the sending host on a different interface from that on which it was sent, |
253 | if the host belongs to the destination group on that other interface. | | 253 | if the host belongs to the destination group on that other interface. |
254 | The loopback control option has no effect on such delivery. | | 254 | The loopback control option has no effect on such delivery. |
255 | .Pp | | 255 | .Pp |
256 | A host must become a member of a multicast group before it can receive | | 256 | A host must become a member of a multicast group before it can receive |
257 | datagrams sent to the group. | | 257 | datagrams sent to the group. |
258 | To join a multicast group, use the | | 258 | To join a multicast group, use the |
259 | .Dv IP_ADD_MEMBERSHIP | | 259 | .Dv IP_ADD_MEMBERSHIP |
260 | option: | | 260 | option: |
261 | .Bd -literal | | 261 | .Bd -literal |
262 | struct ip_mreq mreq; | | 262 | struct ip_mreq mreq; |
263 | setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); | | 263 | setsockopt(s, IPPROTO_IP, IP_ADD_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); |
264 | .Ed | | 264 | .Ed |
265 | .Pp | | 265 | .Pp |
266 | where | | 266 | where |
267 | .Fa mreq | | 267 | .Fa mreq |
268 | is the following structure: | | 268 | is the following structure: |
269 | .Bd -literal | | 269 | .Bd -literal |
270 | struct ip_mreq { | | 270 | struct ip_mreq { |
271 | struct in_addr imr_multiaddr; /* multicast group to join */ | | 271 | struct in_addr imr_multiaddr; /* multicast group to join */ |
272 | struct in_addr imr_interface; /* interface to join on */ | | 272 | struct in_addr imr_interface; /* interface to join on */ |
273 | } | | 273 | } |
274 | .Ed | | 274 | .Ed |
275 | .Pp | | 275 | .Pp |
276 | .Dv imr_interface | | 276 | .Dv imr_interface |
277 | should be | | 277 | should be |
278 | .Dv INADDR_ANY | | 278 | .Dv INADDR_ANY |
279 | to choose the default multicast interface, or the | | 279 | to choose the default multicast interface, or the |
280 | .Tn IP | | 280 | .Tn IP |
281 | address of a particular multicast-capable interface if | | 281 | address of a particular multicast-capable interface if |
282 | the host is multihomed. | | 282 | the host is multihomed. |
283 | Membership is associated with a single interface; | | 283 | Membership is associated with a single interface; |
284 | programs running on multihomed hosts may need to | | 284 | programs running on multihomed hosts may need to |
285 | join the same group on more than one interface. | | 285 | join the same group on more than one interface. |
286 | Up to | | 286 | Up to |
287 | .Dv IP_MAX_MEMBERSHIPS | | 287 | .Dv IP_MAX_MEMBERSHIPS |
288 | (currently 20) memberships may be added on a single socket. | | 288 | (currently 20) memberships may be added on a single socket. |
289 | .Pp | | 289 | .Pp |
290 | To drop a membership, use: | | 290 | To drop a membership, use: |
291 | .Bd -literal | | 291 | .Bd -literal |
292 | struct ip_mreq mreq; | | 292 | struct ip_mreq mreq; |
293 | setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); | | 293 | setsockopt(s, IPPROTO_IP, IP_DROP_MEMBERSHIP, \*[Am]mreq, sizeof(mreq)); |
294 | .Ed | | 294 | .Ed |
295 | .Pp | | 295 | .Pp |
296 | where | | 296 | where |
297 | .Fa mreq | | 297 | .Fa mreq |
298 | contains the same values as used to add the membership. | | 298 | contains the same values as used to add the membership. |
299 | Memberships are dropped when the socket is closed or the process exits. | | 299 | Memberships are dropped when the socket is closed or the process exits. |
300 | .\"----------------------- | | 300 | .\"----------------------- |
301 | .Ss RAW IP SOCKETS | | 301 | .Ss RAW IP SOCKETS |
302 | Raw | | 302 | Raw |
303 | .Tn IP | | 303 | .Tn IP |
304 | sockets are connectionless, and are normally used with the | | 304 | sockets are connectionless, and are normally used with the |
305 | .Xr sendto 2 | | 305 | .Xr sendto 2 |
306 | and | | 306 | and |
307 | .Xr recvfrom 2 | | 307 | .Xr recvfrom 2 |
308 | calls, though the | | 308 | calls, though the |
309 | .Xr connect 2 | | 309 | .Xr connect 2 |
310 | call may also be used to fix the destination for future | | 310 | call may also be used to fix the destination for future |
311 | packets (in which case the | | 311 | packets (in which case the |
312 | .Xr read 2 | | 312 | .Xr read 2 |
313 | or | | 313 | or |
314 | .Xr recv 2 | | 314 | .Xr recv 2 |
315 | and | | 315 | and |
316 | .Xr write 2 | | 316 | .Xr write 2 |
317 | or | | 317 | or |
318 | .Xr send 2 | | 318 | .Xr send 2 |
319 | system calls may be used). | | 319 | system calls may be used). |
320 | .Pp | | 320 | .Pp |
321 | If | | 321 | If |
322 | .Fa proto | | 322 | .Fa proto |
323 | is 0, the default protocol | | 323 | is 0, the default protocol |
324 | .Dv IPPROTO_RAW | | 324 | .Dv IPPROTO_RAW |
325 | is used for outgoing packets, and only incoming packets destined | | 325 | is used for outgoing packets, and only incoming packets destined |
326 | for that protocol are received. | | 326 | for that protocol are received. |
327 | If | | 327 | If |
328 | .Fa proto | | 328 | .Fa proto |
329 | is non-zero, that protocol number will be used on outgoing packets | | 329 | is non-zero, that protocol number will be used on outgoing packets |
330 | and to filter incoming packets. | | 330 | and to filter incoming packets. |
331 | .Pp | | 331 | .Pp |
332 | Outgoing packets automatically have an | | 332 | Outgoing packets automatically have an |
333 | .Tn IP | | 333 | .Tn IP |
334 | header prepended to them (based on the destination address and the | | 334 | header prepended to them (based on the destination address and the |
335 | protocol number the socket is created with), unless the | | 335 | protocol number the socket is created with), unless the |
336 | .Dv IP_HDRINCL | | 336 | .Dv IP_HDRINCL |
337 | option has been set. | | 337 | option has been set. |
338 | Incoming packets are received with | | 338 | Incoming packets are received with |
339 | .Tn IP | | 339 | .Tn IP |
340 | header and options intact. | | 340 | header and options intact. |
341 | .Pp | | 341 | .Pp |
342 | .Dv IP_HDRINCL | | 342 | .Dv IP_HDRINCL |
343 | indicates the complete IP header is included with the data and may | | 343 | indicates the complete IP header is included with the data and may |
344 | be used only with the | | 344 | be used only with the |
345 | .Dv SOCK_RAW | | 345 | .Dv SOCK_RAW |
346 | type. | | 346 | type. |
347 | .Bd -literal | | 347 | .Bd -literal |
348 | #include \*[Lt]netinet/ip.h\*[Gt] | | 348 | #include \*[Lt]netinet/ip.h\*[Gt] |
349 | | | 349 | |
350 | int hincl = 1; /* 1 = on, 0 = off */ | | 350 | int hincl = 1; /* 1 = on, 0 = off */ |
351 | setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl)); | | 351 | setsockopt(s, IPPROTO_IP, IP_HDRINCL, \*[Am]hincl, sizeof(hincl)); |
352 | .Ed | | 352 | .Ed |
353 | .Pp | | 353 | .Pp |
354 | Unlike previous | | 354 | Unlike previous |
355 | .Bx | | 355 | .Bx |
356 | releases, the program must set all | | 356 | releases, the program must set all |
357 | the fields of the IP header, including the following: | | 357 | the fields of the IP header, including the following: |
358 | .Bd -literal | | 358 | .Bd -literal |
359 | ip-\*[Gt]ip_v = IPVERSION; | | 359 | ip-\*[Gt]ip_v = IPVERSION; |
360 | ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2; | | 360 | ip-\*[Gt]ip_hl = hlen \*[Gt]\*[Gt] 2; |
361 | ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */ | | 361 | ip-\*[Gt]ip_id = 0; /* 0 means kernel set appropriate value */ |
362 | ip-\*[Gt]ip_off = offset; | | 362 | ip-\*[Gt]ip_off = offset; |
363 | .Ed | | 363 | .Ed |
364 | .Pp | | 364 | .Pp |
365 | If the header source address is set to | | 365 | If the header source address is set to |
366 | .Dv INADDR_ANY , | | 366 | .Dv INADDR_ANY , |
367 | the kernel will choose an appropriate address. | | 367 | the kernel will choose an appropriate address. |
368 | .Sh DIAGNOSTICS | | 368 | .Sh DIAGNOSTICS |
369 | A socket operation may fail with one of the following errors returned: | | 369 | A socket operation may fail with one of the following errors returned: |
370 | .Bl -tag -width [EADDRNOTAVAIL] | | 370 | .Bl -tag -width [EADDRNOTAVAIL] |
371 | .It Bq Er EISCONN | | 371 | .It Bq Er EISCONN |
372 | when trying to establish a connection on a socket which already | | 372 | when trying to establish a connection on a socket which already |
373 | has one, or when trying to send a datagram with the destination | | 373 | has one, or when trying to send a datagram with the destination |
374 | address specified and the socket is already connected; | | 374 | address specified and the socket is already connected; |
375 | .It Bq Er ENOTCONN | | 375 | .It Bq Er ENOTCONN |
376 | when trying to send a datagram, but no destination address is | | 376 | when trying to send a datagram, but no destination address is |
377 | specified, and the socket hasn't been connected; | | 377 | specified, and the socket hasn't been connected; |
378 | .It Bq Er ENOBUFS | | 378 | .It Bq Er ENOBUFS |
379 | when the system runs out of memory for an internal data structure; | | 379 | when the system runs out of memory for an internal data structure; |
380 | .It Bq Er EADDRNOTAVAIL | | 380 | .It Bq Er EADDRNOTAVAIL |
381 | when an attempt is made to create a socket with a network address | | 381 | when an attempt is made to create a socket with a network address |
382 | for which no network interface exists. | | 382 | for which no network interface exists. |
383 | .It Bq Er EACCES | | 383 | .It Bq Er EACCES |
384 | when an attempt is made to create a raw IP socket by a non-privileged process. | | 384 | when an attempt is made to create a raw IP socket by a non-privileged process. |
385 | .El | | 385 | .El |
386 | .Pp | | 386 | .Pp |
387 | The following errors specific to | | 387 | The following errors specific to |
388 | .Tn IP | | 388 | .Tn IP |
389 | may occur when setting or getting | | 389 | may occur when setting or getting |
390 | .Tn IP | | 390 | .Tn IP |
391 | options: | | 391 | options: |
392 | .Bl -tag -width EADDRNOTAVAILxx | | 392 | .Bl -tag -width EADDRNOTAVAILxx |
393 | .It Bq Er EINVAL | | 393 | .It Bq Er EINVAL |
394 | An unknown socket option name was given. | | 394 | An unknown socket option name was given. |
395 | .It Bq Er EINVAL | | 395 | .It Bq Er EINVAL |
396 | The IP option field was improperly formed; an option field was | | 396 | The IP option field was improperly formed; an option field was |
397 | shorter than the minimum value or longer than the option buffer provided. | | 397 | shorter than the minimum value or longer than the option buffer provided. |
398 | .El | | 398 | .El |
399 | .Sh SEE ALSO | | 399 | .Sh SEE ALSO |
400 | .Xr getsockopt 2 , | | 400 | .Xr getsockopt 2 , |
401 | .Xr recv 2 , | | 401 | .Xr recv 2 , |
402 | .Xr send 2 , | | 402 | .Xr send 2 , |
403 | .Xr ipsec_set_policy 3 , | | 403 | .Xr ipsec_set_policy 3 , |
404 | .Xr icmp 4 , | | 404 | .Xr icmp 4 , |
405 | .Xr inet 4 , | | 405 | .Xr inet 4 , |
406 | .Xr intro 4 | | 406 | .Xr intro 4 |
407 | .Rs | | 407 | .Rs |
408 | .%R RFC | | 408 | .%R RFC |
409 | .%N 791 | | 409 | .%N 791 |
410 | .%D September 1981 | | 410 | .%D September 1981 |
411 | .%T "Internet Protocol" | | 411 | .%T "Internet Protocol" |
412 | .Re | | 412 | .Re |
413 | .Rs | | 413 | .Rs |
414 | .%R RFC | | 414 | .%R RFC |
415 | .%N 1112 | | 415 | .%N 1112 |
416 | .%D August 1989 | | 416 | .%D August 1989 |
417 | .%T "Host Extensions for IP Multicasting" | | 417 | .%T "Host Extensions for IP Multicasting" |
418 | .Re | | 418 | .Re |
419 | .Rs | | 419 | .Rs |
420 | .%R RFC | | 420 | .%R RFC |
421 | .%N 1122 | | 421 | .%N 1122 |
422 | .%D October 1989 | | 422 | .%D October 1989 |
423 | .%T "Requirements for Internet Hosts -- Communication Layers" | | 423 | .%T "Requirements for Internet Hosts -- Communication Layers" |
424 | .Re | | 424 | .Re |
425 | .Sh HISTORY | | 425 | .Sh HISTORY |
426 | The | | 426 | The |
427 | .Nm | | 427 | .Nm |
428 | protocol appeared in | | 428 | protocol appeared in |
429 | .Bx 4.2 . | | 429 | .Bx 4.2 . |