← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/golang.org/x/net/ipv4/doc.go

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/golang.org/x/net/ipv4/doc.go
 
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
//
 
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 IPv4 transport.  When a single TCP connection carrying
 
25
// a data flow of multiple packets needs to indicate the flow is
 
26
// important, ipv4.Conn is used to set the type-of-service field on
 
27
// the IPv4 header for each packet.
 
28
//
 
29
//      ln, err := net.Listen("tcp4", "0.0.0.0: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 := ipv4.NewConn(c).SetTOS(DiffServAF11); 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
// IPv4 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.IPv4(224, 0, 0, 250)
 
72
//
 
73
// First, an application listens to an appropriate address with an
 
74
// appropriate service port.
 
75
//
 
76
//      c, err := net.ListenPacket("udp4", "0.0.0.0: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 IPv4 and Ethernet.
 
87
//
 
88
//      p := ipv4.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 ipv4.PacketConn is used to enable control
 
100
// message transmissons.
 
101
//
 
102
//      if err := p.SetControlMessage(ipv4.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, cm, src, err := p.ReadFrom(b)
 
113
//              if err != nil {
 
114
//                      // error handling
 
115
//              }
 
116
//              if cm.Dst.IsMulticast() {
 
117
//                      if cm.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.SetTOS(DiffServCS0)
 
128
//              p.SetTTL(16)
 
129
//              if _, err := p.WriteTo(data, nil, src); err != nil {
 
130
//                      // error handling
 
131
//              }
 
132
//              dst := &net.UDPAddr{IP: group, Port: 1024}
 
133
//              for _, ifi := range []*net.Interface{en0, en1} {
 
134
//                      if err := p.SetMulticastInterface(ifi); err != nil {
 
135
//                              // error handling
 
136
//                      }
 
137
//                      p.SetMulticastTTL(2)
 
138
//                      if _, err := p.WriteTo(data, nil, dst); err != nil {
 
139
//                              // error handling
 
140
//                      }
 
141
//              }
 
142
//      }
 
143
//
 
144
//
 
145
// More multicasting
 
146
//
 
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:
 
151
//
 
152
//      c, err := net.ListenPacket("udp4", "0.0.0.0:1024")
 
153
//      if err != nil {
 
154
//              // error handling
 
155
//      }
 
156
//      defer c.Close()
 
157
//      p := ipv4.NewPacketConn(c)
 
158
//      if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
 
159
//              // error handling
 
160
//      }
 
161
//      if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil {
 
162
//              // error handling
 
163
//      }
 
164
//      if err := p.JoinGroup(en1, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 249)}); err != nil {
 
165
//              // error handling
 
166
//      }
 
167
//
 
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.
 
173
//
 
174
//      c1, err := net.ListenPacket("udp4", "224.0.0.0:1024")
 
175
//      if err != nil {
 
176
//              // error handling
 
177
//      }
 
178
//      defer c1.Close()
 
179
//      c2, err := net.ListenPacket("udp4", "224.0.0.0:1024")
 
180
//      if err != nil {
 
181
//              // error handling
 
182
//      }
 
183
//      defer c2.Close()
 
184
//      p1 := ipv4.NewPacketConn(c1)
 
185
//      if err := p1.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
 
186
//              // error handling
 
187
//      }
 
188
//      p2 := ipv4.NewPacketConn(c2)
 
189
//      if err := p2.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
 
190
//              // error handling
 
191
//      }
 
192
//
 
193
// Also it is possible for the application to leave or rejoin a
 
194
// multicast group on the network interface.
 
195
//
 
196
//      if err := p.LeaveGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 248)}); err != nil {
 
197
//              // error handling
 
198
//      }
 
199
//      if err := p.JoinGroup(en0, &net.UDPAddr{IP: net.IPv4(224, 0, 0, 250)}); err != nil {
 
200
//              // error handling
 
201
//      }
 
202
//
 
203
//
 
204
// Source-specific multicasting
 
205
//
 
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,
 
210
//
 
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 {
 
214
//              // error handling
 
215
//      }
 
216
//      if err := p.LeaveSourceSpecificGroup(en0, &ssmgroup, &ssmsource); err != nil {
 
217
//              // error handling
 
218
//      }
 
219
//
 
220
// or JoinGroup, ExcludeSourceSpecificGroup,
 
221
// IncludeSourceSpecificGroup and LeaveGroup for the operation known
 
222
// as "exclude" mode.
 
223
//
 
224
//      exclsource := net.UDPAddr{IP: net.IPv4(192, 168, 0, 254)}
 
225
//      if err := p.JoinGroup(en0, &ssmgroup); err != nil {
 
226
//              // error handling
 
227
//      }
 
228
//      if err := p.ExcludeSourceSpecificGroup(en0, &ssmgroup, &exclsource); err != nil {
 
229
//              // error handling
 
230
//      }
 
231
//      if err := p.LeaveGroup(en0, &ssmgroup); err != nil {
 
232
//              // error handling
 
233
//      }
 
234
//
 
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"