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