Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Oping(3)	      User Contributed Perl Documentation	 Net::Oping(3)

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://verplant.org/liboping/>.	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 1A	...A 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 thie 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://verplant.org/liboping/>.
       Information about its mailing list may be found at
       <http://mailman.verplant.org/listinfo/liboping>.

AUTHORS
       First XSA port by Olivier Fredj,	extended XS functionality and high-
       level Perl interface by Florian Forster.

COPYRIGHT AND LICENSE
       Copyright (C) 2007 by Olivier Fredj <ofredjA atA	proxad.net>

       Copyright (C) 2008,2009 by Florian Forster <octoA atA verplant.org>

       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.A e. binary packages) may therefore
       be subject to stricter licensing	terms than the source code of this
       package.

perl v5.32.1			  2011-03-12			 Net::Oping(3)

NAME | SYNOPSIS | DESCRIPTION | INTERFACE | CAVEATS | SEE ALSO | AUTHORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Oping&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help