--- /dev/null
+NAME
+ Net::Ping - check a remote host for reachability
+
+ $Id: Ping.pm,v 1.13 2001/12/07 02:18:44 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 four different protocols to use for the ping. The
+ "udp" protocol is the default. Note that a live remote host may still
+ fail to be pingable by one or more of these protocols. For example,
+ www.microsoft.com is generally alive but not pingable.
+
+ 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. It should be borne in
+ mind that, for a udp ping, a host will be reported as unreachable if it
+ is not running the appropriate echo service. For Unix-like systems see
+ the inetd(8) manpage for more information.
+
+ 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.
+
+ If the "external" protocol is specified, the ping() method attempts to
+ use the `Net::Ping::External' module to ping the remote host.
+ `Net::Ping::External' interfaces with your system's default `ping'
+ utility to perform the ping, and generally produces relatively accurate
+ results. If `Net::Ping::External' if not installed on your system,
+ specifying the "external" protocol will result in an error.
+
+ 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->open($host);
+ When you are using the stream protocol, this call pre-opens the tcp
+ socket. It's only necessary to do this if you want to provide a
+ different timeout when creating the connection, or remove the
+ overhead of establishing the connection from the first ping. If you
+ don't call `open()', the connection is automatically opened the
+ first time `ping()' is called. This call simply does nothing if you
+ are using any protocol other than stream.
+
+ $p->open($host);
+ When you are using the stream protocol, this call pre-opens the tcp
+ socket. It's only necessary to do this if you want to provide a
+ different timeout when creating the connection, or remove the
+ overhead of establishing the connection from the first ping. If you
+ don't call `open()', the connection is automatically opened the
+ first time `ping()' is called. This call simply does nothing if you
+ are using any protocol other than stream.
+
+ $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 other protocols do not require special privileges,
+ but not all network devices implement tcp or udp echo.
+
+ 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. tcp is slightly better
+ at indicating the health of a system than icmp because it uses more of
+ the networking stack to respond.
+
+ 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)
+ Current maintainer Net::Ping base code:
+ colinm@cpan.org (Colin McMillen)
+
+ Stream protocol:
+ bronson@trestle.com (Scott Bronson)
+
+ Original pingecho():
+ karrer@bernina.ethz.ch (Andreas Karrer)
+ pmarquess@bfsec.bt.co.uk (Paul Marquess)
+
+ Original Net::Ping author:
+ mose@ns.ccsn.edu (Russell Mosemann)
+
+ Compatibility porting:
+ bbb@cpan.org (Rob Brown)
+
+COPYRIGHT
+ Copyright (c) 2001, Colin McMillen. All rights reserved. Copyright (c)
+ 2001, Rob Brown. All rights reserved.
+
+ This program is free software; you may redistribute it and/or modify it
+ under the same terms as Perl itself.
+
--- /dev/null
+BEGIN {
+ if ($ENV{PERL_CORE}) {
+ unless ($ENV{PERL_TEST_Net_Ping}) {
+ print "1..0 # Skip: network dependent test\n";
+ exit;
+ }
+ chdir 't' if -d 't';
+ @INC = qw(../lib);
+ }
+}
+
+# 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. If you know you do not have a direct
+# connection to remote networks, but you still want the tests
+# to pass, use the following:
+#
+# $ PERL_CORE=1 make test
+
+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");
projects / p5sagit/p5-mst-13.2.git / commitdiff