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