single-ping

A simple, lightweight ICMP ping library for Rust that supports both IPv4 and IPv6.

Features

Support for both IPv4 and IPv6
Simple API
Synchronous ping operations
DNS hostname resolution
Latency measurement in milliseconds
Packet validation

Installation

Add this to your Cargo.toml:

[dependencies]
single-ping = "0.1.1"

Usage

Basic Example

use single_ping::ping;

fn main() {
    // Ping with 1000ms timeout and 32 bytes of data
    match ping("8.8.8.8", 1000, 32) {
        Ok(result) => {
            if result.dropped {
                println!("Packet dropped!");
            } else {
                println!("Ping successful! Latency: {}ms", result.latency_ms);
            }
        }
        Err(e) => eprintln!("Ping failed: {}", e),
    }
}

Ping a Hostname

use single_ping::ping;

fn main() {
    // Ping google.com with 2 second timeout and 56 bytes of data
    match ping("google.com", 2000, 56) {
        Ok(result) => {
            println!("Latency: {}ms", result.latency_ms);
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

Check for Dropped Packets

use single_ping::ping;

fn main() {
    let result = ping("example.com", 1000, 32).unwrap();

    if result.dropped {
        println!("No response received within timeout period");
    } else {
        println!("Response received in {}ms", result.latency_ms);
    }
}

API

`ping(host: &str, timeout: u64, size: u64) -> Result<PingResult, Box<dyn std::error::Error>>`

Sends an ICMP echo request to the specified host.

Parameters:

host - Target host as an IP address or hostname (e.g., "8.8.8.8" or "google.com")
timeout - Maximum time to wait for a response, in milliseconds
size - Size of the data payload in bytes

Returns:

Ok(PingResult) - Contains information about the ping result
Err(_) - If the host cannot be resolved or network errors occur

`PingResult`

The result of a ping operation.

Fields:

dropped: bool - Whether the packet was dropped (no response or invalid response)
latency_ms: u64 - Round-trip time in milliseconds

Requirements

Elevated Privileges

Creating raw ICMP sockets requires elevated privileges:

Linux/macOS:

sudo cargo run

Or set capabilities on the binary:

sudo setcap cap_net_raw+ep target/release/your_binary

Windows: Run your terminal or IDE as Administrator.

Supported Platforms

Linux
macOS
Windows
Other Unix-like systems

How It Works

DNS Resolution: The library first resolves the hostname to an IP address (or parses it if already an IP)
Socket Creation: Creates a raw ICMP socket (ICMPv4 or ICMPv6 based on the resolved address)
Packet Construction: Builds an ICMP Echo Request packet with the specified payload size
Send & Receive: Sends the packet and waits for an Echo Reply within the timeout period
Validation: Validates the received packet to ensure it's a proper Echo Reply
Latency Calculation: Measures the round-trip time from send to receive

Examples

Run the examples with elevated privileges:

# Basic ping example (if you create one)
sudo cargo run --example basic_ping

# Run tests
sudo cargo test

Dependencies

socket2 - Cross-platform socket operations

License

Apache-2.0

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Troubleshooting

"Permission denied" or "Operation not permitted"

You need to run with elevated privileges (see Requirements).

"Host unreachable" or resolution failures

Check your network connection
Verify the hostname is correct
Ensure DNS resolution is working (ping command works)

IPv6 issues

Some networks may not support IPv6. The library will automatically use IPv4 or IPv6 based on the resolved address.

single-ping 0.1.1