2 # Net-Oping - lib/Net/Oping.pm
3 # Copyright (C) 2007 Olivier Fredj
4 # Copyright (C) 2008,2009 Florian octo Forster
6 # This program is free software; you can redistribute it and/or modify
7 # it under the terms of the GNU General Public License as published by
8 # the Free Software Foundation; only version 2 of the License is
11 # This program is distributed in the hope that it will be useful,
12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 # GNU General Public License for more details.
16 # You should have received a copy of the GNU General Public License
17 # along with this program; if not, write to the Free Software
18 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
21 # Olivier Fredj <ofredj at proxad.net>
22 # Florian octo Forster <octo at verplant.org>
29 Net::Oping - ICMP latency measurement module using the oping library.
35 my $obj = Net::Oping->new ();
36 $obj->host_add (qw(one.example.org two.example.org));
38 my $ret = $obj->ping ();
39 print "Latency to `one' is " . $ret->{'one.example.org'} . "\n";
43 This Perl module is a high-level interface to the
44 L<oping library|http://verplant.org/liboping/>. Its purpose it to send
45 C<ICMP ECHO_REQUEST> packets (also known as "ping") to a host and measure the
46 time that elapses until the reception of an C<ICMP ECHO_REPLY> packet (also
47 known as "pong"). If no such packet is received after a certain timeout the
48 host is considered to be unreachable.
50 The used I<oping> library supports "ping"ing multiple hosts in parallel and
51 works with IPv4 and IPv6 transparently. Other advanced features that are
52 provided by the underlying library, such as setting the data sent, are not yet
53 supported by this interface.
62 use Carp (qw(cluck confess));
64 our $VERSION = '1.10';
67 XSLoader::load ('Net::Oping', $VERSION);
72 The interface is kept simple and clean. First you need to create an object to
73 which you then add hosts. Using the C<ping> method you can request a latency
74 measurement and get the current values returned. If necessary you can remove
75 hosts from the object, too.
77 The constructor and methods are defined as follows:
81 =item I<$obj> = Net::Oping-E<gt>B<new> ();
83 Creates and returns a new object.
90 my $ping_obj = _ping_construct ();
92 my $obj = bless ({ c_obj => $ping_obj }, $pkg);
99 _ping_destroy ($obj->{'c_obj'});
102 =item I<$status> = I<$obj>-E<gt>B<timeout> (I<$timeout>);
104 Sets the timeout before a host is considered unreachable to I<$timeout>
105 seconds, which may be a floating point number to specify fractional seconds.
115 $status = _ping_setopt_timeout ($obj->{'c_obj'}, $timeout);
118 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
125 =item I<$status> = I<$obj>-E<gt>B<ttl> (I<$ttl>);
127 Sets the I<Time to Live> (TTL) of outgoing packets. I<$ttl> must be in the
128 range B<1>E<nbsp>...E<nbsp>B<255>. Returns true when successful and false
129 when an error occurred.
139 $status = _ping_setopt_ttl ($obj->{'c_obj'}, $ttl);
142 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
149 =item I<$status> = I<$obj>-E<gt>B<bind> (I<$ip_addr>);
151 Sets the source IP-address to use. I<$ip_addr> must be a string containing an
152 IP-address, such as "192.168.0.1" or "2001:f00::1". As a side-effect this will
153 set the address-family (IPv4 or IPv6) to a fixed value, too, for obvious
164 $status = _ping_setopt_source ($obj->{'c_obj'}, $addr);
167 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
174 =item I<$status> = I<$obj>-E<gt>B<device> (I<$device>);
176 Sets the network device used for communication. This may not be supported on
179 I<Requires liboping 1.3 or later.>
189 $status = _ping_setopt_device ($obj->{'c_obj'}, $device);
190 if ($status == -95) # Feature not supported.
192 $obj->{'err_msg'} = "Feature not supported by your version of liboping.";
196 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
203 =item I<$status> = I<$obj>-E<gt>B<host_add> (I<$host>, [I<$host>, ...]);
205 Adds one or more hosts to the Net::Oping-object I<$obj>. The number of
206 successfully added hosts is returned. If this number differs from the number of
207 hosts that were passed to the method you can use B<get_error> (see below) to
208 get the error message of the last failure.
220 my $status = _ping_host_add ($obj->{'c_obj'}, $_);
223 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
234 =item I<$status> = I<$obj>-E<gt>B<host_remove> (I<$host>, [I<$host>, ...]);
236 Same semantic as B<host_add> but removes hosts.
248 my $status = _ping_host_remove ($obj->{'c_obj'}, $_);
251 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
261 =item I<$latency> = I<$obj>-E<gt>B<ping> ()
263 The central method of this module sends ICMP packets to the hosts and waits for
264 replies. The time it takes for replies to arrive is measured and returned.
266 The returned scalar is a hash reference where each host associated with the
267 I<$obj> object is a key and the associated value is the corresponding latency
268 in milliseconds. An example hash reference would be:
270 $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };
272 If a value is C<undef>, as for "host2" in this example, the host has timed out
273 and considered unreachable.
284 $status = _ping_send ($obj->{'c_obj'});
287 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
291 $iter = _ping_iterator_get ($obj->{'c_obj'});
294 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
300 my $host = _ping_iterator_get_hostname ($iter);
303 $iter = _ping_iterator_next ($iter);
307 my $latency = _ping_iterator_get_latency ($iter);
313 $data->{$host} = $latency;
315 $iter = _ping_iterator_next ($iter);
321 =item I<$dropped> = I<$obj>-E<gt>B<get_dropped> ()
323 Returns a hash reference holding the number of "drops" (echo requests which
324 were not answered in time) for each host. An example return
327 $droprate = { host1 => 0, host2 => 3, host3 => undef, ... };
329 Hosts to which no data has been sent yet will return C<undef> ("host3" in thie
340 $iter = _ping_iterator_get ($obj->{'c_obj'});
343 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
349 my $host = _ping_iterator_get_hostname ($iter);
352 $iter = _ping_iterator_next ($iter);
356 my $dropped = _ping_iterator_get_dropped ($iter);
362 $data->{$host} = $dropped;
364 $iter = _ping_iterator_next ($iter);
370 =item I<$ttl> = I<$obj>-E<gt>B<get_recv_ttl> ()
372 Returns a hash reference holding the I<Time to Live> (TTL) of the last received
373 packet for each host. An example return value would be:
375 $ttl = { host1 => 60, host2 => 41, host3 => 243, ... };
377 To signal an invalid or unavailable TTL, a negative number is returned.
387 $iter = _ping_iterator_get ($obj->{'c_obj'});
390 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
396 my $host = _ping_iterator_get_hostname ($iter);
399 $data->{$host} = _ping_iterator_get_recv_ttl ($iter);
402 $iter = _ping_iterator_next ($iter);
408 =item I<$errmsg> = I<$obj>-E<gt>B<get_error> ();
410 Returns the last error that occurred.
417 return ($obj->{'err_msg'} || 'Success');
424 The I<oping> library opens a raw socket to be able to send ICMP packets. On
425 most systems normal users are not allowed to do this. This is why on most
426 systems the L<ping(1)> utility is installed as SetUID-root. Since, when using
427 this module, no external process is spawned B<this> process needs the
428 appropriate permissions. This means that either your script has to run as
429 superuser or, under Linux, needs the C<CAP_NET_RAW> capability.
435 The I<liboping> homepage may be found at L<http://verplant.org/liboping/>.
436 Information about its mailing list may be found at
437 L<http://mailman.verplant.org/listinfo/liboping>.
441 First XSE<nbsp>port by Olivier Fredj, extended XS functionality and high-level
442 Perl interface by Florian Forster.
444 =head1 COPYRIGHT AND LICENSE
446 Copyright (C) 2007 by Olivier Fredj E<lt>ofredjE<nbsp>atE<nbsp>proxad.netE<gt>
448 Copyright (C) 2008,2009 by Florian Forster
449 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
451 This library is free software; you can redistribute it and/or modify
452 it under the same terms as Perl itself, either Perl version 5.8.7 or,
453 at your option, any later version of Perl 5 you may have available.
455 Please note that I<liboping> is licensed under the GPLv2. Derived works of
456 both, I<Net::Oping> and I<liboping>, (i.E<nbsp>e. binary packages) may
457 therefore be subject to stricter licensing terms than the source code of this
462 # vim: set shiftwidth=2 softtabstop=2 tabstop=8 :