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 //! This module provides networking functionality for the Transmission Control and User
  14 //! Datagram Protocols, as well as types for IP and socket addresses.
  15 //!
  16 //! # Organization
  17 //!
  18 //! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP
  19 //! * [`UdpSocket`] provides functionality for communication over UDP
  20 //! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and
  21 //!   [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses
  22 //! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`]
  23 //!   and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses
  24 //! * [`ToSocketAddrs`] is a trait that used for generic address resolution when interacting
  25 //!   with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`]
  26 //! * Other types are return or parameter types for various methods in this module
  27 //!
  28 //! [`IpAddr`]: ../../std/net/enum.IpAddr.html
  29 //! [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
  30 //! [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
  31 //! [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
  32 //! [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
  33 //! [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
  34 //! [`TcpListener`]: ../../std/net/struct.TcpListener.html
  35 //! [`TcpStream`]: ../../std/net/struct.TcpStream.html
  36 //! [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
  37 //! [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
  38
  39 #![stable(feature = "rust1", since = "1.0.0")]
  40
  41 use io::{self, Error, ErrorKind};
  42
  43 #[stable(feature = "rust1", since = "1.0.0")]
  44 pub use self::ip::{IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope};
  45 #[stable(feature = "rust1", since = "1.0.0")]
  46 pub use self::addr::{SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs};
  47 #[stable(feature = "rust1", since = "1.0.0")]
  48 pub use self::tcp::{TcpStream, TcpListener, Incoming};
  49 #[stable(feature = "rust1", since = "1.0.0")]
  50 pub use self::udp::UdpSocket;
  51 #[stable(feature = "rust1", since = "1.0.0")]
  52 pub use self::parser::AddrParseError;
  53
  54 mod ip;
  55 mod addr;
  56 mod tcp;
  57 mod udp;
  58 mod parser;
  59 #[cfg(test)]
  60 mod test;
  61
  62 /// Possible values which can be passed to the [`shutdown`] method of
  63 /// [`TcpStream`].
  64 ///
  65 /// [`shutdown`]: struct.TcpStream.html#method.shutdown
  66 /// [`TcpStream`]: struct.TcpStream.html
  67 #[derive(Copy, Clone, PartialEq, Eq, Debug)]
  68 #[stable(feature = "rust1", since = "1.0.0")]
  69 pub enum Shutdown {
  70     /// The reading portion of the [`TcpStream`] should be shut down.
  71     ///
  72     /// All currently blocked and future [reads] will return [`Ok(0)`].
  73     ///
  74     /// [`TcpStream`]: ../../std/net/struct.TcpStream.html
  75     /// [reads]: ../../std/io/trait.Read.html
  76     /// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
  77     #[stable(feature = "rust1", since = "1.0.0")]
  78     Read,
  79     /// The writing portion of the [`TcpStream`] should be shut down.
  80     ///
  81     /// All currently blocked and future [writes] will return an error.
  82     ///
  83     /// [`TcpStream`]: ../../std/net/struct.TcpStream.html
  84     /// [writes]: ../../std/io/trait.Write.html
  85     #[stable(feature = "rust1", since = "1.0.0")]
  86     Write,
  87     /// Both the reading and the writing portions of the [`TcpStream`] should be shut down.
  88     ///
  89     /// See [`Shutdown::Read`] and [`Shutdown::Write`] for more information.
  90     ///
  91     /// [`TcpStream`]: ../../std/net/struct.TcpStream.html
  92     /// [`Shutdown::Read`]: #variant.Read
  93     /// [`Shutdown::Write`]: #variant.Write
  94     #[stable(feature = "rust1", since = "1.0.0")]
  95     Both,
  96 }
  97
  98 #[doc(hidden)]
  99 trait NetInt {
 100     fn from_be(i: Self) -> Self;
 101     fn to_be(&self) -> Self;
 102 }
 103 macro_rules! doit {
 104     ($($t:ident)*) => ($(impl NetInt for $t {
 105         fn from_be(i: Self) -> Self { <$t>::from_be(i) }
 106         fn to_be(&self) -> Self { <$t>::to_be(*self) }
 107     })*)
 108 }
 109 doit! { i8 i16 i32 i64 isize u8 u16 u32 u64 usize }
 110
 111 fn hton<I: NetInt>(i: I) -> I { i.to_be() }
 112 fn ntoh<I: NetInt>(i: I) -> I { I::from_be(i) }
 113
 114 fn each_addr<A: ToSocketAddrs, F, T>(addr: A, mut f: F) -> io::Result<T>
 115     where F: FnMut(io::Result<&SocketAddr>) -> io::Result<T>
 116 {
 117     let addrs = match addr.to_socket_addrs() {
 118         Ok(addrs) => addrs,
 119         Err(e) => return f(Err(e))
 120     };
 121     let mut last_err = None;
 122     for addr in addrs {
 123         match f(Ok(&addr)) {
 124             Ok(l) => return Ok(l),
 125             Err(e) => last_err = Some(e),
 126         }
 127     }
 128     Err(last_err.unwrap_or_else(|| {
 129         Error::new(ErrorKind::InvalidInput,
 130                    "could not resolve to any addresses")
 131     }))
 132 }