]>
Commit | Line | Data |
---|---|---|
77117f4f | 1 | .\" This man page is Copyright (C) 2000 Andi Kleen <ak@muc.de>. |
2297bf0e | 2 | .\" |
00acdba1 | 3 | .\" %%%LICENSE_START(VERBATIM_ONE_PARA) |
77117f4f MK |
4 | .\" Permission is granted to distribute possibly modified copies |
5 | .\" of this page provided the header is included verbatim, | |
6 | .\" and in case of nontrivial modification author and date | |
7 | .\" of the modification is added to the header. | |
8ff7380d | 8 | .\" %%%LICENSE_END |
6a717e5e | 9 | .\" |
77117f4f | 10 | .\" $Id: ipv6.7,v 1.3 2000/12/20 18:10:31 ak Exp $ |
c6a7484a MK |
11 | .\" |
12 | .\" The following socket options are undocumented | |
78a87bf9 | 13 | .\" All of the following are from: |
c6a7484a MK |
14 | .\" commit 333fad5364d6b457c8d837f7d05802d2aaf8a961 |
15 | .\" Author: YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org> | |
16 | .\" Support several new sockopt / ancillary data in Advanced API (RFC3542). | |
17 | .\" IPV6_2292PKTINFO (2.6.14) | |
18 | .\" Formerly IPV6_PKTINFO | |
19 | .\" IPV6_2292HOPOPTS (2.6.14) | |
20 | .\" Formerly IPV6_HOPOPTS, which is documented | |
21 | .\" IPV6_2292DSTOPTS (2.6.14) | |
22 | .\" Formerly IPV6_DSTOPTS, which is documented | |
23 | .\" IPV6_2292RTHDR (2.6.14) | |
24 | .\" Formerly IPV6_RTHDR, which is documented | |
25 | .\" IPV6_2292PKTOPTIONS (2.6.14) | |
26 | .\" Formerly IPV6_PKTOPTIONS | |
27 | .\" IPV6_2292HOPLIMIT (2.6.14) | |
28 | .\" Formerly IPV6_HOPLIMIT, which is documented | |
e6d86b41 | 29 | .\" |
c6a7484a MK |
30 | .\" IPV6_RECVHOPLIMIT (2.6.14) |
31 | .\" IPV6_RECVHOPOPTS (2.6.14) | |
32 | .\" IPV6_RTHDRDSTOPTS (2.6.14) | |
33 | .\" IPV6_RECVRTHDR (2.6.14) | |
34 | .\" IPV6_RECVDSTOPTS (2.6.14) | |
35 | .\" | |
36 | .\" IPV6_RECVPATHMTU (2.6.35, flag value added in 2.6.14) | |
37 | .\" commit 793b14731686595a741d9f47726ad8b9a235385a | |
38 | .\" Author: Brian Haley <brian.haley@hp.com> | |
39 | .\" IPV6_PATHMTU (2.6.35, flag value added in 2.6.14) | |
40 | .\" commit 793b14731686595a741d9f47726ad8b9a235385a | |
41 | .\" Author: Brian Haley <brian.haley@hp.com> | |
42 | .\" IPV6_DONTFRAG (2.6.35, flag value added in 2.6.14) | |
43 | .\" commit 793b14731686595a741d9f47726ad8b9a235385a | |
44 | .\" Author: Brian Haley <brian.haley@hp.com> | |
45 | .\" commit 4b340ae20d0e2366792abe70f46629e576adaf5e | |
46 | .\" Author: Brian Haley <brian.haley@hp.com> | |
47 | .\" | |
48 | .\" IPV6_RECVTCLASS (2.6.14) | |
49 | .\" commit 41a1f8ea4fbfcdc4232f023732584aae2220de31 | |
50 | .\" Author: YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org> | |
51 | .\" Based on patch from David L Stevens <dlstevens@us.ibm.com> | |
52 | .\" | |
53 | .\" IPV6_CHECKSUM (2.2) | |
54 | .\" IPV6_NEXTHOP (2.2) | |
55 | .\" IPV6_JOIN_ANYCAST (2.4.21 / 2.6) | |
56 | .\" IPV6_LEAVE_ANYCAST (2.4.21 / 2.6) | |
57 | .\" IPV6_FLOWLABEL_MGR (2.2.7 / 2.4) | |
58 | .\" IPV6_FLOWINFO_SEND (2.2.7 / 2.4) | |
59 | .\" IPV6_IPSEC_POLICY (2.6) | |
60 | .\" IPV6_XFRM_POLICY (2.6) | |
61 | .\" IPV6_TCLASS (2.6) | |
62 | .\" | |
63 | .\" IPV6_ADDR_PREFERENCES (2.6.26) | |
64 | .\" commit 7cbca67c073263c179f605bdbbdc565ab29d801d | |
65 | .\" Author: YOSHIFUJI Hideaki <yoshfuji@linux-ipv6.org> | |
66 | .\" IPV6_MINHOPCOUNT (2.6.35) | |
67 | .\" commit e802af9cabb011f09b9c19a82faef3dd315f27eb | |
68 | .\" Author: Stephen Hemminger <shemminger@vyatta.com> | |
69 | .\" IPV6_ORIGDSTADDR (2.6.37) | |
70 | .\" Actually a CMSG rather than a sockopt? | |
71 | .\" In header file, we have IPV6_RECVORIGDSTADDR == IPV6_ORIGDSTADDR | |
72 | .\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 | |
73 | .\" Author: Balazs Scheidler <bazsi@balabit.hu> | |
74 | .\" IPV6_RECVORIGDSTADDR (2.6.37) | |
75 | .\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 | |
76 | .\" Author: Balazs Scheidler <bazsi@balabit.hu> | |
77 | .\" Support for IPV6_RECVORIGDSTADDR sockopt for UDP sockets | |
78 | .\" were contributed by Harry Mason. | |
79 | .\" IPV6_TRANSPARENT (2.6.37) | |
80 | .\" commit 6c46862280c5f55eda7750391bc65cd7e08c7535 | |
81 | .\" Author: Balazs Scheidler <bazsi@balabit.hu> | |
82 | .\" IPV6_UNICAST_IF (3.4) | |
83 | .\" commit c4062dfc425e94290ac427a98d6b4721dd2bc91f | |
84 | .\" Author: Erich E. Hoover <ehoover@mines.edu> | |
85 | .\" | |
1e64c86b | 86 | .TH IPV6 7 2015-03-29 "Linux" "Linux Programmer's Manual" |
77117f4f | 87 | .SH NAME |
61310e03 | 88 | ipv6 \- Linux IPv6 protocol implementation |
77117f4f MK |
89 | .SH SYNOPSIS |
90 | .B #include <sys/socket.h> | |
91 | .br | |
92 | .B #include <netinet/in.h> | |
93 | .sp | |
d4c8c97c | 94 | .IB tcp6_socket " = socket(AF_INET6, SOCK_STREAM, 0);" |
77117f4f | 95 | .br |
d4c8c97c | 96 | .IB raw6_socket " = socket(AF_INET6, SOCK_RAW, " protocol ");" |
77117f4f | 97 | .br |
d4c8c97c | 98 | .IB udp6_socket " = socket(AF_INET6, SOCK_DGRAM, " protocol ");" |
77117f4f MK |
99 | .SH DESCRIPTION |
100 | Linux 2.2 optionally implements the Internet Protocol, version 6. | |
101 | This man page contains a description of the IPv6 basic API as | |
102 | implemented by the Linux kernel and glibc 2.1. | |
103 | The interface | |
104 | is based on the BSD sockets interface; see | |
105 | .BR socket (7). | |
106 | .PP | |
107 | The IPv6 API aims to be mostly compatible with the | |
acae0322 MK |
108 | IPv4 API (see |
109 | .BR ip (7)). | |
77117f4f MK |
110 | Only differences are described in this man page. |
111 | .PP | |
112 | To bind an | |
113 | .B AF_INET6 | |
acae0322 | 114 | socket to any process, the local address should be copied from the |
77117f4f MK |
115 | .I in6addr_any |
116 | variable which has | |
117 | .I in6_addr | |
118 | type. | |
acae0322 | 119 | In static initializations, |
77117f4f MK |
120 | .B IN6ADDR_ANY_INIT |
121 | may also be used, which expands to a constant expression. | |
acae0322 | 122 | Both of them are in network byte order. |
77117f4f MK |
123 | .PP |
124 | The IPv6 loopback address (::1) is available in the global | |
125 | .I in6addr_loopback | |
126 | variable. | |
acae0322 | 127 | For initializations, |
77117f4f MK |
128 | .B IN6ADDR_LOOPBACK_INIT |
129 | should be used. | |
130 | .PP | |
131 | IPv4 connections can be handled with the v6 API by using the | |
132 | v4-mapped-on-v6 address type; | |
043649cd | 133 | thus a program needs to support only this API type to |
77117f4f MK |
134 | support both protocols. |
135 | This is handled transparently by the address | |
acae0322 | 136 | handling functions in the C library. |
77117f4f MK |
137 | .PP |
138 | IPv4 and IPv6 share the local port space. | |
139 | When you get an IPv4 connection | |
acae0322 | 140 | or packet to a IPv6 socket, its source address will be mapped |
77117f4f | 141 | to v6 and it will be mapped to v6. |
73d8cece | 142 | .SS Address format |
77117f4f MK |
143 | .in +4n |
144 | .nf | |
145 | struct sockaddr_in6 { | |
191702ea TH |
146 | sa_family_t sin6_family; /* AF_INET6 */ |
147 | in_port_t sin6_port; /* port number */ | |
77117f4f MK |
148 | uint32_t sin6_flowinfo; /* IPv6 flow information */ |
149 | struct in6_addr sin6_addr; /* IPv6 address */ | |
150 | uint32_t sin6_scope_id; /* Scope ID (new in 2.4) */ | |
151 | }; | |
152 | ||
153 | struct in6_addr { | |
154 | unsigned char s6_addr[16]; /* IPv6 address */ | |
155 | }; | |
156 | .fi | |
157 | .in | |
158 | .sp | |
159 | .I sin6_family | |
160 | is always set to | |
161 | .BR AF_INET6 ; | |
162 | .I sin6_port | |
163 | is the protocol port (see | |
164 | .I sin_port | |
165 | in | |
166 | .BR ip (7)); | |
167 | .I sin6_flowinfo | |
168 | is the IPv6 flow identifier; | |
169 | .I sin6_addr | |
170 | is the 128-bit IPv6 address. | |
171 | .I sin6_scope_id | |
acae0322 | 172 | is an ID depending on the scope of the address. |
77117f4f | 173 | It is new in Linux 2.4. |
33a0ccb2 | 174 | Linux supports it only for link-local addresses, in that case |
77117f4f MK |
175 | .I sin6_scope_id |
176 | contains the interface index (see | |
177 | .BR netdevice (7)) | |
178 | .PP | |
179 | IPv6 supports several address types: unicast to address a single | |
180 | host, multicast to address a group of hosts, | |
181 | anycast to address the nearest member of a group of hosts | |
182 | (not implemented in Linux), IPv4-on-IPv6 to | |
183 | address a IPv4 host, and other reserved address types. | |
184 | .PP | |
c080d579 | 185 | The address notation for IPv6 is a group of 8 4-digit hexadecimal |
77117f4f MK |
186 | numbers, separated with a \(aq:\(aq. |
187 | \&"::" stands for a string of 0 bits. | |
188 | Special addresses are ::1 for loopback and ::FFFF:<IPv4 address> | |
189 | for IPv4-mapped-on-IPv6. | |
190 | .PP | |
191 | The port space of IPv6 is shared with IPv4. | |
73d8cece | 192 | .SS Socket options |
77117f4f MK |
193 | IPv6 supports some protocol-specific socket options that can be set with |
194 | .BR setsockopt (2) | |
195 | and read with | |
196 | .BR getsockopt (2). | |
197 | The socket option level for IPv6 is | |
198 | .BR IPPROTO_IPV6 . | |
199 | A boolean integer flag is zero when it is false, otherwise true. | |
200 | .TP | |
201 | .B IPV6_ADDRFORM | |
202 | Turn an | |
203 | .B AF_INET6 | |
204 | socket into a socket of a different address family. | |
205 | Only | |
206 | .B AF_INET | |
207 | is currently supported for that. | |
33a0ccb2 | 208 | It is allowed only for IPv6 sockets |
77117f4f MK |
209 | that are connected and bound to a v4-mapped-on-v6 address. |
210 | The argument is a pointer to an integer containing | |
211 | .BR AF_INET . | |
212 | This is useful to pass v4-mapped sockets as file descriptors to | |
213 | programs that don't know how to deal with the IPv6 API. | |
214 | .TP | |
215 | .B IPV6_ADD_MEMBERSHIP, IPV6_DROP_MEMBERSHIP | |
216 | Control membership in multicast groups. | |
217 | Argument is a pointer to a | |
437b953c | 218 | .IR "struct ipv6_mreq" . |
77117f4f MK |
219 | .TP |
220 | .B IPV6_MTU | |
2970eb3b | 221 | .BR getsockopt (): |
032e1ba5 | 222 | Retrieve the current known path MTU of the current socket. |
d4c45a8e | 223 | Valid only when the socket has been connected. |
032e1ba5 GF |
224 | Returns an integer. |
225 | ||
2970eb3b | 226 | .BR setsockopt (): |
77117f4f MK |
227 | Set the MTU to be used for the socket. |
228 | The MTU is limited by the device | |
4023450d | 229 | MTU or the path MTU when path MTU discovery is enabled. |
77117f4f MK |
230 | Argument is a pointer to integer. |
231 | .TP | |
232 | .B IPV6_MTU_DISCOVER | |
4023450d | 233 | Control path-MTU discovery on the socket. |
77117f4f MK |
234 | See |
235 | .B IP_MTU_DISCOVER | |
236 | in | |
237 | .BR ip (7) | |
238 | for details. | |
239 | .TP | |
240 | .B IPV6_MULTICAST_HOPS | |
241 | Set the multicast hop limit for the socket. | |
242 | Argument is a pointer to an | |
243 | integer. | |
244 | \-1 in the value means use the route default, otherwise it should be | |
245 | between 0 and 255. | |
246 | .TP | |
247 | .B IPV6_MULTICAST_IF | |
248 | Set the device for outgoing multicast packets on the socket. | |
33a0ccb2 | 249 | This is allowed only for |
77117f4f MK |
250 | .B SOCK_DGRAM |
251 | and | |
252 | .B SOCK_RAW | |
253 | socket. | |
254 | The argument is a pointer to an interface index (see | |
255 | .BR netdevice (7)) | |
256 | in an integer. | |
257 | .TP | |
258 | .B IPV6_MULTICAST_LOOP | |
259 | Control whether the socket sees multicast packets that it has send itself. | |
260 | Argument is a pointer to boolean. | |
261 | .TP | |
d796c68d | 262 | .BR IPV6_RECVPKTINFO " (since Linux 2.6.14)" |
77117f4f MK |
263 | Set delivery of the |
264 | .B IPV6_PKTINFO | |
265 | control message on incoming datagrams. | |
b33062e5 DP |
266 | Such control messages contain a |
267 | .IR "struct in6_pktinfo" , | |
268 | as per RFC 3542. | |
d4c45a8e | 269 | Allowed only for |
77117f4f MK |
270 | .B SOCK_DGRAM |
271 | or | |
272 | .B SOCK_RAW | |
273 | sockets. | |
274 | Argument is a pointer to a boolean value in an integer. | |
275 | .TP | |
276 | .nh | |
52e27aeb | 277 | .B IPV6_RTHDR, IPV6_AUTHHDR, IPV6_DSTOPTS, IPV6_HOPOPTS, IPV6_FLOWINFO, IPV6_HOPLIMIT |
77117f4f MK |
278 | .hy |
279 | Set delivery of control messages for incoming datagrams containing | |
280 | extension headers from the received packet. | |
281 | .B IPV6_RTHDR | |
282 | delivers the routing header, | |
283 | .B IPV6_AUTHHDR | |
284 | delivers the authentication header, | |
285 | .B IPV6_DSTOPTS | |
286 | delivers the destination options, | |
287 | .B IPV6_HOPOPTS | |
288 | delivers the hop options, | |
289 | .B IPV6_FLOWINFO | |
290 | delivers an integer containing the flow ID, | |
291 | .B IPV6_HOPLIMIT | |
292 | delivers an integer containing the hop count of the packet. | |
293 | The control messages have the same type as the socket option. | |
294 | All these header options can also be set for outgoing packets | |
295 | by putting the appropriate control message into the control buffer of | |
296 | .BR sendmsg (2). | |
d4c45a8e | 297 | Allowed only for |
77117f4f MK |
298 | .B SOCK_DGRAM |
299 | or | |
300 | .B SOCK_RAW | |
301 | sockets. | |
302 | Argument is a pointer to a boolean value. | |
303 | .TP | |
304 | .B IPV6_RECVERR | |
305 | Control receiving of asynchronous error options. | |
306 | See | |
307 | .B IP_RECVERR | |
308 | in | |
309 | .BR ip (7) | |
310 | for details. | |
311 | Argument is a pointer to boolean. | |
312 | .TP | |
313 | .B IPV6_ROUTER_ALERT | |
314 | Pass forwarded packets containing a router alert hop-by-hop option to | |
315 | this socket. | |
d4c45a8e | 316 | Allowed only for |
b834c23e YK |
317 | .B SOCK_RAW |
318 | sockets. | |
77117f4f MK |
319 | The tapped packets are not forwarded by the kernel, it is the |
320 | user's responsibility to send them out again. | |
321 | Argument is a pointer to an integer. | |
322 | A positive integer indicates a router alert option value to intercept. | |
323 | Packets carrying a router alert option with a value field containing | |
324 | this integer will be delivered to the socket. | |
325 | A negative integer disables delivery of packets with router alert options | |
326 | to this socket. | |
327 | .TP | |
328 | .B IPV6_UNICAST_HOPS | |
329 | Set the unicast hop limit for the socket. | |
330 | Argument is a pointer to an integer. | |
331 | \-1 in the value means use the route default, | |
332 | otherwise it should be between 0 and 255. | |
333 | .TP | |
334 | .BR IPV6_V6ONLY " (since Linux 2.4.21 and 2.6)" | |
335 | .\" See RFC 3493 | |
c7094399 | 336 | If this flag is set to true (nonzero), then the socket is restricted |
77117f4f MK |
337 | to sending and receiving IPv6 packets only. |
338 | In this case, an IPv4 and an IPv6 application can bind | |
339 | to a single port at the same time. | |
340 | ||
341 | If this flag is set to false (zero), | |
342 | then the socket can be used to send and receive packets | |
343 | to and from an IPv6 address or an IPv4-mapped IPv6 address. | |
344 | ||
345 | The argument is a pointer to a boolean value in an integer. | |
346 | ||
347 | The default value for this flag is defined by the contents of the file | |
f08b799c | 348 | .IR /proc/sys/net/ipv6/bindv6only . |
77117f4f MK |
349 | The default value for that file is 0 (false). |
350 | .\" FLOWLABEL_MGR, FLOWINFO_SEND | |
85ab5d7a | 351 | .SH ERRORS |
85ab5d7a SP |
352 | .TP |
353 | .B ENODEV | |
354 | The user tried to | |
355 | .BR bind (2) | |
356 | to a link-local IPv6 address, but the | |
357 | .I sin6_scope_id | |
358 | in the supplied | |
359 | .I sockaddr_in6 | |
360 | structure is not a valid | |
361 | interface index. | |
77117f4f | 362 | .SH VERSIONS |
77117f4f MK |
363 | Linux 2.4 will break binary compatibility for the |
364 | .I sockaddr_in6 | |
365 | for 64-bit | |
366 | hosts by changing the alignment of | |
367 | .I in6_addr | |
368 | and adding an additional | |
369 | .I sin6_scope_id | |
370 | field. | |
371 | The kernel interfaces stay compatible, but a program including | |
372 | .I sockaddr_in6 | |
373 | or | |
374 | .I in6_addr | |
375 | into other structures may not be. | |
376 | This is not | |
377 | a problem for 32-bit hosts like i386. | |
378 | .PP | |
379 | The | |
380 | .I sin6_flowinfo | |
381 | field is new in Linux 2.4. | |
382 | It is transparently passed/read by the kernel | |
383 | when the passed address length contains it. | |
384 | Some programs that pass a longer address buffer and then | |
385 | check the outgoing address length may break. | |
47297adb | 386 | .SH NOTES |
77117f4f MK |
387 | The |
388 | .I sockaddr_in6 | |
389 | structure is bigger than the generic | |
390 | .IR sockaddr . | |
391 | Programs that assume that all address types can be stored safely in a | |
392 | .I struct sockaddr | |
393 | need to be changed to use | |
394 | .I struct sockaddr_storage | |
395 | for that instead. | |
8013e4ef SA |
396 | .PP |
397 | .BR SOL_IP , | |
398 | .BR SOL_IPV6 , | |
399 | .B SOL_ICMPV6 | |
400 | and other | |
401 | .BR SOL_ * | |
636355f9 | 402 | socket options are nonportable variants of |
8013e4ef | 403 | .BR IPPROTO_ *. |
636355f9 MK |
404 | See also |
405 | .BR ip (7). | |
77117f4f MK |
406 | .SH BUGS |
407 | The IPv6 extended API as in RFC\ 2292 is currently only partly | |
408 | implemented; | |
409 | although the 2.2 kernel has near complete support for receiving options, | |
410 | the macros for generating IPv6 options are missing in glibc 2.1. | |
411 | .PP | |
412 | IPSec support for EH and AH headers is missing. | |
413 | .PP | |
414 | Flow label management is not complete and not documented here. | |
415 | .PP | |
416 | This man page is not complete. | |
47297adb | 417 | .SH SEE ALSO |
77117f4f MK |
418 | .BR cmsg (3), |
419 | .BR ip (7) | |
420 | .PP | |
173fe7e7 | 421 | RFC\ 2553: IPv6 BASIC API; |
77117f4f | 422 | Linux tries to be compliant to this. |
77117f4f | 423 | RFC\ 2460: IPv6 specification. |