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://noping.cc/>. 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 this 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://noping.cc/>.  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 <ff at octo.it>

       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.

perl v5.38.2                                       2024-03-31                                    Net::Oping(3pm)