src/libstd/net/mod.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 //! Networking primitives for TCP/UDP communication.
  12
  13 #![stable(feature = "rust1", since = "1.0.0")]
  14
  15 use fmt;
  16 use io::{self, Error, ErrorKind};
  17 use sys_common::net as net_imp;
  18
  19 #[stable(feature = "rust1", since = "1.0.0")]
  20 pub use self::ip::{IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope};
  21 #[stable(feature = "rust1", since = "1.0.0")]
  22 pub use self::addr::{SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs};
  23 #[stable(feature = "rust1", since = "1.0.0")]
  24 pub use self::tcp::{TcpStream, TcpListener, Incoming};
  25 #[stable(feature = "rust1", since = "1.0.0")]
  26 pub use self::udp::UdpSocket;
  27 #[stable(feature = "rust1", since = "1.0.0")]
  28 pub use self::parser::AddrParseError;
  29
  30 mod ip;
  31 mod addr;
  32 mod tcp;
  33 mod udp;
  34 mod parser;
  35 #[cfg(test)]
  36 mod test;
  37
  38 /// Possible values which can be passed to the [`shutdown`] method of
  39 /// [`TcpStream`].
  40 ///
  41 /// [`shutdown`]: struct.TcpStream.html#method.shutdown
  42 /// [`TcpStream`]: struct.TcpStream.html
  43 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
  44 #[stable(feature = "rust1", since = "1.0.0")]
  45 pub enum Shutdown {
  46     /// Indicates that the reading portion of this stream/socket should be shut
  47     /// down. All currently blocked and future reads will return `Ok(0)`.
  48     #[stable(feature = "rust1", since = "1.0.0")]
  49     Read,
  50     /// Indicates that the writing portion of this stream/socket should be shut
  51     /// down. All currently blocked and future writes will return an error.
  52     #[stable(feature = "rust1", since = "1.0.0")]
  53     Write,
  54     /// Shut down both the reading and writing portions of this stream.
  55     ///
  56     /// See `Shutdown::Read` and `Shutdown::Write` for more information.
  57     #[stable(feature = "rust1", since = "1.0.0")]
  58     Both,
  59 }
  60
  61 #[doc(hidden)]
  62 trait NetInt {
  63     fn from_be(i: Self) -> Self;
  64     fn to_be(&self) -> Self;
  65 }
  66 macro_rules! doit {
  67     ($($t:ident)*) => ($(impl NetInt for $t {
  68         fn from_be(i: Self) -> Self { <$t>::from_be(i) }
  69         fn to_be(&self) -> Self { <$t>::to_be(*self) }
  70     })*)
  71 }
  72 doit! { i8 i16 i32 i64 isize u8 u16 u32 u64 usize }
  73
  74 fn hton<I: NetInt>(i: I) -> I { i.to_be() }
  75 fn ntoh<I: NetInt>(i: I) -> I { I::from_be(i) }
  76
  77 fn each_addr<A: ToSocketAddrs, F, T>(addr: A, mut f: F) -> io::Result<T>
  78     where F: FnMut(&SocketAddr) -> io::Result<T>
  79 {
  80     let mut last_err = None;
  81     for addr in addr.to_socket_addrs()? {
  82         match f(&addr) {
  83             Ok(l) => return Ok(l),
  84             Err(e) => last_err = Some(e),
  85         }
  86     }
  87     Err(last_err.unwrap_or_else(|| {
  88         Error::new(ErrorKind::InvalidInput,
  89                    "could not resolve to any addresses")
  90     }))
  91 }
  92
  93 /// An iterator over `SocketAddr` values returned from a host lookup operation.
  94 #[unstable(feature = "lookup_host", reason = "unsure about the returned \
  95                                               iterator and returning socket \
  96                                               addresses",
  97            issue = "27705")]
  98 pub struct LookupHost(net_imp::LookupHost);
  99
 100 #[unstable(feature = "lookup_host", reason = "unsure about the returned \
 101                                               iterator and returning socket \
 102                                               addresses",
 103            issue = "27705")]
 104 impl Iterator for LookupHost {
 105     type Item = SocketAddr;
 106     fn next(&mut self) -> Option<SocketAddr> { self.0.next() }
 107 }
 108
 109 #[stable(feature = "std_debug", since = "1.15.0")]
 110 impl fmt::Debug for LookupHost {
 111     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 112         f.pad("LookupHost { .. }")
 113     }
 114 }
 115
 116 /// Resolve the host specified by `host` as a number of `SocketAddr` instances.
 117 ///
 118 /// This method may perform a DNS query to resolve `host` and may also inspect
 119 /// system configuration to resolve the specified hostname.
 120 ///
 121 /// The returned iterator will skip over any unknown addresses returned by the
 122 /// operating system.
 123 ///
 124 /// # Examples
 125 ///
 126 /// ```no_run
 127 /// #![feature(lookup_host)]
 128 ///
 129 /// use std::net;
 130 ///
 131 /// # fn foo() -> std::io::Result<()> {
 132 /// for host in net::lookup_host("rust-lang.org")? {
 133 ///     println!("found address: {}", host);
 134 /// }
 135 /// # Ok(())
 136 /// # }
 137 /// ```
 138 #[unstable(feature = "lookup_host", reason = "unsure about the returned \
 139                                               iterator and returning socket \
 140                                               addresses",
 141            issue = "27705")]
 142 pub fn lookup_host(host: &str) -> io::Result<LookupHost> {
 143     net_imp::lookup_host(host).map(LookupHost)
 144 }