ping_host_add(3) liboping ping_host_add(3)NAME
ping_host_add - Add a host to a liboping object
SYNOPSIS
#include <oping.h>
int ping_host_add (pingobj_t *obj, const char *host);
int ping_host_remove (pingobj_t *obj, const char *host);
DESCRIPTION
The ping_host_add method tries to resolve the host argument, open a socket and associate everything with the liboping object obj.
The obj argument is a pointer to an liboping object, as returned by ping_construct(3).
The host parameter is a ' ' terminated string which is interpreted as a hostname or an IP address. Depending on the address family
setting, set with ping_setopt(3), the hostname is resolved to an IPv4 or IPv6 address.
The ping_host_remove method looks for host within obj and remove it if found. It will close the socket and deallocate the memory, too.
The names passed to ping_host_add and ping_host_remove must match. This name can be queried using ping_iterator_get_info(3).
RETURN VALUE
If ping_host_add succeeds it returns zero. If an error occurs a value less than zero is returned and the last error is saved internally.
You can receive the error message using ping_get_error(3).
ping_host_remove returns zero upon success and less than zero if it failed. Currently the only reason for failure is that the host isn't
found, but this is subject to change. Use ping_get_error(3) to receive the error message.
SEE ALSO ping_construct(3), ping_setopt(3), ping_get_error(3), liboping(3)AUTHOR
liboping is written by Florian "octo" Forster <octo at verplant.org>. Its homepage can be found at <http://verplant.org/liboping/>.
Copyright (c) 2005-2011 by Florian "octo" Forster.
1.6.2 2012-01-31 ping_host_add(3)
Check Out this Related Man Page
Net::Oping(3pm) User Contributed Perl Documentation Net::Oping(3pm)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'} . "
";
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 1 ... 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 XS port by Olivier Fredj, extended XS functionality and high-level Perl interface by Florian Forster.
COPYRIGHT AND LICENSE
Copyright (C) 2007 by Olivier Fredj <ofredj at proxad.net>
Copyright (C) 2008,2009 by Florian Forster <octo at 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. e. binary packages) may
therefore be subject to stricter licensing terms than the source code of this package.
perl v5.14.2 2012-01-31 Net::Oping(3pm)