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
  39 /// [`TcpStream`].
  40 ///
  41 /// [`shutdown`]: struct.TcpStream.html#method.shutdown
  42 /// [`TcpStream`]: struct.TcpStream.html
  43 #[derive(Copy, Clone, PartialEq, 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 /// Resolve the host specified by `host` as a number of `SocketAddr` instances.
 110 ///
 111 /// This method may perform a DNS query to resolve `host` and may also inspect
 112 /// system configuration to resolve the specified hostname.
 113 ///
 114 /// The returned iterator will skip over any unknown addresses returned by the
 115 /// operating system.
 116 ///
 117 /// # Examples
 118 ///
 119 /// ```no_run
 120 /// #![feature(lookup_host)]
 121 ///
 122 /// use std::net;
 123 ///
 124 /// # fn foo() -> std::io::Result<()> {
 125 /// for host in try!(net::lookup_host("rust-lang.org")) {
 126 ///     println!("found address: {}", host);
 127 /// }
 128 /// # Ok(())
 129 /// # }
 130 /// ```
 131 #[unstable(feature = "lookup_host", reason = "unsure about the returned \
 132                                               iterator and returning socket \
 133                                               addresses",
 134            issue = "27705")]
 135 pub fn lookup_host(host: &str) -> io::Result<LookupHost> {
 136     net_imp::lookup_host(host).map(LookupHost)
 137 }