diff options
| -rw-r--r-- | share/man/man4/Makefile | 4 | ||||
| -rw-r--r-- | share/man/man4/icmp6.4 | 262 | ||||
| -rw-r--r-- | share/man/man4/inet6.4 | 6 | ||||
| -rw-r--r-- | share/man/man4/ip6.4 | 647 |
4 files changed, 916 insertions, 3 deletions
diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 1b42f68cc97..5ca7a6d3682 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.90 1999/12/15 16:27:24 jason Exp $ +# $OpenBSD: Makefile,v 1.91 1999/12/19 03:14:27 itojun Exp $ # $NetBSD: Makefile,v 1.22.4.2 1996/07/18 00:51:10 jtc Exp $ MAN= ac97.4 atalk.4 atapiscsi.4 audio.4 adv.4 ahc.4 al.4 ax.4 bpf.4 \ @@ -16,7 +16,7 @@ MAN= ac97.4 atalk.4 atapiscsi.4 audio.4 adv.4 ahc.4 al.4 ax.4 bpf.4 \ zero.4 # IPv6 -MAN+= faith.4 gif.4 inet6.4 +MAN+= faith.4 gif.4 icmp6.4 inet6.4 ip6.4 MLINKS+=fd.4 stderr.4 fd.4 stdin.4 fd.4 stdout.4 MLINKS+=netintro.4 networking.4 diff --git a/share/man/man4/icmp6.4 b/share/man/man4/icmp6.4 new file mode 100644 index 00000000000..58093019cab --- /dev/null +++ b/share/man/man4/icmp6.4 @@ -0,0 +1,262 @@ +.\" $OpenBSD: icmp6.4,v 1.1 1999/12/19 03:14:27 itojun Exp $ +.\" +.\" Copyright (C) 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Copyright (c) 1986, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" KAME Id: icmp6.4,v 1.1 1999/12/17 09:47:01 itojun Exp +.\" +.Dd December 17, 1999 +.Dt ICMP6 4 +.Os +." +.Sh NAME +.Nm icmp6 +.Nd Internet Control Message Protocol for IPv6 +." +.Sh SYNOPSIS +.Fd #include <sys/socket.h> +.Fd #include <netinet/in.h> +.Fd #include <netinet/icmp6.h> +.Ft int +.Fn socket AF_INET6 SOCK_RAW proto +." +.Sh DESCRIPTION +.Tn ICMPv6 +is the error and control message protocol used +by +.Tn IPv6 +and the Internet protocol family. +It may be accessed through a +.Dq raw socket +for network monitoring and diagnostic functions. +The +.Fa proto +parameter to the socket call to create an +.Tn ICMPv6 +socket is obtained from +.Xr getprotobyname 3 , +or you can use +.Dv IPPROTO_ICMPV6 . +.Tn ICMPv6 +sockets are connectionless, and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, though the +.Xr connect 2 +call may also be used to fix the destination for future packets +(in which case the +.Xr read 2 +or +.Xr recv 2 +and +.Xr write 2 +or +.Xr send 2 +system calls may be used). +.Pp +Outgoing packets automatically have an +.Tn IPv6 +header prepended to them +.Pq based on the destination address . +.Tn ICMPv6 +pseudo header checksum field +.Pq Li icmp6_cksum +will be filled automatically by the kernel. +Incoming packets are received without the +.Tn IPv6 +header nor IPv6 extension headers. +Notice that this behavior is opposite from +.Tn IPv4 +raw sockets and. +.Tn ICMPv4 +sockets. +.Pp +.Ss ICMPv6 type/code filter +Each +.Tn ICMPv6 +raw socket has an associated filter whose datatype is defined as +.Li struct icmp6_filter ; +.Pp +This structure, along with the macros and constants defined later in +this section, are defined as a result of including the +.Aq Li netinet/icmp6.h +header. +.Pp +The current filter is fetched and stored using +.Xr getsockopt 2 +and +.Xr setsockopt 2 +with a level of +.Dv IPPROTO_ICMPV6 +and an option name of +.Dv ICMP6_FILTER . +.Pp +Six macros operate on an icmp6_filter structure: +.\" is "Fn" legal for macros? +.Bl -item -compact -offset indent +.It Ft void +.Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *" +.It Ft void +.Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *" +.It Ft void +.Fn ICMP6_FILTER_SETPASS "int" "struct icmp6_filter *" +.It Ft void +.Fn ICMP6_FILTER_SETBLOCK "int" "struct icmp6_filter *" +.It Ft int +.Fn ICMP6_FILTER_WILLPASS "int" "const struct icmp6_filter *" +.It Ft int +.Fn ICMP6_FILTER_WILLBLOCK "int" "const struct icmp6_filter *" +.El +.Pp +The first argument to the last four macros +.Pq an integer +is an +.Tn ICMPv6 +message type, between 0 and 255. +The pointer argument to all six +macros is a pointer to a filter that is modified by the first four +macros examined by the last two macros. +.Pp +The first two macros, +.Dv SETPASSALL +and +.Dv SETBLOCKALL , +let us specify that +all +.Tn ICMPv6 messages are passed to the application or that all +.Tn ICMPv6 +messages are blocked from being passed to the application. +.Pp +The next two macros, +.Dv SETPASS +and +.Dv SETBLOCK , +let us specify that +messages of a given +.Tn ICMPv6 +type should be passed to the application +or not passed to the application +.Pq blocked . +.Pp +The final two macros, +.Dv WILLPASS +and +.Dv WILLBLOCK , +return true or false +depending whether the specified message type is passed to the +application or blocked from being passed to the application by the +filter pointed to by the second argument. +.Pp +When an +.Tn ICMPv6 +raw socket is created, it will by default pass all +.Tn ICMPv6 +message types to the application. +.Pp +For further discussions see RFC2292. +.\" +.Sh DIAGNOSTICS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width [EADDRNOTAVAIL] +.It Bq Er EISCONN +when trying to establish a connection on a socket which +already has one, or when trying to send a datagram with the destination +address specified and the socket is already connected; +.It Bq Er ENOTCONN +when trying to send a datagram, but +no destination address is specified, and the socket hasn't been +connected; +.It Bq Er ENOBUFS +when the system runs out of memory for +an internal data structure; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a +socket with a network address for which no network interface exists. +.El +." +.Sh SEE ALSO +.Xr send 2 , +.Xr recv 2 , +.Xr intro 4 , +.Xr inet6 4 , +.Xr ip6 4 +.Rs +.%A W. Stevens +.%A M. Thomas +.%R RFC +.%N 2292 +.%D February 1998 +.%T "Advanced Sockets API for IPv6" +.Re +.Rs +.%A A. Conta +.%A S. Deering +.%R RFC +.%N 2463 +.%D December 1998 +.%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification" +.Re +." +.Sh HISTORY +The implementation is based on KAME stack +.Po +which is decendant of WIDE hydrangea IPv6 stack kit +.Pc . +.Pp +Part of the document was shamelessly copied from RFC2292. diff --git a/share/man/man4/inet6.4 b/share/man/man4/inet6.4 index 7328dfae2f0..6e4ad619e55 100644 --- a/share/man/man4/inet6.4 +++ b/share/man/man4/inet6.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: inet6.4,v 1.1 1999/12/08 13:58:42 itojun Exp $ +.\" $OpenBSD: inet6.4,v 1.2 1999/12/19 03:14:27 itojun Exp $ .\" .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. .\" All rights reserved. @@ -110,6 +110,10 @@ can be obtained by setting field into 0, or by using the address contained in variable .Dv in6addr_any . .Pp +The implementation intentionally does not support RFC1993 IPv4 mapped address +.Pq IPv4 traffic on top of AF_INET6 socket , +due to its possible negative impact to security and access control. +.Pp IPv6 defines scoped address such as link-local or site-local address. To manipulate link-local addresses properly from the userland, programs must use advanced API defined in RFC2292. diff --git a/share/man/man4/ip6.4 b/share/man/man4/ip6.4 new file mode 100644 index 00000000000..37a1030a9a2 --- /dev/null +++ b/share/man/man4/ip6.4 @@ -0,0 +1,647 @@ +.\" $OpenBSD: ip6.4,v 1.1 1999/12/19 03:14:27 itojun Exp $ +.\" +.\" Copyright (C) 1999 WIDE Project. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. Neither the name of the project nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" Copyright (c) 1983, 1991, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" KAME Id: ip6.4,v 1.2 1999/12/19 03:11:04 itojun Exp +.\" +.Dd December 17, 1999 +.Dt IP6 4 +.Os +.\" +.Sh NAME +.Nm ip6 +.Nd Internet Protocol version 6 (IPv6) +.\" +.Sh SYNOPSIS +.Fd #include <sys/socket.h> +.Fd #include <netinet/in.h> +.Ft int +.Fn socket AF_INET6 SOCK_RAW proto +.\" +.Sh DESCRIPTION +.Tn IPv6 +is the network layer protocol used by the Internet protocol version 6 family +.Pq Dv AF_INET6 . +Options may be set at the +.Tn IPv6 +level when using higher-level protocols that are based on +.Tn IPv6 +(such as +.Tn TCP +and +.Tn UDP ) . +It may also be accessed through a +.Dq raw socket +when developing new protocols, or special-purpose applications. +.Pp +There are several +.Tn IPv6-level +.Xr setsockopt 2 / Ns Xr getsockopt 2 +options. +They are be separated into basic IPv6 socket API +.Pq defined in RFC2553 , +and advanced API +.Pq defined in RFC2292 . +Basic API looks very similar to the API presented in +.Xr ip 4 . +Advanced API uses ancillary data and can handle more complex cases. +.Pp +To specify some of socket options, certain privilege +(i.e. root privilege) is required. +.\" +.Ss Basic IPv6 socket API +.Dv IPV6_UNICAST_HOPS +may be used to set the hoplimit field in the +.Tn IPv6 +header. +As symbol name suggests, the option controls hoplimit field on unicast packets. +If -1 is specified, the kernel will use a default value. +If a value of 0 to 255 is specified, the packet will have the specified +value as hoplimit. +Other values are considered invalid, and +.Dv EINVAL +will be returned. +For example: +.Bd -literal -offset indent +int hlim = 60; /* max = 255 */ +setsockopt(s, IPPROTO_IPV6, IPV6_UNICAST_HOPS, &hlim, sizeof(hlim)); +.Ed +.Pp +.Tn IPv6 +multicasting is supported only on +.Dv AF_INET6 +sockets of type +.Dv SOCK_DGRAM +and +.Dv SOCK_RAW, +and only on networks where the interface driver supports multicasting. +.Pp +The +.Dv IPV6_MULTICAST_HOPS +option changes the hoplimit for outgoing multicast datagrams +in order to control the scope of the multicasts: +.Bd -literal -offset indent +unsigned int hlim; /* range: 0 to 255, default = 1 */ +setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_HOPS, &hlim, sizeof(hlim)); +.Ed +.Pp +Datagrams with a hoplimit of 1 are not forwarded beyond the local network. +Multicast datagrams with a hoplimit of 0 will not be transmitted on any network, +but may be delivered locally if the sending host belongs to the destination +group and if multicast loopback has not been disabled on the sending socket +(see below). +Multicast datagrams with hoplimit greater than 1 may be forwarded +to other networks if a multicast router is attached to the local network. +.Pp +For hosts with multiple interfaces, each multicast transmission is +sent from the primary network interface. +The +.Dv IPV6_MULTICAST_IF +option overrides the default for +subsequent transmissions from a given socket: +.Bd -literal -offset indent +unsigned int outif; +outif = if_nametoindex("ne0"); +setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_IF, &outif, sizeof(outif)); +.Ed +.Pp +where "outif" is an interface index of the desired interface, +or 0 to specify the default interface. +.Pp +If a multicast datagram is sent to a group to which the sending host itself +belongs (on the outgoing interface), a copy of the datagram is, by default, +looped back by the IPv6 layer for local delivery. +The +.Dv IPV6_MULTICAST_LOOP +option gives the sender explicit control +over whether or not subsequent datagrams are looped back: +.Bd -literal -offset indent +u_char loop; /* 0 = disable, 1 = enable (default) */ +setsockopt(s, IPPROTO_IPV6, IPV6_MULTICAST_LOOP, &loop, sizeof(loop)); +.Ed +.Pp +This option +improves performance for applications that may have no more than one +instance on a single host (such as a router demon), by eliminating +the overhead of receiving their own transmissions. +It should generally not be used by applications for which there +may be more than one instance on a single host (such as a conferencing +program) or for which the sender does not belong to the destination +group (such as a time querying program). +.Pp +A multicast datagram sent with an initial hoplimit greater than 1 may be delivered +to the sending host on a different interface from that on which it was sent, +if the host belongs to the destination group on that other interface. +The loopback control option has no effect on such delivery. +.Pp +A host must become a member of a multicast group before it can receive +datagrams sent to the group. +To join a multicast group, use the +.Dv IPV6_JOIN_GROUP +option: +.Bd -literal -offset indent +struct ipv6_mreq mreq6; +setsockopt(s, IPPROTO_IPV6, IPV6_JOIN_GROUP, &mreq6, sizeof(mreq6)); +.Ed +.Pp +where +.Fa mreq6 +is the following structure: +.Bd -literal -offset indent +struct ipv6_mreq { + struct in6_addr ipv6mr_multiaddr; + u_int ipv6mr_interface; +}; +.Ed +.Pp +.Dv ipv6mr_interface +should be 0 to choose the default multicast interface, or the +interface index of a particular multicast-capable interface if +the host is multihomed. +Membership is associated with a single interface; +programs running on multihomed hosts may need to +join the same group on more than one interface. +.Pp +To drop a membership, use: +.Bd -literal -offset indent +struct ipv6_mreq mreq6; +setsockopt(s, IPPROTO_IPV6, IPV6_LEAVE_GROUP, &mreq6, sizeof(mreq6)); +.Ed +.Pp +where +.Fa mreq6 +contains the same values as used to add the membership. +Memberships are dropped when the socket is closed or the process exits. +.Pp +.Dv IPV6_PORTRANGE +controls how ephemeral ports are allocated for +.Dv SOCK_STREAM +and +.Dv SOCK_DGRAM +sockets. +For example, +.Bd -literal -offset indent +int range = IPV6_PORTRANGE_LOW; /* see <netinet/in.h> */ +setsockopt(s, IPPROTO_IPV6, IPV6_PORTRANGE, &range, sizeof(range)); +.Ed +.\" +.Ss Advanced IPv6 socket API +Advanced IPv6 socket API lets userland program to specify, or obtain, +details about IPv6 header and IPv6 extension headers on packets. +Advanced API uses ancillary data for passing data from/to the kernel. +.Pp +There are +.Xr setsockopt 2 / Ns Xr getsockopt 2 +flags to get optional information on packets for incoming packets. +They are +.Dv IPV6_PKTINFO , +.Dv IPV6_HOPLIMIT , +.Dv IPV6_HOPOPTS , +.Dv IPV6_DSTOPTS , +and +.Dv IPV6_RTHDR . +.Bd -literal -offset indent +int on = 1; + +setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on)); +setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on)); +setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on)); +setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on)); +setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on)); +.Ed +.Pp +When any of these options are enabled, the corresponding data is +returned as control information by +.Xr recvmsg2 , +as one or more ancillary data objects. +.Pp +If +.Dv IPV6_PKTINFO +is enabled, destination IPv6 address and arriving interface index +will be made available via +.Li struct in6_pktinfo +on ancillary data stream. +You can pick the structure by checking for an ancillary data item with +.Li cmsg_level +equals to +.Dv IPPROTO_IPV6 , +and +.Li cmsg_type +equals to +.Dv IPV6_PKTINFO . +.Pp +If +.Dv IPV6_HOPLIMIT +is enabled, hoplimit value on the packet will be made available to the +userland program. +ancillary data stream will contain an integer data item with +.Li cmsg_level +equals to +.Dv IPPROTO_IPV6 , +and +.Li cmsg_type +equals to +.Dv IPV6_HOPLIMIT . +.Pp +.Xr inet6_option_space 3 +and friends will help you parse ancillary data items for +.Dv IPV6_HOPOPTS +and +.Dv IPV6_DSTOPTS . +Similarly, +.Xr inet6_rthdr_space 3 +and friends will help you parse ancillary data items for +.Dv IPV6_RTHDR . +.Pp +.Dv IPV6_HOPOPTS +and +.Dv IPV6_DSTOPTS +may appear multiple times on an ancillary data stream. +Other ancillary data item will appear no more than once. +.Pp +For outgoing direction, +you can pass ancillary data items with normal payload data, using +.Xr sendmsg 2 . +Ancillary data items will be parsed by the kernel, and used to construct +the IPv6 header and extension headers. +For the 5 +.Li cmsg_level +values listed above, ancillary data format is the same as inbound case. +Additionally, you can specify +.Dv IPV6_NEXTHOP +data object. +The +.Dv IPV6_NEXTHOP +ancillary data object specifies the next hop for the +datagram as a socket address structure. +In the +.Li cmsghdr +structure +containing this ancillary data, the +.Li cmsg_level +member will be +.Dv IPPROTO_IPV6 , +the +.Li cmsg_type +member will be +.Dv IPV6_NEXTHOP , +and the first byte of +.Li cmsg_data[] +will be the first byte of the socket address structure. +.Pp +If the socket address structure contains an IPv6 address (e.g., the +sin6_family member is +.Dv AF_INET6 +), then the node identified by that +address must be a neighbor of the sending host. +If that address +equals the destination IPv6 address of the datagram, then this is +equivalent to the existing +.Dv SO_DONTROUTE +socket option. +.Pp +For applications that do not, or unable to use +.Xr sendmsg 2 +or +.Xr recvmsg 2 , +.Dv IPV6_PKTOPTIONS +socket option is defined. +Setting the socket option specifies any of the optional output fields: +.Bd -literal -offset indent +setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len); +.Ed +.Pp +The fourth argument points to a buffer containing one or more +ancillary data objects, and the fifth argument is the total length of +all these objects. +The application fills in this buffer exactly as +if the buffer were being passed to +.Xr sendmsg 2 +as control information. +.Pp +The options set by calling +.Xr setsockopt 2 +for +.Dv IPV6_PKTOPTIONS +are +called "sticky" options because once set they apply to all packets +sent on that socket. +The application can call +.Xr setsockopt 2 +again to +change all the sticky options, or it can call +.Xr setsockopt 2 +with a +length of 0 to remove all the sticky options for the socket. +.Pp +The corresponding receive option +.Bd -literal -offset indent +getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len); +.Ed +.Pp +returns a buffer with one or more ancillary data objects for all the +optional receive information that the application has previously +specified that it wants to receive. +The fourth argument points to +the buffer that is filled in by the call. +The fifth argument is a +pointer to a value-result integer: when the function is called the +integer specifies the size of the buffer pointed to by the fourth +argument, and on return this integer contains the actual number of +bytes that were returned. +The application processes this buffer +exactly as if the buffer were returned by +.Xr recvmsg 2 +as control information. +.\" +.Ss Advanced API and TCP sockets +When using +.Xr getsockopt 2 +with the +.Dv IPV6_PKTOPTIONS +option and a +.Tn TCP +socket, only the options from the most recently received segment are +retained and returned to the caller, and only after the socket option +has been set. +.\" That is, +.\" .Tn TCP +.\" need not start saving a copy of the options until the application says +.\" to do so. +The application is not allowed to specify ancillary data in a call to +.Xr sendmsg 2 +on a +.Tn TCP +socket, and none of the ancillary data that we +described above is ever returned as control information by +.Xr recvmsg 2 +on a +.Tn TCP +socket. +.\" +.Ss Conflict resolution +In some cases, there are multiple APIs defined for manipulating +a IPv6 header field. +A good example is the outgoing interface for multicast datagrams: +it can be manipulated by +.Dv IPV6_MULTICAST_IF +in basic API, +.Dv IPV6_PKTINFO +in advanced API, and +.Li sin6_scope_id +field of the socket address passed to +.Xr sendto 2 . +.Pp +When conflicting options are given to the kernel, +the kernel will get the value in the following preference: +(1) options specified by using advanced API, +(2) options specified by socket address, and lastly +(3) options specified by using basic API. +.\" +.Ss "Raw IPv6 Sockets" +Raw +.Tn IPv6 +sockets are connectionless, and are normally used with the +.Xr sendto 2 +and +.Xr recvfrom 2 +calls, though the +.Xr connect 2 +call may also be used to fix the destination for future +packets (in which case the +.Xr read 2 +or +.Xr recv 2 +and +.Xr write 2 +or +.Xr send 2 +system calls may be used). +.Pp +If +.Fa proto +is 0, the default protocol +.Dv IPPROTO_RAW +is used for outgoing packets, and only incoming packets destined +for that protocol are received. +If +.Fa proto +is non-zero, that protocol number will be used on outgoing packets +and to filter incoming packets. +.Pp +Outgoing packets automatically have an +.Tn IPv6 +header prepended to them (based on the destination address and the +protocol number the socket is created with). +Incoming packets are received without +.Tn IPv6 +header nor extension headers. +.Pp +All data sent via raw sockets MUST be in network byte order and all +data received via raw sockets will be in network byte order. +This differs from the IPv4 raw sockets, which did not specify a byte +ordering and typically used the host's byte order. +.Pp +Another difference from IPv4 raw sockets is that complete packets +(that is, IPv6 packets with extension headers) cannot be read or +written using the IPv6 raw sockets API. +Instead, ancillary data +objects are used to transfer the extension headers, as described above. +Should an application need access to the +complete IPv6 packet, some other technique, such as the datalink +interfaces, such as +.Xr bpf 4 , +must be used. +.Pp +All fields in the IPv6 header that an application might want to +change (i.e., everything other than the version number) can be +modified using ancillary data and/or socket options by the +application for output. +All fields in a received IPv6 header (other +than the version number and Next Header fields) and all extension +headers are also made available to the application as ancillary data +on input. +Hence there is no need for a socket option similar to the +IPv4 +.Dv IP_HDRINCL +socket option. +.Pp +When writing to a raw socket the kernel will automatically fragment +the packet if its size exceeds the path MTU, inserting the required +fragmentation headers. On input the kernel reassembles received +fragments, so the reader of a raw socket never sees any fragment +headers. +.Pp +Most IPv4 implementations give special treatment to a raw socket +created with a third argument to +.Xr socket 2 +of +.Dv IPPROTO_RAW , +whose value is normally 255. +We note that this value has no special meaning to +an IPv6 raw socket (and the IANA currently reserves the value of 255 +when used as a next-header field). +.\" Note: This feature was added to +.\" IPv4 in 1988 by Van Jacobson to support traceroute, allowing a +.\" complete IP header to be passed by the application, before the +.\" .Dv IP_HDRINCL +.\" socket option was added. +.Pp +For ICMPv6 raw sockets, +the kernel will calculate and insert the ICMPv6 checksum for +since this checksum is mandatory. +.Pp +For other raw IPv6 sockets (that is, for raw IPv6 sockets created +with a third argument other than IPPROTO_ICMPV6), the application +must set the new IPV6_CHECKSUM socket option to have the kernel (1) +compute and store a psuedo header checksum for output, +and (2) verify the received +pseudo header checksum on input, +discarding the packet if the checksum is in error. +This option prevents applications from having to perform source +address selection on the packets they send. +The checksum will +incorporate the IPv6 pseudo-header, defined in Section 8.1 of RFC2460. +This new socket option also specifies an integer offset into +the user data of where the checksum is located. +.Bd -literal -offset indent +int offset = 2; +setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); +.Ed +.Pp +By default, this socket option is disabled. Setting the offset to -1 +also disables the option. By disabled we mean (1) the kernel will +not calculate and store a checksum for outgoing packets, and (2) the +kernel will not verify a checksum for received packets. +.Pp +Note: Since the checksum is always calculated by the kernel for an +ICMPv6 socket, applications are not able to generate ICMPv6 packets +with incorrect checksums (presumably for testing purposes) using this +API. +.\" +.Sh DIAGNOSTICS +A socket operation may fail with one of the following errors returned: +.Bl -tag -width [EADDRNOTAVAIL] +.It Bq Er EISCONN +when trying to establish a connection on a socket which already +has one, or when trying to send a datagram with the destination +address specified and the socket is already connected; +.It Bq Er ENOTCONN +when trying to send a datagram, but no destination address is +specified, and the socket hasn't been connected; +.It Bq Er ENOBUFS +when the system runs out of memory for an internal data structure; +.It Bq Er EADDRNOTAVAIL +when an attempt is made to create a socket with a network address +for which no network interface exists. +.It Bq Er EACCES +when an attempt is made to create a raw IPv6 socket by a non-privileged process. +.El +.Pp +The following errors specific to +.Tn IPv6 +may occur: +.Bl -tag -width EADDRNOTAVAILxx +.It Bq Er EINVAL +An unknown socket option name was given. +.It Bq Er EINVAL +The ancillary data items were improperly formed, or option name was unknown. +.El +.\" +.Sh SEE ALSO +.Xr getsockopt 2 , +.Xr send 2 , +.Xr setsockopt 2 , +.Xr recv 2 , +.Xr inet6_option_space 3 , +.Xr inet6_rthdr_space 3 , +.Xr intro 4 , +.Xr icmp6 4 , +.Xr inet6 4 +.Rs +.%A W. Stevens +.%A M. Thomas +.%R RFC +.%N 2292 +.%D February 1998 +.%T "Advanced Sockets API for IPv6" +.Re +.Rs +.%A S. Deering +.%A R. Hinden +.%R RFC +.%N 2460 +.%D December 1998 +.%T "Internet Protocol, Version 6 (IPv6) Specification" +.Re +.\" +.Sh STANDARDS +Most of the socket options are defined in +RFC2292 and/or RFC2553. +.Dv IPV6_PORTRANGE +and conflict resolution rule +is not defined in the RFCs and should be considered implementation dependent. +.\" +.Sh HISTORY +The implementation is based on KAME stack +.Po +which is decendant of WIDE hydrangea IPv6 stack kit +.Pc . +.Pp +Part of the document was shamelessly copied from RFC2553 and RFC2292. |