github.com/graybobo/golang.org-package-offline-cache@v0.0.0-20200626051047-6608995c132f/x/net/ipv6/doc.go (about)

     1  // Copyright 2013 The Go Authors.  All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package ipv6 implements IP-level socket options for the Internet
     6  // Protocol version 6.
     7  //
     8  // The package provides IP-level socket options that allow
     9  // manipulation of IPv6 facilities.
    10  //
    11  // The IPv6 protocol is defined in RFC 2460.
    12  // Basic and advanced socket interface extensions are defined in RFC
    13  // 3493 and RFC 3542.
    14  // Socket interface extensions for multicast source filters are
    15  // defined in RFC 3678.
    16  // MLDv1 and MLDv2 are defined in RFC 2710 and RFC 3810.
    17  // Source-specific multicast is defined in RFC 4607.
    18  //
    19  //
    20  // Unicasting
    21  //
    22  // The options for unicasting are available for net.TCPConn,
    23  // net.UDPConn and net.IPConn which are created as network connections
    24  // that use the IPv6 transport.  When a single TCP connection carrying
    25  // a data flow of multiple packets needs to indicate the flow is
    26  // important, ipv6.Conn is used to set the traffic class field on the
    27  // IPv6 header for each packet.
    28  //
    29  //	ln, err := net.Listen("tcp6", "[::]:1024")
    30  //	if err != nil {
    31  //		// error handling
    32  //	}
    33  //	defer ln.Close()
    34  //	for {
    35  //		c, err := ln.Accept()
    36  //		if err != nil {
    37  //			// error handling
    38  //		}
    39  //		go func(c net.Conn) {
    40  //			defer c.Close()
    41  //
    42  // The outgoing packets will be labeled DiffServ assured forwarding
    43  // class 1 low drop precedence, known as AF11 packets.
    44  //
    45  //			if err := ipv6.NewConn(c).SetTrafficClass(0x28); err != nil {
    46  //				// error handling
    47  //			}
    48  //			if _, err := c.Write(data); err != nil {
    49  //				// error handling
    50  //			}
    51  //		}(c)
    52  //	}
    53  //
    54  //
    55  // Multicasting
    56  //
    57  // The options for multicasting are available for net.UDPConn and
    58  // net.IPconn which are created as network connections that use the
    59  // IPv6 transport.  A few network facilities must be prepared before
    60  // you begin multicasting, at a minimum joining network interfaces and
    61  // multicast groups.
    62  //
    63  //	en0, err := net.InterfaceByName("en0")
    64  //	if err != nil {
    65  //		// error handling
    66  //	}
    67  //	en1, err := net.InterfaceByIndex(911)
    68  //	if err != nil {
    69  //		// error handling
    70  //	}
    71  //	group := net.ParseIP("ff02::114")
    72  //
    73  // First, an application listens to an appropriate address with an
    74  // appropriate service port.
    75  //
    76  //	c, err := net.ListenPacket("udp6", "[::]:1024")
    77  //	if err != nil {
    78  //		// error handling
    79  //	}
    80  //	defer c.Close()
    81  //
    82  // Second, the application joins multicast groups, starts listening to
    83  // the groups on the specified network interfaces.  Note that the
    84  // service port for transport layer protocol does not matter with this
    85  // operation as joining groups affects only network and link layer
    86  // protocols, such as IPv6 and Ethernet.
    87  //
    88  //	p := ipv6.NewPacketConn(c)
    89  //	if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil {
    90  //		// error handling
    91  //	}
    92  //	if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil {
    93  //		// error handling
    94  //	}
    95  //
    96  // The application might set per packet control message transmissions
    97  // between the protocol stack within the kernel.  When the application
    98  // needs a destination address on an incoming packet,
    99  // SetControlMessage of ipv6.PacketConn is used to enable control
   100  // message transmissons.
   101  //
   102  //	if err := p.SetControlMessage(ipv6.FlagDst, true); err != nil {
   103  //		// error handling
   104  //	}
   105  //
   106  // The application could identify whether the received packets are
   107  // of interest by using the control message that contains the
   108  // destination address of the received packet.
   109  //
   110  //	b := make([]byte, 1500)
   111  //	for {
   112  //		n, rcm, src, err := p.ReadFrom(b)
   113  //		if err != nil {
   114  //			// error handling
   115  //		}
   116  //		if rcm.Dst.IsMulticast() {
   117  //			if rcm.Dst.Equal(group) {
   118  //				// joined group, do something
   119  //			} else {
   120  //				// unknown group, discard
   121  //				continue
   122  //			}
   123  //		}
   124  //
   125  // The application can also send both unicast and multicast packets.
   126  //
   127  //		p.SetTrafficClass(0x0)
   128  //		p.SetHopLimit(16)
   129  //		if _, err := p.WriteTo(data[:n], nil, src); err != nil {
   130  //			// error handling
   131  //		}
   132  //		dst := &net.UDPAddr{IP: group, Port: 1024}
   133  //		wcm := ipv6.ControlMessage{TrafficClass: 0xe0, HopLimit: 1}
   134  //		for _, ifi := range []*net.Interface{en0, en1} {
   135  //			wcm.IfIndex = ifi.Index
   136  //			if _, err := p.WriteTo(data[:n], &wcm, dst); err != nil {
   137  //				// error handling
   138  //			}
   139  //		}
   140  //	}
   141  //
   142  //
   143  // More multicasting
   144  //
   145  // An application that uses PacketConn may join multiple multicast
   146  // groups.  For example, a UDP listener with port 1024 might join two
   147  // different groups across over two different network interfaces by
   148  // using:
   149  //
   150  //	c, err := net.ListenPacket("udp6", "[::]:1024")
   151  //	if err != nil {
   152  //		// error handling
   153  //	}
   154  //	defer c.Close()
   155  //	p := ipv6.NewPacketConn(c)
   156  //	if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::1:114")}); err != nil {
   157  //		// error handling
   158  //	}
   159  //	if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
   160  //		// error handling
   161  //	}
   162  //	if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
   163  //		// error handling
   164  //	}
   165  //
   166  // It is possible for multiple UDP listeners that listen on the same
   167  // UDP port to join the same multicast group.  The net package will
   168  // provide a socket that listens to a wildcard address with reusable
   169  // UDP port when an appropriate multicast address prefix is passed to
   170  // the net.ListenPacket or net.ListenUDP.
   171  //
   172  //	c1, err := net.ListenPacket("udp6", "[ff02::]:1024")
   173  //	if err != nil {
   174  //		// error handling
   175  //	}
   176  //	defer c1.Close()
   177  //	c2, err := net.ListenPacket("udp6", "[ff02::]:1024")
   178  //	if err != nil {
   179  //		// error handling
   180  //	}
   181  //	defer c2.Close()
   182  //	p1 := ipv6.NewPacketConn(c1)
   183  //	if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
   184  //		// error handling
   185  //	}
   186  //	p2 := ipv6.NewPacketConn(c2)
   187  //	if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
   188  //		// error handling
   189  //	}
   190  //
   191  // Also it is possible for the application to leave or rejoin a
   192  // multicast group on the network interface.
   193  //
   194  //	if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
   195  //		// error handling
   196  //	}
   197  //	if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil {
   198  //		// error handling
   199  //	}
   200  //
   201  //
   202  // Source-specific multicasting
   203  //
   204  // An application that uses PacketConn on MLDv2 supported platform is
   205  // able to join source-specific multicast groups.
   206  // The application may use JoinSourceSpecificGroup and
   207  // LeaveSourceSpecificGroup for the operation known as "include" mode,
   208  //
   209  //	ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")}
   210  //	ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")}
   211  //	if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
   212  //		// error handling
   213  //	}
   214  //	if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
   215  //		// error handling
   216  //	}
   217  //
   218  // or JoinGroup, ExcludeSourceSpecificGroup,
   219  // IncludeSourceSpecificGroup and LeaveGroup for the operation known
   220  // as "exclude" mode.
   221  //
   222  //	exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")}
   223  //	if err := p.JoinGroup(en0, &ssmgroup); err != nil {
   224  //		// error handling
   225  //	}
   226  //	if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
   227  //		// error handling
   228  //	}
   229  //	if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
   230  //		// error handling
   231  //	}
   232  //
   233  // Note that it depends on each platform implementation what happens
   234  // when an application which runs on MLDv2 unsupported platform uses
   235  // JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
   236  // In general the platform tries to fall back to conversations using
   237  // MLDv1 and starts to listen to multicast traffic.
   238  // In the fallback case, ExcludeSourceSpecificGroup and
   239  // IncludeSourceSpecificGroup may return an error.
   240  package ipv6 // import "golang.org/x/net/ipv6"