1 // Copyright 2012 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 ipv4 implements IP-level socket options for the Internet
8 // The package provides IP-level socket options that allow
9 // manipulation of IPv4 facilities.
11 // The IPv4 protocol and basic host requirements for IPv4 are defined
12 // in RFC 791 and RFC 1122.
13 // Host extensions for multicasting and socket interface extensions
14 // for multicast source filters are defined in RFC 1112 and RFC 3678.
15 // IGMPv1, IGMPv2 and IGMPv3 are defined in RFC 1112, RFC 2236 and RFC
17 // Source-specific multicast is defined in RFC 4607.
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 IPv4 transport. When a single TCP connection carrying
25 // a data flow of multiple packets needs to indicate the flow is
26 // important, Conn is used to set the type-of-service field on the
27 // IPv4 header for each packet.
29 // ln, err := net.Listen("tcp4", "0.0.0.0:1024")
35 // c, err := ln.Accept()
39 // go func(c net.Conn) {
42 // The outgoing packets will be labeled DiffServ assured forwarding
43 // class 1 low drop precedence, known as AF11 packets.
45 // if err := ipv4.NewConn(c).SetTOS(0x28); err != nil {
48 // if _, err := c.Write(data); err != nil {
57 // The options for multicasting are available for net.UDPConn and
58 // net.IPconn which are created as network connections that use the
59 // IPv4 transport. A few network facilities must be prepared before
60 // you begin multicasting, at a minimum joining network interfaces and
63 // en0, err := net.InterfaceByName("en0")
67 // en1, err := net.InterfaceByIndex(911)
71 // group := net.IPv4(224, 0, 0, 250)
73 // First, an application listens to an appropriate address with an
74 // appropriate service port.
76 // c, err := net.ListenPacket("udp4", "0.0.0.0:1024")
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 IPv4 and Ethernet.
88 // p := ipv4.NewPacketConn(c)
89 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: group}); err != nil {
92 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: group}); err != nil {
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 PacketConn is used to enable control message
102 // if err := p.SetControlMessage(ipv4.FlagDst, true); err != nil {
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.
110 // b := make([]byte, 1500)
112 // n, cm, src, err := p.ReadFrom(b)
116 // if cm.Dst.IsMulticast() {
117 // if cm.Dst.Equal(group) {
118 // // joined group, do something
120 // // unknown group, discard
125 // The application can also send both unicast and multicast packets.
129 // if _, err := p.WriteTo(data, nil, src); err != nil {
132 // dst := &net.UDPAddr{IP: group, Port: 1024}
133 // for _, ifi := range []*net.Interface{en0, en1} {
134 // if err := p.SetMulticastInterface(ifi); err != nil {
137 // p.SetMulticastTTL(2)
138 // if _, err := p.WriteTo(data, nil, dst); err != nil {
147 // An application that uses PacketConn or RawConn may join multiple
148 // multicast groups. For example, a UDP listener with port 1024 might
149 // join two different groups across over two different network
150 // interfaces by using:
152 // c, err := net.ListenPacket("udp4", "0.0.0.0:1024")
157 // p := ipv4.NewPacketConn(c)
158 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
161 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil {
164 // if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil {
168 // It is possible for multiple UDP listeners that listen on the same
169 // UDP port to join the same multicast group. The net package will
170 // provide a socket that listens to a wildcard address with reusable
171 // UDP port when an appropriate multicast address prefix is passed to
172 // the net.ListenPacket or net.ListenUDP.
174 // c1, err := net.ListenPacket("udp4", "224.0.0.0:1024")
179 // c2, err := net.ListenPacket("udp4", "224.0.0.0:1024")
184 // p1 := ipv4.NewPacketConn(c1)
185 // if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
188 // p2 := ipv4.NewPacketConn(c2)
189 // if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
193 // Also it is possible for the application to leave or rejoin a
194 // multicast group on the network interface.
196 // if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
199 // if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 250)}); err != nil {
204 // Source-specific multicasting
206 // An application that uses PacketConn or RawConn on IGMPv3 supported
207 // platform is able to join source-specific multicast groups.
208 // The application may use JoinSourceSpecificGroup and
209 // LeaveSourceSpecificGroup for the operation known as "include" mode,
211 // ssmgroup := net.UDPAddr{IP: net.IPv4(232, 7, 8, 9)}
212 // ssmsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 1)})
213 // if err := p.JoinSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
216 // if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
220 // or JoinGroup, ExcludeSourceSpecificGroup,
221 // IncludeSourceSpecificGroup and LeaveGroup for the operation known
222 // as "exclude" mode.
224 // exclsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 254)}
225 // if err := p.JoinGroup(en0, &ssmgroup); err != nil {
228 // if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
231 // if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
235 // Note that it depends on each platform implementation what happens
236 // when an application which runs on IGMPv3 unsupported platform uses
237 // JoinSourceSpecificGroup and LeaveSourceSpecificGroup.
238 // In general the platform tries to fall back to conversations using
239 // IGMPv1 or IGMPv2 and starts to listen to multicast traffic.
240 // In the fallback case, ExcludeSourceSpecificGroup and
241 // IncludeSourceSpecificGroup may return an error.
242 package ipv4 // import "golang.org/x/net/ipv4"
244 // BUG(mikio): This package is not implemented on NaCl and Plan 9.