xref: /dragonfly/share/man/man4/icmp6.4 (revision 333227be) 
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
81is the error and control message protocol used
82by
83.Tn IPv6
84and the Internet protocol family.
85It may be accessed through a
86.Dq raw socket
87for network monitoring and diagnostic functions.
88The
89.Fa proto
90parameter to the socket call to create an
91.Tn ICMPv6
92socket is obtained from
93.Xr getprotobyname 3 ,
94or you can use
95.Dv IPPROTO_ICMPV6 .
96.Tn ICMPv6
97sockets are connectionless, and are normally used with the
98.Xr sendto 2
99and
100.Xr recvfrom 2
101calls, though the
102.Xr connect 2
103call may also be used to fix the destination for future packets
104(in which case the
105.Xr read 2
106or
107.Xr recv 2
108and
109.Xr write 2
110or
111.Xr send 2
112system calls may be used).
113.Pp
114Outgoing packets automatically have an
115.Tn IPv6
116header prepended to them
117(based on the destination address).
118.Tn ICMPv6
119pseudo header checksum field
120.Pq Li icmp6_cksum
121will be filled automatically by the kernel.
122Incoming packets are received without the
123.Tn IPv6
124header nor IPv6 extension headers.
125Notice that this behavior is opposite from
126.Tn IPv4
127raw sockets and.
128.Tn ICMPv4
129sockets.
130.Pp
131.Ss ICMPv6 type/code filter
132Each
133.Tn ICMPv6
134raw socket has an associated filter whose datatype is defined as
135.Li struct icmp6_filter ;
136.Pp
137This structure, along with the macros and constants defined later in
138this section, are defined as a result of including the
139.Aq Li netinet/icmp6.h
140header.
141.Pp
142The current filter is fetched and stored using
143.Xr getsockopt 2
144and
145.Xr setsockopt 2
146with a level of
147.Dv IPPROTO_ICMPV6
148and an option name of
149.Dv ICMP6_FILTER .
150.Pp
151Six 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
174The first argument to the last four macros
175(an integer)
176is an
177.Tn ICMPv6
178message type, between 0 and 255.
179The pointer argument to all six
180macros is a pointer to a filter that is modified by the first four
181macros examined by the last two macros.
182.Pp
183The first two macros,
184.Dv SETPASSALL
185and
186.Dv SETBLOCKALL ,
187let us specify that
188all
189.Tn ICMPv6
190messages are passed to the application or that all
191.Tn ICMPv6
192messages are blocked from being passed to the application.
193.Pp
194The next two macros,
195.Dv SETPASS
196and
197.Dv SETBLOCK ,
198let us specify that
199messages of a given
200.Tn ICMPv6
201type should be passed to the application
202or not passed to the application
203(blocked).
204.Pp
205The final two macros,
206.Dv WILLPASS
207and
208.Dv WILLBLOCK ,
209return true or false
210depending whether the specified message type is passed to the
211application or blocked from being passed to the application by the
212filter pointed to by the second argument.
213.Pp
214When an
215.Tn ICMPv6
216raw socket is created, it will by default pass all
217.Tn ICMPv6
218message types to the application.
219.Pp
220For further discussions see RFC2292.
221.\"
222.Sh ERRORS
223A socket operation may fail with one of the following errors returned:
224.Bl -tag -width Er
225.It Bq Er EISCONN
226when trying to establish a connection on a socket which
227already has one, or when trying to send a datagram with the destination
228address specified and the socket is already connected;
229.It Bq Er ENOTCONN
230when trying to send a datagram, but
231no destination address is specified, and the socket hasn't been
232connected;
233.It Bq Er ENOBUFS
234when the system runs out of memory for
235an internal data structure;
236.It Bq Er EADDRNOTAVAIL
237when an attempt is made to create a
238socket 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
265The implementation is based on KAME stack
266(which is descendant of WIDE hydrangea IPv6 stack kit).
267.Pp
268Part of the document was shamelessly copied from RFC2292.
269