NAME

       Net::Oping - ICMP latency measurement module using the oping library.

SYNOPSIS

         use Net::Oping ();

         my $obj = Net::Oping->new ();
         $obj->host_add (qw(one.example.org two.example.org));

         my $ret = $obj->ping ();
         print "Latency to `one' is " . $ret->{'one.example.org'} . "\n";

DESCRIPTION

       This Perl module is a high-level interface to the oping library
       <http://verplant.org/liboping/>. Its purpose it to send "ICMP ECHO_REQUEST" packets (also
       known as "ping") to a host and measure the time that elapses until the reception of an
       "ICMP ECHO_REPLY" packet (also known as "pong"). If no such packet is received after a
       certain timeout the host is considered to be unreachable.

       The used oping library supports "ping"ing multiple hosts in parallel and works with IPv4
       and IPv6 transparently. Other advanced features that are provided by the underlying
       library, such as setting the data sent, are not yet supported by this interface.

INTERFACE

       The interface is kept simple and clean. First you need to create an object to which you
       then add hosts. Using the "ping" method you can request a latency measurement and get the
       current values returned. If necessary you can remove hosts from the object, too.

       The constructor and methods are defined as follows:

       $obj = Net::Oping->new ();
           Creates and returns a new object.

       $status = $obj->timeout ($timeout);
           Sets the timeout before a host is considered unreachable to $timeout seconds, which
           may be a floating point number to specify fractional seconds.

       $status = $obj->ttl ($ttl);
           Sets the Time to Live (TTL) of outgoing packets. $ttl must be in the range 1 ... 255.
           Returns true when successful and false when an error occurred.

       $status = $obj->bind ($ip_addr);
           Sets the source IP-address to use. $ip_addr must be a string containing an IP-address,
           such as "192.168.0.1" or "2001:f00::1". As a side-effect this will set the address-
           family (IPv4 or IPv6) to a fixed value, too, for obvious reasons.

       $status = $obj->device ($device);
           Sets the network device used for communication. This may not be supported on all
           platforms.

           Requires liboping 1.3 or later.

       $status = $obj->host_add ($host, [$host, ...]);
           Adds one or more hosts to the Net::Oping-object $obj. The number of successfully added
           hosts is returned. If this number differs from the number of hosts that were passed to
           the method you can use get_error (see below) to get the error message of the last
           failure.

       $status = $obj->host_remove ($host, [$host, ...]);
           Same semantic as host_add but removes hosts.

       $latency = $obj->ping ()
           The central method of this module sends ICMP packets to the hosts and waits for
           replies. The time it takes for replies to arrive is measured and returned.

           The returned scalar is a hash reference where each host associated with the $obj
           object is a key and the associated value is the corresponding latency in milliseconds.
           An example hash reference would be:

             $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };

           If a value is "undef", as for "host2" in this example, the host has timed out and
           considered unreachable.

       $dropped = $obj->get_dropped ()
           Returns a hash reference holding the number of "drops" (echo requests which were not
           answered in time) for each host. An example return values would be:

             $droprate = { host1 => 0, host2 => 3, host3 => undef, ... };

           Hosts to which no data has been sent yet will return "undef" ("host3" in thie
           example).

       $ttl = $obj->get_recv_ttl ()
           Returns a hash reference holding the Time to Live (TTL) of the last received packet
           for each host. An example return value would be:

             $ttl = { host1 => 60, host2 => 41, host3 => 243, ... };

           To signal an invalid or unavailable TTL, a negative number is returned.

       $errmsg = $obj->get_error ();
           Returns the last error that occurred.

CAVEATS

       The oping library opens a raw socket to be able to send ICMP packets. On most systems
       normal users are not allowed to do this. This is why on most systems the ping(1) utility
       is installed as SetUID-root. Since, when using this module, no external process is spawned
       this process needs the appropriate permissions. This means that either your script has to
       run as superuser or, under Linux, needs the "CAP_NET_RAW" capability.

SEE ALSO

       liboping(3)

       The liboping homepage may be found at <http://verplant.org/liboping/>.  Information about
       its mailing list may be found at <http://mailman.verplant.org/listinfo/liboping>.

AUTHORS

       First XS port by Olivier Fredj, extended XS functionality and high-level Perl interface by
       Florian Forster.

COPYRIGHT AND LICENSE

       Copyright (C) 2007 by Olivier Fredj <ofredj at proxad.net>

       Copyright (C) 2008,2009 by Florian Forster <octo at verplant.org>

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of
       Perl 5 you may have available.

       Please note that liboping is licensed under the GPLv2. Derived works of both, Net::Oping
       and liboping, (i. e. binary packages) may therefore be subject to stricter licensing terms
       than the source code of this package.