rust tiny-ping

Ping function implemented in rust, made for small compile times.

Small async ICMP library. No proc macros.

Installation

Cargo

cargo install tiny-ping

Arch Linux / AUR

yay -S tiny-ping
yay -S tiny-ping-bin
yay -S tiny-ping-git

macOS / Homebrew

brew install --cask Fierthraix/tap/tiny-ping

Windows / Scoop

scoop bucket add fierthraix https://github.com/Fierthraix/scoop-bucket
scoop install tiny-ping

Nix

nix profile install github:Fierthraix/nur-packages#tiny-ping

Release Assets

https://github.com/Fierthraix/tiny-ping/releases/latest

Usage

use std::{net::IpAddr, time::Duration};use tiny_ping::Pinger;
# asyncfnexample() -> Result<(),Box<dyn std::error::Error>>{letmut pinger = Pinger::new("1.1.1.1".parse::<IpAddr>()?)?;
pinger.timeout(Duration::from_secs(1));let result = pinger.ping(1).await?;println!("reply from {} in {:?}", result.reply.source, result.rtt);
# Ok(())
# }

Use PingRequest when you need to control the ICMP echo payload:

use std::{net::IpAddr, time::Duration};use tiny_ping::{Pinger,PingRequest};
# asyncfnexample() -> Result<(),Box<dyn std::error::Error>>{letmut pinger = Pinger::new("1.1.1.1".parse::<IpAddr>()?)?;
pinger.timeout(Duration::from_secs(1));let request = PingRequest::new(1).payload(b"tiny-ping");let result = pinger.ping(request).await?;println!("reply payload was {} bytes", result.reply.payload_len);
# Ok(())
# }

For multicast or other cases where more than one host may reply to a single request, use ping_replies:

use std::{net::{Ipv6Addr,SocketAddr,SocketAddrV6}, time::Duration};use tiny_ping::{Pinger,SocketType};
# asyncfnexample() -> Result<(),Box<dyn std::error::Error>>{let target = SocketAddr::V6(SocketAddrV6::new("ff02::1".parse::<Ipv6Addr>()?,0,0,2,));letmut pinger = Pinger::with_socket_addr(target,SocketType::Raw)?;
pinger.timeout(Duration::from_secs(1));for result in pinger.ping_replies(1).await? {println!("reply from {} in {:?}", result.reply.source, result.rtt);}
# Ok(())
# }

Raw sockets usually need root or capabilities.

DGRAM sockets can work without that on some systems:

use std::net::IpAddr;use tiny_ping::{Pinger,SocketType};
# asyncfnexample() -> Result<(),Box<dyn std::error::Error>>{let pinger = Pinger::with_socket_type("1.1.1.1".parse::<IpAddr>()?,SocketType::Dgram,)?;let result = pinger.ping(1).await?;println!("reply from {} in {:?}", result.reply.source, result.rtt);
# Ok(())
# }

For repeated pings, use PingSeries:

use std::{net::IpAddr, time::Duration};use tiny_ping::{Pinger,PingSeries};
# asyncfnexample() -> Result<(),Box<dyn std::error::Error>>{letmut pinger = Pinger::new("1.1.1.1".parse::<IpAddr>()?)?;
pinger.timeout(Duration::from_secs(1));let series = PingSeries::new(1,4).interval(Duration::from_secs(1));let results = pinger.ping_many(series).await;println!("{} transmitted, {} received, {:.1}% loss",
results.summary.transmitted,
results.summary.received,
results.summary.loss,);
# Ok(())
# }

Use bind_source to bind the socket to a local source address. The port is ignored for ICMP.

Tests

cargo test

Real ping tests are opt-in with TINY_PING_RUN_NET_TESTS=1 or TINY_PING_RUN_RAW_TESTS=1.

License

This library contains codes from https://github.com/knsd/tokio-ping, which is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

And other codes is licensed under

• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)