1Net::Oping(3) User Contributed Perl Documentation Net::Oping(3)
2
6 Net::Oping - ICMP latency measurement module using the oping library.
7
9 use Net::Oping ();
10 my $obj = Net::Oping->new ();
12 $obj->host_add (qw(one.example.org two.example.org));
13 my $ret = $obj->ping ();
15 print "Latency to `one' is " . $ret->{'one.example.org'} . "\n";
16
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 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
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 The constructor and methods are defined as follows:
37 $obj = Net::Oping->new ();
39 Creates and returns a new object.
40 $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 $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 $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 $status = $obj->device ($device);
58 Sets the network device used for communication. This may not be
59 supported on all platforms.
60 Requires liboping 1.3 or later.
62 $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 $status = $obj->host_remove ($host, [$host, ...]);
70 Same semantic as host_add but removes hosts.
71 $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 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 $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };
83 If a value is "undef", as for "host2" in this example, the host has
85 timed out and considered unreachable.
86 $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 $droprate = { host1 => 0, host2 => 3, host3 => undef, ... };
93 Hosts to which no data has been sent yet will return "undef"
95 ("host3" in thie example).
96 $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 $ttl = { host1 => 60, host2 => 41, host3 => 243, ... };
102 To signal an invalid or unavailable TTL, a negative number is
104 returned.
105 $errmsg = $obj->get_error ();
107 Returns the last error that occurred.
108
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
119 liboping(3)
120 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
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 Copyright (C) 2008,2009 by Florian Forster <ff at octo.it>
133 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 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.
142perl v5.38.0 2023-07-20 Net::Oping(3)