add a new icmp6(4) manpage, rewritten from scratch

1 files changed, 198 insertions, 0 deletions

diff --git a/share/man/man4/icmp6.4 b/share/man/man4/icmp6.4
new file mode 100644
index 00000000000..b153767cbad
--- /dev/null
+++ b/share/man/man4/icmp6.4
@@ -0,0 +1,198 @@
+.\"	$OpenBSD: icmp6.4,v 1.18 2004/12/20 19:17:04 jaredy Exp $
+.\" 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. 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.
+.Dd December 20, 2004
+.Dt ICMP6 4
+.Os
+.Sh NAME
+.Nm icmp6
+.Nd Internet Control Message Protocol for IPv6
+.Sh SYNOPSIS
+.In sys/socket.h
+.In netinet/in.h
+.In netinet/icmp6.h
+.Ft int
+.Fn socket AF_INET6 SOCK_RAW IPPROTO_ICMPV6
+.Sh DESCRIPTION
+ICMPv6 is the error and control message protocol used by IPv6 and the
+IPv6 protocol family (see
+.Xr ip6 4
+and
+.Xr inet6 4 ) .
+It may be accessed through a
+.Dq raw socket
+for network monitoring and diagnostic functions.
+.Pp
+The
+.Fa proto
+parameter to the
+.Xr socket 2
+call to create an ICMPv6 socket may be obtained from
+.Xr getprotobyname 3 .
+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
+.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 IPv6 header prepended to them
+(based on the destination address).
+Incoming packets on the socket are received with the IPv6 header and any
+extension headers removed.
+.Pp
+All ICMPv6 messages are prefixed with an ICMPv6 header.
+This header corresponds to the
+.Vt icmp6_hdr
+structure and has the following definition:
+.Bd -literal -offset indent
+struct icmp6_hdr {
+	u_int8_t	icmp6_type;	/* type field */
+	u_int8_t	icmp6_code;	/* code field */
+	u_int16_t	icmp6_cksum;	/* checksum field */
+	union {
+		u_int32_t icmp6_un_data32[1]; /* type-specific */
+		u_int16_t icmp6_un_data16[2]; /* type-specific */
+		u_int8_t  icmp6_un_data8[4];  /* type-specific */
+	} icmp6_dataun;
+} __packed;
+
+#define icmp6_data32	icmp6_dataun.icmp6_un_data32
+#define icmp6_data16	icmp6_dataun.icmp6_un_data16
+#define icmp6_data8	icmp6_dataun.icmp6_un_data8
+#define icmp6_pptr	icmp6_data32[0]	/* parameter prob */
+#define icmp6_mtu	icmp6_data32[0]	/* packet too big */
+#define icmp6_id	icmp6_data16[0]	/* echo request/reply */
+#define icmp6_seq	icmp6_data16[1]	/* echo request/reply */
+#define icmp6_maxdelay	icmp6_data16[0]	/* mcast group membership*/
+.Ed
+.Pp
+.Va icmp6_type
+describes the type of the message.
+Suitable values are defined in
+.Aq Pa netinet/icmp6.h .
+.Va icmp6_code
+describes the sub-type of the message and depends on
+.Va icmp6_type .
+.Va icmp6_cksum
+contains the checksum for the message and is filled in by the
+kernel on outgoing messages.
+The other fields are used for type-specific purposes.
+.Pp
+Because of the extra functionality of ICMPv6 in comparison to ICMPv4,
+a larger number of messages may be potentially received on an ICMPv6
+socket.
+Input filters may therefore be used to restrict input to a subset of the
+incoming ICMPv6 messages so only interesting messages are returned by the
+.Xr recv 2
+family of calls to an application.
+.Pp
+The
+.Vt icmp6_filter
+structure may be used to refine the input message set according to the
+ICMPv6 type.
+By default, all messages types are allowed on newly created raw ICMPv6
+sockets.
+The following macros may be used to refine the input set:
+.Bl -tag -width Ds
+.It Fn "void ICMP6_FILTER_SETPASSALL" "struct icmp6_filter *filterp"
+Allow all incoming messages.
+.Va filterp
+is modified to allow all message types.
+.It Fn "void ICMP6_FILTER_SETBLOCKALL" "struct icmp6_filter *filterp"
+Ignore all incoming messages.
+.Va filterp
+is modified to ignore all message types.
+.It Fn "void ICMP6_FILTER_SETPASS" "int type" \
+    "struct icmp6_filter *filterp"
+Allow ICMPv6 messages with the given
+.Fa type .
+.Va filterp
+is modified to allow such messages.
+.It Fn "void ICMP6_FILTER_SETBLOCK" "int type" \
+    "struct icmp6_filter *filterp"
+Ignore ICMPv6 messages with the given
+.Fa type .
+.Va filterp
+is modified to ignore such messages.
+.It Fn "int ICMP6_FILTER_WILLPASS" "int type" \
+    "const struct icmp6_filter *filterp"
+Determine if the given filter will allow an ICMPv6 message of the given
+type.
+.It Fn "int ICMP6_FILTER_WILLBLOCK" "int type" \
+    "const struct icmp6_filter *filterp"
+Determine if the given filter will ignore an ICMPv6 message of the given
+type.
+.El
+.Pp
+The
+.Xr getsockopt 2
+and
+.Xr setsockopt 2
+calls may be used to obtain and install the filter on ICMPv6 sockets at
+option level
+.Dv IPPROTO_ICMPV6
+and name
+.Dv ICMPV6_FILTER
+with a pointer to the
+.Vt icmp6_filter
+structure as the option value.
+.Sh SEE ALSO
+.Xr getsockopt 2 ,
+.Xr recv 2 ,
+.Xr send 2 ,
+.Xr setsockopt 2 ,
+.Xr socket 2 ,
+.Xr getprotobyname 3 ,
+.Xr inet6 4 ,
+.Xr ip6 4 ,
+.Xr netintro 4
+.Rs
+.%A W. Stevens
+.%A M. Thomas
+.%T Advanced Sockets API for IPv6
+.%N RFC 2292
+.%D February 1998
+.Re
+.Rs
+.%A A. Conta
+.%A S. Deering
+.%T "Internet Control Message Protocol (ICMPv6) for the Internet" \
+    "Protocol Version 6 (IPv6) Specification"
+.%N RFC 2463
+.%D December 1998
+.Re