pinger

Documentation

Overview

Package ping is an ICMP ping library seeking to emulate the unix "ping" command.

Here is a very simple example that sends & receives 3 packets:

pinger, err := ping.NewPinger("www.google.com")
if err != nil {
	panic(err)
}

pinger.Count = 3
pinger.Run() // blocks until finished
stats := pinger.Statistics() // get send/receive/rtt stats

Here is an example that emulates the unix ping command:

pinger, err := ping.NewPinger("www.google.com")
if err != nil {
	fmt.Printf("ERROR: %s\n", err.Error())
	return
}

pinger.OnRecv = func(pkt *ping.Packet) {
	fmt.Printf("%d bytes from %s: icmp_seq=%d time=%v\n",
		pkt.Nbytes, pkt.IPAddr, pkt.Seq, pkt.Rtt)
}
pinger.OnFinish = func(stats *ping.Statistics) {
	fmt.Printf("\n--- %s ping statistics ---\n", stats.Addr)
	fmt.Printf("%d packets transmitted, %d packets received, %v%% packet loss\n",
		stats.PacketsSent, stats.PacketsRecv, stats.PacketLoss)
	fmt.Printf("round-trip min/avg/max/stddev = %v/%v/%v/%v\n",
		stats.MinRtt, stats.AvgRtt, stats.MaxRtt, stats.StdDevRtt)
}

fmt.Printf("PING %s (%s):\n", pinger.Addr(), pinger.IPAddr())
pinger.Run()

It sends ICMP packet(s) and waits for a response. If it receives a response, it calls the "receive" callback. When it's finished, it calls the "finish" callback.

For a full ping example, see "cmd/ping/ping.go".

Index

• type Packet
• type Pinger
  • func NewPinger(privileged bool) (*Pinger, error)
  • func (p *Pinger) Addr() string
  • func (p *Pinger) Privileged() bool
  • func (p *Pinger) Recv()
  • func (p *Pinger) Send(addr string, timeout int64) (*Statistics, error)
  • func (p *Pinger) SetPrivileged(privileged bool)
  • func (p *Pinger) Statistics() *Statistics
• type SendEntries
  • func (s *SendEntries) Add(addr string, timeout int64) *SendEntry
  • func (s *SendEntries) Del(item string)
  • func (s *SendEntries) FindById(id int) *SendEntry
  • func (s *SendEntries) Get(item string) *SendEntry
  • func (s *SendEntries) GetTimeouts() []*SendEntry
  • func (s *SendEntries) Set(item string, entry *SendEntry)
• type SendEntry
• type Statistics

Types

type Packet

type Packet struct {
	// Rtt is the round-trip time it took to ping.
	Rtt time.Duration

	// IPAddr is the address of the host being pinged.
	IPAddr *net.IPAddr

	// NBytes is the number of bytes in the message.
	Nbytes int

	// Seq is the ICMP sequence number.
	Seq int
}

Packet represents a received and processed ICMP echo packet.

type Pinger

type Pinger struct {
	// Interval is the wait time between each packet send. Default is 1s.
	Interval time.Duration

	// Timeout specifies a timeout before ping exits, regardless of how many
	// packets have been received.
	Timeout time.Duration

	// Count tells pinger to stop after sending (and receiving) Count echo
	// packets. If this option is not specified, pinger will operate until
	// interrupted.
	Count int

	// Debug runs in debug mode
	Debug bool

	// Number of packets sent
	PacketsSent int

	// Number of packets received
	PacketsRecv int

	// Size of packet being sent
	Size int
	// contains filtered or unexported fields
}

Pinger represents ICMP packet sender/receiver

func NewPinger

func NewPinger(privileged bool) (*Pinger, error)

NewPinger returns a new Pinger struct pointer

func (*Pinger) Addr

func (p *Pinger) Addr() string

Addr returns the string ip address of the target host.

func (*Pinger) Privileged

func (p *Pinger) Privileged() bool

Privileged returns whether pinger is running in privileged mode.

func (*Pinger) Recv

func (p *Pinger) Recv()

func (*Pinger) Send

func (p *Pinger) Send(addr string, timeout int64) (*Statistics, error)

func (*Pinger) SetPrivileged

func (p *Pinger) SetPrivileged(privileged bool)

SetPrivileged sets the type of ping pinger will send. false means pinger will send an "unprivileged" UDP ping. true means pinger will send a "privileged" raw ICMP ping. NOTE: setting to true requires that it be run with super-user privileges.

func (*Pinger) Statistics

func (p *Pinger) Statistics() *Statistics

Statistics returns the statistics of the pinger. This can be run while the pinger is running or after it is finished. OnFinish calls this function to get it's finished statistics.

type SendEntries

type SendEntries struct {
	// contains filtered or unexported fields
}

func (*SendEntries) Add

func (s *SendEntries) Add(addr string, timeout int64) *SendEntry

func (*SendEntries) Del

func (s *SendEntries) Del(item string)

func (*SendEntries) FindById

func (s *SendEntries) FindById(id int) *SendEntry

func (*SendEntries) Get

func (s *SendEntries) Get(item string) *SendEntry

func (*SendEntries) GetTimeouts

func (s *SendEntries) GetTimeouts() []*SendEntry

func (*SendEntries) Set

func (s *SendEntries) Set(item string, entry *SendEntry)

type SendEntry

type SendEntry struct {
	// contains filtered or unexported fields
}

type Statistics

type Statistics struct {
	// PacketsRecv is the number of packets received.
	PacketsRecv int

	// PacketsSent is the number of packets sent.
	PacketsSent int

	// PacketLoss is the percentage of packets lost.
	PacketLoss float64

	// IPAddr is the address of the host being pinged.
	IPAddr *net.IPAddr

	// Addr is the string address of the host being pinged.
	Addr string

	// Rtts is all of the round-trip times sent via this pinger.
	Rtt time.Duration
}

Statistics represent the stats of a currently running or finished pinger operation.