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 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 = SocketAddr;
 102     fn next(&mut self) -> Option<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 /// The returned iterator will skip over any unknown addresses returned by the
 111 /// operating system.
 112 ///
 113 /// # Examples
 114 ///
 115 /// ```no_run
 116 /// #![feature(lookup_host)]
 117 ///
 118 /// use std::net;
 119 ///
 120 /// # fn foo() -> std::io::Result<()> {
 121 /// for host in try!(net::lookup_host("rust-lang.org")) {
 122 ///     println!("found address: {}", host);
 123 /// }
 124 /// # Ok(())
 125 /// # }
 126 /// ```
 127 #[unstable(feature = "lookup_host", reason = "unsure about the returned \
 128                                               iterator and returning socket \
 129                                               addresses",
 130            issue = "27705")]
 131 pub fn lookup_host(host: &str) -> io::Result<LookupHost> {
 132     net_imp::lookup_host(host).map(LookupHost)
 133 }