1.\" $OpenBSD: icmp6.4,v 1.14 2003/06/26 19:54:35 jmc Exp $ 2.\" $KAME: icmp6.4,v 1.3 2000/11/24 08:44:40 itojun Exp $ 3.\" 4.\" Copyright (C) 1999 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" Copyright (c) 1986, 1991, 1993 32.\" The Regents of the University of California. All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 3. Neither the name of the University nor the names of its contributors 43.\" may be used to endorse or promote products derived from this software 44.\" without specific prior written permission. 45.\" 46.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 47.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 48.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 49.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 50.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 51.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 52.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 54.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 56.\" SUCH DAMAGE. 57.\" 58.Dd December 17, 1999 59.Dt ICMP6 4 60.Os 61.Sh NAME 62.Nm icmp6 63.Nd Internet Control Message Protocol for IPv6 64.Sh SYNOPSIS 65.Fd #include <sys/socket.h> 66.Fd #include <netinet/in.h> 67.Fd #include <netinet/icmp6.h> 68.Ft int 69.Fn socket AF_INET6 SOCK_RAW proto 70.Sh DESCRIPTION 71.Tn ICMPv6 72is the error and control message protocol used 73by 74.Tn IPv6 75and the Internet protocol family. 76It may be accessed through a 77.Dq raw socket 78for network monitoring and diagnostic functions. 79The 80.Fa proto 81parameter to the socket call to create an 82.Tn ICMPv6 83socket is obtained from 84.Xr getprotobyname 3 , 85or you can use 86.Dv IPPROTO_ICMPV6 . 87.Tn ICMPv6 88sockets are connectionless, and are normally used with the 89.Xr sendto 2 90and 91.Xr recvfrom 2 92calls, though the 93.Xr connect 2 94call may also be used to fix the destination for future packets 95(in which case the 96.Xr read 2 97or 98.Xr recv 2 99and 100.Xr write 2 101or 102.Xr send 2 103system calls may be used). 104.Pp 105Outgoing packets automatically have an 106.Tn IPv6 107header prepended to them 108.Pq based on the destination address . 109The 110.Tn ICMPv6 111pseudo-header checksum field 112.Pq Li icmp6_cksum 113is filled automatically by the kernel. 114Incoming packets are received without the 115.Tn IPv6 116header or IPv6 extension headers. 117Notice that this behavior is opposite to that of 118.Tn IPv4 119raw sockets and 120.Tn ICMPv4 121sockets. 122.Ss ICMPv6 type/code filter 123Each 124.Tn ICMPv6 125raw socket has an associated filter whose datatype is defined as 126.Li struct icmp6_filter ; 127.Pp 128This structure, along with the macros and constants defined later in 129this section, are defined as a result of including the 130.Aq Li netinet/icmp6.h 131header. 132.Pp 133The current filter is fetched and stored using 134.Xr getsockopt 2 135and 136.Xr setsockopt 2 137with a level of 138.Dv IPPROTO_ICMPV6 139and an option name of 140.Dv ICMP6_FILTER . 141.Pp 142Six macros operate on an icmp6_filter structure: 143.\" is "Fn" legal for macros? 144.Bl -item -compact -offset indent 145.It 146.Ft void 147.Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *" 148.It 149.Ft void 150.Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *" 151.It 152.Ft void 153.Fn ICMP6_FILTER_SETPASS "int" "struct icmp6_filter *" 154.It 155.Ft void 156.Fn ICMP6_FILTER_SETBLOCK "int" "struct icmp6_filter *" 157.It 158.Ft int 159.Fn ICMP6_FILTER_WILLPASS "int" "const struct icmp6_filter *" 160.It 161.Ft int 162.Fn ICMP6_FILTER_WILLBLOCK "int" "const struct icmp6_filter *" 163.El 164.Pp 165The first argument to the last four macros 166.Pq an integer 167is an 168.Tn ICMPv6 169message type, between 0 and 255. 170The pointer argument to all six 171macros is a pointer to a filter that is modified by the first four 172macros examined by the last two macros. 173.Pp 174The first two macros, 175.Dv SETPASSALL 176and 177.Dv SETBLOCKALL , 178specify that all 179.Tn ICMPv6 messages are passed to the application or that all 180.Tn ICMPv6 181messages are blocked from being passed to the application. 182.Pp 183The next two macros, 184.Dv SETPASS 185and 186.Dv SETBLOCK , 187specify that messages of a given 188.Tn ICMPv6 189type should be passed to the application 190or not passed to the application 191.Pq blocked . 192.Pp 193The final two macros, 194.Dv WILLPASS 195and 196.Dv WILLBLOCK , 197return true or false 198depending on whether the specified message type is passed to the 199application or blocked from being passed to the application by the 200filter pointed to by the second argument. 201.Pp 202When an 203.Tn ICMPv6 204raw socket is created, it will by default pass all 205.Tn ICMPv6 206message types to the application. 207.Pp 208For further discussions see RFC2292. 209.Sh DIAGNOSTICS 210A socket operation may fail with one of the following errors returned: 211.Bl -tag -width [EADDRNOTAVAIL] 212.It Bq Er EISCONN 213when trying to establish a connection on a socket which 214already has one, or when trying to send a datagram with the destination 215address specified and the socket is already connected. 216.It Bq Er ENOTCONN 217when trying to send a datagram, but 218no destination address is specified, and the socket hasn't been 219connected. 220.It Bq Er ENOBUFS 221when the system runs out of memory for 222an internal data structure. 223.It Bq Er EADDRNOTAVAIL 224when an attempt is made to create a 225socket with a network address for which no network interface exists. 226.El 227.Sh SEE ALSO 228.Xr recv 2 , 229.Xr send 2 , 230.Xr inet6 4 , 231.Xr ip6 4 , 232.Xr netintro 4 233.Rs 234.%A W. Stevens 235.%A M. Thomas 236.%R RFC 237.%N 2292 238.%D February 1998 239.%T "Advanced Sockets API for IPv6" 240.Re 241.Rs 242.%A A. Conta 243.%A S. Deering 244.%R RFC 245.%N 2463 246.%D December 1998 247.%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification" 248.Re 249.Sh HISTORY 250The implementation is based on KAME stack 251.Po 252which is a descendant of WIDE hydrangea IPv6 stack kit 253.Pc . 254.Pp 255Part of the document was shamelessly copied from RFC2292. 256