[apple/xnu.git] / bsd / man / man4 / icmp6.4

.\" Copyright (C) 1999 WIDE Project.
.\" 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 project 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 PROJECT 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 PROJECT 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.
.\"
.\" 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. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. 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.
.\"
.\"	KAME $Id: icmp6.4,v 1.2 2002/04/17 00:18:23 lindak Exp $
.\" $FreeBSD: src/share/man/man4/icmp6.4,v 1.1.2.7 2001/12/17 11:30:12 ru Exp $
.\"
.Dd March 13, 2000
.Dt ICMP6 4
.Os
.\"
.Sh NAME
.Nm icmp6
.Nd Internet Control Message Protocol for IPv6
.\"
.Sh SYNOPSIS
.In sys/types.h
.In sys/socket.h
.In netinet/in.h
.In netinet/icmp6.h
.Ft int
.Fn socket AF_INET6 SOCK_RAW proto
.\"
.Sh DESCRIPTION
.Tn ICMPv6
is the error and control message protocol used
by
.Tn IPv6
and the Internet protocol family.
It may be accessed through a
.Dq raw socket
for network monitoring and diagnostic functions.
The
.Fa proto
parameter to the socket call to create an
.Tn ICMPv6
socket is obtained from
.Xr getprotobyname 3 ,
or you can use
.Dv IPPROTO_ICMPV6 .
.Tn 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 the
.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
.Tn IPv6
header prepended to them
(based on the destination address).
.Tn ICMPv6
pseudo header checksum field
.Pq Li icmp6_cksum
will be filled automatically by the kernel.
Incoming packets are received without the
.Tn IPv6
header nor IPv6 extension headers.
Notice that this behavior is opposite from
.Tn IPv4
raw sockets and.
.Tn ICMPv4
sockets.
.Pp
.Ss ICMPv6 type/code filter
Each
.Tn ICMPv6
raw socket has an associated filter whose datatype is defined as
.Li struct icmp6_filter ;
.Pp
This structure, along with the macros and constants defined later in
this section, are defined as a result of including the
.Aq Li netinet/icmp6.h
header.
.Pp
The current filter is fetched and stored using
.Xr getsockopt 2
and
.Xr setsockopt 2
with a level of
.Dv IPPROTO_ICMPV6
and an option name of
.Dv ICMP6_FILTER .
.Pp
Six macros operate on an icmp6_filter structure:
.\" is "Fn" legal for macros?
.Bl -item -offset indent
.It
.Ft void
.Fn ICMP6_FILTER_SETPASSALL "struct icmp6_filter *filterp"
.It
.Ft void
.Fn ICMP6_FILTER_SETBLOCKALL "struct icmp6_filter *filterp"
.It
.Ft void
.Fn ICMP6_FILTER_SETPASS "int type" "struct icmp6_filter *filterp"
.It
.Ft void
.Fn ICMP6_FILTER_SETBLOCK "int type" "struct icmp6_filter *filterp"
.It
.Ft int
.Fn ICMP6_FILTER_WILLPASS "int type" "const struct icmp6_filter *filterp"
.It
.Ft int
.Fn ICMP6_FILTER_WILLBLOCK "int type" "const struct icmp6_filter *filterp"
.El
.Pp
The first argument to the last four macros
(an integer)
is an
.Tn ICMPv6
message type, between 0 and 255.
The pointer argument to all six
macros is a pointer to a filter that is modified by the first four
macros examined by the last two macros.
.Pp
The first two macros,
.Dv SETPASSALL
and
.Dv SETBLOCKALL ,
let us specify that
all
.Tn ICMPv6
messages are passed to the application or that all
.Tn ICMPv6
messages are blocked from being passed to the application.
.Pp
The next two macros,
.Dv SETPASS
and
.Dv SETBLOCK ,
let us specify that
messages of a given
.Tn ICMPv6
type should be passed to the application
or not passed to the application
(blocked).
.Pp
The final two macros,
.Dv WILLPASS
and
.Dv WILLBLOCK ,
return true or false
depending whether the specified message type is passed to the
application or blocked from being passed to the application by the
filter pointed to by the second argument.
.Pp
When an
.Tn ICMPv6
raw socket is created, it will by default pass all
.Tn ICMPv6
message types to the application.
.Pp
For further discussions see RFC2292.
.\"
.Sh ERRORS
A socket operation may fail with one of the following errors returned:
.Bl -tag -width Er
.It Bq Er EISCONN
when trying to establish a connection on a socket which
already has one, or when trying to send a datagram with the destination
address specified and the socket is already connected;
.It Bq Er ENOTCONN
when trying to send a datagram, but
no destination address is specified, and the socket hasn't been
connected;
.It Bq Er ENOBUFS
when the system runs out of memory for
an internal data structure;
.It Bq Er EADDRNOTAVAIL
when an attempt is made to create a
socket with a network address for which no network interface exists.
.El
.\"
.Sh SEE ALSO
.Xr recv 2 ,
.Xr send 2 ,
.Xr inet6 4 ,
.Xr intro 4 ,
.Xr ip6 4
.Rs
.%A W. Stevens
.%A M. Thomas
.%R RFC
.%N 2292
.%D February 1998
.%T "Advanced Sockets API for IPv6"
.Re
.Rs
.%A A. Conta
.%A S. Deering
.%R RFC
.%N 2463
.%D December 1998
.%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
.Re
.\"
.Sh HISTORY
The implementation is based on KAME stack
(which is descendant of WIDE hydrangea IPv6 stack kit).
.Pp
Part of the document was shamelessly copied from RFC2292.
Commit	Line	Data
9bccf70c A	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.