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"