x/net/ipv6: update package documentation
LGTM=iant
R=iant
CC=golang-codereviews
https://golang.org/cl/177840043
diff --git a/ipv6/dgramopt_posix.go b/ipv6/dgramopt_posix.go
index 419cf7c..93ff2f1 100644
--- a/ipv6/dgramopt_posix.go
+++ b/ipv6/dgramopt_posix.go
@@ -93,14 +93,15 @@
return setInt(fd, &sockOpts[ssoMulticastLoopback], boolint(on))
}
-// JoinGroup joins the group address group on the interface ifi. By
-// default all sources that can cast data to group are accepted. It's
-// possible to mute and unmute data transmission from a specific
+// JoinGroup joins the group address group on the interface ifi.
+// By default all sources that can cast data to group are accepted.
+// It's possible to mute and unmute data transmission from a specific
// source by using ExcludeSourceSpecificGroup and
// IncludeSourceSpecificGroup.
-// It uses the system assigned multicast interface when ifi is nil,
-// although this is not recommended because the assignment depends on
-// platforms and sometimes it might require routing configuration.
+// JoinGroup uses the system assigned multicast interface when ifi is
+// nil, although this is not recommended because the assignment
+// depends on platforms and sometimes it might require routing
+// configuration.
func (c *dgramOpt) JoinGroup(ifi *net.Interface, group net.Addr) error {
if !c.ok() {
return syscall.EINVAL
@@ -116,9 +117,9 @@
return setGroup(fd, &sockOpts[ssoJoinGroup], ifi, grp)
}
-// LeaveGroup leaves the group address group on the interface ifi.
-// It's allowed to leave the group which is formed by
-// JoinSourceSpecificGroup for convenience.
+// LeaveGroup leaves the group address group on the interface ifi
+// regardless of whether the group is any-source group or
+// source-specific group.
func (c *dgramOpt) LeaveGroup(ifi *net.Interface, group net.Addr) error {
if !c.ok() {
return syscall.EINVAL
@@ -134,11 +135,12 @@
return setGroup(fd, &sockOpts[ssoLeaveGroup], ifi, grp)
}
-// JoinSourceSpecificGroup joins the source-specific group consisting
-// group and source on the interface ifi. It uses the system assigned
-// multicast interface when ifi is nil, although this is not
-// recommended because the assignment depends on platforms and
-// sometimes it might require routing configuration.
+// JoinSourceSpecificGroup joins the source-specific group comprising
+// group and source on the interface ifi.
+// JoinSourceSpecificGroup uses the system assigned multicast
+// interface when ifi is nil, although this is not recommended because
+// the assignment depends on platforms and sometimes it might require
+// routing configuration.
func (c *dgramOpt) JoinSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
if !c.ok() {
return syscall.EINVAL
@@ -180,8 +182,8 @@
}
// ExcludeSourceSpecificGroup excludes the source-specific group from
-// the already joined groups by either JoinGroup or
-// JoinSourceSpecificGroup on the interface ifi.
+// the already joined any-source groups by JoinGroup on the interface
+// ifi.
func (c *dgramOpt) ExcludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
if !c.ok() {
return syscall.EINVAL
diff --git a/ipv6/dgramopt_stub.go b/ipv6/dgramopt_stub.go
index 4978bc7..fb067fb 100644
--- a/ipv6/dgramopt_stub.go
+++ b/ipv6/dgramopt_stub.go
@@ -44,30 +44,32 @@
return errOpNoSupport
}
-// JoinGroup joins the group address group on the interface ifi. By
-// default all sources that can cast data to group are accepted. It's
-// possible to mute and unmute data transmission from a specific
+// JoinGroup joins the group address group on the interface ifi.
+// By default all sources that can cast data to group are accepted.
+// It's possible to mute and unmute data transmission from a specific
// source by using ExcludeSourceSpecificGroup and
// IncludeSourceSpecificGroup.
-// It uses the system assigned multicast interface when ifi is nil,
-// although this is not recommended because the assignment depends on
-// platforms and sometimes it might require routing configuration.
+// JoinGroup uses the system assigned multicast interface when ifi is
+// nil, although this is not recommended because the assignment
+// depends on platforms and sometimes it might require routing
+// configuration.
func (c *dgramOpt) JoinGroup(ifi *net.Interface, group net.Addr) error {
return errOpNoSupport
}
-// LeaveGroup leaves the group address group on the interface ifi.
-// It's allowed to leave the group which is formed by
-// JoinSourceSpecificGroup for convenience.
+// LeaveGroup leaves the group address group on the interface ifi
+// regardless of whether the group is any-source group or
+// source-specific group.
func (c *dgramOpt) LeaveGroup(ifi *net.Interface, group net.Addr) error {
return errOpNoSupport
}
-// JoinSourceSpecificGroup joins the source-specific group consisting
-// group and source on the interface ifi. It uses the system assigned
-// multicast interface when ifi is nil, although this is not
-// recommended because the assignment depends on platforms and
-// sometimes it might require routing configuration.
+// JoinSourceSpecificGroup joins the source-specific group comprising
+// group and source on the interface ifi.
+// JoinSourceSpecificGroup uses the system assigned multicast
+// interface when ifi is nil, although this is not recommended because
+// the assignment depends on platforms and sometimes it might require
+// routing configuration.
func (c *dgramOpt) JoinSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
return errOpNoSupport
}
@@ -79,8 +81,8 @@
}
// ExcludeSourceSpecificGroup excludes the source-specific group from
-// the already joined groups by either JoinGroup or
-// JoinSourceSpecificGroup on the interface ifi.
+// the already joined any-source groups by JoinGroup on the interface
+// ifi.
func (c *dgramOpt) ExcludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
return errOpNoSupport
}
diff --git a/ipv6/doc.go b/ipv6/doc.go
index e524627..3f91fa3 100644
--- a/ipv6/doc.go
+++ b/ipv6/doc.go
@@ -34,7 +34,7 @@
// defer c.Close()
//
// The outgoing packets will be labeled DiffServ assured forwarding
-// class 1 low drop precedence, as known as AF11 packets.
+// class 1 low drop precedence, known as AF11 packets.
//
// if err := ipv6.NewConn(c).SetTrafficClass(DiffServAF11); err != nil {
// // error handling
@@ -191,4 +191,44 @@
// if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil {
// // error handling
// }
+//
+//
+// Source-specific multicasting
+//
+// An application that uses PacketConn on MLDv2 supported platform is
+// able to join source-specific multicast groups as described in RFC
+// 3678. The application may use JoinSourceSpecificGroup and
+// LeaveSourceSpecificGroup for the operation known as "include" mode,
+//
+// ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")}
+// ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")}
+// if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
+// // error handling
+// }
+// if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
+// // error handling
+// }
+//
+// or JoinGroup, ExcludeSourceSpecificGroup,
+// IncludeSourceSpecificGroup and LeaveGroup for the operation known
+// as "exclude" mode.
+//
+// exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")}
+// if err := p.JoinGroup(en0, &ssmgroup); err != nil {
+// // error handling
+// }
+// if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
+// // error handling
+// }
+// if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
+// // error handling
+// }
+//
+// Note that it depends on each platform implementation what happens
+// when an application which runs on MLDv2 unsupported platform uses
+// JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
+// In general the platform tries to fall back to conversations using
+// MLDv1 and starts to listen to multicast traffic.
+// In the fallback case, ExcludeSourceSpecificGroup and
+// IncludeSourceSpecificGroup may return an error.
package ipv6
