x/net/ipv4: update package documentation

LGTM=iant
R=iant
CC=golang-codereviews
https://golang.org/cl/173300043

ipv4/dgramopt_posix.go

@@ -93,14 +93,15 @@ func (c *dgramOpt) SetMulticastLoopback(on bool) error {
 	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 @@ func (c *dgramOpt) JoinGroup(ifi *net.Interface, group net.Addr) error {
 	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 @@ func (c *dgramOpt) LeaveGroup(ifi *net.Interface, group net.Addr) error {
 	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 @@ func (c *dgramOpt) LeaveSourceSpecificGroup(ifi *net.Interface, group, source ne
 }
 
 // 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

ipv4/dgramopt_stub.go

@@ -8,50 +8,87 @@ package ipv4
 
 import "net"
 
+// MulticastTTL returns the time-to-live field value for outgoing
+// multicast packets.
 func (c *dgramOpt) MulticastTTL() (int, error) {
 	return 0, errOpNoSupport
 }
 
+// SetMulticastTTL sets the time-to-live field value for future
+// outgoing multicast packets.
 func (c *dgramOpt) SetMulticastTTL(ttl int) error {
 	return errOpNoSupport
 }
 
+// MulticastInterface returns the default interface for multicast
+// packet transmissions.
 func (c *dgramOpt) MulticastInterface() (*net.Interface, error) {
 	return nil, errOpNoSupport
 }
 
+// SetMulticastInterface sets the default interface for future
+// multicast packet transmissions.
 func (c *dgramOpt) SetMulticastInterface(ifi *net.Interface) error {
 	return errOpNoSupport
 }
 
+// MulticastLoopback reports whether transmitted multicast packets
+// should be copied and send back to the originator.
 func (c *dgramOpt) MulticastLoopback() (bool, error) {
 	return false, errOpNoSupport
 }
 
+// SetMulticastLoopback sets whether transmitted multicast packets
+// should be copied and send back to the originator.
 func (c *dgramOpt) SetMulticastLoopback(on bool) error {
 	return errOpNoSupport
 }
 
-func (c *dgramOpt) JoinGroup(ifi *net.Interface, grp net.Addr) error {
+// 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.
+// 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
 }
 
-func (c *dgramOpt) LeaveGroup(ifi *net.Interface, grp net.Addr) error {
+// 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 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
 }
 
+// LeaveSourceSpecificGroup leaves the source-specific group on the
+// interface ifi.
 func (c *dgramOpt) LeaveSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
 	return errOpNoSupport
 }
 
+// ExcludeSourceSpecificGroup excludes the source-specific group from
+// 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
 }
 
+// IncludeSourceSpecificGroup includes the excluded source-specific
+// group by ExcludeSourceSpecificGroup again on the interface ifi.
 func (c *dgramOpt) IncludeSourceSpecificGroup(ifi *net.Interface, group, source net.Addr) error {
 	return errOpNoSupport
 }

ipv4/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 := ipv4.NewConn(c).SetTOS(DiffServAF11); err != nil {
 //				// error handling
@@ -193,4 +193,45 @@
 //	if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 250)}); err != nil {
 //		// error handling
 //	}
+//
+//
+// Source-specific multicasting
+//
+// An application that uses PacketConn or RawConn on IGMPv3 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.IPv4(232, 7, 8, 9)}
+//	ssmsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)})
+//	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.IPv4(192, 168, 0, 254)}
+//	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 IGMPv3 unsupported platform uses
+// JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
+// In general the platform tries to fall back to conversations using
+// IGMPv1 or IGMP2 and starts to listen to multicast traffic.
+// In the fallback case, ExcludeSourceSpecificGroup and
+// IncludeSourceSpecificGroup may return an error.
 package ipv4

ipv4/genericopt_stub.go

@@ -6,18 +6,24 @@
 
 package ipv4
 
+// TOS returns the type-of-service field value for outgoing packets.
 func (c *genericOpt) TOS() (int, error) {
 	return 0, errOpNoSupport
 }
 
+// SetTOS sets the type-of-service field value for future outgoing
+// packets.
 func (c *genericOpt) SetTOS(tos int) error {
 	return errOpNoSupport
 }
 
+// TTL returns the time-to-live field value for outgoing packets.
 func (c *genericOpt) TTL() (int, error) {
 	return 0, errOpNoSupport
 }
 
+// SetTTL sets the time-to-live field value for future outgoing
+// packets.
 func (c *genericOpt) SetTTL(ttl int) error {
 	return errOpNoSupport
 }

ipv4/payload_cmsg.go

@@ -50,7 +50,7 @@ func (c *payloadHandler) ReadFrom(b []byte) (n int, cm *ControlMessage, src net.
 // address dst through the endpoint c, copying the payload from b.  It
 // returns the number of bytes written.  The control message cm allows
 // the datagram path and the outgoing interface to be specified.
-// Currently only Darwin and Darwin support this.  The cm may be nil if
+// Currently only Darwin and Linux support this.  The cm may be nil if
 // control of the outgoing datagram is not required.
 func (c *payloadHandler) WriteTo(b []byte, cm *ControlMessage, dst net.Addr) (n int, err error) {
 	if !c.ok() {