fastping

README

go-fastping

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

All original functions haven't been implemented yet.

Installation

Install and update with go get -u github.com/tatsushid/go-fastping

Examples

Import this package and write

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)
}

The example sends an ICMP packet and waits for a response. If it receives a response, it calls the "receive" callback. After that, once MaxRTT time has passed, it calls the "idle" callback. For more details, refer to the godoc, and if you need more examples, please see "cmd/ping/ping.go".

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 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) AddHandler(event string, handler interface{}) error
  • func (p *Pinger) AddIP(ipaddr string) error
  • func (p *Pinger) AddIPAddr(ip *net.IPAddr)
  • func (p *Pinger) Done() <-chan bool
  • func (p *Pinger) Err() error
  • func (p *Pinger) Network(network string) (string, error)
  • func (p *Pinger) RemoveIP(ipaddr string) error
  • func (p *Pinger) RemoveIPAddr(ip *net.IPAddr)
  • func (p *Pinger) Run() error
  • func (p *Pinger) RunLoop()
  • func (p *Pinger) Source(source string) (string, error)
  • func (p *Pinger) Stop()

Constants

const (
	TimeSliceLength  = 8
	ProtocolICMP     = 1
	ProtocolIPv6ICMP = 58
)

Types

type Pinger

type Pinger struct {

	// 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
	// OnRecv is called with a response packet's source address and its
	// elapsed time when Pinger receives a response packet.
	OnRecv func(*net.IPAddr, time.Duration)
	// OnIdle is called when MaxRTT time passed
	OnIdle func()
	// If Debug is true, it prints debug messages to stdout.
	Debug bool
	// 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) AddHandler

func (p *Pinger) AddHandler(event string, handler interface{}) error

AddHandler adds event handler to Pinger. event arg should be "receive" or "idle" string.

**CAUTION** This function is deprecated. Please use OnRecv and OnIdle field of Pinger struct to set following handlers.

"receive" handler should be

func(addr *net.IPAddr, rtt time.Duration)

type function. The handler is called with a response packet's source address and its elapsed time when Pinger receives a response packet.

"idle" handler should be

func()

type function. The handler is called when MaxRTT time passed. For more detail, please see Run() and RunLoop().

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) Done

func (p *Pinger) Done() <-chan bool

Done returns a channel that is closed when RunLoop() is stopped by an error or Stop(). It must be called after RunLoop() call. If not, it causes panic.

func (*Pinger) Err

func (p *Pinger) Err() error

Err returns an error that is set by RunLoop(). It must be called after RunLoop(). If not, it causes panic.

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) RemoveIPAddr

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

RemoveIPAddr removes an IP address from Pinger. ip arg should be a net.IPAddr pointer.

func (*Pinger) Run

func (p *Pinger) Run() 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. For the purpose of sending/receiving packets over and over, use RunLoop().

func (*Pinger) RunLoop

func (p *Pinger) RunLoop()

RunLoop invokes send/receive procedure repeatedly. 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, resend packets and wait those response. MaxRTT works as an interval time.

This is a non-blocking method so immediately returns. If you want to monitor and stop sending packets, use Done() and Stop() methods. For example,

p.RunLoop()
ticker := time.NewTicker(time.Millisecond * 250)
select {
case <-p.Done():
	if err := p.Err(); err != nil {
		log.Fatalf("Ping failed: %v", err)
	}
case <-ticker.C:
	break
}
ticker.Stop()
p.Stop()

For more details, please see "cmd/ping/ping.go".

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).

func (*Pinger) Stop

func (p *Pinger) Stop()

Stop stops RunLoop(). It must be called after RunLoop(). If not, it causes panic.