rust/src/libstd/net/mod.rs

129 lines
4.8 KiB
Rust
Raw Normal View History

// Copyright 2015 The Rust Project Developers. See the COPYRIGHT
// file at the top-level directory of this distribution and at
// http://rust-lang.org/COPYRIGHT.
//
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
// option. This file may not be copied, modified, or distributed
// except according to those terms.
//! Networking primitives for TCP/UDP communication.
//!
//! This module provides networking functionality for the Transmission Control and User
//! Datagram Protocols, as well as types for IP and socket addresses.
//!
//! # Organization
//!
//! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP
//! * [`UdpSocket`] provides functionality for communication over UDP
//! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and
//! [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses
//! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`]
//! and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses
//! * [`ToSocketAddrs`] is a trait that used for generic address resolution when interacting
//! with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`]
//! * Other types are return or parameter types for various methods in this module
//!
//! [`IpAddr`]: ../../std/net/enum.IpAddr.html
//! [`Ipv4Addr`]: ../../std/net/struct.Ipv4Addr.html
//! [`Ipv6Addr`]: ../../std/net/struct.Ipv6Addr.html
//! [`SocketAddr`]: ../../std/net/enum.SocketAddr.html
//! [`SocketAddrV4`]: ../../std/net/struct.SocketAddrV4.html
//! [`SocketAddrV6`]: ../../std/net/struct.SocketAddrV6.html
//! [`TcpListener`]: ../../std/net/struct.TcpListener.html
//! [`TcpStream`]: ../../std/net/struct.TcpStream.html
//! [`ToSocketAddrs`]: ../../std/net/trait.ToSocketAddrs.html
//! [`UdpSocket`]: ../../std/net/struct.UdpSocket.html
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
#![stable(feature = "rust1", since = "1.0.0")]
use io::{self, Error, ErrorKind};
2015-11-16 16:54:28 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::ip::{IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope};
2015-11-16 16:54:28 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
pub use self::addr::{SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs};
2015-11-16 16:54:28 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::tcp::{TcpStream, TcpListener, Incoming};
2015-11-16 16:54:28 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::udp::UdpSocket;
2015-11-16 16:54:28 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
pub use self::parser::AddrParseError;
mod ip;
mod addr;
mod tcp;
mod udp;
mod parser;
#[cfg(test)]
mod test;
/// Possible values which can be passed to the [`shutdown`] method of
/// [`TcpStream`].
///
/// [`shutdown`]: struct.TcpStream.html#method.shutdown
/// [`TcpStream`]: struct.TcpStream.html
2016-09-12 19:37:41 +00:00
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
pub enum Shutdown {
/// The reading portion of the [`TcpStream`] should be shut down.
///
/// All currently blocked and future [reads] will return [`Ok(0)`].
///
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
/// [reads]: ../../std/io/trait.Read.html
/// [`Ok(0)`]: ../../std/result/enum.Result.html#variant.Ok
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
Read,
/// The writing portion of the [`TcpStream`] should be shut down.
///
/// All currently blocked and future [writes] will return an error.
///
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
/// [writes]: ../../std/io/trait.Write.html
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
Write,
/// Both the reading and the writing portions of the [`TcpStream`] should be shut down.
///
/// See [`Shutdown::Read`] and [`Shutdown::Write`] for more information.
///
/// [`TcpStream`]: ../../std/net/struct.TcpStream.html
/// [`Shutdown::Read`]: #variant.Read
/// [`Shutdown::Write`]: #variant.Write
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
#[stable(feature = "rust1", since = "1.0.0")]
Both,
}
#[doc(hidden)]
trait NetInt {
fn from_be(i: Self) -> Self;
fn to_be(&self) -> Self;
}
macro_rules! doit {
($($t:ident)*) => ($(impl NetInt for $t {
fn from_be(i: Self) -> Self { <$t>::from_be(i) }
fn to_be(&self) -> Self { <$t>::to_be(*self) }
})*)
}
doit! { i8 i16 i32 i64 isize u8 u16 u32 u64 usize }
fn hton<I: NetInt>(i: I) -> I { i.to_be() }
fn ntoh<I: NetInt>(i: I) -> I { I::from_be(i) }
std: Stabilize the `net` module This commit performs a stabilization pass over the std::net module, incorporating the changes from RFC 923. Specifically, the following actions were taken: Stable functionality: * `net` (the name) * `Shutdown` * `Shutdown::{Read, Write, Both}` * `lookup_host` * `LookupHost` * `SocketAddr` * `SocketAddr::{V4, V6}` * `SocketAddr::port` * `SocketAddrV4` * `SocketAddrV4::{new, ip, port}` * `SocketAddrV6` * `SocketAddrV4::{new, ip, port, flowinfo, scope_id}` * Common trait impls for socket addr structures * `ToSocketAddrs` * `ToSocketAddrs::Iter` * `ToSocketAddrs::to_socket_addrs` * `ToSocketAddrs for {SocketAddr*, (Ipv*Addr, u16), str, (str, u16)}` * `Ipv4Addr` * `Ipv4Addr::{new, octets, to_ipv6_compatible, to_ipv6_mapped}` * `Ipv6Addr` * `Ipv6Addr::{new, segments, to_ipv4}` * `TcpStream` * `TcpStream::connect` * `TcpStream::{peer_addr, local_addr, shutdown, try_clone}` * `{Read,Write} for {TcpStream, &TcpStream}` * `TcpListener` * `TcpListener::bind` * `TcpListener::{local_addr, try_clone, accept, incoming}` * `Incoming` * `UdpSocket` * `UdpSocket::bind` * `UdpSocket::{recv_from, send_to, local_addr, try_clone}` Unstable functionality: * Extra methods on `Ipv{4,6}Addr` for various methods of inspecting the address and determining qualities of it. * Extra methods on `TcpStream` to configure various protocol options. * Extra methods on `UdpSocket` to configure various protocol options. Deprecated functionality: * The `socket_addr` method has been renamed to `local_addr` This commit is a breaking change due to the restructuring of the `SocketAddr` type as well as the renaming of the `socket_addr` method. Migration should be fairly straightforward, however, after accounting for the new level of abstraction in `SocketAddr` (protocol distinction at the socket address level, not the IP address). [breaking-change]
2015-03-13 21:22:33 +00:00
fn each_addr<A: ToSocketAddrs, F, T>(addr: A, mut f: F) -> io::Result<T>
where F: FnMut(&SocketAddr) -> io::Result<T>
{
let mut last_err = None;
for addr in addr.to_socket_addrs()? {
match f(&addr) {
Ok(l) => return Ok(l),
Err(e) => last_err = Some(e),
}
}
Err(last_err.unwrap_or_else(|| {
Error::new(ErrorKind::InvalidInput,
"could not resolve to any addresses")
}))
}