Documentation
¶
Overview ¶
Package ping provides an api for efficiently pinging lots of hosts using ICMP echos.
Index ¶
- Variables
- func HostFlood(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, ...) error
- func HostInterval(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, ...) error
- func IPFlood(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, ...) error
- func IPInterval(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, ...) error
- func SetWorkers(n int)
- type HandleFunc
- type HostConn
- type IPConn
- type Ping
- type Socket
- func (s *Socket) HostFlood(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, ...) error
- func (s *Socket) HostInterval(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, ...) error
- func (s *Socket) HostOnce(host string, timeout time.Duration) (*Ping, error)
- func (s *Socket) IPFlood(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, ...) error
- func (s *Socket) IPInterval(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, ...) error
- func (s *Socket) IPOnce(dst *net.IPAddr, timeout time.Duration) (*Ping, error)
- func (s *Socket) NewHostConn(host string, reResolveEvery int, handle HandleFunc, timeout time.Duration) *HostConn
- func (s *Socket) NewIPConn(dst *net.IPAddr, handle HandleFunc, timeout time.Duration) (*IPConn, error)
- func (s *Socket) SetWorkers(n int)
Constants ¶
This section is empty.
Variables ¶
var ErrNoIDs = socket.ErrNoIDs
ErrNoIDs is returned when there are no icmp ids left to use
Either you are trying to ping the same host with more than 2^16 connections or you are on windows and are running more than 2^16 connections total
var ErrNotRunning = conn.ErrNotRunning
ErrNotRunning is returned if a ping is set to a closed connection.
var ErrTimedOut = socket.ErrTimedOut
ErrTimedOut is returned when a ping times out
Functions ¶
func HostFlood ¶
func HostFlood(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, count int, timeout time.Duration) error
HostFlood performs HostFlood using the default socket.
func HostInterval ¶
func HostInterval(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, count int, interval, timeout time.Duration) error
HostInterval performs HostInterval using the default socket.
func IPFlood ¶
func IPFlood(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, timeout time.Duration) error
IPFlood performs IPFlood using the default socket.
Types ¶
type HandleFunc ¶
HandleFunc is a function to handle responses and errors
type HostConn ¶
type HostConn struct {
// contains filtered or unexported fields
}
HostConn is an ICMP connection based on hostname
Pings run from a HostConn can be configured to periodically re-resolve
func NewHostConn ¶
func NewHostConn(host string, reResolveEvery int, handle HandleFunc, timeout time.Duration) *HostConn
NewHostConn returns a new HostConn
func (*HostConn) Close ¶
Close closes the host connection. Further attempts to send pings via this connection will panic.
type IPConn ¶
type IPConn struct {
// contains filtered or unexported fields
}
IPConn holds a connection to a destination ip address
func (*IPConn) Drain ¶
func (c *IPConn) Drain()
Drain blocks until all outstanding pings have been handled.
type Ping ¶
type Ping struct {
// Host is the hostname that was pinged
Host string
// Src is the source IP. This is probably 0.0.0.0 for sent packets, but a
// specific IP on the sending host for recieved packets
Src *net.IPAddr
// Dst is the destination IP.
// This will be nil for recieved packets on windows. The reason is that
// the recieve function does not provide the source address
// on windows ICMP messages are mathed only by the 16 bit ICMP id.
Dst *net.IPAddr
// ID is the ICMP ID
ID int
// Seq is the ICMP Sequence
Seq int
// Count is the count of this ICMP
Count int
// Sent is the time the echo was sent
Sent time.Time
// Recieved is the time the echo was recieved.
Recieved time.Time
// TimeOut is timeout duration
TimeOut time.Duration
// TTL is the ttl on the recieved packet.
// This is not supported on windows and will always be zero
TTL int
// Len is the length of the recieved packet
Len int
}
Ping is an ICMP packet that has been received
func (*Ping) TimeOutTime ¶
TimeOutTime returns the time this ping times out
type Socket ¶
type Socket struct {
// contains filtered or unexported fields
}
Socket is a raw socket connection (one for ipv4 and one for ipv6).
Sockets are only actively listening when there are one or more open connections ¶
Sockets must be created via NewSocket ¶
In most cases using DefaultSocket() is appropriate
func (*Socket) HostFlood ¶
func (s *Socket) HostFlood(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, count int, timeout time.Duration) error
HostFlood works like HostInterval, but instead of sending on an interval, the next ping is sent as soon as the previous ping is handled.
func (*Socket) HostInterval ¶
func (s *Socket) HostInterval(ctx context.Context, host string, reResolveEvery int, handler HandleFunc, count int, interval, timeout time.Duration) error
HostInterval sends a ping each interval up to count pings or until ctx is canceled.
If an interval of zero is specified, it will send pings as fast as possible. When there are 2^16 pending pings which have not received a reply, or timed out sending will block. This may be a limiting factor in how quickly pings can be sent.
If a timeout of zero is specifed, pings will never time out.
If a count of zero is specified, interval will continue to send pings until ctx is canceled.
func (*Socket) HostOnce ¶
HostOnce sends a single echo request and returns, it blocks until a reply is recieved or the ping times out
Zero is no timeout and IPOnce will block forever if a reply is never recieved ¶
It is not recommended to use IPOnce in a loop, use Interval, or create a Conn and call SendPing() in a loop
func (*Socket) IPFlood ¶
func (s *Socket) IPFlood(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, timeout time.Duration) error
IPFlood continuously sends pings, sending the next ping as soon as the previous one is replied or times out.
func (*Socket) IPInterval ¶
func (s *Socket) IPInterval(ctx context.Context, dst *net.IPAddr, handler HandleFunc, count int, interval, timeout time.Duration) error
IPInterval sends a ping each interval up to count pings or until ctx is canceled.
If an interval of zero is specified, it will send pings as fast as possible. When there are 2^16 pending pings which have not received a reply, or timed out sending will block. This may be a limiting factor in how quickly pings can be sent.
If a timeout of zero is specifed, pings will never time out.
If a count of zero is specified, interval will continue to send pings until ctx is canceled.
func (*Socket) IPOnce ¶
IPOnce sends a single echo request and returns, it blocks until a reply is recieved or the ping times out
Zero is no timeout and IPOnce will block forever if a reply is never recieved ¶
It is not recommended to use IPOnce in a loop, use Interval, or create a Conn and call SendPing() in a loop
func (*Socket) NewHostConn ¶
func (s *Socket) NewHostConn(host string, reResolveEvery int, handle HandleFunc, timeout time.Duration) *HostConn
NewHostConn returns a new HostConn
func (*Socket) NewIPConn ¶
func (s *Socket) NewIPConn(dst *net.IPAddr, handle HandleFunc, timeout time.Duration) (*IPConn, error)
NewIPConn creates a new connection
func (*Socket) SetWorkers ¶
SetWorkers sets a number of workers to process incoming packets and run handlers
Consider increasing this if your handlers take a long time to return.
A higher number of workers will prevent dropping replies, at the cost of more memory and cpu usage.
This change will only take effect once all open connections are closed
Source Files
Directories