share/man/man4/ip6.4

   1 .\"     $KAME: ip6.4,v 1.14 2001/02/26 09:31:39 itojun Exp $
   2 .\"
   3 .\" Copyright (C) 1999 WIDE Project.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the project nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  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
  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
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" Copyright (c) 1983, 1991, 1993
  31 .\"     The Regents of the University of California.  All rights reserved.
  32 .\"
  33 .\" Redistribution and use in source and binary forms, with or without
  34 .\" modification, are permitted provided that the following conditions
  35 .\" are met:
  36 .\" 1. Redistributions of source code must retain the above copyright
  37 .\"    notice, this list of conditions and the following disclaimer.
  38 .\" 2. Redistributions in binary form must reproduce the above copyright
  39 .\"    notice, this list of conditions and the following disclaimer in the
  40 .\"    documentation and/or other materials provided with the distribution.
  41 .\" 3. All advertising materials mentioning features or use of this software
  42 .\"    must display the following acknowledgement:
  43 .\"     This product includes software developed by the University of
  44 .\"     California, Berkeley and its contributors.
  45 .\" 4. Neither the name of the University nor the names of its contributors
  46 .\"    may be used to endorse or promote products derived from this software
  47 .\"    without specific prior written permission.
  48 .\"
  49 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  50 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  51 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  52 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  53 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  54 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  55 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  56 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  57 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  58 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  59 .\" SUCH DAMAGE.
  60 .\"
  61 .\" $FreeBSD: src/share/man/man4/ip6.4,v 1.1.2.8 2001/12/17 11:30:12 ru Exp $
  62 .\" $DragonFly: src/share/man/man4/ip6.4,v 1.2 2003/06/17 04:36:59 dillon Exp $
  63 .\"
  64 .Dd March 13, 2000
  65 .Dt IP6 4
  66 .Os
  67 .\"
  68 .Sh NAME
  69 .Nm ip6
  70 .Nd Internet Protocol version 6 (IPv6)
  71 .\"
  72 .Sh SYNOPSIS
  73 .In sys/types.h
  74 .In sys/socket.h
  75 .In netinet/in.h
  76 .Ft int
  77 .Fn socket AF_INET6 SOCK_RAW proto
  78 .\"
  79 .Sh DESCRIPTION
  80 .Tn IPv6
  81 is the network layer protocol used by the Internet protocol version 6 family
  82 .Pq Dv AF_INET6 .
  83 Options may be set at the
  84 .Tn IPv6
  85 level when using higher-level protocols that are based on
  86 .Tn IPv6
  87 (such as
  88 .Tn TCP
  89 and
  90 .Tn UDP ) .
  91 It may also be accessed through a
  92 .Dq raw socket
  93 when developing new protocols, or special-purpose applications.
  94 .Pp
  95 There are several
  96 .Tn IPv6-level
  97 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
  98 options.
  99 They are separated into the basic IPv6 sockets API
 100 (defined in RFC2553),
 101 and the advanced API
 102 (defined in RFC2292).
 103 The basic API looks very similar to the API presented in
 104 .Xr ip 4 .
 105 Advanced API uses ancillary data and can handle more complex cases.
 106 .Pp
 107 To specify some of socket options, certain privilege
 108 (i.e. root privilege) is required.
 109 .\"
 110 .Ss Basic IPv6 sockets API
 111 .Dv IPV6_UNICAST_HOPS
 112 may be used to set the hoplimit field in the
 113 .Tn IPv6
 114 header.
 115 As symbol name suggests, the option controls hoplimit field on unicast packets.
 116 If -1 is specified, the kernel will use a default value.
 117 If a value of 0 to 255 is specified, the packet will have the specified
 118 value as hoplimit.
 119 Other values are considered invalid, and
 120 .Er EINVAL
 121 will be returned.
 122 For example:
 123 .Bd -literal -offset indent
 124 int hlim = 60;                   /* max = 255 */
 125 setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim));
 126 .Ed
 127 .Pp
 128 .Tn IPv6
 129 multicasting is supported only on
 130 .Dv AF_INET6
 131 sockets of type
 132 .Dv SOCK_DGRAM
 133 and
 134 .Dv SOCK_RAW,
 135 and only on networks where the interface driver supports multicasting.
 136 .Pp
 137 The
 138 .Dv IPV6_MULTICAST_HOPS
 139 option changes the hoplimit for outgoing multicast datagrams
 140 in order to control the scope of the multicasts:
 141 .Bd -literal -offset indent
 142 unsigned int hlim;      /* range: 0 to 255, default = 1 */
 143 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim));
 144 .Ed
 145 .Pp
 146 Datagrams with a hoplimit of 1 are not forwarded beyond the local network.
 147 Multicast datagrams with a hoplimit of 0 will not be transmitted on any network,
 148 but may be delivered locally if the sending host belongs to the destination
 149 group and if multicast loopback has not been disabled on the sending socket
 150 (see below).
 151 Multicast datagrams with hoplimit greater than 1 may be forwarded
 152 to other networks if a multicast router is attached to the local network.
 153 .Pp
 154 For hosts with multiple interfaces, each multicast transmission is
 155 sent from the primary network interface.
 156 The
 157 .Dv IPV6_MULTICAST_IF
 158 option overrides the default for
 159 subsequent transmissions from a given socket:
 160 .Bd -literal -offset indent
 161 unsigned int outif;
 162 outif = if_nametoindex("ne0");
 163 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif));
 164 .Ed
 165 .Pp
 166 where "outif" is an interface index of the desired interface,
 167 or 0 to specify the default interface.
 168 .Pp
 169 If a multicast datagram is sent to a group to which the sending host itself
 170 belongs (on the outgoing interface), a copy of the datagram is, by default,
 171 looped back by the IPv6 layer for local delivery.
 172 The
 173 .Dv IPV6_MULTICAST_LOOP
 174 option gives the sender explicit control
 175 over whether or not subsequent datagrams are looped back:
 176 .Bd -literal -offset indent
 177 u_char loop;    /* 0 = disable, 1 = enable (default) */
 178 setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop));
 179 .Ed
 180 .Pp
 181 This option
 182 improves performance for applications that may have no more than one
 183 instance on a single host (such as a router daemon), by eliminating
 184 the overhead of receiving their own transmissions.
 185 It should generally not be used by applications for which there
 186 may be more than one instance on a single host (such as a conferencing
 187 program) or for which the sender does not belong to the destination
 188 group (such as a time querying program).
 189 .Pp
 190 A multicast datagram sent with an initial hoplimit greater than 1 may be delivered
 191 to the sending host on a different interface from that on which it was sent,
 192 if the host belongs to the destination group on that other interface.
 193 The loopback control option has no effect on such delivery.
 194 .Pp
 195 A host must become a member of a multicast group before it can receive
 196 datagrams sent to the group.
 197 To join a multicast group, use the
 198 .Dv IPV6_JOIN_GROUP
 199 option:
 200 .Bd -literal -offset indent
 201 struct ipv6_mreq mreq6;
 202 setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6));
 203 .Ed
 204 .Pp
 205 where
 206 .Fa mreq6
 207 is the following structure:
 208 .Bd -literal -offset indent
 209 struct ipv6_mreq {
 210     struct in6_addr ipv6mr_multiaddr;
 211     u_int ipv6mr_interface;
 212 };
 213 .Ed
 214 .Pp
 215 .Dv ipv6mr_interface
 216 should be 0 to choose the default multicast interface, or the
 217 interface index of a particular multicast-capable interface if
 218 the host is multihomed.
 219 Membership is associated with a single interface;
 220 programs running on multihomed hosts may need to
 221 join the same group on more than one interface.
 222 .Pp
 223 To drop a membership, use:
 224 .Bd -literal -offset indent
 225 struct ipv6_mreq mreq6;
 226 setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6));
 227 .Ed
 228 .Pp
 229 where
 230 .Fa mreq6
 231 contains the same values as used to add the membership.
 232 Memberships are dropped when the socket is closed or the process exits.
 233 .Pp
 234 .Dv IPV6_PORTRANGE
 235 controls how ephemeral ports are allocated for
 236 .Dv SOCK_STREAM
 237 and
 238 .Dv SOCK_DGRAM
 239 sockets.
 240 For example,
 241 .Bd -literal -offset indent
 242 int range = IPV6_PORTRANGE_LOW;       /* see <netinet/in.h> */
 243 setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range));
 244 .Ed
 245 .Pp
 246 .Dv IPV6_V6ONLY
 247 controls behavior of
 248 .Dv AF_INET6
 249 wildcard listening socket.
 250 The following example sets the option to 1:
 251 .Bd -literal -offset indent
 252 int on = 1;
 253 setsockopt(s, IPPROTO_IPV6, IPV6_V6ONLY, &on, sizeof(on));
 254 .Ed
 255 .Pp
 256 If set to 1,
 257 .Dv AF_INET6
 258 wildcard listening socket will accept IPv6 traffic only.
 259 If set to 0, it will accept IPv4 traffic as well,
 260 as if it was from IPv4 mapped address like
 261 .Li ::ffff:10.1.1.1 .
 262 .\" RFC2553 defines the behavior when the variable is set to 0.
 263 Note that if you set it this to 0,
 264 IPv4 access control gets much more complicated.
 265 For example, even if you have no listening
 266 .Dv AF_INET
 267 listening socket on port
 268 .Li X ,
 269 you will end up accepting IPv4 traffic by
 270 .Dv AF_INET6
 271 listening socket on the same port.
 272 The default value for this flag is copied at socket instantiation time,
 273 from
 274 .Li net.inet6.ip6.v6only
 275 .Xr sysctl 3
 276 variable.
 277 The option affects
 278 .Tn TCP
 279 and
 280 .Tn UDP
 281 sockets only.
 282 .\"
 283 .Ss Advanced IPv6 sockets API
 284 The advanced IPv6 sockets API lets userland programs specify or obtain
 285 details about the IPv6 header and the IPv6 extension headers on packets.
 286 The advanced API uses ancillary data for passing data from/to the kernel.
 287 .Pp
 288 There are
 289 .Xr setsockopt 2 Ns / Ns Xr getsockopt 2
 290 options to get optional information on incoming packets.
 291 They are
 292 .Dv IPV6_PKTINFO ,
 293 .Dv IPV6_HOPLIMIT ,
 294 .Dv IPV6_HOPOPTS ,
 295 .Dv IPV6_DSTOPTS ,
 296 and
 297 .Dv IPV6_RTHDR .
 298 .Bd -literal -offset indent
 299 int  on = 1;
 300
 301 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO,  &on, sizeof(on));
 302 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on));
 303 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS,  &on, sizeof(on));
 304 setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS,  &on, sizeof(on));
 305 setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR,    &on, sizeof(on));
 306 .Ed
 307 .Pp
 308 When any of these options are enabled, the corresponding data is
 309 returned as control information by
 310 .Xr recvmsg 2 ,
 311 as one or more ancillary data objects.
 312 .Pp
 313 If
 314 .Dv IPV6_PKTINFO
 315 is enabled, the destination IPv6 address and the arriving interface index
 316 will be available via
 317 .Li struct in6_pktinfo
 318 on ancillary data stream.
 319 You can pick the structure by checking for an ancillary data item with
 320 .Li cmsg_level
 321 equals to
 322 .Dv IPPROTO_IPV6 ,
 323 and
 324 .Li cmsg_type
 325 equals to
 326 .Dv IPV6_PKTINFO .
 327 .Pp
 328 If
 329 .Dv IPV6_HOPLIMIT
 330 is enabled, hoplimit value on the packet will be made available to the
 331 userland program.
 332 Ancillary data stream will contain an integer data item with
 333 .Li cmsg_level
 334 equals to
 335 .Dv IPPROTO_IPV6 ,
 336 and
 337 .Li cmsg_type
 338 equals to
 339 .Dv IPV6_HOPLIMIT .
 340 .Pp
 341 .Xr inet6_option_space 3
 342 and friends will help you parse ancillary data items for
 343 .Dv IPV6_HOPOPTS
 344 and
 345 .Dv IPV6_DSTOPTS .
 346 Similarly,
 347 .Xr inet6_rthdr_space 3
 348 and friends will help you parse ancillary data items for
 349 .Dv IPV6_RTHDR .
 350 .Pp
 351 .Dv IPV6_HOPOPTS
 352 and
 353 .Dv IPV6_DSTOPTS
 354 may appear multiple times on an ancillary data stream
 355 (note that the behavior is slightly different than the specification).
 356 Other ancillary data item will appear no more than once.
 357 .Pp
 358 For outgoing direction,
 359 you can pass ancillary data items with normal payload data, using
 360 .Xr sendmsg 2 .
 361 Ancillary data items will be parsed by the kernel, and used to construct
 362 the IPv6 header and extension headers.
 363 For the 5
 364 .Li cmsg_level
 365 values listed above, ancillary data format is the same as inbound case.
 366 Additionally, you can specify
 367 .Dv IPV6_NEXTHOP
 368 data object.
 369 The
 370 .Dv IPV6_NEXTHOP
 371 ancillary data object specifies the next hop for the
 372 datagram as a socket address structure.
 373 In the
 374 .Li cmsghdr
 375 structure
 376 containing this ancillary data, the
 377 .Li cmsg_level
 378 member will be
 379 .Dv IPPROTO_IPV6 ,
 380 the
 381 .Li cmsg_type
 382 member will be
 383 .Dv IPV6_NEXTHOP ,
 384 and the first byte of
 385 .Li cmsg_data[]
 386 will be the first byte of the socket address structure.
 387 .Pp
 388 If the socket address structure contains an IPv6 address (e.g., the
 389 sin6_family member is
 390 .Dv AF_INET6 ) ,
 391 then the node identified by that
 392 address must be a neighbor of the sending host.
 393 If that address
 394 equals the destination IPv6 address of the datagram, then this is
 395 equivalent to the existing
 396 .Dv SO_DONTROUTE
 397 socket option.
 398 .Pp
 399 For applications that do not, or unable to use
 400 .Xr sendmsg 2
 401 or
 402 .Xr recvmsg 2 ,
 403 .Dv IPV6_PKTOPTIONS
 404 socket option is defined.
 405 Setting the socket option specifies any of the optional output fields:
 406 .Bd -literal -offset indent
 407 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len);
 408 .Ed
 409 .Pp
 410 The fourth argument points to a buffer containing one or more
 411 ancillary data objects, and the fifth argument is the total length of
 412 all these objects.
 413 The application fills in this buffer exactly as
 414 if the buffer were being passed to
 415 .Xr sendmsg 2
 416 as control information.
 417 .Pp
 418 The options set by calling
 419 .Xr setsockopt 2
 420 for
 421 .Dv IPV6_PKTOPTIONS
 422 are
 423 called "sticky" options because once set they apply to all packets
 424 sent on that socket.
 425 The application can call
 426 .Xr setsockopt 2
 427 again to
 428 change all the sticky options, or it can call
 429 .Xr setsockopt 2
 430 with a
 431 length of 0 to remove all the sticky options for the socket.
 432 .Pp
 433 The corresponding receive option
 434 .Bd -literal -offset indent
 435 getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len);
 436 .Ed
 437 .Pp
 438 returns a buffer with one or more ancillary data objects for all the
 439 optional receive information that the application has previously
 440 specified that it wants to receive.
 441 The fourth argument points to
 442 the buffer that is filled in by the call.
 443 The fifth argument is a
 444 pointer to a value-result integer: when the function is called the
 445 integer specifies the size of the buffer pointed to by the fourth
 446 argument, and on return this integer contains the actual number of
 447 bytes that were returned.
 448 The application processes this buffer
 449 exactly as if the buffer were returned by
 450 .Xr recvmsg 2
 451 as control information.
 452 .\"
 453 .Ss Advanced API and TCP sockets
 454 When using
 455 .Xr getsockopt 2
 456 with the
 457 .Dv IPV6_PKTOPTIONS
 458 option and a
 459 .Tn TCP
 460 socket, only the options from the most recently received segment are
 461 retained and returned to the caller, and only after the socket option
 462 has been set.
 463 .\" That is,
 464 .\" .Tn TCP
 465 .\" need not start saving a copy of the options until the application says
 466 .\" to do so.
 467 The application is not allowed to specify ancillary data in a call to
 468 .Xr sendmsg 2
 469 on a
 470 .Tn TCP
 471 socket, and none of the ancillary data that we
 472 described above is ever returned as control information by
 473 .Xr recvmsg 2
 474 on a
 475 .Tn TCP
 476 socket.
 477 .\"
 478 .Ss Conflict resolution
 479 In some cases, there are multiple APIs defined for manipulating
 480 a IPv6 header field.
 481 A good example is the outgoing interface for multicast datagrams:
 482 it can be manipulated by
 483 .Dv IPV6_MULTICAST_IF
 484 in basic API,
 485 .Dv IPV6_PKTINFO
 486 in advanced API, and
 487 .Li sin6_scope_id
 488 field of the socket address passed to
 489 .Xr sendto 2 .
 490 .Pp
 491 When conflicting options are given to the kernel,
 492 the kernel will get the value in the following preference:
 493 (1) options specified by using ancillary data,
 494 (2) options specified by a sticky option of the advanced API,
 495 (3) options specified by using the basic API, and lastly
 496 (4) options specified by a socket address.
 497 Note that the conflict resolution is undefined in the API specifcation
 498 and implementation dependent.
 499 .\"
 500 .Ss "Raw IPv6 Sockets"
 501 Raw
 502 .Tn IPv6
 503 sockets are connectionless, and are normally used with the
 504 .Xr sendto 2
 505 and
 506 .Xr recvfrom 2
 507 calls, though the
 508 .Xr connect 2
 509 call may also be used to fix the destination for future
 510 packets (in which case the
 511 .Xr read 2
 512 or
 513 .Xr recv 2
 514 and
 515 .Xr write 2
 516 or
 517 .Xr send 2
 518 system calls may be used).
 519 .Pp
 520 If
 521 .Fa proto
 522 is 0, the default protocol
 523 .Dv IPPROTO_RAW
 524 is used for outgoing packets, and only incoming packets destined
 525 for that protocol are received.
 526 If
 527 .Fa proto
 528 is non-zero, that protocol number will be used on outgoing packets
 529 and to filter incoming packets.
 530 .Pp
 531 Outgoing packets automatically have an
 532 .Tn IPv6
 533 header prepended to them (based on the destination address and the
 534 protocol number the socket is created with).
 535 Incoming packets are received without
 536 .Tn IPv6
 537 header nor extension headers.
 538 .Pp
 539 All data sent via raw sockets MUST be in network byte order and all
 540 data received via raw sockets will be in network byte order.
 541 This differs from the IPv4 raw sockets, which did not specify a byte
 542 ordering and typically used the host's byte order.
 543 .Pp
 544 Another difference from IPv4 raw sockets is that complete packets
 545 (that is, IPv6 packets with extension headers) cannot be read or
 546 written using the IPv6 raw sockets API.
 547 Instead, ancillary data
 548 objects are used to transfer the extension headers, as described above.
 549 Should an application need access to the
 550 complete IPv6 packet, some other technique, such as the datalink
 551 interfaces, such as
 552 .Xr bpf 4 ,
 553 must be used.
 554 .Pp
 555 All fields in the IPv6 header that an application might want to
 556 change (i.e., everything other than the version number) can be
 557 modified using ancillary data and/or socket options by the
 558 application for output.
 559 All fields in a received IPv6 header (other
 560 than the version number and Next Header fields) and all extension
 561 headers are also made available to the application as ancillary data
 562 on input.
 563 Hence there is no need for a socket option similar to the
 564 IPv4
 565 .Dv IP_HDRINCL
 566 socket option.
 567 .Pp
 568 When writing to a raw socket the kernel will automatically fragment
 569 the packet if its size exceeds the path MTU, inserting the required
 570 fragmentation headers.  On input the kernel reassembles received
 571 fragments, so the reader of a raw socket never sees any fragment
 572 headers.
 573 .Pp
 574 Most IPv4 implementations give special treatment to a raw socket
 575 created with a third argument to
 576 .Xr socket 2
 577 of
 578 .Dv IPPROTO_RAW ,
 579 whose value is normally 255.
 580 We note that this value has no special meaning to
 581 an IPv6 raw socket (and the IANA currently reserves the value of 255
 582 when used as a next-header field).
 583 .\" Note: This feature was added to
 584 .\" IPv4 in 1988 by Van Jacobson to support traceroute, allowing a
 585 .\" complete IP header to be passed by the application, before the
 586 .\" .Dv IP_HDRINCL
 587 .\" socket option was added.
 588 .Pp
 589 For ICMPv6 raw sockets,
 590 the kernel will calculate and insert the ICMPv6 checksum for
 591 since this checksum is mandatory.
 592 .Pp
 593 For other raw IPv6 sockets (that is, for raw IPv6 sockets created
 594 with a third argument other than IPPROTO_ICMPV6), the application
 595 must set the new IPV6_CHECKSUM socket option to have the kernel (1)
 596 compute and store a psuedo header checksum for output,
 597 and (2) verify the received
 598 pseudo header checksum on input,
 599 discarding the packet if the checksum is in error.
 600 This option prevents applications from having to perform source
 601 address selection on the packets they send.
 602 The checksum will
 603 incorporate the IPv6 pseudo-header, defined in Section 8.1 of RFC2460.
 604 This new socket option also specifies an integer offset into
 605 the user data of where the checksum is located.
 606 .Bd -literal -offset indent
 607 int offset = 2;
 608 setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset));
 609 .Ed
 610 .Pp
 611 By default, this socket option is disabled.  Setting the offset to -1
 612 also disables the option.  By disabled we mean (1) the kernel will
 613 not calculate and store a checksum for outgoing packets, and (2) the
 614 kernel will not verify a checksum for received packets.
 615 .Pp
 616 Note: Since the checksum is always calculated by the kernel for an
 617 ICMPv6 socket, applications are not able to generate ICMPv6 packets
 618 with incorrect checksums (presumably for testing purposes) using this
 619 API.
 620 .\"
 621 .Sh ERRORS
 622 A socket operation may fail with one of the following errors returned:
 623 .Bl -tag -width Er
 624 .It Bq Er EISCONN
 625 when trying to establish a connection on a socket which already
 626 has one, or when trying to send a datagram with the destination
 627 address specified and the socket is already connected;
 628 .It Bq Er ENOTCONN
 629 when trying to send a datagram, but no destination address is
 630 specified, and the socket hasn't been connected;
 631 .It Bq Er ENOBUFS
 632 when the system runs out of memory for an internal data structure;
 633 .It Bq Er EADDRNOTAVAIL
 634 when an attempt is made to create a socket with a network address
 635 for which no network interface exists.
 636 .It Bq Er EACCES
 637 when an attempt is made to create a raw IPv6 socket by a non-privileged process.
 638 .El
 639 .Pp
 640 The following errors specific to
 641 .Tn IPv6
 642 may occur:
 643 .Bl -tag -width EADDRNOTAVAILxx
 644 .It Bq Er EINVAL
 645 An unknown socket option name was given.
 646 .It Bq Er EINVAL
 647 The ancillary data items were improperly formed, or option name was unknown.
 648 .El
 649 .\"
 650 .Sh SEE ALSO
 651 .Xr getsockopt 2 ,
 652 .Xr recv 2 ,
 653 .Xr send 2 ,
 654 .Xr setsockopt 2 ,
 655 .Xr inet6_option_space 3 ,
 656 .Xr inet6_rthdr_space 3 ,
 657 .Xr icmp6 4 ,
 658 .Xr inet6 4 ,
 659 .Xr intro 4
 660 .Rs
 661 .%A W. Stevens
 662 .%A M. Thomas
 663 .%R RFC
 664 .%N 2292
 665 .%D February 1998
 666 .%T "Advanced Sockets API for IPv6"
 667 .Re
 668 .Rs
 669 .%A S. Deering
 670 .%A R. Hinden
 671 .%R RFC
 672 .%N 2460
 673 .%D December 1998
 674 .%T "Internet Protocol, Version 6 (IPv6) Specification"
 675 .Re
 676 .Rs
 677 .%A R. Gilligan
 678 .%A S. Thomson
 679 .%A J. Bound
 680 .%A W. Stevens
 681 .%R RFC
 682 .%N 2553
 683 .%D March 1999
 684 .%T "Basic Socket Interface Extensions for IPv6"
 685 .Re
 686 .\"
 687 .Sh STANDARDS
 688 Most of the socket options are defined in
 689 RFC2292 and/or RFC2553.
 690 .Pp
 691 .Dv IPV6_V6ONLY
 692 socket option is defined in draft-ietf-ipngwg-rfc2553bis-03.
 693 .Dv IPV6_PORTRANGE
 694 socket option
 695 and
 696 conflict resolution rule
 697 are not defined in the RFCs and should be considered implementation dependent.
 698 .\"
 699 .Sh HISTORY
 700 The implementation is based on KAME stack
 701 (which is descendant of WIDE hydrangea IPv6 stack kit).
 702 .Pp
 703 Part of the document was shamelessly copied from RFC2553 and RFC2292.
 704 .\"
 705 .Sh BUGS
 706 The
 707 .Dv IPV6_NEXTHOP
 708 object/option is not fully implemented as of writing this.