1Net::Oping(3)         User Contributed Perl Documentation        Net::Oping(3)
2
3
4

NAME

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

SYNOPSIS

9         use Net::Oping ();
10
11         my $obj = Net::Oping->new ();
12         $obj->host_add (qw(one.example.org two.example.org));
13
14         my $ret = $obj->ping ();
15         print "Latency to `one' is " . $ret->{'one.example.org'} . "\n";
16

DESCRIPTION

18       This Perl module is a high-level interface to the oping library
19       <http://noping.cc/>. Its purpose it to send "ICMP ECHO_REQUEST" packets
20       (also known as "ping") to a host and measure the time that elapses
21       until the reception of an "ICMP ECHO_REPLY" packet (also known as
22       "pong"). If no such packet is received after a certain timeout the host
23       is considered to be unreachable.
24
25       The used oping library supports "ping"ing multiple hosts in parallel
26       and works with IPv4 and IPv6 transparently. Other advanced features
27       that are provided by the underlying library, such as setting the data
28       sent, are not yet supported by this interface.
29

INTERFACE

31       The interface is kept simple and clean. First you need to create an
32       object to which you then add hosts. Using the "ping" method you can
33       request a latency measurement and get the current values returned. If
34       necessary you can remove hosts from the object, too.
35
36       The constructor and methods are defined as follows:
37
38       $obj = Net::Oping->new ();
39           Creates and returns a new object.
40
41       $status = $obj->timeout ($timeout);
42           Sets the timeout before a host is considered unreachable to
43           $timeout seconds, which may be a floating point number to specify
44           fractional seconds.
45
46       $status = $obj->ttl ($ttl);
47           Sets the Time to Live (TTL) of outgoing packets. $ttl must be in
48           the range 1 ... 255. Returns true when successful and false when an
49           error occurred.
50
51       $status = $obj->bind ($ip_addr);
52           Sets the source IP-address to use. $ip_addr must be a string
53           containing an IP-address, such as "192.168.0.1" or "2001:f00::1".
54           As a side-effect this will set the address-family (IPv4 or IPv6) to
55           a fixed value, too, for obvious reasons.
56
57       $status = $obj->device ($device);
58           Sets the network device used for communication. This may not be
59           supported on all platforms.
60
61           Requires liboping 1.3 or later.
62
63       $status = $obj->host_add ($host, [$host, ...]);
64           Adds one or more hosts to the Net::Oping-object $obj. The number of
65           successfully added hosts is returned. If this number differs from
66           the number of hosts that were passed to the method you can use
67           get_error (see below) to get the error message of the last failure.
68
69       $status = $obj->host_remove ($host, [$host, ...]);
70           Same semantic as host_add but removes hosts.
71
72       $latency = $obj->ping ()
73           The central method of this module sends ICMP packets to the hosts
74           and waits for replies. The time it takes for replies to arrive is
75           measured and returned.
76
77           The returned scalar is a hash reference where each host associated
78           with the $obj object is a key and the associated value is the
79           corresponding latency in milliseconds. An example hash reference
80           would be:
81
82             $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };
83
84           If a value is "undef", as for "host2" in this example, the host has
85           timed out and considered unreachable.
86
87       $dropped = $obj->get_dropped ()
88           Returns a hash reference holding the number of "drops" (echo
89           requests which were not answered in time) for each host. An example
90           return values would be:
91
92             $droprate = { host1 => 0, host2 => 3, host3 => undef, ... };
93
94           Hosts to which no data has been sent yet will return "undef"
95           ("host3" in thie example).
96
97       $ttl = $obj->get_recv_ttl ()
98           Returns a hash reference holding the Time to Live (TTL) of the last
99           received packet for each host. An example return value would be:
100
101             $ttl = { host1 => 60, host2 => 41, host3 => 243, ... };
102
103           To signal an invalid or unavailable TTL, a negative number is
104           returned.
105
106       $errmsg = $obj->get_error ();
107           Returns the last error that occurred.
108

CAVEATS

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

SEE ALSO

119       liboping(3)
120
121       The liboping homepage may be found at <http://noping.cc/>.  Information
122       about its mailing list may be found at
123       <http://mailman.verplant.org/listinfo/liboping>.
124

AUTHORS

126       First XS port by Olivier Fredj, extended XS functionality and high-
127       level Perl interface by Florian Forster.
128
130       Copyright (C) 2007 by Olivier Fredj <ofredj at proxad.net>
131
132       Copyright (C) 2008,2009 by Florian Forster <ff at octo.it>
133
134       This library is free software; you can redistribute it and/or modify it
135       under the same terms as Perl itself, either Perl version 5.8.7 or, at
136       your option, any later version of Perl 5 you may have available.
137
138       Please note that liboping is licensed under the GPLv2. Derived works of
139       both, Net::Oping and liboping, (i. e. binary packages) may therefore be
140       subject to stricter licensing terms than the source code of this
141       package.
142
143
144
145perl v5.38.0                      2023-07-20                     Net::Oping(3)
Impressum