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