5 Net::Oping - ICMP latency measurement module using the oping library.
11 my $obj = Net::Oping->new ();
12 $obj->host_add (qw(one.example.org two.example.org));
14 my $ret = $obj->ping ();
15 print "Latency to `one' is " . $ret->{'one.example.org'} . "\n";
19 This Perl module is a high-level interface to the
20 L<oping library|http://verplant.org/liboping/>. Its purpose it to send C<ICMP
21 ECHO_REQUEST> packets (also known as "ping") to a host and measure the time
22 that elapses until the reception of an C<ICMP ECHO_REPLY> packet (also known as
23 "pong"). If no such packet is received after a certain timeout the host is considered to be unreachable.
25 The used C<oping> library supports "ping"ing multiple hosts in parallel and
26 works with IPv4 and IPv6 transparently. Other advanced features that are
27 provided by the underlying library, such as setting the data sent or
28 configuring the time of live (TTL) are not yet supported by this interface.
35 use Carp (qw(cluck confess));
37 our $VERSION = '1.00';
40 XSLoader::load ('Net::Oping', $VERSION);
45 The interface is kept simple and clean. First you need to create an object to
46 which you then add hosts. Using the C<ping> method you can request a latency
47 measurement and get the current values returned. If neccessary you can remove
48 hosts from the object, too.
50 The constructor and methods are defined as follows:
54 =item my I<$obj> = Net::Oping-E<gt>B<new> ();
56 Creates and returns a new object.
63 my $ping_obj = _ping_construct ();
65 my $obj = bless ({ c_obj => $ping_obj }, $pkg);
72 _ping_destroy ($obj->{'c_obj'});
75 =item my I<$status> = I<$obj>-E<gt>B<timeout> (I<$timeout>);
77 Sets the timeout before a host is considered unreachable to I<$timeout>
78 seconds, which may be a floating point number to specify fractional seconds.
88 $status = _ping_setopt_timeout ($obj->{'c_obj'}, $timeout);
91 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
98 =item my I<$status> = I<$obj>-E<gt>B<bind> (I<$ip_addr>);
100 Sets the source IP-address to use. I<$ip_addr> must be a string containing an
101 IP-address, such as "192.168.0.1" or "2001:f00::1". As a side-effect this will
102 set the address-family (IPv4 or IPv6) to a fixed, value, too, for obvious
113 $status = _ping_setopt_source ($obj->{'c_obj'}, $addr);
116 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
123 =item my I<$status> = I<$obj>-E<gt>B<host_add> (I<$host>, [I<$host>, ...]);
125 Adds one or more hosts to the Net::Oping-object I<$obj>. The number of
126 successfully added hosts is returned. If this number differs from the number of
127 hosts that were passed to the method you can use B<get_error> (see below) to
128 get the error message of the last failure.
140 my $status = _ping_host_add ($obj->{'c_obj'}, $_);
143 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
154 =item my I<$status> = I<$obj>-E<gt>B<host_remove> (I<$host>, [I<$host>, ...]);
156 Same semantic as B<host_add> but removes hosts.
168 my $status = _ping_host_remove ($obj->{'c_obj'}, $_);
171 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
181 =item my I<$latency> = I<$obj>-E<gt>B<ping> ()
183 The central method of this module sends ICMP packets to the hosts and waits for
184 replies. The time it takes for replies to arrive is measured and returned.
186 The returned scalar is a hash reference where each host associated with the
187 I<$obj> object is a key and the associated value is the corresponding latency
188 in milliseconds. An example hash reference would be:
190 $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };
192 If a value is C<undef>, as for "host2" in this example, the host has timed out
193 and considered unreachable.
204 $status = _ping_send ($obj->{'c_obj'});
207 print "\$status = $status;\n";
208 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
212 $iter = _ping_iterator_get ($obj->{'c_obj'});
215 my $host = _ping_iterator_get_hostname ($iter);
218 $iter = _ping_iterator_next ($iter);
222 my $latency = _ping_iterator_get_latency ($iter);
228 $data->{$host} = $latency;
230 $iter = _ping_iterator_next ($iter);
236 =item my I<$errmsg> = I<$obj>-E<gt>B<get_error> ();
238 Returns the last error that occured.
245 return ($obj->{'err_msg'} || 'Success');
252 The C<oping> library opens a raw socket to be able to send ICMP packets. On
253 most systems normal users are not allowed to do this. This is why on most
254 systems the L<ping(1)> utility is installed as SetUID-root. Since, when using
255 this module, no external process is spawned B<this> process needs the
256 appropriate permissions. This means that either your script has to run as
257 superuser or, under Linux, needs the C<CAP_NET_RAW> capability.
263 The C<liboping> homepage may be found at L<http://verplant.org/liboping/>.
264 Information about its mailing list may be found at
265 L<http://mailman.verplant.org/listinfo/liboping>.
269 First XSE<nbsp>port by Olivier Fredj, extended XS functionality and high-level
270 Perl interface by Florian Forster.
272 =head1 COPYRIGHT AND LICENSE
274 Copyright (C) 2007 by Olivier Fredj E<lt>ofredjE<nbsp>atE<nbsp>proxad.netE<gt>
276 Copyright (C) 2008 by Florian Forster
277 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
279 This library is free software; you can redistribute it and/or modify
280 it under the same terms as Perl itself, either Perl version 5.8.7 or,
281 at your option, any later version of Perl 5 you may have available.
285 # vim: set shiftwidth=2 softtabstop=2 tabstop=8 :