External(3) User Contributed Perl Documentation External(3)NAMENet::Ping::External - Cross-platform interface to ICMP "ping" utilities
SYNOPSIS
In general:
use Net::Ping::Externalqw(ping);
ping(%options);
Some examples:
use Net::Ping::Externalqw(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);
DESCRIPTIONNet::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.
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.
SUPPORTED PLATFORMS
Support currently exists for interfacing with the standard ping
utilities on the following systems. Please note that the path to the
`ping' should be somewhere in your PATH environment variable (or your
system's closest equivalent thereof.) Otherwise, Net::Ping::External
will be unable to locate your system's `ping' command.
· Win32
Tested OK on Win98, Win XP. It should work on other Windows systems
as well.
· Cygwin
Tested OK on Cygwin 1.5.21. Problem is that we may be running
windows ping. They have different options.
· Linux
Tested OK on Debian 2.2 and Redhat 6.2. It appears that different
versions of Linux use different versions of ping, which support
different options. Not sure how I'm going to resolve this yet; for
now, all the options but "count" are disabled.
· BSD
Tested OK on OpenBSD 2.7 and 3.0, Netbsd 1.5.3, Freebsd 4.6.2, 5.4.
Needs testing for BSDi.
· Solaris
Tested OK on Solaris 2.6 and 2.7.
· IRIX
Tested OK on IRIX 6.5.
· AIX, DEC OSF, UNICOSMK, NeXTStep, HP-UX, BSD/OS (BSDi), BeOS
Support for these systems is integrated into this module but none
have been tested yet. If you have successful or unsuccessful test
results for any of these systems, please send them to me. On some
of these systems, some of the arguments may not be supported. If
you'd like to see better support on your system, please e-mail me.
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.
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
Alexandr Ciornii (alexchorny AT gmail.com), Colin McMillen (colinm AT
cpan.org)
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
CREDITS
Dan Moore contributed command-line options and code for NeXT, BeOS, HP-
UX, and BSD/OS.
Jarkko Hietaniemi contributed a huge list of command-line options and
results for the `ping' command on 9 different systems.
Randy Moore contributed several patches for Win32 support.
Marc-Andre Dumas contributed a patch for FreeBSD support.
Jonathan Stowe fixed a bug in 0.09 that prevented the module from
running on some systems.
Numerous people sent in a patch to fix a bug in 0.10 that broke ping on
Windown systems.
Peter N. Lewis contributed a patch that works correctly on Mac OS X
10.2 (and hopefully other versions as well).
SEE ALSO
Net::Ping
perl v5.14.1 2007-02-05 External(3)
