share/man/man4/icmp6.4

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