fastping

README

go-fastping

WARNING: this is thread-unsafe fork of original https://github.com/tatsushid/go-fastping with many changes (limit usage of locks, channels, send packets in chunks and many other).

In common cases please use original version.

---

go-fastping is a Go language's ICMP ping library inspired by AnyEvent::FastPing Perl module to send ICMP ECHO REQUEST packets quickly. Original Perl module is available at http://search.cpan.org/~mlehmann/AnyEvent-FastPing-2.01/

It hasn't been fully implemented original functions yet.

Installation

Install and update this go package with go get -u github.com/kanocz/go-fastping

Examples

Import this package and write

p := fastping.NewPinger()
p.AddIP(os.Args[1])

result, err := p.Run(map[string]bool{},0,0)
if err != nil {
	fmt.Println(err)
} else {
	fmt.Printf("Result: %s:%+v\n",os.Args[1], result[os.Args[1]])
}

It sends an ICMP packet and wait a response. Result is map with ip->rtt, in case of loss rtt == -1

Caution

This package implements ICMP ping using both raw socket and UDP. If your program uses this package in raw socket mode, it needs to be run as a root user.

License

go-fastping is under MIT License. See the [LICENSE][license] file for details.

Documentation

Overview

Package fastping is an ICMP ping library inspired by AnyEvent::FastPing Perl module to send ICMP ECHO REQUEST packets quickly. Original Perl module is available at http://search.cpan.org/~mlehmann/AnyEvent-FastPing-2.01/

It hasn't been fully implemented original functions yet.

Here is an example:

p := fastping.NewPinger()
ra, err := net.ResolveIPAddr("ip4:icmp", os.Args[1])
if err != nil {
	fmt.Println(err)
	os.Exit(1)
}
p.AddIPAddr(ra)
p.OnRecv = func(addr *net.IPAddr, rtt time.Duration) {
	fmt.Printf("IP Addr: %s receive, RTT: %v\n", addr.String(), rtt)
}
p.OnIdle = func() {
	fmt.Println("finish")
}
err = p.Run()
if err != nil {
	fmt.Println(err)
}

It sends an ICMP packet and wait a response. If it receives a response, it calls "receive" callback. After that, MaxRTT time passed, it calls "idle" callback. If you need more example, please see "cmd/ping/ping.go".

This library needs to run as a superuser for sending ICMP packets when privileged raw ICMP endpoints is used so in such a case, to run go test for the package, please run like a following

sudo go test

Index

• Constants
• type Pinger
  • func NewPinger() *Pinger
  • func (p *Pinger) AddIP(ipaddr string) error
  • func (p *Pinger) AddIPAddr(ip *net.IPAddr)
  • func (p *Pinger) Network(network string) (string, error)
  • func (p *Pinger) RemoveIP(ipaddr string) error
  • func (p *Pinger) Run(skip map[string]bool, id int, seq int) (map[string]time.Duration, error)
  • func (p *Pinger) Source(source string) (string, error)

Constants

const (
	// TimeSliceLength lenght of time slice in bytes
	TimeSliceLength = unsafe.Sizeof(syscall.Timeval{})
	// ProtocolICMP id of ICMP ip proto
	ProtocolICMP = 1
	// ProtocolIPv6ICMP id of ICMPv6 ip proto
	ProtocolIPv6ICMP = 58
)

Types

type Pinger

type Pinger struct {

	// Chunk is number of pings to send before sleep
	Chunk int
	// Sleep duration between sending chunks
	Sleep time.Duration

	// Size in bytes of the payload to send
	Size int
	// Number of (nano,milli)seconds of an idle timeout. Once it passed,
	// the library calls an idle callback function. It is also used for an
	// interval time of RunLoop() method
	MaxRTT time.Duration
	// NumGoroutines defines how many goroutines are used when sending ICMP
	// packets and receiving IPv4/IPv6 ICMP responses. Its default is
	// runtime.NumCPU().
	NumGoroutines int
	// contains filtered or unexported fields
}

Pinger represents ICMP packet sender/receiver

func NewPinger

func NewPinger() *Pinger

NewPinger returns a new Pinger struct pointer

func (*Pinger) AddIP

func (p *Pinger) AddIP(ipaddr string) error

AddIP adds an IP address to Pinger. ipaddr arg should be a string like "192.0.2.1".

func (*Pinger) AddIPAddr

func (p *Pinger) AddIPAddr(ip *net.IPAddr)

AddIPAddr adds an IP address to Pinger. ip arg should be a net.IPAddr pointer.

func (*Pinger) Network

func (p *Pinger) Network(network string) (string, error)

Network sets a network endpoints for ICMP ping and returns the previous setting. network arg should be "ip" or "udp" string or if others are specified, it returns an error. If this function isn't called, Pinger uses "ip" as default.

func (*Pinger) RemoveIP

func (p *Pinger) RemoveIP(ipaddr string) error

RemoveIP removes an IP address from Pinger. ipaddr arg should be a string like "192.0.2.1".

func (*Pinger) Run

func (p *Pinger) Run(skip map[string]bool, id int, seq int) (map[string]time.Duration, error)

Run invokes a single send/receive procedure. It sends packets to all hosts which have already been added by AddIP() etc. and wait those responses. When it receives a response, it calls "receive" handler registered by AddHander(). After MaxRTT seconds, it calls "idle" handler and returns to caller with an error value. It means it blocks until MaxRTT seconds passed.

func (*Pinger) Source

func (p *Pinger) Source(source string) (string, error)

Source sets ipv4/ipv6 source IP for sending ICMP packets and returns the previous setting. Empty value indicates to use system default one (for both ipv4 and ipv6).