src/libstd/net/addr.rs

   1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use fmt;
  12 use hash;
  13 use io;
  14 use mem;
  15 use net::{lookup_host, ntoh, hton, IpAddr, Ipv4Addr, Ipv6Addr};
  16 use option;
  17 use sys::net::netc as c;
  18 use sys_common::{FromInner, AsInner, IntoInner};
  19 use vec;
  20 use iter;
  21 use slice;
  22
  23 /// Representation of a socket address for networking applications.
  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.
  28 #[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)]
  29 #[stable(feature = "rust1", since = "1.0.0")]
  30 pub enum SocketAddr {
  31     /// An IPv4 socket address which is a (ip, port) combination.
  32     #[stable(feature = "rust1", since = "1.0.0")]
  33     V4(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV4),
  34     /// An IPv6 socket address.
  35     #[stable(feature = "rust1", since = "1.0.0")]
  36     V6(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV6),
  37 }
  38
  39 /// An IPv4 socket address which is a (ip, port) combination.
  40 #[derive(Copy)]
  41 #[stable(feature = "rust1", since = "1.0.0")]
  42 pub struct SocketAddrV4 { inner: c::sockaddr_in }
  43
  44 /// An IPv6 socket address.
  45 #[derive(Copy)]
  46 #[stable(feature = "rust1", since = "1.0.0")]
  47 pub struct SocketAddrV6 { inner: c::sockaddr_in6 }
  48
  49 impl SocketAddr {
  50     /// Creates a new socket address from the (ip, port) pair.
  51     ///
  52     /// # Examples
  53     ///
  54     /// ```
  55     /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
  56     ///
  57     /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
  58     /// assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)));
  59     /// assert_eq!(socket.port(), 8080);
  60     /// ```
  61     #[stable(feature = "ip_addr", since = "1.7.0")]
  62     pub fn new(ip: IpAddr, port: u16) -> SocketAddr {
  63         match ip {
  64             IpAddr::V4(a) => SocketAddr::V4(SocketAddrV4::new(a, port)),
  65             IpAddr::V6(a) => SocketAddr::V6(SocketAddrV6::new(a, port, 0, 0)),
  66         }
  67     }
  68
  69     /// Returns the IP address associated with this socket address.
  70     ///
  71     /// # Examples
  72     ///
  73     /// ```
  74     /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
  75     ///
  76     /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
  77     /// assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)));
  78     /// ```
  79     #[stable(feature = "ip_addr", since = "1.7.0")]
  80     pub fn ip(&self) -> IpAddr {
  81         match *self {
  82             SocketAddr::V4(ref a) => IpAddr::V4(*a.ip()),
  83             SocketAddr::V6(ref a) => IpAddr::V6(*a.ip()),
  84         }
  85     }
  86
  87     /// Change the IP address associated with this socket address.
  88     ///
  89     /// # Examples
  90     ///
  91     /// ```
  92     /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
  93     ///
  94     /// let mut socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
  95     /// socket.set_ip(IpAddr::V4(Ipv4Addr::new(10, 10, 0, 1)));
  96     /// assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(10, 10, 0, 1)));
  97     /// ```
  98     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
  99     pub fn set_ip(&mut self, new_ip: IpAddr) {
 100         // `match (*self, new_ip)` would have us mutate a copy of self only to throw it away.
 101         match (self, new_ip) {
 102             (&mut SocketAddr::V4(ref mut a), IpAddr::V4(new_ip)) => a.set_ip(new_ip),
 103             (&mut SocketAddr::V6(ref mut a), IpAddr::V6(new_ip)) => a.set_ip(new_ip),
 104             (self_, new_ip) => *self_ = Self::new(new_ip, self_.port()),
 105         }
 106     }
 107
 108     /// Returns the port number associated with this socket address.
 109     ///
 110     /// # Examples
 111     ///
 112     /// ```
 113     /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 114     ///
 115     /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
 116     /// assert_eq!(socket.port(), 8080);
 117     /// ```
 118     #[stable(feature = "rust1", since = "1.0.0")]
 119     pub fn port(&self) -> u16 {
 120         match *self {
 121             SocketAddr::V4(ref a) => a.port(),
 122             SocketAddr::V6(ref a) => a.port(),
 123         }
 124     }
 125
 126     /// Change the port number associated with this socket address.
 127     ///
 128     /// # Examples
 129     ///
 130     /// ```
 131     /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 132     ///
 133     /// let mut socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
 134     /// socket.set_port(1025);
 135     /// assert_eq!(socket.port(), 1025);
 136     /// ```
 137     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 138     pub fn set_port(&mut self, new_port: u16) {
 139         match *self {
 140             SocketAddr::V4(ref mut a) => a.set_port(new_port),
 141             SocketAddr::V6(ref mut a) => a.set_port(new_port),
 142         }
 143     }
 144
 145     /// Returns true if the IP in this `SocketAddr` is a valid IPv4 address,
 146     /// false if it's a valid IPv6 address.
 147     ///
 148     /// # Examples
 149     ///
 150     /// ```
 151     /// use std::net::{IpAddr, Ipv4Addr, SocketAddr};
 152     ///
 153     /// fn main() {
 154     ///     let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080);
 155     ///     assert_eq!(socket.is_ipv4(), true);
 156     ///     assert_eq!(socket.is_ipv6(), false);
 157     /// }
 158     /// ```
 159     #[stable(feature = "sockaddr_checker", since = "1.16.0")]
 160     pub fn is_ipv4(&self) -> bool {
 161         match *self {
 162             SocketAddr::V4(_) => true,
 163             SocketAddr::V6(_) => false,
 164         }
 165     }
 166
 167     /// Returns true if the IP in this `SocketAddr` is a valid IPv6 address,
 168     /// false if it's a valid IPv4 address.
 169     ///
 170     /// # Examples
 171     ///
 172     /// ```
 173     /// use std::net::{IpAddr, Ipv6Addr, SocketAddr};
 174     ///
 175     /// fn main() {
 176     ///     let socket = SocketAddr::new(
 177     ///                      IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 65535, 0, 1)), 8080);
 178     ///     assert_eq!(socket.is_ipv4(), false);
 179     ///     assert_eq!(socket.is_ipv6(), true);
 180     /// }
 181     /// ```
 182     #[stable(feature = "sockaddr_checker", since = "1.16.0")]
 183     pub fn is_ipv6(&self) -> bool {
 184         match *self {
 185             SocketAddr::V4(_) => false,
 186             SocketAddr::V6(_) => true,
 187         }
 188     }
 189 }
 190
 191 impl SocketAddrV4 {
 192     /// Creates a new socket address from the (ip, port) pair.
 193     ///
 194     /// # Examples
 195     ///
 196     /// ```
 197     /// use std::net::{SocketAddrV4, Ipv4Addr};
 198     ///
 199     /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
 200     /// ```
 201     #[stable(feature = "rust1", since = "1.0.0")]
 202     pub fn new(ip: Ipv4Addr, port: u16) -> SocketAddrV4 {
 203         SocketAddrV4 {
 204             inner: c::sockaddr_in {
 205                 sin_family: c::AF_INET as c::sa_family_t,
 206                 sin_port: hton(port),
 207                 sin_addr: *ip.as_inner(),
 208                 .. unsafe { mem::zeroed() }
 209             },
 210         }
 211     }
 212
 213     /// Returns the IP address associated with this socket address.
 214     ///
 215     /// # Examples
 216     ///
 217     /// ```
 218     /// use std::net::{SocketAddrV4, Ipv4Addr};
 219     ///
 220     /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
 221     /// assert_eq!(socket.ip(), &Ipv4Addr::new(127, 0, 0, 1));
 222     /// ```
 223     #[stable(feature = "rust1", since = "1.0.0")]
 224     pub fn ip(&self) -> &Ipv4Addr {
 225         unsafe {
 226             &*(&self.inner.sin_addr as *const c::in_addr as *const Ipv4Addr)
 227         }
 228     }
 229
 230     /// Change the IP address associated with this socket address.
 231     ///
 232     /// # Examples
 233     ///
 234     /// ```
 235     /// use std::net::{SocketAddrV4, Ipv4Addr};
 236     ///
 237     /// let mut socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
 238     /// socket.set_ip(Ipv4Addr::new(192, 168, 0, 1));
 239     /// assert_eq!(socket.ip(), &Ipv4Addr::new(192, 168, 0, 1));
 240     /// ```
 241     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 242     pub fn set_ip(&mut self, new_ip: Ipv4Addr) {
 243         self.inner.sin_addr = *new_ip.as_inner()
 244     }
 245
 246     /// Returns the port number associated with this socket address.
 247     ///
 248     /// # Examples
 249     ///
 250     /// ```
 251     /// use std::net::{SocketAddrV4, Ipv4Addr};
 252     ///
 253     /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
 254     /// assert_eq!(socket.port(), 8080);
 255     /// ```
 256     #[stable(feature = "rust1", since = "1.0.0")]
 257     pub fn port(&self) -> u16 {
 258         ntoh(self.inner.sin_port)
 259     }
 260
 261     /// Change the port number associated with this socket address.
 262     ///
 263     /// # Examples
 264     ///
 265     /// ```
 266     /// use std::net::{SocketAddrV4, Ipv4Addr};
 267     ///
 268     /// let mut socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080);
 269     /// socket.set_port(4242);
 270     /// assert_eq!(socket.port(), 4242);
 271     /// ```
 272     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 273     pub fn set_port(&mut self, new_port: u16) {
 274         self.inner.sin_port = hton(new_port);
 275     }
 276 }
 277
 278 impl SocketAddrV6 {
 279     /// Creates a new socket address from the ip/port/flowinfo/scope_id
 280     /// components.
 281     ///
 282     /// # Examples
 283     ///
 284     /// ```
 285     /// use std::net::{SocketAddrV6, Ipv6Addr};
 286     ///
 287     /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
 288     /// ```
 289     #[stable(feature = "rust1", since = "1.0.0")]
 290     pub fn new(ip: Ipv6Addr, port: u16, flowinfo: u32, scope_id: u32)
 291                -> SocketAddrV6 {
 292         SocketAddrV6 {
 293             inner: c::sockaddr_in6 {
 294                 sin6_family: c::AF_INET6 as c::sa_family_t,
 295                 sin6_port: hton(port),
 296                 sin6_addr: *ip.as_inner(),
 297                 sin6_flowinfo: flowinfo,
 298                 sin6_scope_id: scope_id,
 299                 .. unsafe { mem::zeroed() }
 300             },
 301         }
 302     }
 303
 304     /// Returns the IP address associated with this socket address.
 305     ///
 306     /// # Examples
 307     ///
 308     /// ```
 309     /// use std::net::{SocketAddrV6, Ipv6Addr};
 310     ///
 311     /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
 312     /// assert_eq!(socket.ip(), &Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
 313     /// ```
 314     #[stable(feature = "rust1", since = "1.0.0")]
 315     pub fn ip(&self) -> &Ipv6Addr {
 316         unsafe {
 317             &*(&self.inner.sin6_addr as *const c::in6_addr as *const Ipv6Addr)
 318         }
 319     }
 320
 321     /// Change the IP address associated with this socket address.
 322     ///
 323     /// # Examples
 324     ///
 325     /// ```
 326     /// use std::net::{SocketAddrV6, Ipv6Addr};
 327     ///
 328     /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
 329     /// socket.set_ip(Ipv6Addr::new(76, 45, 0, 0, 0, 0, 0, 0));
 330     /// assert_eq!(socket.ip(), &Ipv6Addr::new(76, 45, 0, 0, 0, 0, 0, 0));
 331     /// ```
 332     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 333     pub fn set_ip(&mut self, new_ip: Ipv6Addr) {
 334         self.inner.sin6_addr = *new_ip.as_inner()
 335     }
 336
 337     /// Returns the port number associated with this socket address.
 338     ///
 339     /// # Examples
 340     ///
 341     /// ```
 342     /// use std::net::{SocketAddrV6, Ipv6Addr};
 343     ///
 344     /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
 345     /// assert_eq!(socket.port(), 8080);
 346     /// ```
 347     #[stable(feature = "rust1", since = "1.0.0")]
 348     pub fn port(&self) -> u16 {
 349         ntoh(self.inner.sin6_port)
 350     }
 351
 352     /// Change the port number associated with this socket address.
 353     ///
 354     /// # Examples
 355     ///
 356     /// ```
 357     /// use std::net::{SocketAddrV6, Ipv6Addr};
 358     ///
 359     /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0);
 360     /// socket.set_port(4242);
 361     /// assert_eq!(socket.port(), 4242);
 362     /// ```
 363     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 364     pub fn set_port(&mut self, new_port: u16) {
 365         self.inner.sin6_port = hton(new_port);
 366     }
 367
 368     /// Returns the flow information associated with this address,
 369     /// corresponding to the `sin6_flowinfo` field in C.
 370     ///
 371     /// # Examples
 372     ///
 373     /// ```
 374     /// use std::net::{SocketAddrV6, Ipv6Addr};
 375     ///
 376     /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 10, 0);
 377     /// assert_eq!(socket.flowinfo(), 10);
 378     /// ```
 379     #[stable(feature = "rust1", since = "1.0.0")]
 380     pub fn flowinfo(&self) -> u32 {
 381         self.inner.sin6_flowinfo
 382     }
 383
 384     /// Change the flow information associated with this socket address.
 385     ///
 386     /// # Examples
 387     ///
 388     /// ```
 389     /// use std::net::{SocketAddrV6, Ipv6Addr};
 390     ///
 391     /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 10, 0);
 392     /// socket.set_flowinfo(56);
 393     /// assert_eq!(socket.flowinfo(), 56);
 394     /// ```
 395     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 396     pub fn set_flowinfo(&mut self, new_flowinfo: u32) {
 397         self.inner.sin6_flowinfo = new_flowinfo;
 398     }
 399
 400     /// Returns the scope ID associated with this address,
 401     /// corresponding to the `sin6_scope_id` field in C.
 402     ///
 403     /// # Examples
 404     ///
 405     /// ```
 406     /// use std::net::{SocketAddrV6, Ipv6Addr};
 407     ///
 408     /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 78);
 409     /// assert_eq!(socket.scope_id(), 78);
 410     /// ```
 411     #[stable(feature = "rust1", since = "1.0.0")]
 412     pub fn scope_id(&self) -> u32 {
 413         self.inner.sin6_scope_id
 414     }
 415
 416     /// Change the scope ID associated with this socket address.
 417     ///
 418     /// # Examples
 419     ///
 420     /// ```
 421     /// use std::net::{SocketAddrV6, Ipv6Addr};
 422     ///
 423     /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 78);
 424     /// socket.set_scope_id(42);
 425     /// assert_eq!(socket.scope_id(), 42);
 426     /// ```
 427     #[stable(feature = "sockaddr_setters", since = "1.9.0")]
 428     pub fn set_scope_id(&mut self, new_scope_id: u32) {
 429         self.inner.sin6_scope_id = new_scope_id;
 430     }
 431 }
 432
 433 impl FromInner<c::sockaddr_in> for SocketAddrV4 {
 434     fn from_inner(addr: c::sockaddr_in) -> SocketAddrV4 {
 435         SocketAddrV4 { inner: addr }
 436     }
 437 }
 438
 439 impl FromInner<c::sockaddr_in6> for SocketAddrV6 {
 440     fn from_inner(addr: c::sockaddr_in6) -> SocketAddrV6 {
 441         SocketAddrV6 { inner: addr }
 442     }
 443 }
 444
 445 #[stable(feature = "ip_from_ip", since = "1.16.0")]
 446 impl From<SocketAddrV4> for SocketAddr {
 447     fn from(sock4: SocketAddrV4) -> SocketAddr {
 448         SocketAddr::V4(sock4)
 449     }
 450 }
 451
 452 #[stable(feature = "ip_from_ip", since = "1.16.0")]
 453 impl From<SocketAddrV6> for SocketAddr {
 454     fn from(sock6: SocketAddrV6) -> SocketAddr {
 455         SocketAddr::V6(sock6)
 456     }
 457 }
 458
 459 impl<'a> IntoInner<(*const c::sockaddr, c::socklen_t)> for &'a SocketAddr {
 460     fn into_inner(self) -> (*const c::sockaddr, c::socklen_t) {
 461         match *self {
 462             SocketAddr::V4(ref a) => {
 463                 (a as *const _ as *const _, mem::size_of_val(a) as c::socklen_t)
 464             }
 465             SocketAddr::V6(ref a) => {
 466                 (a as *const _ as *const _, mem::size_of_val(a) as c::socklen_t)
 467             }
 468         }
 469     }
 470 }
 471
 472 #[stable(feature = "rust1", since = "1.0.0")]
 473 impl fmt::Display for SocketAddr {
 474     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 475         match *self {
 476             SocketAddr::V4(ref a) => a.fmt(f),
 477             SocketAddr::V6(ref a) => a.fmt(f),
 478         }
 479     }
 480 }
 481
 482 #[stable(feature = "rust1", since = "1.0.0")]
 483 impl fmt::Display for SocketAddrV4 {
 484     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 485         write!(f, "{}:{}", self.ip(), self.port())
 486     }
 487 }
 488
 489 #[stable(feature = "rust1", since = "1.0.0")]
 490 impl fmt::Debug for SocketAddrV4 {
 491     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 492         fmt::Display::fmt(self, fmt)
 493     }
 494 }
 495
 496 #[stable(feature = "rust1", since = "1.0.0")]
 497 impl fmt::Display for SocketAddrV6 {
 498     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 499         write!(f, "[{}]:{}", self.ip(), self.port())
 500     }
 501 }
 502
 503 #[stable(feature = "rust1", since = "1.0.0")]
 504 impl fmt::Debug for SocketAddrV6 {
 505     fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
 506         fmt::Display::fmt(self, fmt)
 507     }
 508 }
 509
 510 #[stable(feature = "rust1", since = "1.0.0")]
 511 impl Clone for SocketAddrV4 {
 512     fn clone(&self) -> SocketAddrV4 { *self }
 513 }
 514 #[stable(feature = "rust1", since = "1.0.0")]
 515 impl Clone for SocketAddrV6 {
 516     fn clone(&self) -> SocketAddrV6 { *self }
 517 }
 518
 519 #[stable(feature = "rust1", since = "1.0.0")]
 520 impl PartialEq for SocketAddrV4 {
 521     fn eq(&self, other: &SocketAddrV4) -> bool {
 522         self.inner.sin_port == other.inner.sin_port &&
 523             self.inner.sin_addr.s_addr == other.inner.sin_addr.s_addr
 524     }
 525 }
 526 #[stable(feature = "rust1", since = "1.0.0")]
 527 impl PartialEq for SocketAddrV6 {
 528     fn eq(&self, other: &SocketAddrV6) -> bool {
 529         self.inner.sin6_port == other.inner.sin6_port &&
 530             self.inner.sin6_addr.s6_addr == other.inner.sin6_addr.s6_addr &&
 531             self.inner.sin6_flowinfo == other.inner.sin6_flowinfo &&
 532             self.inner.sin6_scope_id == other.inner.sin6_scope_id
 533     }
 534 }
 535 #[stable(feature = "rust1", since = "1.0.0")]
 536 impl Eq for SocketAddrV4 {}
 537 #[stable(feature = "rust1", since = "1.0.0")]
 538 impl Eq for SocketAddrV6 {}
 539
 540 #[stable(feature = "rust1", since = "1.0.0")]
 541 impl hash::Hash for SocketAddrV4 {
 542     fn hash<H: hash::Hasher>(&self, s: &mut H) {
 543         (self.inner.sin_port, self.inner.sin_addr.s_addr).hash(s)
 544     }
 545 }
 546 #[stable(feature = "rust1", since = "1.0.0")]
 547 impl hash::Hash for SocketAddrV6 {
 548     fn hash<H: hash::Hasher>(&self, s: &mut H) {
 549         (self.inner.sin6_port, &self.inner.sin6_addr.s6_addr,
 550          self.inner.sin6_flowinfo, self.inner.sin6_scope_id).hash(s)
 551     }
 552 }
 553
 554 /// A trait for objects which can be converted or resolved to one or more
 555 /// `SocketAddr` values.
 556 ///
 557 /// This trait is used for generic address resolution when constructing network
 558 /// objects.  By default it is implemented for the following types:
 559 ///
 560 ///  * `SocketAddr`, `SocketAddrV4`, `SocketAddrV6` - `to_socket_addrs` is
 561 ///    identity function.
 562 ///
 563 ///  * `(IpvNAddr, u16)` - `to_socket_addrs` constructs `SocketAddr` trivially.
 564 ///
 565 ///  * `(&str, u16)` - the string should be either a string representation of an
 566 ///    IP address expected by `FromStr` implementation for `IpvNAddr` or a host
 567 ///    name.
 568 ///
 569 ///  * `&str` - the string should be either a string representation of a
 570 ///    `SocketAddr` as expected by its `FromStr` implementation or a string like
 571 ///    `<host_name>:<port>` pair where `<port>` is a `u16` value.
 572 ///
 573 /// This trait allows constructing network objects like `TcpStream` or
 574 /// `UdpSocket` easily with values of various types for the bind/connection
 575 /// address. It is needed because sometimes one type is more appropriate than
 576 /// the other: for simple uses a string like `"localhost:12345"` is much nicer
 577 /// than manual construction of the corresponding `SocketAddr`, but sometimes
 578 /// `SocketAddr` value is *the* main source of the address, and converting it to
 579 /// some other type (e.g. a string) just for it to be converted back to
 580 /// `SocketAddr` in constructor methods is pointless.
 581 ///
 582 /// Addresses returned by the operating system that are not IP addresses are
 583 /// silently ignored.
 584 ///
 585 /// Some examples:
 586 ///
 587 /// ```no_run
 588 /// use std::net::{SocketAddrV4, TcpStream, UdpSocket, TcpListener, Ipv4Addr};
 589 ///
 590 /// fn main() {
 591 ///     let ip = Ipv4Addr::new(127, 0, 0, 1);
 592 ///     let port = 12345;
 593 ///
 594 ///     // The following lines are equivalent modulo possible "localhost" name
 595 ///     // resolution differences
 596 ///     let tcp_s = TcpStream::connect(SocketAddrV4::new(ip, port));
 597 ///     let tcp_s = TcpStream::connect((ip, port));
 598 ///     let tcp_s = TcpStream::connect(("127.0.0.1", port));
 599 ///     let tcp_s = TcpStream::connect(("localhost", port));
 600 ///     let tcp_s = TcpStream::connect("127.0.0.1:12345");
 601 ///     let tcp_s = TcpStream::connect("localhost:12345");
 602 ///
 603 ///     // TcpListener::bind(), UdpSocket::bind() and UdpSocket::send_to()
 604 ///     // behave similarly
 605 ///     let tcp_l = TcpListener::bind("localhost:12345");
 606 ///
 607 ///     let mut udp_s = UdpSocket::bind(("127.0.0.1", port)).unwrap();
 608 ///     udp_s.send_to(&[7], (ip, 23451)).unwrap();
 609 /// }
 610 /// ```
 611 #[stable(feature = "rust1", since = "1.0.0")]
 612 pub trait ToSocketAddrs {
 613     /// Returned iterator over socket addresses which this type may correspond
 614     /// to.
 615     #[stable(feature = "rust1", since = "1.0.0")]
 616     type Iter: Iterator<Item=SocketAddr>;
 617
 618     /// Converts this object to an iterator of resolved `SocketAddr`s.
 619     ///
 620     /// The returned iterator may not actually yield any values depending on the
 621     /// outcome of any resolution performed.
 622     ///
 623     /// Note that this function may block the current thread while resolution is
 624     /// performed.
 625     ///
 626     /// # Errors
 627     ///
 628     /// Any errors encountered during resolution will be returned as an `Err`.
 629     #[stable(feature = "rust1", since = "1.0.0")]
 630     fn to_socket_addrs(&self) -> io::Result<Self::Iter>;
 631 }
 632
 633 #[stable(feature = "rust1", since = "1.0.0")]
 634 impl ToSocketAddrs for SocketAddr {
 635     type Iter = option::IntoIter<SocketAddr>;
 636     fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
 637         Ok(Some(*self).into_iter())
 638     }
 639 }
 640
 641 #[stable(feature = "rust1", since = "1.0.0")]
 642 impl ToSocketAddrs for SocketAddrV4 {
 643     type Iter = option::IntoIter<SocketAddr>;
 644     fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
 645         SocketAddr::V4(*self).to_socket_addrs()
 646     }
 647 }
 648
 649 #[stable(feature = "rust1", since = "1.0.0")]
 650 impl ToSocketAddrs for SocketAddrV6 {
 651     type Iter = option::IntoIter<SocketAddr>;
 652     fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
 653         SocketAddr::V6(*self).to_socket_addrs()
 654     }
 655 }
 656
 657 #[stable(feature = "rust1", since = "1.0.0")]
 658 impl ToSocketAddrs for (IpAddr, u16) {
 659     type Iter = option::IntoIter<SocketAddr>;
 660     fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
 661         let (ip, port) = *self;
 662         match ip {
 663             IpAddr::V4(ref a) => (*a, port).to_socket_addrs(),
 664             IpAddr::V6(ref a) => (*a, port).to_socket_addrs(),
 665         }
 666     }
 667 }
 668
 669 #[stable(feature = "rust1", since = "1.0.0")]
 670 impl ToSocketAddrs for (Ipv4Addr, u16) {
 671     type Iter = option::IntoIter<SocketAddr>;
 672     fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
 673         let (ip, port) = *self;
 674         SocketAddrV4::new(ip, port).to_socket_addrs()
 675     }
 676 }
 677
 678 #[stable(feature = "rust1", since = "1.0.0")]
 679 impl ToSocketAddrs for (Ipv6Addr, u16) {
 680     type Iter = option::IntoIter<SocketAddr>;
 681     fn to_socket_addrs(&self) -> io::Result<option::IntoIter<SocketAddr>> {
 682         let (ip, port) = *self;
 683         SocketAddrV6::new(ip, port, 0, 0).to_socket_addrs()
 684     }
 685 }
 686
 687 fn resolve_socket_addr(s: &str, p: u16) -> io::Result<vec::IntoIter<SocketAddr>> {
 688     let ips = lookup_host(s)?;
 689     let v: Vec<_> = ips.map(|mut a| { a.set_port(p); a }).collect();
 690     Ok(v.into_iter())
 691 }
 692
 693 #[stable(feature = "rust1", since = "1.0.0")]
 694 impl<'a> ToSocketAddrs for (&'a str, u16) {
 695     type Iter = vec::IntoIter<SocketAddr>;
 696     fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
 697         let (host, port) = *self;
 698
 699         // try to parse the host as a regular IP address first
 700         if let Ok(addr) = host.parse::<Ipv4Addr>() {
 701             let addr = SocketAddrV4::new(addr, port);
 702             return Ok(vec![SocketAddr::V4(addr)].into_iter())
 703         }
 704         if let Ok(addr) = host.parse::<Ipv6Addr>() {
 705             let addr = SocketAddrV6::new(addr, port, 0, 0);
 706             return Ok(vec![SocketAddr::V6(addr)].into_iter())
 707         }
 708
 709         resolve_socket_addr(host, port)
 710     }
 711 }
 712
 713 // accepts strings like 'localhost:12345'
 714 #[stable(feature = "rust1", since = "1.0.0")]
 715 impl ToSocketAddrs for str {
 716     type Iter = vec::IntoIter<SocketAddr>;
 717     fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
 718         // try to parse as a regular SocketAddr first
 719         if let Some(addr) = self.parse().ok() {
 720             return Ok(vec![addr].into_iter());
 721         }
 722
 723         macro_rules! try_opt {
 724             ($e:expr, $msg:expr) => (
 725                 match $e {
 726                     Some(r) => r,
 727                     None => return Err(io::Error::new(io::ErrorKind::InvalidInput,
 728                                                       $msg)),
 729                 }
 730             )
 731         }
 732
 733         // split the string by ':' and convert the second part to u16
 734         let mut parts_iter = self.rsplitn(2, ':');
 735         let port_str = try_opt!(parts_iter.next(), "invalid socket address");
 736         let host = try_opt!(parts_iter.next(), "invalid socket address");
 737         let port: u16 = try_opt!(port_str.parse().ok(), "invalid port value");
 738         resolve_socket_addr(host, port)
 739     }
 740 }
 741
 742 #[stable(feature = "slice_to_socket_addrs", since = "1.8.0")]
 743 impl<'a> ToSocketAddrs for &'a [SocketAddr] {
 744     type Iter = iter::Cloned<slice::Iter<'a, SocketAddr>>;
 745
 746     fn to_socket_addrs(&self) -> io::Result<Self::Iter> {
 747         Ok(self.iter().cloned())
 748     }
 749 }
 750
 751 #[stable(feature = "rust1", since = "1.0.0")]
 752 impl<'a, T: ToSocketAddrs + ?Sized> ToSocketAddrs for &'a T {
 753     type Iter = T::Iter;
 754     fn to_socket_addrs(&self) -> io::Result<T::Iter> {
 755         (**self).to_socket_addrs()
 756     }
 757 }
 758
 759 #[stable(feature = "string_to_socket_addrs", since = "1.16.0")]
 760 impl ToSocketAddrs for String {
 761     type Iter = vec::IntoIter<SocketAddr>;
 762     fn to_socket_addrs(&self) -> io::Result<vec::IntoIter<SocketAddr>> {
 763         (&**self).to_socket_addrs()
 764     }
 765 }
 766
 767 #[cfg(all(test, not(target_os = "emscripten")))]
 768 mod tests {
 769     use net::*;
 770     use net::test::{tsa, sa6, sa4};
 771
 772     #[test]
 773     fn to_socket_addr_ipaddr_u16() {
 774         let a = Ipv4Addr::new(77, 88, 21, 11);
 775         let p = 12345;
 776         let e = SocketAddr::V4(SocketAddrV4::new(a, p));
 777         assert_eq!(Ok(vec![e]), tsa((a, p)));
 778     }
 779
 780     #[test]
 781     fn to_socket_addr_str_u16() {
 782         let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 24352);
 783         assert_eq!(Ok(vec![a]), tsa(("77.88.21.11", 24352)));
 784
 785         let a = sa6(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53);
 786         assert_eq!(Ok(vec![a]), tsa(("2a02:6b8:0:1::1", 53)));
 787
 788         let a = sa4(Ipv4Addr::new(127, 0, 0, 1), 23924);
 789         assert!(tsa(("localhost", 23924)).unwrap().contains(&a));
 790     }
 791
 792     #[test]
 793     fn to_socket_addr_str() {
 794         let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 24352);
 795         assert_eq!(Ok(vec![a]), tsa("77.88.21.11:24352"));
 796
 797         let a = sa6(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53);
 798         assert_eq!(Ok(vec![a]), tsa("[2a02:6b8:0:1::1]:53"));
 799
 800         let a = sa4(Ipv4Addr::new(127, 0, 0, 1), 23924);
 801         assert!(tsa("localhost:23924").unwrap().contains(&a));
 802     }
 803
 804     #[test]
 805     fn to_socket_addr_string() {
 806         let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 24352);
 807         assert_eq!(Ok(vec![a]), tsa(&*format!("{}:{}", "77.88.21.11", "24352")));
 808         assert_eq!(Ok(vec![a]), tsa(&format!("{}:{}", "77.88.21.11", "24352")));
 809         assert_eq!(Ok(vec![a]), tsa(format!("{}:{}", "77.88.21.11", "24352")));
 810
 811         let s = format!("{}:{}", "77.88.21.11", "24352");
 812         assert_eq!(Ok(vec![a]), tsa(s));
 813         // s has been moved into the tsa call
 814     }
 815
 816     // FIXME: figure out why this fails on openbsd and bitrig and fix it
 817     #[test]
 818     #[cfg(not(any(windows, target_os = "openbsd", target_os = "bitrig")))]
 819     fn to_socket_addr_str_bad() {
 820         assert!(tsa("1200::AB00:1234::2552:7777:1313:34300").is_err());
 821     }
 822
 823     #[test]
 824     fn set_ip() {
 825         fn ip4(low: u8) -> Ipv4Addr { Ipv4Addr::new(77, 88, 21, low) }
 826         fn ip6(low: u16) -> Ipv6Addr { Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, low) }
 827
 828         let mut v4 = SocketAddrV4::new(ip4(11), 80);
 829         assert_eq!(v4.ip(), &ip4(11));
 830         v4.set_ip(ip4(12));
 831         assert_eq!(v4.ip(), &ip4(12));
 832
 833         let mut addr = SocketAddr::V4(v4);
 834         assert_eq!(addr.ip(), IpAddr::V4(ip4(12)));
 835         addr.set_ip(IpAddr::V4(ip4(13)));
 836         assert_eq!(addr.ip(), IpAddr::V4(ip4(13)));
 837         addr.set_ip(IpAddr::V6(ip6(14)));
 838         assert_eq!(addr.ip(), IpAddr::V6(ip6(14)));
 839
 840         let mut v6 = SocketAddrV6::new(ip6(1), 80, 0, 0);
 841         assert_eq!(v6.ip(), &ip6(1));
 842         v6.set_ip(ip6(2));
 843         assert_eq!(v6.ip(), &ip6(2));
 844
 845         let mut addr = SocketAddr::V6(v6);
 846         assert_eq!(addr.ip(), IpAddr::V6(ip6(2)));
 847         addr.set_ip(IpAddr::V6(ip6(3)));
 848         assert_eq!(addr.ip(), IpAddr::V6(ip6(3)));
 849         addr.set_ip(IpAddr::V4(ip4(4)));
 850         assert_eq!(addr.ip(), IpAddr::V4(ip4(4)));
 851     }
 852
 853     #[test]
 854     fn set_port() {
 855         let mut v4 = SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80);
 856         assert_eq!(v4.port(), 80);
 857         v4.set_port(443);
 858         assert_eq!(v4.port(), 443);
 859
 860         let mut addr = SocketAddr::V4(v4);
 861         assert_eq!(addr.port(), 443);
 862         addr.set_port(8080);
 863         assert_eq!(addr.port(), 8080);
 864
 865         let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 0, 0);
 866         assert_eq!(v6.port(), 80);
 867         v6.set_port(443);
 868         assert_eq!(v6.port(), 443);
 869
 870         let mut addr = SocketAddr::V6(v6);
 871         assert_eq!(addr.port(), 443);
 872         addr.set_port(8080);
 873         assert_eq!(addr.port(), 8080);
 874     }
 875
 876     #[test]
 877     fn set_flowinfo() {
 878         let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 10, 0);
 879         assert_eq!(v6.flowinfo(), 10);
 880         v6.set_flowinfo(20);
 881         assert_eq!(v6.flowinfo(), 20);
 882     }
 883
 884     #[test]
 885     fn set_scope_id() {
 886         let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 0, 10);
 887         assert_eq!(v6.scope_id(), 10);
 888         v6.set_scope_id(20);
 889         assert_eq!(v6.scope_id(), 20);
 890     }
 891
 892     #[test]
 893     fn is_v4() {
 894         let v4 = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80));
 895         assert!(v4.is_ipv4());
 896         assert!(!v4.is_ipv6());
 897     }
 898
 899     #[test]
 900     fn is_v6() {
 901         let v6 = SocketAddr::V6(SocketAddrV6::new(
 902                 Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 10, 0));
 903         assert!(!v6.is_ipv4());
 904         assert!(v6.is_ipv6());
 905     }
 906 }