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