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 (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 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 (*Pinger) AddHandler ¶
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 ¶
AddIP adds an IP address to Pinger. ipaddr arg should be a string like "192.0.2.1".
func (*Pinger) AddIPAddr ¶
AddIPAddr adds an IP address to Pinger. ip arg should be a net.IPAddr pointer.
func (*Pinger) Done ¶
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 ¶
Err returns an error that is set by RunLoop(). It must be called after RunLoop(). If not, it causes panic.
func (*Pinger) Network ¶
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 ¶
RemoveIP removes an IP address from Pinger. ipaddr arg should be a string like "192.0.2.1".
func (*Pinger) RemoveIPAddr ¶
RemoveIPAddr removes an IP address from Pinger. ip arg should be a net.IPAddr pointer.
func (*Pinger) Run ¶
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".
Source Files
Directories