]>
Commit | Line | Data |
---|---|---|
bd371182 | 1 | //! Networking primitives for TCP/UDP communication. |
cc61c64b XL |
2 | //! |
3 | //! This module provides networking functionality for the Transmission Control and User | |
4 | //! Datagram Protocols, as well as types for IP and socket addresses. | |
5 | //! | |
6 | //! # Organization | |
7 | //! | |
8 | //! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP | |
9 | //! * [`UdpSocket`] provides functionality for communication over UDP | |
10 | //! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and | |
11 | //! [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses | |
12 | //! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`] | |
13 | //! and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses | |
487cf647 | 14 | //! * [`ToSocketAddrs`] is a trait that is used for generic address resolution when interacting |
cc61c64b XL |
15 | //! with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`] |
16 | //! * Other types are return or parameter types for various methods in this module | |
5e7ed085 FG |
17 | //! |
18 | //! Rust disables inheritance of socket objects to child processes by default when possible. For | |
19 | //! example, through the use of the `CLOEXEC` flag in UNIX systems or the `HANDLE_FLAG_INHERIT` | |
20 | //! flag on Windows. | |
85aaf69f | 21 | |
c34b1796 | 22 | #![stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 23 | |
5099ac24 | 24 | use crate::io::{self, ErrorKind}; |
85aaf69f | 25 | |
dfeec247 | 26 | #[stable(feature = "rust1", since = "1.0.0")] |
f2b60f7d | 27 | pub use self::ip_addr::{IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope}; |
92a42be0 | 28 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 | 29 | pub use self::parser::AddrParseError; |
f2b60f7d FG |
30 | #[stable(feature = "rust1", since = "1.0.0")] |
31 | pub use self::socket_addr::{SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs}; | |
5099ac24 FG |
32 | #[unstable(feature = "tcplistener_into_incoming", issue = "88339")] |
33 | pub use self::tcp::IntoIncoming; | |
92a42be0 | 34 | #[stable(feature = "rust1", since = "1.0.0")] |
dfeec247 | 35 | pub use self::tcp::{Incoming, TcpListener, TcpStream}; |
92a42be0 | 36 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f SL |
37 | pub use self::udp::UdpSocket; |
38 | ||
f2b60f7d FG |
39 | mod display_buffer; |
40 | mod ip_addr; | |
85aaf69f | 41 | mod parser; |
f2b60f7d | 42 | mod socket_addr; |
dfeec247 | 43 | mod tcp; |
c30ab7b3 | 44 | #[cfg(test)] |
f2b60f7d | 45 | pub(crate) mod test; |
dfeec247 | 46 | mod udp; |
85aaf69f | 47 | |
3dfed10e | 48 | /// Possible values which can be passed to the [`TcpStream::shutdown`] method. |
9e0c209e | 49 | #[derive(Copy, Clone, PartialEq, Eq, Debug)] |
c34b1796 | 50 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 51 | pub enum Shutdown { |
cc61c64b XL |
52 | /// The reading portion of the [`TcpStream`] should be shut down. |
53 | /// | |
c295e0f8 | 54 | /// All currently blocked and future [reads] will return <code>[Ok]\(0)</code>. |
cc61c64b | 55 | /// |
c295e0f8 | 56 | /// [reads]: crate::io::Read "io::Read" |
c34b1796 | 57 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 58 | Read, |
cc61c64b XL |
59 | /// The writing portion of the [`TcpStream`] should be shut down. |
60 | /// | |
61 | /// All currently blocked and future [writes] will return an error. | |
62 | /// | |
c295e0f8 | 63 | /// [writes]: crate::io::Write "io::Write" |
c34b1796 | 64 | #[stable(feature = "rust1", since = "1.0.0")] |
85aaf69f | 65 | Write, |
cc61c64b XL |
66 | /// Both the reading and the writing portions of the [`TcpStream`] should be shut down. |
67 | /// | |
68 | /// See [`Shutdown::Read`] and [`Shutdown::Write`] for more information. | |
c34b1796 AL |
69 | #[stable(feature = "rust1", since = "1.0.0")] |
70 | Both, | |
85aaf69f SL |
71 | } |
72 | ||
c34b1796 | 73 | fn each_addr<A: ToSocketAddrs, F, T>(addr: A, mut f: F) -> io::Result<T> |
dfeec247 XL |
74 | where |
75 | F: FnMut(io::Result<&SocketAddr>) -> io::Result<T>, | |
85aaf69f | 76 | { |
0731742a XL |
77 | let addrs = match addr.to_socket_addrs() { |
78 | Ok(addrs) => addrs, | |
dfeec247 | 79 | Err(e) => return f(Err(e)), |
0731742a | 80 | }; |
85aaf69f | 81 | let mut last_err = None; |
0731742a XL |
82 | for addr in addrs { |
83 | match f(Ok(&addr)) { | |
85aaf69f SL |
84 | Ok(l) => return Ok(l), |
85 | Err(e) => last_err = Some(e), | |
86 | } | |
87 | } | |
88 | Err(last_err.unwrap_or_else(|| { | |
5099ac24 | 89 | io::const_io_error!(ErrorKind::InvalidInput, "could not resolve to any addresses") |
85aaf69f SL |
90 | })) |
91 | } |