NAME

Net::Ping::External - Cross-platform interface to ICMP "ping" utilities

SYNOPSIS

In general:

use Net::Ping::External qw(ping);
ping(%options);

Some examples:

use Net::Ping::External qw(ping);

# Ping a single host
my $alive = ping(host => "127.0.0.1");
print "127.0.0.1 is online" if $alive;

# Or a list of hosts
my @hosts = qw(127.0.0.1 127.0.0.2 127.0.0.3 127.0.0.4);
my $num_alive = 0;
foreach (@hosts) {
  $alive = ping(hostname => $_, timeout => 5);
  print "$_ is alive!\n" if $alive;
  $num_alive++;
}
print "$num_alive hosts are alive.\n";

# Using all the fancy options:
ping(hostname => "127.0.0.1", count => 5, size => 1024, timeout => 3);

DESCRIPTION

Net::Ping::External is a module which interfaces with the "ping" command on many systems. It presently provides a single function, ping(), that takes in a hostname and (optionally) a timeout and returns true if the host is alive, and false otherwise. Unless you have the ability (and willingness) to run your scripts as the superuser on your system, this module will probably provide more accurate results than Net::Ping will.

Why?

• ICMP ping is the most reliable way to tell whether a remote host is alive.

• However, Net::Ping cannot use an ICMP ping unless you are running your script with privileged (AKA "root") access.

• The system's "ping" command uses ICMP and does not usually require privileged access.

• While it is relatively trivial to write a Perl script that parses the output of the "ping" command on a given system, the aim of this module is to encapsulate this functionality and provide a single interface for it that works on many systems.

Support currently exists for interfacing with the standard ping utilities on the following systems:

• Win32

  Tested OK on Win98. It should work on other Windows systems as well.

• Linux

  Tested OK on Debian 2.2 and Redhat 6.2, although Linux ping appears not to support the "timeout" option. If you are using this module on a different flavor of Linux, please test it and let me know of the results.

• BSD

  Tested OK on OpenBSD 2.7. Needs testing for FreeBSD, NetBSD, and BSDi.

• Solaris

  Tested OK on Solaris 2.6 and 2.7.

• IRIX

  Tested OK on IRIX 6.5.

• AIX

  I have been informed that this module should work on AIX as well. No official test results yet.

More systems will be added as soon as any users request them. If your system is not currently supported, e-mail me; adding support to your system is probably trivial.

ping() options

This module is still "alpha"; it is expected that more options to the ping() function will be added soon.

• host, hostname

  The hostname (or dotted-quad IP address) of the remote host you are trying to ping. You must specify either the "hostname" option or the "ip" option.

  "host" and "hostname" are synonymous.

• ip

  A packed bit-string representing the 4-byte packed IP address (as returned by Socket.pm's inet_aton() function) of the host that you would like to ping.

• timeout

  The maximum amount of time, in seconds, that ping() will wait for a response. If the remote system does not respond before the timeout has elapsed, ping() will return false.

  Default value: 5.

• count

  The number of ICMP ping packets to send to the remote host. Eventually, Net::Ping::External will return the number of packets that were acknowledged by the remote host; for now, however, ping() still returns just true or false.

  Default value: 1.

• size

  Specifies the number of data bytes to be sent. The default is 56, which translates into 64 ICMP data bytes when combined with the 8 bytes of ICMP header data.

  Default value: 56.

BUGS

This module should be considered alpha. Bugs may exist. Although no specific bugs are known at this time, the module could use testing on a greater variety of systems.

See the warning below.

WARNING

This module calls whatever "ping" program it first finds in your PATH environment variable. If your PATH contains a trojan "ping" program, this module will call that program. This involves a small amount of risk, but no more than simply typing "ping" at a system prompt.

Beware Greeks bearing gifts.

AUTHOR

Colin McMillen (colinm@cpan.org)

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Net::Ping