Net::Oping(3pm)

📦
version 1.10.0-1.21 · 12 versions
, in ubuntu stonking

💖 Net::Oping 💖

okay bestie, welcome to Net::Oping, a User Contributed Perl Documentation page (yes we're in the <3pm section, we're fancy like that) 🎀

🌟 NAME 🌟

Net::Oping — an ICMP latency measurement module that rides on the oping library. no cap, that's literally its whole job 💅

✨ 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";

look at that. three lines and you're already pinging multiple hosts at once. iconic behaviour honestly 🦋

🌸 DESCRIPTION 🌸

So this Perl module is a high-level interface to the oping library at <http://noping.cc/>. Its purpose is to send "ICMP ECHO_REQUEST" packets (you know it, you love it — "ping") to a host, and measure the time that elapses until the reception of an "ICMP ECHO_REPLY" packet (aka the "pong", the lil comeback 🏓). And if no such packet shows up after a certain timeout? The host is considered unreachable. ghosted. blocked. 💀

The oping library underneath supports "ping"ing multiple hosts in parallel, and it works with IPv4 and IPv6 transparently — it does NOT play favourites, both families get the love. Other advanced features the underlying library provides, like setting the data that gets sent, are not yet supported by this interface. so don't ask. not yet bestie 💅

🫶 INTERFACE 🫶

The interface is kept simple and clean, like a well-organised desk or a mind that has done its skincare. Here's the flow:

  1. create an object
  2. add hosts to it
  3. call the "ping" method to request a latency measurement and get the current values returned
  4. and if you need to, remove hosts from the object too. no hard feelings, we're mature 💜

The constructor and methods are defined as follows:

  • $obj = Net::Oping->new (); — creates a brand new object and hands it to you. new object, who dis 🎀
  • $status = $obj->timeout ($timeout); — sets how long we wait before declaring a host unreachable, to $timeout seconds. and yes, it can be a floating point number so you can do fractional seconds. precision queen ✨
  • $status = $obj->ttl ($ttl); — sets the Time to Live (TTL) of outgoing packets. $ttl must be in the range 1 ... 255. returns true when it worked and false when an error occurred, so like, check your status, bestie.
  • $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". ⚠️ side-effect alert: this also sets the address-family (IPv4 or IPv6) to a fixed value, for obvious reasons. like, it has to, babe.
  • $status = $obj->device ($device); — sets the network device used for communication. heads up though: this may not be supported on all platforms. 🙈
requires liboping 1.3 or later. don't @ me if you're on an older one.
  • $status = $obj->host_add ($host, [$host, ...]); — adds one or more hosts to the Net::Oping-object $obj. returns the number of successfully added hosts. if that number differs from the number of hosts you passed in, you can use get_error (see below 👇) to get the error message of the last failure. so you know exactly which one flopped.
  • $status = $obj->host_remove ($host, [$host, ...]); — same semantic as host_add, except it removes hosts. that's it, that's the tea 🍓
  • $latency = $obj->ping () — THE central method of this module, the main character 🫡. it sends ICMP packets to the hosts and waits for replies. the time it takes for those replies to arrive gets 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", like "host2" up there, that host has timed out and is considered unreachable. rip. 🪦

  • $dropped = $obj->get_dropped () — returns a hash reference holding the number of "drops" (that's echo requests which were not answered in time) for each host. an example return value would be:
$droprate = { host1 => 0, host2 => 3, host3 => undef, ... };

hosts you haven't sent any data to yet will return "undef" — that's "host3" in this example, standing there with nothing to report 🙈

  • $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. so if you see a negative, that's the vibe check failing, not a real TTL.

  • $errmsg = $obj->get_error (); — returns the last error that occurred. your receipts. keep them 📝

💀 CAVEATS 💀

okay this part is important, sit up bestie. the oping library opens a raw socket so it can send ICMP packets. on most systems, normal users are not allowed to do this. that's literally why, on most systems, the ping(1) utility is installed as SetUID-root.

since this module doesn't spawn any external process, this process needs the appropriate permissions. which means either:

  • your script has to run as superuser, or
  • under Linux, it needs the "CAP_NET_RAW" capability.

no third option, no shortcuts, no manifesting it into working. sorry babe 😭

🌈 SEE ALSO 🌈

👑 AUTHORS 👑

First XS port by Olivier Fredj, extended XS functionality and high-level Perl interface by Florian Forster. two legends, one module, we stan 🫶

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. so like, go off, remix it, just keep it free 💅

⚠️ important legal note bestie: 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. yes, stricter. read it twice. 😭

🌸 that's the whole page, bestie! this was written against perl v5.42.3 and dated 2026-08-20 — go ping something responsibly, and hydrate! ✨💖🎀

📦 where this page comes from