[apple/libc.git] / net / FreeBSD / sourcefilter.3

.\" Copyright (c) 2007-2009 Bruce Simpson.
.\" 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.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
.\"
.\" $FreeBSD: src/lib/libc/net/sourcefilter.3,v 1.2 2009/03/04 01:59:14 bms Exp $
.\"
.Dd February 13, 2009
.Dt SOURCEFILTER 3
.Os
.Sh NAME
.Nm sourcefilter
.Nd advanced multicast group membership API
.Sh SYNOPSIS
.In sys/socket.h
.In netinet/in.h
.Ft int
.Fo getipv4sourcefilter
.Fa "int s"
.Fa "struct in_addr interface"
.Fa "struct in_addr group"
.Fa "uint32_t *fmode"
.Fa "uint32_t *numsrc"
.Fa "struct in_addr *slist"
.Fc
.Ft int
.Fo getsourcefilter
.Fa "int s"
.Fa "uint32_t interface"
.Fa "struct sockaddr *group"
.Fa "socklen_t grouplen"
.Fa "uint32_t *fmode"
.Fa "uint32_t *numsrc"
.Fa "struct sockaddr_storage *slist"
.Fc
.Ft int
.Fo setipv4sourcefilter
.Fa "int s"
.Fa "struct in_addr interface"
.Fa "struct in_addr group"
.Fa "uint32_t fmode"
.Fa "uint32_t numsrc"
.Fa "struct in_addr *slist"
.Fc
.Ft int
.Fo setsourcefilter
.Fa "int s"
.Fa "uint32_t interface"
.Fa "struct sockaddr *group"
.Fa "socklen_t grouplen"
.Fa "uint32_t fmode"
.Fa "uint32_t numsrc"
.Fa "struct sockaddr_storage *slist"
.Fc
.Sh DESCRIPTION
The
.Nm
functions implement the advanced, full-state multicast API
defined in RFC 3678.
An application may use these functions to atomically set and
retrieve the multicast source address filters associated with a socket
.Fa s
and a multicast
.Fa group .
.Pp
The functions
.Fn getipv4sourcefilter
and
.Fn getsourcefilter
allow an application to discover the filter mode, and
source filter entries,
for an existing group membership.
.Pp
The kernel will always return the number of source filter
entries on the socket for that group in
.Fa *numsrc .
If the
.Fa *numsrc
argument is non-zero, the kernel will attempt to return up to
.Fa *numsrc
filter entries in the array pointed to by
.Fa slist .
The
.Fa *numsrc
argument may be set to 0, in which case the
.Fa slist
argument will be ignored.
.Pp
For the
.Fn setipv4sourcefilter
and
.Fn setsourcefilter
functions,
the
.Fa fmode
argument may be used to place the socket into inclusive or exclusive
group membership modes, by using the
.Dv MCAST_INCLUDE
or
.Dv MCAST_EXCLUDE
constants respectively.
The
.Fa numsrc
argument specifies the number of source entries in the
.Fa slist
array.
If the
.Fa numsrc
argument has a value of 0,
all source filters will be removed from the socket.
Removing all source filters from a membership which is in the
.Dv MCAST_INCLUDE
filter mode will cause the group to be left on that socket.
.Pp
The protocol-independent function
.Fn setsourcefilter
allows an application to join a multicast group on an interface
which may not have an assigned protocol address,
by passing its index for the
.Fa interface
argument.
.Pp
Any changes made by these functions
will be communicated to IGMPv3 and/or MLDv2 routers
on the local network as appropriate.
If no IGMPv3 or MLDv2 routers are present, changes in the source filter
lists made by these functions will not cause
state changes to be transmitted, with the exception of any
change which causes a group to be joined or left.
The kernel will continue to maintain the source filter state
regardless of the IGMP or MLD version in use on the link.
.Sh IMPLEMENTATION NOTES
The IPv4 specific versions of these functions are implemented in terms
of the protocol-independent functions.
Application writers are encouraged to use the protocol-independent functions
for efficiency, and forwards compatibility with IPv6 networks.
.Pp
For the protocol-independent functions
.Fn getsourcefilter
and
.Fn setsourcefilter ,
the argument
.Fa grouplen
argument specifies the size of the structure pointed to by
.Fa group .
This is required in order to differentiate between different
address families.
.Pp
Currently
.Fx
does not support source address selection for the IPv4
protocol family, therefore the use of multicast APIs with
an unnumbered IPv4 interface is
.Em not recommended.
In all cases, the first assigned IPv4 address on the interface
will be used as the source address of IGMP control traffic.
If this address is removed or changed, the results are undefined.
.Sh RETURN VALUES
.Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter
.Sh ERRORS
The
.Nm
functions may fail because of:
.Bl -tag -width Er
.It Bq Er EADDRNOTAVAIL
The network interface which the
.Dv interface
argument refers to was not configured in the system,
or the system is not a member of the
.Dv group .
.It Bq Er EAFNOSUPPORT
The
.Dv group
and/or one or more of the
.Dv slist
arguments were of an address family unsupported by the system,
or the address family of the
.Dv group
and
.Dv slist
arguments were not identical.
.It Bq Er EINVAL
The
.Dv group
argument does not contain a multicast address.
The
.Dv fmode
argument is invalid; it must be set to either
.Dv MCAST_INCLUDE
or
.Dv MCAST_EXCLUDE .
The
.Dv numsrc
or
.Dv slist
arguments do not specify a source list.
.It Bq Er ENOMEM
Insufficient memory was available to carry out the requested
operation.
.El
.Sh SEE ALSO
.Xr ip 4 ,
.Xr ip6 4
.Rs
.%A D. Thaler
.%A B. Fenner
.%A B. Quinn
.%T "Socket Interface Extensions for Multicast Source Filters"
.%N RFC 3678
.%D Jan 2004
.Re
.Sh HISTORY
The
.Nm
functions first appeared in
.Fx 7.0 .
.Sh AUTHORS
Bruce M. Simpson
.Aq bms@FreeBSD.org
Commit	Line	Data
1f2f436a A	1	.\" Copyright (c) 2007-2009 Bruce Simpson.
	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	.\"
	13	.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
	14	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	15	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	16	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
	17	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	18	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	19	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	20	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	21	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	22	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	23	.\" SUCH DAMAGE.
	24	.\"
	25	.\" $FreeBSD: src/lib/libc/net/sourcefilter.3,v 1.2 2009/03/04 01:59:14 bms Exp $
	26	.\"
	27	.Dd February 13, 2009
	28	.Dt SOURCEFILTER 3
	29	.Os
	30	.Sh NAME
	31	.Nm sourcefilter
	32	.Nd advanced multicast group membership API
	33	.Sh SYNOPSIS
	34	.In sys/socket.h
	35	.In netinet/in.h
	36	.Ft int
	37	.Fo getipv4sourcefilter
	38	.Fa "int s"
	39	.Fa "struct in_addr interface"
	40	.Fa "struct in_addr group"
	41	.Fa "uint32_t *fmode"
	42	.Fa "uint32_t *numsrc"
	43	.Fa "struct in_addr *slist"
	44	.Fc
	45	.Ft int
	46	.Fo getsourcefilter
	47	.Fa "int s"
	48	.Fa "uint32_t interface"
	49	.Fa "struct sockaddr *group"
	50	.Fa "socklen_t grouplen"
	51	.Fa "uint32_t *fmode"
	52	.Fa "uint32_t *numsrc"
	53	.Fa "struct sockaddr_storage *slist"
	54	.Fc
	55	.Ft int
	56	.Fo setipv4sourcefilter
	57	.Fa "int s"
	58	.Fa "struct in_addr interface"
	59	.Fa "struct in_addr group"
	60	.Fa "uint32_t fmode"
	61	.Fa "uint32_t numsrc"
	62	.Fa "struct in_addr *slist"
	63	.Fc
	64	.Ft int
65	.Fo setsourcefilter
66	.Fa "int s"
67	.Fa "uint32_t interface"
68	.Fa "struct sockaddr *group"
69	.Fa "socklen_t grouplen"
70	.Fa "uint32_t fmode"
71	.Fa "uint32_t numsrc"
72	.Fa "struct sockaddr_storage *slist"
73	.Fc
74	.Sh DESCRIPTION
75	The
76	.Nm
77	functions implement the advanced, full-state multicast API
78	defined in RFC 3678.
79	An application may use these functions to atomically set and
80	retrieve the multicast source address filters associated with a socket
81	.Fa s
82	and a multicast
83	.Fa group .
84	.Pp
85	The functions
86	.Fn getipv4sourcefilter
87	and
88	.Fn getsourcefilter
89	allow an application to discover the filter mode, and
90	source filter entries,
91	for an existing group membership.
92	.Pp
93	The kernel will always return the number of source filter
94	entries on the socket for that group in
95	.Fa *numsrc .
96	If the
97	.Fa *numsrc
98	argument is non-zero, the kernel will attempt to return up to
99	.Fa *numsrc
100	filter entries in the array pointed to by
101	.Fa slist .
102	The
103	.Fa *numsrc
104	argument may be set to 0, in which case the
105	.Fa slist
106	argument will be ignored.
107	.Pp
108	For the
109	.Fn setipv4sourcefilter
110	and
111	.Fn setsourcefilter
112	functions,
113	the
114	.Fa fmode
115	argument may be used to place the socket into inclusive or exclusive
116	group membership modes, by using the
117	.Dv MCAST_INCLUDE
118	or
119	.Dv MCAST_EXCLUDE
120	constants respectively.
121	The
122	.Fa numsrc
123	argument specifies the number of source entries in the
124	.Fa slist
125	array.
126	If the
127	.Fa numsrc
128	argument has a value of 0,
129	all source filters will be removed from the socket.
130	Removing all source filters from a membership which is in the
131	.Dv MCAST_INCLUDE
132	filter mode will cause the group to be left on that socket.
133	.Pp
134	The protocol-independent function
135	.Fn setsourcefilter
136	allows an application to join a multicast group on an interface
137	which may not have an assigned protocol address,
138	by passing its index for the
139	.Fa interface
140	argument.
141	.Pp
142	Any changes made by these functions
143	will be communicated to IGMPv3 and/or MLDv2 routers
144	on the local network as appropriate.
145	If no IGMPv3 or MLDv2 routers are present, changes in the source filter
146	lists made by these functions will not cause
147	state changes to be transmitted, with the exception of any
148	change which causes a group to be joined or left.
149	The kernel will continue to maintain the source filter state
150	regardless of the IGMP or MLD version in use on the link.
151	.Sh IMPLEMENTATION NOTES
152	The IPv4 specific versions of these functions are implemented in terms
153	of the protocol-independent functions.
154	Application writers are encouraged to use the protocol-independent functions
155	for efficiency, and forwards compatibility with IPv6 networks.
156	.Pp
157	For the protocol-independent functions
158	.Fn getsourcefilter
159	and
160	.Fn setsourcefilter ,
161	the argument
162	.Fa grouplen
163	argument specifies the size of the structure pointed to by
164	.Fa group .
165	This is required in order to differentiate between different
166	address families.
167	.Pp
168	Currently
169	.Fx
170	does not support source address selection for the IPv4
171	protocol family, therefore the use of multicast APIs with
172	an unnumbered IPv4 interface is
173	.Em not recommended.
174	In all cases, the first assigned IPv4 address on the interface
175	will be used as the source address of IGMP control traffic.
176	If this address is removed or changed, the results are undefined.
177	.Sh RETURN VALUES
178	.Rv -std getsourcefilter getipv4sourcefilter setsourcefilter setipv4sourcefilter
179	.Sh ERRORS
180	The
181	.Nm
182	functions may fail because of:
183	.Bl -tag -width Er
184	.It Bq Er EADDRNOTAVAIL
185	The network interface which the
186	.Dv interface
187	argument refers to was not configured in the system,
188	or the system is not a member of the
189	.Dv group .
190	.It Bq Er EAFNOSUPPORT
191	The
192	.Dv group
193	and/or one or more of the
194	.Dv slist
195	arguments were of an address family unsupported by the system,
196	or the address family of the
197	.Dv group
198	and
199	.Dv slist
200	arguments were not identical.
201	.It Bq Er EINVAL
202	The
203	.Dv group
204	argument does not contain a multicast address.
205	The
206	.Dv fmode
207	argument is invalid; it must be set to either
208	.Dv MCAST_INCLUDE
209	or
210	.Dv MCAST_EXCLUDE .
211	The
212	.Dv numsrc
213	or
214	.Dv slist
215	arguments do not specify a source list.
216	.It Bq Er ENOMEM
217	Insufficient memory was available to carry out the requested
218	operation.
219	.El
220	.Sh SEE ALSO
221	.Xr ip 4 ,
ad3c9f2a	222	.Xr ip6 4
1f2f436a A	223	.Rs
	224	.%A D. Thaler
	225	.%A B. Fenner
	226	.%A B. Quinn
	227	.%T "Socket Interface Extensions for Multicast Source Filters"
	228	.%N RFC 3678
	229	.%D Jan 2004
	230	.Re
	231	.Sh HISTORY
	232	The
	233	.Nm
	234	functions first appeared in
	235	.Fx 7.0 .
	236	.Sh AUTHORS
	237	Bruce M. Simpson
	238	.Aq bms@FreeBSD.org