std/net/
socket_addr.rs

Help
1// Tests for this module
2#[cfg(all(test, not(any(target_os = "emscripten", all(target_os = "wasi", target_env = "p1")))))]
3mod tests;
4
5#[stable(feature = "rust1", since = "1.0.0")]
6pub use core::net::{SocketAddr, SocketAddrV4, SocketAddrV6};
7
8use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr};
9use crate::sys::net::LookupHost;
10use crate::{io, iter, option, slice, vec};
11
12/// A trait for objects which can be converted or resolved to one or more
13/// [`SocketAddr`] values.
14///
15/// This trait is used for generic address resolution when constructing network
16/// objects. By default it is implemented for the following types:
17///
18///  * [`SocketAddr`]: [`to_socket_addrs`] is the identity function.
19///
20///  * [`SocketAddrV4`], [`SocketAddrV6`], <code>([IpAddr], [u16])</code>,
21///    <code>([Ipv4Addr], [u16])</code>, <code>([Ipv6Addr], [u16])</code>:
22///    [`to_socket_addrs`] constructs a [`SocketAddr`] trivially.
23///
24///  * <code>(&[str], [u16])</code>: <code>&[str]</code> should be either a string representation
25///    of an [`IpAddr`] address as expected by [`FromStr`] implementation or a host
26///    name. [`u16`] is the port number.
27///
28///  * <code>&[str]</code>: the string should be either a string representation of a
29///    [`SocketAddr`] as expected by its [`FromStr`] implementation or a string like
30///    `<host_name>:<port>` pair where `<port>` is a [`u16`] value.
31///
32/// This trait allows constructing network objects like [`TcpStream`] or
33/// [`UdpSocket`] easily with values of various types for the bind/connection
34/// address. It is needed because sometimes one type is more appropriate than
35/// the other: for simple uses a string like `"localhost:12345"` is much nicer
36/// than manual construction of the corresponding [`SocketAddr`], but sometimes
37/// [`SocketAddr`] value is *the* main source of the address, and converting it to
38/// some other type (e.g., a string) just for it to be converted back to
39/// [`SocketAddr`] in constructor methods is pointless.
40///
41/// Addresses returned by the operating system that are not IP addresses are
42/// silently ignored.
43///
44/// [`FromStr`]: crate::str::FromStr "std::str::FromStr"
45/// [`TcpStream`]: crate::net::TcpStream "net::TcpStream"
46/// [`to_socket_addrs`]: ToSocketAddrs::to_socket_addrs
47/// [`UdpSocket`]: crate::net::UdpSocket "net::UdpSocket"
48///
49/// # Examples
50///
51/// Creating a [`SocketAddr`] iterator that yields one item:
52///
53/// ```
54/// use std::net::{ToSocketAddrs, SocketAddr};
55///
56/// let addr = SocketAddr::from(([127, 0, 0, 1], 443));
57/// let mut addrs_iter = addr.to_socket_addrs().unwrap();
58///
59/// assert_eq!(Some(addr), addrs_iter.next());
60/// assert!(addrs_iter.next().is_none());
61/// ```
62///
63/// Creating a [`SocketAddr`] iterator from a hostname:
64///
65/// ```no_run
66/// use std::net::{SocketAddr, ToSocketAddrs};
67///
68/// // assuming 'localhost' resolves to 127.0.0.1
69/// let mut addrs_iter = "localhost:443".to_socket_addrs().unwrap();
70/// assert_eq!(addrs_iter.next(), Some(SocketAddr::from(([127, 0, 0, 1], 443))));
71/// assert!(addrs_iter.next().is_none());
72///
73/// // assuming 'foo' does not resolve
74/// assert!("foo:443".to_socket_addrs().is_err());
75/// ```
76///
77/// Creating a [`SocketAddr`] iterator that yields multiple items:
78///
79/// ```
80/// use std::net::{SocketAddr, ToSocketAddrs};
81///
82/// let addr1 = SocketAddr::from(([0, 0, 0, 0], 80));
83/// let addr2 = SocketAddr::from(([127, 0, 0, 1], 443));
84/// let addrs = vec![addr1, addr2];
85///
86/// let mut addrs_iter = (&addrs[..]).to_socket_addrs().unwrap();
87///
88/// assert_eq!(Some(addr1), addrs_iter.next());
89/// assert_eq!(Some(addr2), addrs_iter.next());
90/// assert!(addrs_iter.next().is_none());
91/// ```
92///
93/// Attempting to create a [`SocketAddr`] iterator from an improperly formatted
94/// socket address `&str` (missing the port):
95///
96/// ```
97/// use std::io;
98/// use std::net::ToSocketAddrs;
99///
100/// let err = "127.0.0.1".to_socket_addrs().unwrap_err();
101/// assert_eq!(err.kind(), io::ErrorKind::InvalidInput);
102/// ```
103///
104/// [`TcpStream::connect`] is an example of an function that utilizes
105/// `ToSocketAddrs` as a trait bound on its parameter in order to accept
106/// different types:
107///
108/// ```no_run
109/// use std::net::{TcpStream, Ipv4Addr};
110///
111/// let stream = TcpStream::connect(("127.0.0.1", 443));
112/// // or
113/// let stream = TcpStream::connect("127.0.0.1:443");
114/// // or
115/// let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443));
116/// ```
117///
118/// [`TcpStream::connect`]: crate::net::TcpStream::connect
119#[stable(feature = "rust1", since = "1.0.0")]
120pub trait ToSocketAddrs {
121    /// Returned iterator over socket addresses which this type may correspond
122    /// to.
123    #[stable(feature = "rust1", since = "1.0.0")]
124    type Iter: Iterator<Item = SocketAddr>;
125
126    /// Converts this object to an iterator of resolved [`SocketAddr`]s.
127    ///
128    /// The returned iterator might not actually yield any values depending on the
129    /// outcome of any resolution performed.
130    ///
131    /// Note that this function may block the current thread while resolution is
132    /// performed.
133    #[stable(feature = "rust1", since = "1.0.0")]
134    fn to_socket_addrs(&self) -> io::Result<Self::Iter>;
135}
136
137#[stable(feature = "rust1", since = "1.0.0")]
138impl ToSocketAddrs for SocketAddr {
139    type Iter = option::IntoIter<SocketAddr>;
140    fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
141        Ok(Some(*self).into_iter())
142    }
143}
144
145#[stable(feature = "rust1", since = "1.0.0")]
146impl ToSocketAddrs for SocketAddrV4 {
147    type Iter = option::IntoIter<SocketAddr>;
148    fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
149        SocketAddr::V4(*self).to_socket_addrs()
150    }
151}
152
153#[stable(feature = "rust1", since = "1.0.0")]
154impl ToSocketAddrs for SocketAddrV6 {
155    type Iter = option::IntoIter<SocketAddr>;
156    fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
157        SocketAddr::V6(*self).to_socket_addrs()
158    }
159}
160
161#[stable(feature = "rust1", since = "1.0.0")]
162impl ToSocketAddrs for (IpAddr, u16) {
163    type Iter = option::IntoIter<SocketAddr>;
164    fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
165        let (ip, port) = *self;
166        match ip {
167            IpAddr::V4(ref a) => (*a, port).to_socket_addrs(),
168            IpAddr::V6(ref a) => (*a, port).to_socket_addrs(),
169        }
170    }
171}
172
173#[stable(feature = "rust1", since = "1.0.0")]
174impl ToSocketAddrs for (Ipv4Addr, u16) {
175    type Iter = option::IntoIter<SocketAddr>;
176    fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
177        let (ip, port) = *self;
178        SocketAddrV4::new(ip, port).to_socket_addrs()
179    }
180}
181
182#[stable(feature = "rust1", since = "1.0.0")]
183impl ToSocketAddrs for (Ipv6Addr, u16) {
184    type Iter = option::IntoIter<SocketAddr>;
185    fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
186        let (ip, port) = *self;
187        SocketAddrV6::new(ip, port, 0, 0).to_socket_addrs()
188    }
189}
190
191fn resolve_socket_addr(lh: LookupHost) -> io::Result<vec::IntoIter<SocketAddr>> {
192    let p = lh.port();
193    let v: Vec<_> = lh
194        .map(|mut a| {
195            a.set_port(p);
196            a
197        })
198        .collect();
199    Ok(v.into_iter())
200}
201
202#[stable(feature = "rust1", since = "1.0.0")]
203impl ToSocketAddrs for (&str, u16) {
204    type Iter = vec::IntoIter<SocketAddr>;
205    fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
206        let (host, port) = *self;
207
208        // try to parse the host as a regular IP address first
209        if let Ok(addr) = host.parse::<Ipv4Addr>() {
210            let addr = SocketAddrV4::new(addr, port);
211            return Ok(vec![SocketAddr::V4(addr)].into_iter());
212        }
213        if let Ok(addr) = host.parse::<Ipv6Addr>() {
214            let addr = SocketAddrV6::new(addr, port, 0, 0);
215            return Ok(vec![SocketAddr::V6(addr)].into_iter());
216        }
217
218        resolve_socket_addr((host, port).try_into()?)
219    }
220}
221
222#[stable(feature = "string_u16_to_socket_addrs", since = "1.46.0")]
223impl ToSocketAddrs for (String, u16) {
224    type Iter = vec::IntoIter<SocketAddr>;
225    fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
226        (&*self.0, self.1).to_socket_addrs()
227    }
228}
229
230// accepts strings like 'localhost:12345'
231#[stable(feature = "rust1", since = "1.0.0")]
232impl ToSocketAddrs for str {
233    type Iter = vec::IntoIter<SocketAddr>;
234    fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
235        // try to parse as a regular SocketAddr first
236        if let Ok(addr) = self.parse() {
237            return Ok(vec![addr].into_iter());
238        }
239
240        resolve_socket_addr(self.try_into()?)
241    }
242}
243
244#[stable(feature = "slice_to_socket_addrs", since = "1.8.0")]
245impl<'a> ToSocketAddrs for &'a [SocketAddr] {
246    type Iter = iter::Cloned<slice::Iter<'a, SocketAddr>>;
247
248    fn to_socket_addrs(&self) -> io::Result<Self::Iter> {
249        Ok(self.iter().cloned())
250    }
251}
252
253#[stable(feature = "rust1", since = "1.0.0")]
254impl<T: ToSocketAddrs + ?Sized> ToSocketAddrs for &T {
255    type Iter = T::Iter;
256    fn to_socket_addrs(&self) -> io::Result<T::Iter> {
257        (**self).to_socket_addrs()
258    }
259}
260
261#[stable(feature = "string_to_socket_addrs", since = "1.16.0")]
262impl ToSocketAddrs for String {
263    type Iter = vec::IntoIter<SocketAddr>;
264    fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
265        (&**self).to_socket_addrs()
266    }
267}
std/net/socket_addr.rs

std/net/
socket_addr.rs
