Net::Ping::External(3pm)

1External(3)           User Contributed Perl Documentation          External(3)
2
3
4

NAME

6       Net::Ping::External - Cross-platform Perl interface to "ping" utilities
7

SYNOPSIS

9       In general:
10
11         use Net::Ping::External qw(ping);
12         ping(%options);
13
14       Some examples:
15
16         use Net::Ping::External qw(ping);
17
18         # Ping a single host
19         my $alive = ping(host => "127.0.0.1");
20         print "127.0.0.1 is online" if $alive;
21
22         # Or a list of hosts
23         my @hosts = qw(127.0.0.1 127.0.0.2 127.0.0.3 127.0.0.4);
24         my $num_alive = 0;
25         foreach (@hosts) {
26           $alive = ping(hostname => $_, timeout => 5);
27           print "$_ is alive!\n" if $alive;
28           $num_alive++;
29         }
30         print "$num_alive hosts are alive.\n";
31
32         # Using all the fancy options:
33         ping(hostname => "127.0.0.1", count => 5, size => 1024, timeout => 3);
34

DESCRIPTION

36       Net::Ping::External is a module which interfaces with the "ping"
37       command on many systems. It presently provides a single function,
38       "ping()", that takes in a hostname and (optionally) a timeout and
39       returns true if the host is alive, and false otherwise. Unless you have
40       the ability (and willingness) to run your scripts as the superuser on
41       your system, this module will probably provide more accurate results
42       than Net::Ping will.
43
44       Why?
45
46       •   ICMP ping is the most reliable way to tell whether a remote host is
47           alive.
48
49       •   However, Net::Ping cannot use an ICMP ping unless you are running
50           your script with privileged (AKA "root") access.
51
52       •   The system's "ping" command uses ICMP and does not usually require
53           privileged access.
54
55       •   While it is relatively trivial to write a Perl script that parses
56           the output of the "ping" command on a given system, the aim of this
57           module is to encapsulate this functionality and provide a single
58           interface for it that works on many systems.
59
60   ping() OPTIONS
61       This module is still "alpha"; it is expected that more options to the
62       "ping()" function will be added soon.
63
64       •   "host, hostname"
65
66           The hostname (or dotted-quad IP address) of the remote host you are
67           trying to ping. You must specify either the "hostname" option or
68           the "ip" option.
69
70           "host" and "hostname" are synonymous.
71
72       •   "ip"
73
74           A packed bit-string representing the 4-byte packed IP address (as
75           returned by "Socket.pm"'s "inet_aton()" function) of the host that
76           you would like to ping.
77
78       •   "timeout"
79
80           The maximum amount of time, in seconds, that "ping()" will wait for
81           a response.  If the remote system does not respond before the
82           timeout has elapsed, "ping()" will return false.
83
84           Default value: 5.
85
86       •   "count"
87
88           The number of ICMP ping packets to send to the remote host.
89           Eventually, Net::Ping::External will return the number of packets
90           that were acknowledged by the remote host; for now, however,
91           "ping()" still returns just true or false.
92
93           Default value: 1.
94
95       •   "size"
96
97           Specifies the number of data bytes to be sent.  The default is 56,
98           which translates into 64 ICMP data bytes when combined with the 8
99           bytes of ICMP header data.
100
101           Default value: 56.
102
103   SUPPORTED PLATFORMS
104       Support currently exists for interfacing with the standard ping
105       utilities on the following systems. Please note that the path to the
106       `ping' should be somewhere in your PATH environment variable (or your
107       system's closest equivalent thereof.) Otherwise, Net::Ping::External
108       will be unable to locate your system's `ping' command.
109
110       •   Win32
111
112           Tested OK on Win98, Win XP. It should work on other Windows systems
113           as well.
114
115       •   Cygwin
116
117           Tested OK on Cygwin 1.5.21. Problem is that we may be running
118           windows ping.  They have different options.
119
120       •   Linux
121
122           Tested OK on Debian 2.2 and Redhat 6.2. It appears that different
123           versions of Linux use different versions of ping, which support
124           different options.  Not sure how I'm going to resolve this yet; for
125           now, all the options but "count" are disabled.
126
127       •   BSD
128
129           Tested OK on OpenBSD 2.7 and 3.0, Netbsd 1.5.3, Freebsd 4.6.2, 5.4.
130           Needs testing for BSDi.
131
132       •   Solaris
133
134           Tested OK on Solaris 2.6 and 2.7.
135
136       •   IRIX
137
138           Tested OK on IRIX 6.5.
139
140       •   AIX, DEC OSF, UNICOSMK, NeXTStep, HP-UX, BSD/OS (BSDi), BeOS
141
142           Support for these systems is integrated into this module but none
143           have been tested yet. If you have successful or unsuccessful test
144           results for any of these systems, please send them to me. On some
145           of these systems, some of the arguments may not be supported. If
146           you'd like to see better support on your system, please e-mail me.
147
148       More systems will be added as soon as any users request them. If your
149       system is not currently supported, e-mail me; adding support to your
150       system is probably trivial.
151

BUGS

153       This module should be considered beta. Bugs may exist. Although no
154       specific bugs are known at this time, the module could use testing on a
155       greater variety of systems.
156
157       See the warning below.
158

WARNING

160       This module calls whatever "ping" program it first finds in your PATH
161       environment variable. If your PATH contains a trojan "ping" program,
162       this module will call that program. This involves a small amount of
163       risk, but no more than simply typing "ping" at a system prompt.
164
165       Beware Greeks bearing gifts.
166

AUTHOR

168       Alexandr Ciornii (alexchorny AT gmail.com), Colin McMillen (colinm AT
169       cpan.org)
170
171       This library is free software; you can redistribute it and/or modify it
172       under the same terms as Perl itself.
173

CREDITS

175       Dan Moore contributed command-line options and code for NeXT, BeOS, HP-
176       UX, and BSD/OS.
177
178       Jarkko Hietaniemi contributed a huge list of command-line options and
179       results for the `ping' command on 9 different systems.
180
181       Randy Moore contributed several patches for Win32 support.
182
183       Marc-Andre Dumas contributed a patch for FreeBSD support.
184
185       Jonathan Stowe fixed a bug in 0.09 that prevented the module from
186       running on some systems.
187
188       Numerous people sent in a patch to fix a bug in 0.10 that broke ping on
189       Windows systems.
190
191       Peter N. Lewis contributed a patch that works correctly on Mac OS X
192       10.2 (and hopefully other versions as well).
193