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
5package net_test
6
7import (
8	"context"
9	"fmt"
10	"io"
11	"log"
12	"net"
13	"time"
14)
15
16func ExampleListener() {
17	// Listen on TCP port 2000 on all available unicast and
18	// anycast IP addresses of the local system.
19	l, err := net.Listen("tcp", ":2000")
20	if err != nil {
21		log.Fatal(err)
22	}
23	defer l.Close()
24	for {
25		// Wait for a connection.
26		conn, err := l.Accept()
27		if err != nil {
28			log.Fatal(err)
29		}
30		// Handle the connection in a new goroutine.
31		// The loop then returns to accepting, so that
32		// multiple connections may be served concurrently.
33		go func(c net.Conn) {
34			// Echo all incoming data.
35			io.Copy(c, c)
36			// Shut down the connection.
37			c.Close()
38		}(conn)
39	}
40}
41
42func ExampleDialer() {
43	var d net.Dialer
44	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
45	defer cancel()
46
47	conn, err := d.DialContext(ctx, "tcp", "localhost:12345")
48	if err != nil {
49		log.Fatalf("Failed to dial: %v", err)
50	}
51	defer conn.Close()
52
53	if _, err := conn.Write([]byte("Hello, World!")); err != nil {
54		log.Fatal(err)
55	}
56}
57
58func ExampleDialer_unix() {
59	// DialUnix does not take a context.Context parameter. This example shows
60	// how to dial a Unix socket with a Context. Note that the Context only
61	// applies to the dial operation; it does not apply to the connection once
62	// it has been established.
63	var d net.Dialer
64	ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
65	defer cancel()
66
67	d.LocalAddr = nil // if you have a local addr, add it here
68	raddr := net.UnixAddr{Name: "/path/to/unix.sock", Net: "unix"}
69	conn, err := d.DialContext(ctx, "unix", raddr.String())
70	if err != nil {
71		log.Fatalf("Failed to dial: %v", err)
72	}
73	defer conn.Close()
74	if _, err := conn.Write([]byte("Hello, socket!")); err != nil {
75		log.Fatal(err)
76	}
77}
78
79func ExampleIPv4() {
80	fmt.Println(net.IPv4(8, 8, 8, 8))
81
82	// Output:
83	// 8.8.8.8
84}
85
86func ExampleParseCIDR() {
87	ipv4Addr, ipv4Net, err := net.ParseCIDR("192.0.2.1/24")
88	if err != nil {
89		log.Fatal(err)
90	}
91	fmt.Println(ipv4Addr)
92	fmt.Println(ipv4Net)
93
94	ipv6Addr, ipv6Net, err := net.ParseCIDR("2001:db8:a0b:12f0::1/32")
95	if err != nil {
96		log.Fatal(err)
97	}
98	fmt.Println(ipv6Addr)
99	fmt.Println(ipv6Net)
100
101	// Output:
102	// 192.0.2.1
103	// 192.0.2.0/24
104	// 2001:db8:a0b:12f0::1
105	// 2001:db8::/32
106}
107
108func ExampleParseIP() {
109	fmt.Println(net.ParseIP("192.0.2.1"))
110	fmt.Println(net.ParseIP("2001:db8::68"))
111	fmt.Println(net.ParseIP("192.0.2"))
112
113	// Output:
114	// 192.0.2.1
115	// 2001:db8::68
116	// <nil>
117}
118
119func ExampleIP_DefaultMask() {
120	ip := net.ParseIP("192.0.2.1")
121	fmt.Println(ip.DefaultMask())
122
123	// Output:
124	// ffffff00
125}
126
127func ExampleIP_Equal() {
128	ipv4DNS := net.ParseIP("8.8.8.8")
129	ipv4Lo := net.ParseIP("127.0.0.1")
130	ipv6DNS := net.ParseIP("0:0:0:0:0:FFFF:0808:0808")
131
132	fmt.Println(ipv4DNS.Equal(ipv4DNS))
133	fmt.Println(ipv4DNS.Equal(ipv4Lo))
134	fmt.Println(ipv4DNS.Equal(ipv6DNS))
135
136	// Output:
137	// true
138	// false
139	// true
140}
141
142func ExampleIP_IsGlobalUnicast() {
143	ipv6Global := net.ParseIP("2000::")
144	ipv6UniqLocal := net.ParseIP("2000::")
145	ipv6Multi := net.ParseIP("FF00::")
146
147	ipv4Private := net.ParseIP("10.255.0.0")
148	ipv4Public := net.ParseIP("8.8.8.8")
149	ipv4Broadcast := net.ParseIP("255.255.255.255")
150
151	fmt.Println(ipv6Global.IsGlobalUnicast())
152	fmt.Println(ipv6UniqLocal.IsGlobalUnicast())
153	fmt.Println(ipv6Multi.IsGlobalUnicast())
154
155	fmt.Println(ipv4Private.IsGlobalUnicast())
156	fmt.Println(ipv4Public.IsGlobalUnicast())
157	fmt.Println(ipv4Broadcast.IsGlobalUnicast())
158
159	// Output:
160	// true
161	// true
162	// false
163	// true
164	// true
165	// false
166}
167
168func ExampleIP_IsInterfaceLocalMulticast() {
169	ipv6InterfaceLocalMulti := net.ParseIP("ff01::1")
170	ipv6Global := net.ParseIP("2000::")
171	ipv4 := net.ParseIP("255.0.0.0")
172
173	fmt.Println(ipv6InterfaceLocalMulti.IsInterfaceLocalMulticast())
174	fmt.Println(ipv6Global.IsInterfaceLocalMulticast())
175	fmt.Println(ipv4.IsInterfaceLocalMulticast())
176
177	// Output:
178	// true
179	// false
180	// false
181}
182
183func ExampleIP_IsLinkLocalMulticast() {
184	ipv6LinkLocalMulti := net.ParseIP("ff02::2")
185	ipv6LinkLocalUni := net.ParseIP("fe80::")
186	ipv4LinkLocalMulti := net.ParseIP("224.0.0.0")
187	ipv4LinkLocalUni := net.ParseIP("169.254.0.0")
188
189	fmt.Println(ipv6LinkLocalMulti.IsLinkLocalMulticast())
190	fmt.Println(ipv6LinkLocalUni.IsLinkLocalMulticast())
191	fmt.Println(ipv4LinkLocalMulti.IsLinkLocalMulticast())
192	fmt.Println(ipv4LinkLocalUni.IsLinkLocalMulticast())
193
194	// Output:
195	// true
196	// false
197	// true
198	// false
199}
200
201func ExampleIP_IsLinkLocalUnicast() {
202	ipv6LinkLocalUni := net.ParseIP("fe80::")
203	ipv6Global := net.ParseIP("2000::")
204	ipv4LinkLocalUni := net.ParseIP("169.254.0.0")
205	ipv4LinkLocalMulti := net.ParseIP("224.0.0.0")
206
207	fmt.Println(ipv6LinkLocalUni.IsLinkLocalUnicast())
208	fmt.Println(ipv6Global.IsLinkLocalUnicast())
209	fmt.Println(ipv4LinkLocalUni.IsLinkLocalUnicast())
210	fmt.Println(ipv4LinkLocalMulti.IsLinkLocalUnicast())
211
212	// Output:
213	// true
214	// false
215	// true
216	// false
217}
218
219func ExampleIP_IsLoopback() {
220	ipv6Lo := net.ParseIP("::1")
221	ipv6 := net.ParseIP("ff02::1")
222	ipv4Lo := net.ParseIP("127.0.0.0")
223	ipv4 := net.ParseIP("128.0.0.0")
224
225	fmt.Println(ipv6Lo.IsLoopback())
226	fmt.Println(ipv6.IsLoopback())
227	fmt.Println(ipv4Lo.IsLoopback())
228	fmt.Println(ipv4.IsLoopback())
229
230	// Output:
231	// true
232	// false
233	// true
234	// false
235}
236
237func ExampleIP_IsMulticast() {
238	ipv6Multi := net.ParseIP("FF00::")
239	ipv6LinkLocalMulti := net.ParseIP("ff02::1")
240	ipv6Lo := net.ParseIP("::1")
241	ipv4Multi := net.ParseIP("239.0.0.0")
242	ipv4LinkLocalMulti := net.ParseIP("224.0.0.0")
243	ipv4Lo := net.ParseIP("127.0.0.0")
244
245	fmt.Println(ipv6Multi.IsMulticast())
246	fmt.Println(ipv6LinkLocalMulti.IsMulticast())
247	fmt.Println(ipv6Lo.IsMulticast())
248	fmt.Println(ipv4Multi.IsMulticast())
249	fmt.Println(ipv4LinkLocalMulti.IsMulticast())
250	fmt.Println(ipv4Lo.IsMulticast())
251
252	// Output:
253	// true
254	// true
255	// false
256	// true
257	// true
258	// false
259}
260
261func ExampleIP_IsPrivate() {
262	ipv6Private := net.ParseIP("fc00::")
263	ipv6Public := net.ParseIP("fe00::")
264	ipv4Private := net.ParseIP("10.255.0.0")
265	ipv4Public := net.ParseIP("11.0.0.0")
266
267	fmt.Println(ipv6Private.IsPrivate())
268	fmt.Println(ipv6Public.IsPrivate())
269	fmt.Println(ipv4Private.IsPrivate())
270	fmt.Println(ipv4Public.IsPrivate())
271
272	// Output:
273	// true
274	// false
275	// true
276	// false
277}
278
279func ExampleIP_IsUnspecified() {
280	ipv6Unspecified := net.ParseIP("::")
281	ipv6Specified := net.ParseIP("fe00::")
282	ipv4Unspecified := net.ParseIP("0.0.0.0")
283	ipv4Specified := net.ParseIP("8.8.8.8")
284
285	fmt.Println(ipv6Unspecified.IsUnspecified())
286	fmt.Println(ipv6Specified.IsUnspecified())
287	fmt.Println(ipv4Unspecified.IsUnspecified())
288	fmt.Println(ipv4Specified.IsUnspecified())
289
290	// Output:
291	// true
292	// false
293	// true
294	// false
295}
296
297func ExampleIP_Mask() {
298	ipv4Addr := net.ParseIP("192.0.2.1")
299	// This mask corresponds to a /24 subnet for IPv4.
300	ipv4Mask := net.CIDRMask(24, 32)
301	fmt.Println(ipv4Addr.Mask(ipv4Mask))
302
303	ipv6Addr := net.ParseIP("2001:db8:a0b:12f0::1")
304	// This mask corresponds to a /32 subnet for IPv6.
305	ipv6Mask := net.CIDRMask(32, 128)
306	fmt.Println(ipv6Addr.Mask(ipv6Mask))
307
308	// Output:
309	// 192.0.2.0
310	// 2001:db8::
311}
312
313func ExampleIP_String() {
314	ipv6 := net.IP{0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
315	ipv4 := net.IPv4(10, 255, 0, 0)
316
317	fmt.Println(ipv6.String())
318	fmt.Println(ipv4.String())
319
320	// Output:
321	// fc00::
322	// 10.255.0.0
323}
324
325func ExampleIP_To16() {
326	ipv6 := net.IP{0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
327	ipv4 := net.IPv4(10, 255, 0, 0)
328
329	fmt.Println(ipv6.To16())
330	fmt.Println(ipv4.To16())
331
332	// Output:
333	// fc00::
334	// 10.255.0.0
335}
336
337func ExampleIP_to4() {
338	ipv6 := net.IP{0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0}
339	ipv4 := net.IPv4(10, 255, 0, 0)
340
341	fmt.Println(ipv6.To4())
342	fmt.Println(ipv4.To4())
343
344	// Output:
345	// <nil>
346	// 10.255.0.0
347}
348
349func ExampleCIDRMask() {
350	// This mask corresponds to a /31 subnet for IPv4.
351	fmt.Println(net.CIDRMask(31, 32))
352
353	// This mask corresponds to a /64 subnet for IPv6.
354	fmt.Println(net.CIDRMask(64, 128))
355
356	// Output:
357	// fffffffe
358	// ffffffffffffffff0000000000000000
359}
360
361func ExampleIPv4Mask() {
362	fmt.Println(net.IPv4Mask(255, 255, 255, 0))
363
364	// Output:
365	// ffffff00
366}
367
368func ExampleUDPConn_WriteTo() {
369	// Unlike Dial, ListenPacket creates a connection without any
370	// association with peers.
371	conn, err := net.ListenPacket("udp", ":0")
372	if err != nil {
373		log.Fatal(err)
374	}
375	defer conn.Close()
376
377	dst, err := net.ResolveUDPAddr("udp", "192.0.2.1:2000")
378	if err != nil {
379		log.Fatal(err)
380	}
381
382	// The connection can write data to the desired address.
383	_, err = conn.WriteTo([]byte("data"), dst)
384	if err != nil {
385		log.Fatal(err)
386	}
387}
388