@@ -20,34 +20,95 @@ use vec;
20
20
use iter;
21
21
use slice;
22
22
23
- /// Representation of a socket address for networking applications .
23
+ /// An internet socket address, either IPv4 or IPv6 .
24
24
///
25
- /// A socket address can either represent the IPv4 or IPv6 protocol and is
26
- /// paired with at least a port number as well. Each protocol may have more
27
- /// specific information about the address available to it as well.
25
+ /// Internet socket addresses consist of an [IP address], a 16-bit port number, as well
26
+ /// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and
27
+ /// [`SocketAddrV6`]'s respective documentation for more details.
28
+ ///
29
+ /// [IP address]: ../../std/net/enum.IpAddr.html
30
+ /// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
31
+ /// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
32
+ ///
33
+ /// # Examples
34
+ ///
35
+ /// ```
36
+ /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
37
+ ///
38
+ /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
39
+ ///
40
+ /// assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
41
+ /// assert_eq!(socket.port(), 8080);
42
+ /// assert_eq!(socket.is_ipv4(), true);
43
+ /// ```
28
44
#[ derive( Copy , Clone , PartialEq , Eq , Hash , Debug ) ]
29
45
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
30
46
pub enum SocketAddr {
31
- /// An IPv4 socket address which is a (ip, port) combination .
47
+ /// An IPv4 socket address.
32
48
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
33
49
V4 ( #[ stable( feature = "rust1" , since = "1.0.0" ) ] SocketAddrV4 ) ,
34
50
/// An IPv6 socket address.
35
51
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
36
52
V6 ( #[ stable( feature = "rust1" , since = "1.0.0" ) ] SocketAddrV6 ) ,
37
53
}
38
54
39
- /// An IPv4 socket address which is a (ip, port) combination.
55
+ /// An IPv4 socket address.
56
+ ///
57
+ /// IPv4 socket addresses consist of an [IPv4 address] and a 16-bit port number, as
58
+ /// stated in [IETF RFC 793].
59
+ ///
60
+ /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
61
+ ///
62
+ /// [IETF RFC 793]: https://tools.ietf.org/html/rfc793
63
+ /// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
64
+ /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
65
+ ///
66
+ /// # Examples
67
+ ///
68
+ /// ```
69
+ /// use std::net::{Ipv4Addr, SocketAddrV4};
70
+ ///
71
+ /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
72
+ ///
73
+ /// assert_eq!("127.0.0.1:8080".parse(), Ok(socket));
74
+ /// assert_eq!(socket.ip(), &Ipv4Addr::new(127, 0, 0, 1));
75
+ /// assert_eq!(socket.port(), 8080);
76
+ /// ```
40
77
#[ derive( Copy ) ]
41
78
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
42
79
pub struct SocketAddrV4 { inner : c:: sockaddr_in }
43
80
44
81
/// An IPv6 socket address.
82
+ ///
83
+ /// IPv6 socket addresses consist of an [Ipv6 address], a 16-bit port number, as well
84
+ /// as fields containing the traffic class, the flow label, and a scope identifier
85
+ /// (see [IETF RFC 2553, Section 3.3] for more details).
86
+ ///
87
+ /// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses.
88
+ ///
89
+ /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
90
+ /// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
91
+ /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
92
+ ///
93
+ /// # Examples
94
+ ///
95
+ /// ```
96
+ /// use std::net::{Ipv6Addr, SocketAddrV6};
97
+ ///
98
+ /// let socket = SocketAddrV6::new(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
99
+ ///
100
+ /// assert_eq!("[2001:db8::1]:8080".parse(), Ok(socket));
101
+ /// assert_eq!(socket.ip(), &Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1));
102
+ /// assert_eq!(socket.port(), 8080);
103
+ /// ```
45
104
#[ derive( Copy ) ]
46
105
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
47
106
pub struct SocketAddrV6 { inner : c:: sockaddr_in6 }
48
107
49
108
impl SocketAddr {
50
- /// Creates a new socket address from the (ip, port) pair.
109
+ /// Creates a new socket address from an [IP address] and a port number.
110
+ ///
111
+ /// [IP address]: ../../std/net/enum.IpAddr.html
51
112
///
52
113
/// # Examples
53
114
///
@@ -84,7 +145,7 @@ impl SocketAddr {
84
145
}
85
146
}
86
147
87
- /// Change the IP address associated with this socket address.
148
+ /// Changes the IP address associated with this socket address.
88
149
///
89
150
/// # Examples
90
151
///
@@ -123,7 +184,7 @@ impl SocketAddr {
123
184
}
124
185
}
125
186
126
- /// Change the port number associated with this socket address.
187
+ /// Changes the port number associated with this socket address.
127
188
///
128
189
/// # Examples
129
190
///
@@ -142,8 +203,13 @@ impl SocketAddr {
142
203
}
143
204
}
144
205
145
- /// Returns true if the IP in this `SocketAddr` is a valid IPv4 address,
146
- /// false if it's a valid IPv6 address.
206
+ /// Returns [`true`] if the [IP address] in this `SocketAddr` is an
207
+ /// [IPv4 address], and [`false`] otherwise.
208
+ ///
209
+ /// [`true`]: ../../std/primitive.bool.html
210
+ /// [`false`]: ../../std/primitive.bool.html
211
+ /// [IP address]: ../../std/net/enum.IpAddr.html
212
+ /// [IPv4 address]: ../../std/net/enum.IpAddr.html#variant.V4
147
213
///
148
214
/// # Examples
149
215
///
@@ -164,8 +230,13 @@ impl SocketAddr {
164
230
}
165
231
}
166
232
167
- /// Returns true if the IP in this `SocketAddr` is a valid IPv6 address,
168
- /// false if it's a valid IPv4 address.
233
+ /// Returns [`true`] if the [IP address] in this `SocketAddr` is an
234
+ /// [IPv6 address], and [`false`] otherwise.
235
+ ///
236
+ /// [`true`]: ../../std/primitive.bool.html
237
+ /// [`false`]: ../../std/primitive.bool.html
238
+ /// [IP address]: ../../std/net/enum.IpAddr.html
239
+ /// [IPv6 address]: ../../std/net/enum.IpAddr.html#variant.V6
169
240
///
170
241
/// # Examples
171
242
///
@@ -189,7 +260,9 @@ impl SocketAddr {
189
260
}
190
261
191
262
impl SocketAddrV4 {
192
- /// Creates a new socket address from the (ip, port) pair.
263
+ /// Creates a new socket address from an [IPv4 address] and a port number.
264
+ ///
265
+ /// [IPv4 address]: ../../std/net/struct.Ipv4Addr.html
193
266
///
194
267
/// # Examples
195
268
///
@@ -227,7 +300,7 @@ impl SocketAddrV4 {
227
300
}
228
301
}
229
302
230
- /// Change the IP address associated with this socket address.
303
+ /// Changes the IP address associated with this socket address.
231
304
///
232
305
/// # Examples
233
306
///
@@ -258,7 +331,7 @@ impl SocketAddrV4 {
258
331
ntoh ( self . inner . sin_port )
259
332
}
260
333
261
- /// Change the port number associated with this socket address.
334
+ /// Changes the port number associated with this socket address.
262
335
///
263
336
/// # Examples
264
337
///
@@ -276,8 +349,14 @@ impl SocketAddrV4 {
276
349
}
277
350
278
351
impl SocketAddrV6 {
279
- /// Creates a new socket address from the ip/port/flowinfo/scope_id
280
- /// components.
352
+ /// Creates a new socket address from an [IPv6 address], a 16-bit port number,
353
+ /// and the `flowinfo` and `scope_id` fields.
354
+ ///
355
+ /// For more information on the meaning and layout of the `flowinfo` and `scope_id`
356
+ /// parameters, see [IETF RFC 2553, Section 3.3].
357
+ ///
358
+ /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
359
+ /// [IPv6 address]: ../../std/net/struct.Ipv6Addr.html
281
360
///
282
361
/// # Examples
283
362
///
@@ -318,7 +397,7 @@ impl SocketAddrV6 {
318
397
}
319
398
}
320
399
321
- /// Change the IP address associated with this socket address.
400
+ /// Changes the IP address associated with this socket address.
322
401
///
323
402
/// # Examples
324
403
///
@@ -349,7 +428,7 @@ impl SocketAddrV6 {
349
428
ntoh ( self . inner . sin6_port )
350
429
}
351
430
352
- /// Change the port number associated with this socket address.
431
+ /// Changes the port number associated with this socket address.
353
432
///
354
433
/// # Examples
355
434
///
@@ -365,8 +444,17 @@ impl SocketAddrV6 {
365
444
self . inner . sin6_port = hton ( new_port) ;
366
445
}
367
446
368
- /// Returns the flow information associated with this address,
369
- /// corresponding to the `sin6_flowinfo` field in C.
447
+ /// Returns the flow information associated with this address.
448
+ ///
449
+ /// This information corresponds to the `sin6_flowinfo` field in C's `netinet/in.h`,
450
+ /// as specified in [IETF RFC 2553, Section 3.3].
451
+ /// It combines information about the flow label and the traffic class as specified
452
+ /// in [IETF RFC 2460], respectively [Section 6] and [Section 7].
453
+ ///
454
+ /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
455
+ /// [IETF RFC 2460]: https://tools.ietf.org/html/rfc2460
456
+ /// [Section 6]: https://tools.ietf.org/html/rfc2460#section-6
457
+ /// [Section 7]: https://tools.ietf.org/html/rfc2460#section-7
370
458
///
371
459
/// # Examples
372
460
///
@@ -381,7 +469,11 @@ impl SocketAddrV6 {
381
469
self . inner . sin6_flowinfo
382
470
}
383
471
384
- /// Change the flow information associated with this socket address.
472
+ /// Changes the flow information associated with this socket address.
473
+ ///
474
+ /// See the [`flowinfo`] method's documentation for more details.
475
+ ///
476
+ /// [`flowinfo`]: #method.flowinfo
385
477
///
386
478
/// # Examples
387
479
///
@@ -397,8 +489,12 @@ impl SocketAddrV6 {
397
489
self . inner . sin6_flowinfo = new_flowinfo;
398
490
}
399
491
400
- /// Returns the scope ID associated with this address,
401
- /// corresponding to the `sin6_scope_id` field in C.
492
+ /// Returns the scope ID associated with this address.
493
+ ///
494
+ /// This information corresponds to the `sin6_scope_id` field in C's `netinet/in.h`,
495
+ /// as specified in [IETF RFC 2553, Section 3.3].
496
+ ///
497
+ /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3
402
498
///
403
499
/// # Examples
404
500
///
@@ -415,6 +511,10 @@ impl SocketAddrV6 {
415
511
416
512
/// Change the scope ID associated with this socket address.
417
513
///
514
+ /// See the [`scope_id`] method's documentation for more details.
515
+ ///
516
+ /// [`scope_id`]: #method.scope_id
517
+ ///
418
518
/// # Examples
419
519
///
420
520
/// ```
@@ -559,37 +659,51 @@ impl hash::Hash for SocketAddrV6 {
559
659
}
560
660
561
661
/// A trait for objects which can be converted or resolved to one or more
562
- /// `SocketAddr` values.
662
+ /// [ `SocketAddr`] values.
563
663
///
564
664
/// This trait is used for generic address resolution when constructing network
565
665
/// objects. By default it is implemented for the following types:
566
666
///
567
- /// * `SocketAddr`, `SocketAddrV4`, `SocketAddrV6` - `to_socket_addrs` is
568
- /// identity function.
667
+ /// * [`SocketAddr`]: [`to_socket_addrs`] is the identity function.
569
668
///
570
- /// * `(IpvNAddr, u16)` - `to_socket_addrs` constructs `SocketAddr` trivially.
669
+ /// * [`SocketAddrV4`], [`SocketAddrV6`], `(`[`IpAddr`]`, `[`u16`]`)`,
670
+ /// `(`[`Ipv4Addr`]`, `[`u16`]`)`, `(`[`Ipv6Addr`]`, `[`u16`]`)`:
671
+ /// [`to_socket_addrs`] constructs a [`SocketAddr`] trivially.
571
672
///
572
- /// * `(&str, u16)` - the string should be either a string representation of an
573
- /// IP address expected by `FromStr` implementation for `IpvNAddr` or a host
673
+ /// * `(`[` &str`]`, `[` u16`]`)`: the string should be either a string representation
674
+ /// of an [`IpAddr`] address as expected by [ `FromStr`] implementation or a host
574
675
/// name.
575
676
///
576
- /// * `&str` - the string should be either a string representation of a
577
- /// `SocketAddr` as expected by its `FromStr` implementation or a string like
578
- /// `<host_name>:<port>` pair where `<port>` is a `u16` value.
677
+ /// * [ `&str`]: the string should be either a string representation of a
678
+ /// [ `SocketAddr`] as expected by its [ `FromStr`] implementation or a string like
679
+ /// `<host_name>:<port>` pair where `<port>` is a [ `u16`] value.
579
680
///
580
- /// This trait allows constructing network objects like `TcpStream` or
581
- /// `UdpSocket` easily with values of various types for the bind/connection
681
+ /// This trait allows constructing network objects like [ `TcpStream`] or
682
+ /// [ `UdpSocket`] easily with values of various types for the bind/connection
582
683
/// address. It is needed because sometimes one type is more appropriate than
583
684
/// the other: for simple uses a string like `"localhost:12345"` is much nicer
584
- /// than manual construction of the corresponding `SocketAddr`, but sometimes
585
- /// `SocketAddr` value is *the* main source of the address, and converting it to
685
+ /// than manual construction of the corresponding [ `SocketAddr`] , but sometimes
686
+ /// [ `SocketAddr`] value is *the* main source of the address, and converting it to
586
687
/// some other type (e.g. a string) just for it to be converted back to
587
- /// `SocketAddr` in constructor methods is pointless.
688
+ /// [ `SocketAddr`] in constructor methods is pointless.
588
689
///
589
690
/// Addresses returned by the operating system that are not IP addresses are
590
691
/// silently ignored.
591
692
///
592
- /// Some examples:
693
+ /// [`FromStr`]: ../../std/str/trait.FromStr.html
694
+ /// [`IpAddr`]: ../../std/net/enum.IpAddr.html
695
+ /// [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
696
+ /// [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
697
+ /// [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
698
+ /// [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
699
+ /// [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
700
+ /// [`&str`]: ../../std/primitive.str.html
701
+ /// [`TcpStream`]: ../../std/net/struct.TcpStream.html
702
+ /// [`to_socket_addrs`]: #tymethod.to_socket_addrs
703
+ /// [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
704
+ /// [`u16`]: ../../std/primitive.u16.html
705
+ ///
706
+ /// # Examples
593
707
///
594
708
/// ```no_run
595
709
/// use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};
@@ -629,10 +743,6 @@ pub trait ToSocketAddrs {
629
743
///
630
744
/// Note that this function may block the current thread while resolution is
631
745
/// performed.
632
- ///
633
- /// # Errors
634
- ///
635
- /// Any errors encountered during resolution will be returned as an `Err`.
636
746
#[ stable( feature = "rust1" , since = "1.0.0" ) ]
637
747
fn to_socket_addrs ( & self ) -> io:: Result < Self :: Iter > ;
638
748
}
0 commit comments