Upgrade to Net::Ping 2.06.

p4raw-id: //depot/perl@13173

7 files changed, 274 insertions, 0 deletions

diff --git a/lib/Net/Ping/CHANGES b/lib/Net/Ping/CHANGES
new file mode 100644
index 0000000000..1d53d5590a
--- /dev/null
+++ b/lib/Net/Ping/CHANGES
@@ -0,0 +1,17 @@
+CHANGES
+-------
+
+2.05  Nov 18 20:00 2001
+	- Added test suite
+
+2.04  Nov 16 16:00 2001
+	- Added CHANGES and README to tarball.
+	- No functional changes.
+
+2.03  Nov 15 12:00 2001
+	- Portability adjustments to ping_tcp()
+	  made by Rob Brown to work with most
+	  default systems.
+
+2.02  Sep 27 12:00 1996
+	- Magic version by Russell Mosemann from CPAN
diff --git a/lib/Net/Ping/README b/lib/Net/Ping/README
new file mode 100644
index 0000000000..19e3bb3397
--- /dev/null
+++ b/lib/Net/Ping/README
@@ -0,0 +1,158 @@
+NAME
+    Net::Ping - check a remote host for reachability
+
+    $Id: Ping.pm,v 1.5 2001/11/19 09:44:18 rob Exp $
+
+SYNOPSIS
+        use Net::Ping;
+
+        $p = Net::Ping->new();
+        print "$host is alive.\n" if $p->ping($host);
+        $p->close();
+
+        $p = Net::Ping->new("icmp");
+        foreach $host (@host_array)
+        {
+            print "$host is ";
+            print "NOT " unless $p->ping($host, 2);
+            print "reachable.\n";
+            sleep(1);
+        }
+        $p->close();
+
+        $p = Net::Ping->new("tcp", 2);
+        # Try connecting to the www port instead of the echo port
+        $p->{port_num} = getservbyname("http", "tcp");
+        while ($stop_time > time())
+        {
+            print "$host not reachable ", scalar(localtime()), "\n"
+                unless $p->ping($host);
+            sleep(300);
+        }
+        undef($p);
+
+        # For backward compatibility
+        print "$host is alive.\n" if pingecho($host);
+
+DESCRIPTION
+    This module contains methods to test the reachability of remote hosts on
+    a network. A ping object is first created with optional parameters, a
+    variable number of hosts may be pinged multiple times and then the
+    connection is closed.
+
+    You may choose one of three different protocols to use for the ping.
+    With the "tcp" protocol the ping() method attempts to establish a
+    connection to the remote host's echo port. If the connection is
+    successfully established, the remote host is considered reachable. No
+    data is actually echoed. This protocol does not require any special
+    privileges but has higher overhead than the other two protocols.
+
+    Specifying the "udp" protocol causes the ping() method to send a udp
+    packet to the remote host's echo port. If the echoed packet is received
+    from the remote host and the received packet contains the same data as
+    the packet that was sent, the remote host is considered reachable. This
+    protocol does not require any special privileges.
+
+    If the "icmp" protocol is specified, the ping() method sends an icmp
+    echo message to the remote host, which is what the UNIX ping program
+    does. If the echoed message is received from the remote host and the
+    echoed information is correct, the remote host is considered reachable.
+    Specifying the "icmp" protocol requires that the program be run as root
+    or that the program be setuid to root.
+
+  Functions
+
+    Net::Ping->new([$proto [, $def_timeout [, $bytes]]]);
+        Create a new ping object. All of the parameters are optional. $proto
+        specifies the protocol to use when doing a ping. The current choices
+        are "tcp", "udp" or "icmp". The default is "udp".
+
+        If a default timeout ($def_timeout) in seconds is provided, it is
+        used when a timeout is not given to the ping() method (below). The
+        timeout must be greater than 0 and the default, if not specified, is
+        5 seconds.
+
+        If the number of data bytes ($bytes) is given, that many data bytes
+        are included in the ping packet sent to the remote host. The number
+        of data bytes is ignored if the protocol is "tcp". The minimum (and
+        default) number of data bytes is 1 if the protocol is "udp" and 0
+        otherwise. The maximum number of data bytes that can be specified is
+        1024.
+
+    $p->ping($host [, $timeout]);
+        Ping the remote host and wait for a response. $host can be either
+        the hostname or the IP number of the remote host. The optional
+        timeout must be greater than 0 seconds and defaults to whatever was
+        specified when the ping object was created. If the hostname cannot
+        be found or there is a problem with the IP number, undef is
+        returned. Otherwise, 1 is returned if the host is reachable and 0 if
+        it is not. For all practical purposes, undef and 0 and can be
+        treated as the same case.
+
+    $p->close();
+        Close the network connection for this ping object. The network
+        connection is also closed by "undef $p". The network connection is
+        automatically closed if the ping object goes out of scope (e.g. $p
+        is local to a subroutine and you leave the subroutine).
+
+    pingecho($host [, $timeout]);
+        To provide backward compatibility with the previous version of
+        Net::Ping, a pingecho() subroutine is available with the same
+        functionality as before. pingecho() uses the tcp protocol. The
+        return values and parameters are the same as described for the
+        ping() method. This subroutine is obsolete and may be removed in a
+        future version of Net::Ping.
+
+WARNING
+    pingecho() or a ping object with the tcp protocol use alarm() to
+    implement the timeout. So, don't use alarm() in your program while you
+    are using pingecho() or a ping object with the tcp protocol. The udp and
+    icmp protocols do not use alarm() to implement the timeout.
+
+NOTES
+    There will be less network overhead (and some efficiency in your
+    program) if you specify either the udp or the icmp protocol. The tcp
+    protocol will generate 2.5 times or more traffic for each ping than
+    either udp or icmp. If many hosts are pinged frequently, you may wish to
+    implement a small wait (e.g. 25ms or more) between each ping to avoid
+    flooding your network with packets.
+
+    The icmp protocol requires that the program be run as root or that it be
+    setuid to root. The tcp and udp protocols do not require special
+    privileges, but not all network devices implement the echo protocol for
+    tcp or udp.
+
+    Local hosts should normally respond to pings within milliseconds.
+    However, on a very congested network it may take up to 3 seconds or
+    longer to receive an echo packet from the remote host. If the timeout is
+    set too low under these conditions, it will appear that the remote host
+    is not reachable (which is almost the truth).
+
+    Reachability doesn't necessarily mean that the remote host is actually
+    functioning beyond its ability to echo packets.
+
+    Because of a lack of anything better, this module uses its own routines
+    to pack and unpack ICMP packets. It would be better for a separate
+    module to be written which understands all of the different kinds of
+    ICMP packets.
+
+AUTHOR(S)
+      Original pingecho():
+        Andreas Karrer (karrer@bernina.ethz.ch)
+        Paul Marquess (pmarquess@bfsec.bt.co.uk)
+
+      Net::Ping base code:
+        Russell Mosemann (mose@ns.ccsn.edu)
+
+      Compatibility porting so ping_tcp()
+      can work with most remote systems:
+        Rob Brown (rob@roobik.com)
+
+COPYRIGHT
+    Copyright (c) 2001 Rob Brown. All rights reserved.
+
+    Copyright (c) 1996 Russell Mosemann. All rights reserved.
+
+    This program is free software; you may redistribute it and/or modify it
+    under the same terms as Perl itself.
+
diff --git a/lib/Net/Ping/t/100_load.t b/lib/Net/Ping/t/100_load.t
new file mode 100644
index 0000000000..d6a71e0235
--- /dev/null
+++ b/lib/Net/Ping/t/100_load.t
@@ -0,0 +1,19 @@
+# Before `make install' is performed this script should be runnable with
+# `make test'. After `make install' it should work as `perl test.t'
+
+######################### We start with some black magic to print on failure.
+
+use Test;
+BEGIN { plan tests => 1; $loaded = 0}
+END { ok $loaded;}
+
+# Just make sure everything compiles
+use Net::Ping;
+
+$loaded = 1;
+
+######################### End of black magic.
+
+# Insert your test code below (better if it prints "ok 13"
+# (correspondingly "not ok 13") depending on the success of chunk 13
+# of the test code):
diff --git a/lib/Net/Ping/t/110_icmp_inst.t b/lib/Net/Ping/t/110_icmp_inst.t
new file mode 100644
index 0000000000..2e67a5972a
--- /dev/null
+++ b/lib/Net/Ping/t/110_icmp_inst.t
@@ -0,0 +1,12 @@
+# Test to make sure object can be instantiated for icmp protocol.
+# Root access is required to actually perform icmp testing.
+
+use Test;
+use Net::Ping;
+plan tests => 2;
+
+# Everything loaded fine
+ok 1;
+
+my $p = new Net::Ping "tcp";
+ok !!$p;
diff --git a/lib/Net/Ping/t/120_udp_inst.t b/lib/Net/Ping/t/120_udp_inst.t
new file mode 100644
index 0000000000..ee53bd40bf
--- /dev/null
+++ b/lib/Net/Ping/t/120_udp_inst.t
@@ -0,0 +1,12 @@
+# Test to make sure object can be instantiated for udp protocol.
+# I do not know of any servers that support udp echo anymore.
+
+use Test;
+use Net::Ping;
+plan tests => 2;
+
+# Everything loaded fine
+ok 1;
+
+my $p = new Net::Ping "udp";
+ok !!$p;
diff --git a/lib/Net/Ping/t/130_tcp_inst.t b/lib/Net/Ping/t/130_tcp_inst.t
new file mode 100644
index 0000000000..6a547e161e
--- /dev/null
+++ b/lib/Net/Ping/t/130_tcp_inst.t
@@ -0,0 +1,11 @@
+# Test to make sure object can be instantiated for tcp protocol.
+
+use Test;
+use Net::Ping;
+plan tests => 2;
+
+# Everything loaded fine
+ok 1;
+
+my $p = new Net::Ping "tcp";
+ok !!$p;
diff --git a/lib/Net/Ping/t/200_ping_tcp.t b/lib/Net/Ping/t/200_ping_tcp.t
new file mode 100644
index 0000000000..3f5c6bc417
--- /dev/null
+++ b/lib/Net/Ping/t/200_ping_tcp.t
@@ -0,0 +1,45 @@
+# Remote network test using tcp protocol.
+#
+# NOTE:
+#   Network connectivity will be required for all tests to pass.
+#   Firewalls may also cause some tests to fail, so test it
+#   on a clear network.
+
+use Test;
+use Net::Ping;
+plan tests => 13;
+
+# Everything loaded fine
+ok 1;
+
+my $p = new Net::Ping "tcp";
+
+# new() worked?
+ok !!$p;
+
+# Test on the default port
+ok $p -> ping("localhost");
+
+# Change to use the more common web port.
+# This will pull from /etc/services on UNIX.
+# (Make sure getservbyname works in scalar context.)
+ok ($p -> {port_num} = (getservbyname("http", "tcp") || 80));
+
+# Test localhost on the web port
+ok $p -> ping("localhost");
+
+# Hopefully this is not a routeable host
+ok !$p -> ping("10.12.14.16");
+
+# Test a few remote servers
+# Hopefully they are up when the tests are run.
+
+ok $p -> ping("www.geocities.com");
+ok $p -> ping("ftp.geocities.com");
+
+ok $p -> ping("www.freeservers.com");
+ok $p -> ping("ftp.freeservers.com");
+
+ok $p -> ping("yahoo.com");
+ok $p -> ping("www.yahoo.com");
+ok $p -> ping("www.about.com");