.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Net::Oping 3pm"
.TH Net::Oping 3pm "2012-01-31" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Net::Oping \- ICMP latency measurement module using the oping library.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  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\*(Aq is " . $ret\->{\*(Aqone.example.org\*(Aq} . "\en";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This Perl module is a high-level interface to the
oping library <http://verplant.org/liboping/>. Its purpose it to send
\&\f(CW\*(C`ICMP ECHO_REQUEST\*(C'\fR packets (also known as \*(L"ping\*(R") to a host and measure the
time that elapses until the reception of an \f(CW\*(C`ICMP ECHO_REPLY\*(C'\fR packet (also
known as \*(L"pong\*(R"). If no such packet is received after a certain timeout the
host is considered to be unreachable.
.PP
The used \fIoping\fR library supports \*(L"ping\*(R"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.
.SH "INTERFACE"
.IX Header "INTERFACE"
The interface is kept simple and clean. First you need to create an object to
which you then add hosts. Using the \f(CW\*(C`ping\*(C'\fR method you can request a latency
measurement and get the current values returned. If necessary you can remove
hosts from the object, too.
.PP
The constructor and methods are defined as follows:
.ie n .IP "\fI\fI$obj\fI\fR = Net::Oping\->\fBnew\fR ();" 4
.el .IP "\fI\f(CI$obj\fI\fR = Net::Oping\->\fBnew\fR ();" 4
.IX Item "$obj = Net::Oping->new ();"
Creates and returns a new object.
.ie n .IP "\fI\fI$status\fI\fR = \fI\fI$obj\fI\fR\->\fBtimeout\fR (\fI\fI$timeout\fI\fR);" 4
.el .IP "\fI\f(CI$status\fI\fR = \fI\f(CI$obj\fI\fR\->\fBtimeout\fR (\fI\f(CI$timeout\fI\fR);" 4
.IX Item "$status = $obj->timeout ($timeout);"
Sets the timeout before a host is considered unreachable to \fI\f(CI$timeout\fI\fR
seconds, which may be a floating point number to specify fractional seconds.
.ie n .IP "\fI\fI$status\fI\fR = \fI\fI$obj\fI\fR\->\fBttl\fR (\fI\fI$ttl\fI\fR);" 4
.el .IP "\fI\f(CI$status\fI\fR = \fI\f(CI$obj\fI\fR\->\fBttl\fR (\fI\f(CI$ttl\fI\fR);" 4
.IX Item "$status = $obj->ttl ($ttl);"
Sets the \fITime to Live\fR (\s-1TTL\s0) of outgoing packets. \fI\f(CI$ttl\fI\fR must be in the
range \fB1\fR\ ...\ \fB255\fR. Returns true when successful and false
when an error occurred.
.ie n .IP "\fI\fI$status\fI\fR = \fI\fI$obj\fI\fR\->\fBbind\fR (\fI\fI$ip_addr\fI\fR);" 4
.el .IP "\fI\f(CI$status\fI\fR = \fI\f(CI$obj\fI\fR\->\fBbind\fR (\fI\f(CI$ip_addr\fI\fR);" 4
.IX Item "$status = $obj->bind ($ip_addr);"
Sets the source IP-address to use. \fI\f(CI$ip_addr\fI\fR must be a string containing an
IP-address, such as \*(L"192.168.0.1\*(R" or \*(L"2001:f00::1\*(R". As a side-effect this will
set the address-family (IPv4 or IPv6) to a fixed value, too, for obvious
reasons.
.ie n .IP "\fI\fI$status\fI\fR = \fI\fI$obj\fI\fR\->\fBdevice\fR (\fI\fI$device\fI\fR);" 4
.el .IP "\fI\f(CI$status\fI\fR = \fI\f(CI$obj\fI\fR\->\fBdevice\fR (\fI\f(CI$device\fI\fR);" 4
.IX Item "$status = $obj->device ($device);"
Sets the network device used for communication. This may not be supported on
all platforms.
.Sp
\&\fIRequires liboping 1.3 or later.\fR
.ie n .IP "\fI\fI$status\fI\fR = \fI\fI$obj\fI\fR\->\fBhost_add\fR (\fI\fI$host\fI\fR, [\fI\fI$host\fI\fR, ...]);" 4
.el .IP "\fI\f(CI$status\fI\fR = \fI\f(CI$obj\fI\fR\->\fBhost_add\fR (\fI\f(CI$host\fI\fR, [\fI\f(CI$host\fI\fR, ...]);" 4
.IX Item "$status = $obj->host_add ($host, [$host, ...]);"
Adds one or more hosts to the Net::Oping\-object \fI\f(CI$obj\fI\fR. 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 \fBget_error\fR (see below) to
get the error message of the last failure.
.ie n .IP "\fI\fI$status\fI\fR = \fI\fI$obj\fI\fR\->\fBhost_remove\fR (\fI\fI$host\fI\fR, [\fI\fI$host\fI\fR, ...]);" 4
.el .IP "\fI\f(CI$status\fI\fR = \fI\f(CI$obj\fI\fR\->\fBhost_remove\fR (\fI\f(CI$host\fI\fR, [\fI\f(CI$host\fI\fR, ...]);" 4
.IX Item "$status = $obj->host_remove ($host, [$host, ...]);"
Same semantic as \fBhost_add\fR but removes hosts.
.ie n .IP "\fI\fI$latency\fI\fR = \fI\fI$obj\fI\fR\->\fBping\fR ()" 4
.el .IP "\fI\f(CI$latency\fI\fR = \fI\f(CI$obj\fI\fR\->\fBping\fR ()" 4
.IX Item "$latency = $obj->ping ()"
The central method of this module sends \s-1ICMP\s0 packets to the hosts and waits for
replies. The time it takes for replies to arrive is measured and returned.
.Sp
The returned scalar is a hash reference where each host associated with the
\&\fI\f(CI$obj\fI\fR object is a key and the associated value is the corresponding latency
in milliseconds. An example hash reference would be:
.Sp
.Vb 1
\&  $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };
.Ve
.Sp
If a value is \f(CW\*(C`undef\*(C'\fR, as for \*(L"host2\*(R" in this example, the host has timed out
and considered unreachable.
.ie n .IP "\fI\fI$dropped\fI\fR = \fI\fI$obj\fI\fR\->\fBget_dropped\fR ()" 4
.el .IP "\fI\f(CI$dropped\fI\fR = \fI\f(CI$obj\fI\fR\->\fBget_dropped\fR ()" 4
.IX Item "$dropped = $obj->get_dropped ()"
Returns a hash reference holding the number of \*(L"drops\*(R" (echo requests which
were not answered in time) for each host. An example return
values would be:
.Sp
.Vb 1
\&  $droprate = { host1 => 0, host2 => 3, host3 => undef, ... };
.Ve
.Sp
Hosts to which no data has been sent yet will return \f(CW\*(C`undef\*(C'\fR (\*(L"host3\*(R" in thie
example).
.ie n .IP "\fI\fI$ttl\fI\fR = \fI\fI$obj\fI\fR\->\fBget_recv_ttl\fR ()" 4
.el .IP "\fI\f(CI$ttl\fI\fR = \fI\f(CI$obj\fI\fR\->\fBget_recv_ttl\fR ()" 4
.IX Item "$ttl = $obj->get_recv_ttl ()"
Returns a hash reference holding the \fITime to Live\fR (\s-1TTL\s0) of the last received
packet for each host. An example return value would be:
.Sp
.Vb 1
\&  $ttl = { host1 => 60, host2 => 41, host3 => 243, ... };
.Ve
.Sp
To signal an invalid or unavailable \s-1TTL\s0, a negative number is returned.
.ie n .IP "\fI\fI$errmsg\fI\fR = \fI\fI$obj\fI\fR\->\fBget_error\fR ();" 4
.el .IP "\fI\f(CI$errmsg\fI\fR = \fI\f(CI$obj\fI\fR\->\fBget_error\fR ();" 4
.IX Item "$errmsg = $obj->get_error ();"
Returns the last error that occurred.
.SH "CAVEATS"
.IX Header "CAVEATS"
The \fIoping\fR library opens a raw socket to be able to send \s-1ICMP\s0 packets. On
most systems normal users are not allowed to do this. This is why on most
systems the \fIping\fR\|(1) utility is installed as SetUID-root. Since, when using
this module, no external process is spawned \fBthis\fR process needs the
appropriate permissions. This means that either your script has to run as
superuser or, under Linux, needs the \f(CW\*(C`CAP_NET_RAW\*(C'\fR capability.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIliboping\fR\|(3)
.PP
The \fIliboping\fR homepage may be found at <http://verplant.org/liboping/>.
Information about its mailing list may be found at
<http://mailman.verplant.org/listinfo/liboping>.
.SH "AUTHORS"
.IX Header "AUTHORS"
First \s-1XS\s0\ port by Olivier Fredj, extended \s-1XS\s0 functionality and high-level
Perl interface by Florian Forster.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2007 by Olivier Fredj <ofredj\ at\ proxad.net>
.PP
Copyright (C) 2008,2009 by Florian Forster
<octo\ at\ verplant.org>
.PP
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.
.PP
Please note that \fIliboping\fR is licensed under the GPLv2. Derived works of
both, \fINet::Oping\fR and \fIliboping\fR, (i.\ e. binary packages) may
therefore be subject to stricter licensing terms than the source code of this
package.