bsd/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.2 2002/04/17 00:18:23 lindak Exp $
  60 .\" $FreeBSD: src/share/man/man4/icmp6.4,v 1.1.2.7 2001/12/17 11:30:12 ru Exp $
  61 .\"
  62 .Dd March 13, 2000
  63 .Dt ICMP6 4
  64 .Os
  65 .\"
  66 .Sh NAME
  67 .Nm icmp6
  68 .Nd Internet Control Message Protocol for IPv6
  69 .\"
  70 .Sh SYNOPSIS
  71 .In sys/types.h
  72 .In sys/socket.h
  73 .In netinet/in.h
  74 .In netinet/icmp6.h
  75 .Ft int
  76 .Fn socket AF_INET6 SOCK_RAW proto
  77 .\"
  78 .Sh DESCRIPTION
  79 .Tn ICMPv6
  80 is the error and control message protocol used
  81 by
  82 .Tn IPv6
  83 and the Internet protocol family.
  84 It may be accessed through a
  85 .Dq raw socket
  86 for network monitoring and diagnostic functions.
  87 The
  88 .Fa proto
  89 parameter to the socket call to create an
  90 .Tn ICMPv6
  91 socket is obtained from
  92 .Xr getprotobyname 3 ,
  93 or you can use
  94 .Dv IPPROTO_ICMPV6 .
  95 .Tn ICMPv6
  96 sockets are connectionless, and are normally used with the
  97 .Xr sendto 2
  98 and
  99 .Xr recvfrom 2
 100 calls, though the
 101 .Xr connect 2
 102 call may also be used to fix the destination for future packets
 103 (in which case the
 104 .Xr read 2
 105 or
 106 .Xr recv 2
 107 and
 108 .Xr write 2
 109 or
 110 .Xr send 2
 111 system calls may be used).
 112 .Pp
 113 Outgoing packets automatically have an
 114 .Tn IPv6
 115 header prepended to them
 116 (based on the destination address).
 117 .Tn ICMPv6
 118 pseudo header checksum field
 119 .Pq Li icmp6_cksum
 120 will be filled automatically by the kernel.
 121 Incoming packets are received without the
 122 .Tn IPv6
 123 header nor IPv6 extension headers.
 124 Notice that this behavior is opposite from
 125 .Tn IPv4
 126 raw sockets and.
 127 .Tn ICMPv4
 128 sockets.
 129 .Pp
 130 .Ss ICMPv6 type/code filter
 131 Each
 132 .Tn ICMPv6
 133 raw socket has an associated filter whose datatype is defined as
 134 .Li struct icmp6_filter ;
 135 .Pp
 136 This structure, along with the macros and constants defined later in
 137 this section, are defined as a result of including the
 138 .Aq Li netinet/icmp6.h
 139 header.
 140 .Pp
 141 The current filter is fetched and stored using
 142 .Xr getsockopt 2
 143 and
 144 .Xr setsockopt 2
 145 with a level of
 146 .Dv IPPROTO_ICMPV6
 147 and an option name of
 148 .Dv ICMP6_FILTER .
 149 .Pp
 150 Six macros operate on an icmp6_filter structure:
 151 .\" is "Fn" legal for macros?
 152 .Bl -item -offset indent
 153 .It
 154 .Ft void
 155 .Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *filterp"
 156 .It
 157 .Ft void
 158 .Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *filterp"
 159 .It
 160 .Ft void
 161 .Fn ICMP6_FILTER_SETPASS "int type" "struct icmp6_filter *filterp"
 162 .It
 163 .Ft void
 164 .Fn ICMP6_FILTER_SETBLOCK "int type" "struct icmp6_filter *filterp"
 165 .It
 166 .Ft int
 167 .Fn ICMP6_FILTER_WILLPASS "int type" "const struct icmp6_filter *filterp"
 168 .It
 169 .Ft int
 170 .Fn ICMP6_FILTER_WILLBLOCK "int type" "const struct icmp6_filter *filterp"
 171 .El
 172 .Pp
 173 The first argument to the last four macros
 174 (an integer)
 175 is an
 176 .Tn ICMPv6
 177 message type, between 0 and 255.
 178 The pointer argument to all six
 179 macros is a pointer to a filter that is modified by the first four
 180 macros examined by the last two macros.
 181 .Pp
 182 The first two macros,
 183 .Dv SETPASSALL
 184 and
 185 .Dv SETBLOCKALL ,
 186 let us specify that
 187 all
 188 .Tn ICMPv6
 189 messages are passed to the application or that all
 190 .Tn ICMPv6
 191 messages are blocked from being passed to the application.
 192 .Pp
 193 The next two macros,
 194 .Dv SETPASS
 195 and
 196 .Dv SETBLOCK ,
 197 let us specify that
 198 messages of a given
 199 .Tn ICMPv6
 200 type should be passed to the application
 201 or not passed to the application
 202 (blocked).
 203 .Pp
 204 The final two macros,
 205 .Dv WILLPASS
 206 and
 207 .Dv WILLBLOCK ,
 208 return true or false
 209 depending whether the specified message type is passed to the
 210 application or blocked from being passed to the application by the
 211 filter pointed to by the second argument.
 212 .Pp
 213 When an
 214 .Tn ICMPv6
 215 raw socket is created, it will by default pass all
 216 .Tn ICMPv6
 217 message types to the application.
 218 .Pp
 219 For further discussions see RFC2292.
 220 .\"
 221 .Sh ERRORS
 222 A socket operation may fail with one of the following errors returned:
 223 .Bl -tag -width Er
 224 .It Bq Er EISCONN
 225 when trying to establish a connection on a socket which
 226 already has one, or when trying to send a datagram with the destination
 227 address specified and the socket is already connected;
 228 .It Bq Er ENOTCONN
 229 when trying to send a datagram, but
 230 no destination address is specified, and the socket hasn't been
 231 connected;
 232 .It Bq Er ENOBUFS
 233 when the system runs out of memory for
 234 an internal data structure;
 235 .It Bq Er EADDRNOTAVAIL
 236 when an attempt is made to create a
 237 socket with a network address for which no network interface exists.
 238 .El
 239 .\"
 240 .Sh SEE ALSO
 241 .Xr recv 2 ,
 242 .Xr send 2 ,
 243 .Xr inet6 4 ,
 244 .Xr intro 4 ,
 245 .Xr ip6 4
 246 .Rs
 247 .%A W. Stevens
 248 .%A M. Thomas
 249 .%R RFC
 250 .%N 2292
 251 .%D February 1998
 252 .%T "Advanced Sockets API for IPv6"
 253 .Re
 254 .Rs
 255 .%A A. Conta
 256 .%A S. Deering
 257 .%R RFC
 258 .%N 2463
 259 .%D December 1998
 260 .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
 261 .Re
 262 .\"
 263 .Sh HISTORY
 264 The implementation is based on KAME stack
 265 (which is descendant of WIDE hydrangea IPv6 stack kit).
 266 .Pp
 267 Part of the document was shamelessly copied from RFC2292.