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.
5 // Package ipv6 implements IP-level socket options for the Internet
8 // The package provides IP-level socket options that allow
9 // manipulation of IPv6 facilities.
11 // The IPv6 protocol is defined in RFC 8200.
12 // Socket interface extensions are defined in RFC 3493, RFC 3542 and
14 // MLDv1 and MLDv2 are defined in RFC 2710 and RFC 3810.
15 // Source-specific multicast is defined in RFC 4607.
17 // On Darwin, this package requires OS X Mavericks version 10.9 or
18 // above, or equivalent.
23 // The options for unicasting are available for net.TCPConn,
24 // net.UDPConn and net.IPConn which are created as network connections
25 // that use the IPv6 transport. When a single TCP connection carrying
26 // a data flow of multiple packets needs to indicate the flow is
27 // important, Conn is used to set the traffic class field on the IPv6
28 // header for each packet.
30 // ln, err := net.Listen("tcp6", "[::]:1024")
36 // c, err := ln.Accept()
40 // go func(c net.Conn) {
43 // The outgoing packets will be labeled DiffServ assured forwarding
44 // class 1 low drop precedence, known as AF11 packets.
46 // if err := ipv6.NewConn(c).SetTrafficClass(0x28); err != nil {
49 // if _, err := c.Write(data); err != nil {
58 // The options for multicasting are available for net.UDPConn and
59 // net.IPconn which are created as network connections that use the
60 // IPv6 transport. A few network facilities must be prepared before
61 // you begin multicasting, at a minimum joining network interfaces and
64 // en0, err := net.InterfaceByName("en0")
68 // en1, err := net.InterfaceByIndex(911)
72 // group := net.ParseIP("ff02::114")
74 // First, an application listens to an appropriate address with an
75 // appropriate service port.
77 // c, err := net.ListenPacket("udp6", "[::]:1024")
83 // Second, the application joins multicast groups, starts listening to
84 // the groups on the specified network interfaces. Note that the
85 // service port for transport layer protocol does not matter with this
86 // operation as joining groups affects only network and link layer
87 // protocols, such as IPv6 and Ethernet.
89 // p := ipv6.NewPacketConn(c)
90 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil {
93 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil {
97 // The application might set per packet control message transmissions
98 // between the protocol stack within the kernel. When the application
99 // needs a destination address on an incoming packet,
100 // SetControlMessage of PacketConn is used to enable control message
103 // if err := p.SetControlMessage(ipv6.FlagDst, true); err != nil {
107 // The application could identify whether the received packets are
108 // of interest by using the control message that contains the
109 // destination address of the received packet.
111 // b := make([]byte, 1500)
113 // n, rcm, src, err := p.ReadFrom(b)
117 // if rcm.Dst.IsMulticast() {
118 // if rcm.Dst.Equal(group) {
119 // // joined group, do something
121 // // unknown group, discard
126 // The application can also send both unicast and multicast packets.
128 // p.SetTrafficClass(0x0)
130 // if _, err := p.WriteTo(data[:n], nil, src); err != nil {
133 // dst := &net.UDPAddr{IP: group, Port: 1024}
134 // wcm := ipv6.ControlMessage{TrafficClass: 0xe0, HopLimit: 1}
135 // for _, ifi := range []*net.Interface{en0, en1} {
136 // wcm.IfIndex = ifi.Index
137 // if _, err := p.WriteTo(data[:n], &wcm, dst); err != nil {
146 // An application that uses PacketConn may join multiple multicast
147 // groups. For example, a UDP listener with port 1024 might join two
148 // different groups across over two different network interfaces by
151 // c, err := net.ListenPacket("udp6", "[::]:1024")
156 // p := ipv6.NewPacketConn(c)
157 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::1:114")}); err != nil {
160 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
163 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.ParseIP("ff02::2:114")}); err != nil {
167 // It is possible for multiple UDP listeners that listen on the same
168 // UDP port to join the same multicast group. The net package will
169 // provide a socket that listens to a wildcard address with reusable
170 // UDP port when an appropriate multicast address prefix is passed to
171 // the net.ListenPacket or net.ListenUDP.
173 // c1, err := net.ListenPacket("udp6", "[ff02::]:1024")
178 // c2, err := net.ListenPacket("udp6", "[ff02::]:1024")
183 // p1 := ipv6.NewPacketConn(c1)
184 // if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
187 // p2 := ipv6.NewPacketConn(c2)
188 // if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
192 // Also it is possible for the application to leave or rejoin a
193 // multicast group on the network interface.
195 // if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff02::114")}); err != nil {
198 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.ParseIP("ff01::114")}); err != nil {
203 // Source-specific multicasting
205 // An application that uses PacketConn on MLDv2 supported platform is
206 // able to join source-specific multicast groups.
207 // The application may use JoinSourceSpecificGroup and
208 // LeaveSourceSpecificGroup for the operation known as "include" mode,
210 // ssmgroup := net.UDPAddr{IP: net.ParseIP("ff32::8000:9")}
211 // ssmsource := net.UDPAddr{IP: net.ParseIP("fe80::cafe")}
212 // if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
215 // if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
219 // or JoinGroup, ExcludeSourceSpecificGroup,
220 // IncludeSourceSpecificGroup and LeaveGroup for the operation known
221 // as "exclude" mode.
223 // exclsource := net.UDPAddr{IP: net.ParseIP("fe80::dead")}
224 // if err := p.JoinGroup(en0, &ssmgroup); err != nil {
227 // if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
230 // if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
234 // Note that it depends on each platform implementation what happens
235 // when an application which runs on MLDv2 unsupported platform uses
236 // JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
237 // In general the platform tries to fall back to conversations using
238 // MLDv1 and starts to listen to multicast traffic.
239 // In the fallback case, ExcludeSourceSpecificGroup and
240 // IncludeSourceSpecificGroup may return an error.
241 package ipv6 // import "golang.org/x/net/ipv6"
243 // BUG(mikio): This package is not implemented on NaCl and Plan 9.