Net::Oping(3)

📦 version 1.10.0, in nixos 26.05, nixpkgs unstable

💅 Net::Oping — the Perl manual page, bestie edition

okay so you're reading the Net::Oping(3) man page (section 3 of the Perl manual, iykyk) and honestly? you're about to have a great time. let's go 🫶

✨ NAME ✨

Net::Oping — an ICMP latency measurement module that uses the oping library. that's it, that's the whole vibe: it pings stuff and tells you how slow it was. 🎀

🌸 SYNOPSIS 🌸

okay so here's the whole thing in action, no cap:

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

literally just make the object, add your hosts, ping, and read the latency out of the hash. slay. 💅

🦋 DESCRIPTION 🦋

so this Perl module is a high-level interface to the oping library <http://noping.cc/>. its whole purpose in life is to send ICMP ECHO_REQUEST packets (you know, "ping" 💌) to a host and then measure the time that elapses until it receives an ICMP ECHO_REPLY packet (aka "pong" 🏓). if no such packet shows up after a certain timeout, the host gets considered unreachable. sad but fair.

the oping library underneath supports pinging multiple hosts in parallel and works with IPv4 and IPv6 transparently — you don't have to think about it, it just handles it. ✨

heads up bestie: other advanced features the underlying library provides — like setting the data that gets sent — are not yet supported by this interface. so don't come for me. 🙈

👑 INTERFACE 👑

the interface is kept simple and clean (main character energy, honestly). step one: create an object. step two: add hosts to it. then you use the ping method to request a latency measurement and get the current values back. and if you need to, you can also remove hosts from the object. super chill.

the constructor and methods are defined like this:

  • $obj = Net::Oping->new (); — creates and returns a brand new object. your blank canvas. your fresh start. 🎀
  • $status = $obj->timeout ($timeout); — sets the timeout, i.e. how long we wait before a host gets considered unreachable, to $timeout seconds. and yes bestie, it may be a floating point number so you can do fractional seconds — go off with your 0.5. ⏱️
  • $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 happened. 💀
  • $status = $obj->bind ($ip_addr); — sets the source IP-address to use. $ip_addr must be a string containing an IP-address, like 192.168.0.1 or 2001:f00::1. as a side-effect this also pins the address-family (IPv4 or IPv6) to a fixed value — for obvious reasons, honestly. 😌
  • $status = $obj->device ($device); — sets the network device used for communication. this one may not be supported on all platforms, so don't be shocked.
requires liboping 1.3 or later. periodt.
  • $status = $obj->host_add ($host, [$host, ...]); — adds one or more hosts to the Net::Oping-object $obj. it returns the number of successfully added hosts. if that number doesn't match the number of hosts you passed in, you can call get_error (see below 👇) to get the error message of the last failure. we love diagnostics.
  • $status = $obj->host_remove ($host, [$host, ...]); — same semantics as host_add, except it ✨removes✨ hosts. bye bestie 👋
  • $latency = $obj->ping () — the central method of this whole module. it sends ICMP packets to the hosts and waits for replies. the time it takes for 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 for host2 in this example — that host timed out and is considered unreachable. rip. 😭

  • $dropped = $obj->get_dropped () — returns a hash reference holding the number of "drops" for each host, where a drop is an echo request that wasn't answered in time. an example return value 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, and yes the original doc says "thie example", we keep the lore 📜).

  • $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 minus sign, that's the signal, not a vibe. ⭐

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

💀 CAVEATS 💀

okay bestie, this is the serious part, listen up. 👂

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 exactly why on most systems the ping(1) utility is installed as SetUID-root. and since this module spawns no external process, this process needs the appropriate permissions itself.

which means: either your script has to run as superuser, or — under Linux — it needs the CAP_NET_RAW capability. no way around it, no cap. 🔥

🌈 SEE ALSO 🌈

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

legends, both of them. 👑

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: 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. read your licenses, bestie, it's giving responsible adult. 📜

and that's the whole page! 🌸 this little beauty is documented as perl v5.42.3, dated 2017-05-11, and it lives at Net::Oping(3). go ping something, you've got this 💖✨🎀

📦 where this page comes from