1 package Net::Oping;
3 =head1 NAME
5 Net::Oping - ICMP latency measurement module using the oping library.
7 =head1 SYNOPSIS
9 use Net::Oping;
11 my $obj = Net::Oping->new ();
12 $obj->host_add (qw(one.example.org two.example.org));
14 my $ret = $obj->ping ();
15 print "Latency to `one' is " . $ret->{'one.example.org'} . "\n";
17 =head1 DESCRIPTION
19 This Perl module is a high-level interface to the
20 L<oping library|http://verplant.org/liboping/>. Its purpose it to send C<ICMP
21 ECHO_REQUEST> packets (also known as "ping") to a host and measure the time
22 that elapses until the reception of an C<ICMP ECHO_REPLY> packet (also known as
23 "pong"). If no such packet is received after a certain timeout the host is considered to be unreachable.
25 The used C<oping> library supports "ping"ing multiple hosts in parallel and
26 works with IPv4 and IPv6 transparently. Other advanced features that are
27 provided by the underlying library, such as setting the data sent or
28 configuring the time of live (TTL) are not yet supported by this interface.
30 =cut
32 use 5.008007;
34 use strict;
35 use warnings;
37 use Carp (qw(cluck confess));
39 our $VERSION = '1.00';
41 require XSLoader;
42 XSLoader::load('Net::Oping', $VERSION);
43 return (1);
45 =head1 INTERFACE
47 The interface is kept simple and clean. First you need to create an object to
48 which you then add hosts. Using the C<ping> method you can request a latency
49 measurement and get the current values returned. If neccessary you can remove
50 hosts from the object, too.
52 The constructor and methods are defined as follows:
54 =over 4
56 =item my I<$obj> = Net::Oping-E<gt>B<new> ();
58 Creates and returns a new object.
60 =cut
62 sub new
63 {
64 my $pkg = shift;
65 my $ping_obj = _ping_construct ();
67 my $obj = bless ({ c_obj => $ping_obj }, $pkg);
68 return ($obj);
69 }
71 sub DESTROY
72 {
73 my $obj = shift;
74 _ping_destroy ($obj->{'c_obj'});
75 }
77 =item my I<$status> = I<$obj>-E<gt>B<timeout> (I<$timeout>);
79 Sets the timeout before a host is considered unreachable to I<$timeout>
80 seconds, which may be a floating point number to specify fractional seconds.
82 =cut
84 sub timeout
85 {
86 my $obj = shift;
87 my $timeout = shift;
88 my $status;
90 $status = _ping_setopt_timeout ($obj->{'c_obj'}, $timeout);
91 if ($status != 0)
92 {
93 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
94 return;
95 }
97 return (1);
98 }
100 =item my I<$status> = I<$obj>-E<gt>B<bind> (I<$ip_addr>);
102 Sets the source IP-address to use. I<$ip_addr> must be a string containing an
103 IP-address, such as "192.168.0.1" or "2001:f00::1". As a side-effect this will
104 set the address-family (IPv4 or IPv6) to a fixed, value, too, for obvious
105 reasons.
107 =cut
109 sub bind
110 {
111 my $obj = shift;
112 my $addr = shift;
113 my $status;
115 $status = _ping_setopt_source ($obj->{'c_obj'}, $addr);
116 if ($status != 0)
117 {
118 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
119 return;
120 }
122 return (1);
123 }
125 =item my I<$status> = I<$obj>-E<gt>B<host_add> (I<$host>, [I<$host>, ...]);
127 Adds one or more hosts to the Net::Oping-object I<$obj>. The number of
128 successfully added hosts is returned. If this number differs from the number of
129 hosts that were passed to the method you can use B<get_error> (see below) to
130 get the error message of the last failure.
132 =cut
134 sub host_add
135 {
136 my $obj = shift;
137 my $i;
139 $i = 0;
140 for (@_)
141 {
142 my $status = _ping_host_add ($obj->{'c_obj'}, $_);
143 if ($status != 0)
144 {
145 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
146 }
147 else
148 {
149 $i++;
150 }
151 }
153 return ($i);
154 }
156 =item my I<$status> = I<$obj>-E<gt>B<host_remove> (I<$host>, [I<$host>, ...]);
158 Same semantic as B<host_add> but removes hosts.
160 =cut
162 sub host_remove
163 {
164 my $obj = shift;
165 my $i;
167 $i = 0;
168 for (@_)
169 {
170 my $status = _ping_host_remove ($obj->{'c_obj'}, $_);
171 if ($status != 0)
172 {
173 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
174 }
175 else
176 {
177 $i++;
178 }
179 }
180 return ($i);
181 }
183 =item my I<$latency> = I<$obj>-E<gt>B<ping> ()
185 The central method of this module sends ICMP packets to the hosts and waits for
186 replies. The time it takes for replies to arrive is measured and returned.
188 The returned scalar is a hash reference where each host associated with the
189 I<$obj> object is a key and the associated value is the corresponding latency
190 in milliseconds. An example hash reference would be:
192 $latency = { host1 => 51.143, host2 => undef, host3 => 54.697, ... };
194 If a value is C<undef>, as for "host2" in this example, the host has timed out
195 and considered unreachable.
197 =cut
199 sub ping
200 {
201 my $obj = shift;
202 my $iter;
203 my $data = {};
204 my $status;
206 $status = _ping_send ($obj->{'c_obj'});
207 if ($status < 0)
208 {
209 print "\$status = $status;\n";
210 $obj->{'err_msg'} = "" . _ping_get_error ($obj->{'c_obj'});
211 return;
212 }
214 $iter = _ping_iterator_get ($obj->{'c_obj'});
215 while ($iter)
216 {
217 my $host = _ping_iterator_get_hostname ($iter);
218 if (!$host)
219 {
220 $iter = _ping_iterator_next ($iter);
221 next;
222 }
224 my $latency = _ping_iterator_get_latency ($iter);
225 if ($latency < 0.0)
226 {
227 $latency = undef;
228 }
230 $data->{$host} = $latency;
232 $iter = _ping_iterator_next ($iter);
233 }
235 return ($data);
236 }
238 =item my I<$errmsg> = I<$obj>-E<gt>B<get_error> ();
240 Returns the last error that occured.
242 =cut
244 sub get_error
245 {
246 my $obj = shift;
247 return ($obj->{'err_msg'} || 'Success');
248 }
250 =back
252 =head1 SEE ALSO
254 L<liboping(3)>
256 The C<liboping> homepage may be found at L<http://verplant.org/liboping/>.
257 Information about its mailing list may be found at
258 L<http://mailman.verplant.org/listinfo/liboping>.
260 =head1 AUTHOR
262 First XSE<nbsp>port by Olivier Fredj, extended XS functionality and high-level
263 Perl interface by Florian Forster.
265 =head1 COPYRIGHT AND LICENSE
267 Copyright (C) 2007 by Olivier Fredj E<lt>ofredjE<nbsp>atE<nbsp>proxad.netE<gt>
269 Copyright (C) 2008 by Florian Forster
270 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
272 This library is free software; you can redistribute it and/or modify
273 it under the same terms as Perl itself, either Perl version 5.8.7 or,
274 at your option, any later version of Perl 5 you may have available.
276 =cut
278 # vim: set shiftwidth=2 softtabstop=2 tabstop=8 :