ping 0.10.0

Simple and naive ping implementation in Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

//! An ICMP echo ("ping") implementation for IPv4 and IPv6.
//!
//! Send ICMP echo requests to a target [`IpAddr`] and wait for the reply or a
//! timeout.
//!
//! # Quick start
//!
//! For a one off ping, call [`ping()`] with a target and a timeout.
//!
//! ```no_run
//! use std::net::IpAddr;
//! use std::time::Duration;
//!
//! let target: IpAddr = "8.8.8.8".parse().unwrap();
//! let reply = ping::ping(target, Duration::from_secs(1))?;
//! println!("rtt {:?} from {}", reply.rtt, reply.source);
//! # Ok::<(), ping::Error>(())
//! ```
//!
//! [`ping()`] opens a new socket every time. To ping repeatedly, create a
//! [`Pinger`] and call [`Pinger::ping`] instead. The pinger keeps its sockets
//! open between pings.
//!
//! ```no_run
//! use std::net::IpAddr;
//! use std::time::Duration;
//! use ping::Pinger;
//!
//! let target: IpAddr = "8.8.8.8".parse().unwrap();
//! let mut pinger = Pinger::new();
//! let reply = pinger.ping(target, Duration::from_secs(1))?;
//! println!("rtt {:?} from {}", reply.rtt, reply.source);
//! # Ok::<(), ping::Error>(())
//! ```
//!
//! Per request options such as the TTL and the payload are set on a
//! [`Request`], and socket options such as the socket type are set with
//! [`Pinger::builder`].
//!
//! ```no_run
//! use std::net::IpAddr;
//! use std::time::Duration;
//! use ping::{Pinger, Request, SocketType};
//!
//! let target: IpAddr = "8.8.8.8".parse().unwrap();
//! let mut pinger = Pinger::builder()
//!     .socket_type(SocketType::RAW)
//!     .build()?;
//! let request = Request::new(target).ttl(5).payload(b"hello".to_vec());
//! pinger.ping(request, Duration::from_secs(1))?;
//! # Ok::<(), ping::Error>(())
//! ```
//!
//! # Pinging a host name
//!
//! Only an [`IpAddr`] is accepted. To ping a host name, resolve it first with
//! [`ToSocketAddrs`](std::net::ToSocketAddrs).
//!
//! ```no_run
//! use std::net::ToSocketAddrs;
//! use std::time::Duration;
//!
//! // The port is irrelevant, we only need the resolved IP.
//! let addr = "www.google.com:0"
//!     .to_socket_addrs()
//!     .unwrap()
//!     .next()
//!     .unwrap()
//!     .ip();
//!
//! ping::ping(addr, Duration::from_secs(1))?;
//! # Ok::<(), ping::Error>(())
//! ```
//!
//! # Socket types
//!
//! Sending ICMP traffic over a [`RAW`](SocketType::RAW) socket needs elevated
//! privileges, while a [`DGRAM`](SocketType::DGRAM) socket works unprivileged
//! on most systems. See [`SocketType`] for the default order.
//!
//! # Tokio
//!
//! With the `tokio` feature, `ping::tokio::ping` and `ping::tokio::Pinger`
//! provide the same API with an `async` ping. Configure an async pinger with
//! [`Pinger::builder`] and `build_tokio`.
//!
//! [`IpAddr`]: std::net::IpAddr

mod errors;
mod legacy;
// Copied from tokio-ping, so unused parts are kept.
#[allow(dead_code, unused_imports)]
mod packet;
mod pinger;
mod socket;
#[cfg(feature = "tokio")]
pub mod tokio;

pub use crate::errors::Error;
#[allow(deprecated)]
pub use crate::legacy::{DGRAM, Ping, PingResult, RAW, dgramsock, new, rawsock};
pub use crate::pinger::{Pinger, PingerBuilder, Reply, Request, SocketType, ping};