Documentation
¶
Overview ¶
Package ping is an ICMP ping library seeking to emulate the unix "ping" command.
Here is a very simple example that sends and receives 3 packets:
pinger, err := ping.NewPinger("www.google.com") if err != nil { panic(err) } pinger.PacketLimit = 3 pinger.Run() // blocks until finished stats := pinger.Statistics // get send/receive/rtt stats
For a full ping example, see "cmd/ping/ping.go".
Index ¶
- Constants
- type Packet
- type Pinger
- type Statistics
- func (s *Statistics) Add(rtt time.Duration)
- func (s *Statistics) Counters() (recv, sent int)
- func (s *Statistics) Durations() (min, mean, max time.Duration)
- func (s *Statistics) IncSent()
- func (s *Statistics) PacketLoss() float64
- func (s *Statistics) StandardDeviation() time.Duration
- func (s *Statistics) Variance() time.Duration
Constants ¶
const ( DefaultSize = 8 DefaultInterval = 1 * time.Second DefaultTimeLimit = 100000 * time.Second )
Default values for the Pinger
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 // Host is the string address of the host being pinged. Host string // Source is the source address the ping was sent from. Source string // NBytes is the number of bytes in the message. Size 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 // TimeLimit specifies a timeout before ping exits, regardless of how many // packets have been received. TimeLimit time.Duration // PacketLimit tells pinger to stop after sending (and receiving) PacketLimit echo // packets. If this option is not specified, pinger will operate until // interrupted. PacketLimit int // Number of packets sent Sent int // Number of packets received Received int // OnReceive is called when Pinger receives and processes a packet OnReceive func(*Packet) // OnFinish is called when Pinger exits OnFinish func(*Statistics) // Size of packet being sent Size int // Resolved IP Address IPAddr *net.IPAddr // Host to ping Host string // Resolved source IP Address SourceAddr *net.IPAddr // Source host Source string // Statistics returns the statistics of the pinger. This can be run while the // pinger is running or after it is finished. OnFinish uses this to get its // finished statistics. // Access is thread-safe as long as Statistics is set before calling Run(). Statistics *Statistics // contains filtered or unexported fields }
Pinger represents ICMP packet sender/receiver. It is not entirely thread-safe. Troublesome attributes are marked as such.
func NewPinger ¶
NewPinger returns a new Pinger struct pointer with initialized statistics. The source address may be an empty string.
func (*Pinger) Run ¶
Run runs the pinger. This is a blocking function that will exit when it's done. If PacketLimit or Interval are not specified, it will run continuously until it is interrupted.
type Statistics ¶
type Statistics struct { sync.Mutex // Received is the number of packets received. Received int // Sent is the number of packets sent. Sent int // IPAddr is the address of the host being pinged. IPAddr *net.IPAddr // Host is the hostname of the host being pinged. Host string // Source is the source hostname or IP pings are sent from. Source string // Min is the minimum round-trip time. Min time.Duration // Max is the maximum round-trip time. Max time.Duration // Mean is the average round-trip time. Mean time.Duration // Sum is the of all round-trip times. Sum time.Duration // contains filtered or unexported fields }
Statistics represent the stats of a currently running or finished pinger operation. All methods on *Statistics are thread safe, but field access is not.
func NewStatistics ¶
func NewStatistics(addr string, ipAddr *net.IPAddr) *Statistics
NewStatistics returns an initialised Statistics struct pointer
func (*Statistics) Add ¶
func (s *Statistics) Add(rtt time.Duration)
Add updates the statistics with this new value
func (*Statistics) Counters ¶
func (s *Statistics) Counters() (recv, sent int)
Counters returns the counter values of the statistics.
func (*Statistics) Durations ¶
func (s *Statistics) Durations() (min, mean, max time.Duration)
Durations returns the durations values of the statistics.
func (*Statistics) PacketLoss ¶
func (s *Statistics) PacketLoss() float64
PacketLoss returns the packet loss ratio.
func (*Statistics) StandardDeviation ¶
func (s *Statistics) StandardDeviation() time.Duration
StandardDeviation returns the standard deviation of the round-trip times sent via this pinger.
func (*Statistics) Variance ¶
func (s *Statistics) Variance() time.Duration
Variance returns the variance of the round-trip times sent via the pinger.