1Net::Ping(3)          User Contributed Perl Documentation         Net::Ping(3)
2
3
4

NAME

6       Net::Ping - check a remote host for reachability
7

SYNOPSIS

9           use Net::Ping;
10
11           my $p = Net::Ping->new();
12           print "$host is alive.\n" if $p->ping($host);
13           $p->close();
14
15           my $p = Net::Ping->new("icmp");
16           $p->bind($my_addr); # Specify source interface of pings
17           foreach my $host (@host_array)
18           {
19               print "$host is ";
20               print "NOT " unless $p->ping($host, 2);
21               print "reachable.\n";
22               sleep(1);
23           }
24           $p->close();
25
26           my $p = Net::Ping->new("icmpv6");
27           my $ip = "[fd00:dead:beef::4e]";
28           print "$ip is alive.\n" if $p->ping($ip);
29
30           my $p = Net::Ping->new("tcp", 2);
31           # Try connecting to the www port instead of the echo port
32           $p->port_number(scalar(getservbyname("http", "tcp")));
33           while ($stop_time > time())
34           {
35               print "$host not reachable ", scalar(localtime()), "\n"
36                   unless $p->ping($host);
37               sleep(300);
38           }
39           undef($p);
40
41           # Like tcp protocol, but with many hosts
42           my $p = Net::Ping->new("syn");
43           $p->port_number(getservbyname("http", "tcp"));
44           foreach my $host (@host_array) {
45             $p->ping($host);
46           }
47           while (my ($host, $rtt, $ip) = $p->ack) {
48             print "HOST: $host [$ip] ACKed in $rtt seconds.\n";
49           }
50
51           # High precision syntax (requires Time::HiRes)
52           my $p = Net::Ping->new();
53           $p->hires();
54           my ($ret, $duration, $ip) = $p->ping($host, 5.5);
55           printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\n",
56                   1000 * $duration)
57             if $ret;
58           $p->close();
59
60           # For backward compatibility
61           print "$host is alive.\n" if pingecho($host);
62

DESCRIPTION

64       This module contains methods to test the reachability of remote hosts
65       on a network.  A ping object is first created with optional parameters,
66       a variable number of hosts may be pinged multiple times and then the
67       connection is closed.
68
69       You may choose one of six different protocols to use for the ping. The
70       "tcp" protocol is the default. Note that a live remote host may still
71       fail to be pingable by one or more of these protocols. For example,
72       www.microsoft.com is generally alive but not "icmp" pingable.
73
74       With the "tcp" protocol the ping() method attempts to establish a
75       connection to the remote host's echo port.  If the connection is
76       successfully established, the remote host is considered reachable.  No
77       data is actually echoed.  This protocol does not require any special
78       privileges but has higher overhead than the "udp" and "icmp" protocols.
79
80       Specifying the "udp" protocol causes the ping() method to send a udp
81       packet to the remote host's echo port.  If the echoed packet is
82       received from the remote host and the received packet contains the same
83       data as the packet that was sent, the remote host is considered
84       reachable.  This protocol does not require any special privileges.  It
85       should be borne in mind that, for a udp ping, a host will be reported
86       as unreachable if it is not running the appropriate echo service.  For
87       Unix-like systems see inetd(8) for more information.
88
89       If the "icmp" protocol is specified, the ping() method sends an icmp
90       echo message to the remote host, which is what the UNIX ping program
91       does.  If the echoed message is received from the remote host and the
92       echoed information is correct, the remote host is considered reachable.
93       Specifying the "icmp" protocol requires that the program be run as root
94       or that the program be setuid to root.
95
96       If the "external" protocol is specified, the ping() method attempts to
97       use the "Net::Ping::External" module to ping the remote host.
98       "Net::Ping::External" interfaces with your system's default "ping"
99       utility to perform the ping, and generally produces relatively accurate
100       results. If "Net::Ping::External" if not installed on your system,
101       specifying the "external" protocol will result in an error.
102
103       If the "syn" protocol is specified, the "ping" method will only send a
104       TCP SYN packet to the remote host then immediately return.  If the syn
105       packet was sent successfully, it will return a true value, otherwise it
106       will return false.  NOTE: Unlike the other protocols, the return value
107       does NOT determine if the remote host is alive or not since the full
108       TCP three-way handshake may not have completed yet.  The remote host is
109       only considered reachable if it receives a TCP ACK within the timeout
110       specified.  To begin waiting for the ACK packets, use the "ack" method
111       as explained below.  Use the "syn" protocol instead the "tcp" protocol
112       to determine reachability of multiple destinations simultaneously by
113       sending parallel TCP SYN packets.  It will not block while testing each
114       remote host.  This protocol does not require any special privileges.
115
116   Functions
117       Net::Ping->new([proto, timeout, bytes, device, tos, ttl, family, host,
118       port, bind, gateway, retrans, pingstring, source_verify econnrefused
119       dontfrag IPV6_USE_MIN_MTU IPV6_RECVPATHMTU])
120           Create a new ping object.  All of the parameters are optional and
121           can be passed as hash ref.  All options besides the first 7 must be
122           passed as hash ref.
123
124           "proto" specifies the protocol to use when doing a ping.  The
125           current choices are "tcp", "udp", "icmp", "icmpv6", "stream",
126           "syn", or "external".  The default is "tcp".
127
128           If a "timeout" in seconds is provided, it is used when a timeout is
129           not given to the ping() method (below).  The timeout must be
130           greater than 0 and the default, if not specified, is 5 seconds.
131
132           If the number of data bytes ("bytes") is given, that many data
133           bytes are included in the ping packet sent to the remote host. The
134           number of data bytes is ignored if the protocol is "tcp".  The
135           minimum (and default) number of data bytes is 1 if the protocol is
136           "udp" and 0 otherwise.  The maximum number of data bytes that can
137           be specified is 65535, but staying below the MTU (1472 bytes for
138           ICMP) is recommended.  Many small devices cannot deal with
139           fragmented ICMP packets.
140
141           If "device" is given, this device is used to bind the source
142           endpoint before sending the ping packet.  I believe this only works
143           with superuser privileges and with udp and icmp protocols at this
144           time.
145
146           If <tos> is given, this ToS is configured into the socket.
147
148           For icmp, "ttl" can be specified to set the TTL of the outgoing
149           packet.
150
151           Valid "family" values for IPv4:
152
153              4, v4, ip4, ipv4, AF_INET (constant)
154
155           Valid "family" values for IPv6:
156
157              6, v6, ip6, ipv6, AF_INET6 (constant)
158
159           The "host" argument implicitly specifies the family if the family
160           argument is not given.
161
162           The "port" argument is only valid for a udp, tcp or stream ping,
163           and will not do what you think it does. ping returns true when we
164           get a "Connection refused"!  The default is the echo port.
165
166           The "bind" argument specifies the local_addr to bind to.  By
167           specifying a bind argument you don't need the bind method.
168
169           The "gateway" argument is only valid for IPv6, and requires a IPv6
170           address.
171
172           The "retrans" argument the exponential backoff rate, default 1.2.
173           It matches the $def_factor global.
174
175           The "dontfrag" argument sets the IP_DONTFRAG bit, but note that
176           IP_DONTFRAG is not yet defined by Socket, and not available on many
177           systems. Then it is ignored. On linux it also sets IP_MTU_DISCOVER
178           to IP_PMTUDISC_DO but need we don't chunk oversized packets. You
179           need to set $data_size manually.
180
181       $p->ping($host [, $timeout [, $family]]);
182           Ping the remote host and wait for a response.  $host can be either
183           the hostname or the IP number of the remote host.  The optional
184           timeout must be greater than 0 seconds and defaults to whatever was
185           specified when the ping object was created.  Returns a success
186           flag.  If the hostname cannot be found or there is a problem with
187           the IP number, the success flag returned will be undef.  Otherwise,
188           the success flag will be 1 if the host is reachable and 0 if it is
189           not.  For most practical purposes, undef and 0 and can be treated
190           as the same case.  In array context, the elapsed time as well as
191           the string form of the ip the host resolved to are also returned.
192           The elapsed time value will be a float, as returned by the
193           Time::HiRes::time() function, if hires() has been previously
194           called, otherwise it is returned as an integer.
195
196       $p->source_verify( { 0 | 1 } );
197           Allows source endpoint verification to be enabled or disabled.
198           This is useful for those remote destinations with multiples
199           interfaces where the response may not originate from the same
200           endpoint that the original destination endpoint was sent to.  This
201           only affects udp and icmp protocol pings.
202
203           This is enabled by default.
204
205       $p->service_check( { 0 | 1 } );
206           Set whether or not the connect behavior should enforce remote
207           service availability as well as reachability.  Normally, if the
208           remote server reported ECONNREFUSED, it must have been reachable
209           because of the status packet that it reported.  With this option
210           enabled, the full three-way tcp handshake must have been
211           established successfully before it will claim it is reachable.
212           NOTE:  It still does nothing more than connect and disconnect.  It
213           does not speak any protocol (i.e., HTTP or FTP) to ensure the
214           remote server is sane in any way.  The remote server CPU could be
215           grinding to a halt and unresponsive to any clients connecting, but
216           if the kernel throws the ACK packet, it is considered alive anyway.
217           To really determine if the server is responding well would be
218           application specific and is beyond the scope of Net::Ping.  For udp
219           protocol, enabling this option demands that the remote server
220           replies with the same udp data that it was sent as defined by the
221           udp echo service.
222
223           This affects the "udp", "tcp", and "syn" protocols.
224
225           This is disabled by default.
226
227       $p->tcp_service_check( { 0 | 1 } );
228           Deprecated method, but does the same as service_check() method.
229
230       $p->hires( { 0 | 1 } );
231           With 1 causes this module to use Time::HiRes module, allowing
232           milliseconds to be returned by subsequent calls to ping().
233
234       $p->time
235           The current time, hires or not.
236
237       $p->socket_blocking_mode( $fh, $mode );
238           Sets or clears the O_NONBLOCK flag on a file handle.
239
240       $p->IPV6_USE_MIN_MTU
241           With argument sets the option.  Without returns the option value.
242
243       $p->IPV6_RECVPATHMTU
244           Notify an according IPv6 MTU.
245
246           With argument sets the option.  Without returns the option value.
247
248       $p->IPV6_HOPLIMIT
249           With argument sets the option.  Without returns the option value.
250
251       $p->IPV6_REACHCONF NYI
252           Sets ipv6 reachability IPV6_REACHCONF was removed in RFC3542. ping6
253           -R supports it.  IPV6_REACHCONF requires root/admin permissions.
254
255           With argument sets the option.  Without returns the option value.
256
257           Not yet implemented.
258
259       $p->bind($local_addr);
260           Sets the source address from which pings will be sent.  This must
261           be the address of one of the interfaces on the local host.
262           $local_addr may be specified as a hostname or as a text IP address
263           such as "192.168.1.1".
264
265           If the protocol is set to "tcp", this method may be called any
266           number of times, and each call to the ping() method (below) will
267           use the most recent $local_addr.  If the protocol is "icmp" or
268           "udp", then bind() must be called at most once per object, and (if
269           it is called at all) must be called before the first call to ping()
270           for that object.
271
272           The bind() call can be omitted when specifying the "bind" option to
273           new().
274
275       $p->message_type([$ping_type]);
276           When you are using the "icmp" protocol, this call permit to change
277           the message type to 'echo' or 'timestamp' (only for IPv4, see RFC
278           792).
279
280           Without argument, it returns the currently used icmp protocol
281           message type.  By default, it returns 'echo'.
282
283       $p->open($host);
284           When you are using the "stream" protocol, this call pre-opens the
285           tcp socket.  It's only necessary to do this if you want to provide
286           a different timeout when creating the connection, or remove the
287           overhead of establishing the connection from the first ping.  If
288           you don't call open(), the connection is automatically opened the
289           first time ping() is called.  This call simply does nothing if you
290           are using any protocol other than stream.
291
292           The $host argument can be omitted when specifying the "host" option
293           to new().
294
295       $p->ack( [ $host ] );
296           When using the "syn" protocol, use this method to determine the
297           reachability of the remote host.  This method is meant to be called
298           up to as many times as ping() was called.  Each call returns the
299           host (as passed to ping()) that came back with the TCP ACK.  The
300           order in which the hosts are returned may not necessarily be the
301           same order in which they were SYN queued using the ping() method.
302           If the timeout is reached before the TCP ACK is received, or if the
303           remote host is not listening on the port attempted, then the TCP
304           connection will not be established and ack() will return undef.  In
305           list context, the host, the ack time, the dotted ip string, and the
306           port number will be returned instead of just the host.  If the
307           optional $host argument is specified, the return value will be
308           pertaining to that host only.  This call simply does nothing if you
309           are using any protocol other than "syn".
310
311           When "new" had a host option, this host will be used.  Without
312           $host argument, all hosts are scanned.
313
314       $p->nack( $failed_ack_host );
315           The reason that "host $failed_ack_host" did not receive a valid
316           ACK.  Useful to find out why when ack($fail_ack_host) returns a
317           false value.
318
319       $p->ack_unfork($host)
320           The variant called by "ack" with the "syn" protocol and
321           $syn_forking enabled.
322
323       $p->ping_icmp([$host, $timeout, $family])
324           The "ping" method used with the icmp protocol.
325
326       $p->ping_icmpv6([$host, $timeout, $family])
327           The "ping" method used with the icmpv6 protocol.
328
329       $p->ping_stream([$host, $timeout, $family])
330           The "ping" method used with the stream protocol.
331
332           Perform a stream ping.  If the tcp connection isn't already open,
333           it opens it.  It then sends some data and waits for a reply.  It
334           leaves the stream open on exit.
335
336       $p->ping_syn([$host, $ip, $start_time, $stop_time])
337           The "ping" method used with the syn protocol.  Sends a TCP SYN
338           packet to host specified.
339
340       $p->ping_syn_fork([$host, $timeout, $family])
341           The "ping" method used with the forking syn protocol.
342
343       $p->ping_tcp([$host, $timeout, $family])
344           The "ping" method used with the tcp protocol.
345
346       $p->ping_udp([$host, $timeout, $family])
347           The "ping" method used with the udp protocol.
348
349           Perform a udp echo ping.  Construct a message of at least the one-
350           byte sequence number and any additional data bytes.  Send the
351           message out and wait for a message to come back.  If we get a
352           message, make sure all of its parts match.  If they do, we are
353           done.  Otherwise go back and wait for the message until we run out
354           of time.  Return the result of our efforts.
355
356       $p->ping_external([$host, $timeout, $family])
357           The "ping" method used with the external protocol.  Uses
358           Net::Ping::External to do an external ping.
359
360       $p->tcp_connect([$ip, $timeout])
361           Initiates a TCP connection, for a tcp ping.
362
363       $p->tcp_echo([$ip, $timeout, $pingstring])
364           Performs a TCP echo.  It writes the given string to the socket and
365           then reads it back.  It returns 1 on success, 0 on failure.
366
367       $p->close();
368           Close the network connection for this ping object.  The network
369           connection is also closed by "undef $p".  The network connection is
370           automatically closed if the ping object goes out of scope (e.g. $p
371           is local to a subroutine and you leave the subroutine).
372
373       $p->port_number([$port_number])
374           When called with a port number, the port number used to ping is set
375           to $port_number rather than using the echo port.  It also has the
376           effect of calling "$p->service_check(1)" causing a ping to return a
377           successful response only if that specific port is accessible.  This
378           function returns the value of the port that "ping" will connect to.
379
380       $p->mselect
381           A select() wrapper that compensates for platform peculiarities.
382
383       $p->ntop
384           Platform abstraction over inet_ntop()
385
386       $p->checksum($msg)
387           Do a checksum on the message.  Basically sum all of the short words
388           and fold the high order bits into the low order bits.
389
390       $p->icmp_result
391           Returns a list of addr, type, subcode.
392
393       pingecho($host [, $timeout]);
394           To provide backward compatibility with the previous version of
395           Net::Ping, a pingecho() subroutine is available with the same
396           functionality as before.  pingecho() uses the tcp protocol.  The
397           return values and parameters are the same as described for the
398           "ping" method.  This subroutine is obsolete and may be removed in a
399           future version of Net::Ping.
400
401       wakeonlan($mac, [$host, [$port]])
402           Emit the popular wake-on-lan magic udp packet to wake up a local
403           device.  See also Net::Wake, but this has the mac address as 1st
404           arg.  $host should be the local gateway. Without it will broadcast.
405
406           Default host: '255.255.255.255' Default port: 9
407
408             perl -MNet::Ping=wakeonlan -e'wakeonlan "e0:69:95:35:68:d2"'
409

NOTES

411       There will be less network overhead (and some efficiency in your
412       program) if you specify either the udp or the icmp protocol.  The tcp
413       protocol will generate 2.5 times or more traffic for each ping than
414       either udp or icmp.  If many hosts are pinged frequently, you may wish
415       to implement a small wait (e.g. 25ms or more) between each ping to
416       avoid flooding your network with packets.
417
418       The icmp and icmpv6 protocols requires that the program be run as root
419       or that it be setuid to root.  The other protocols do not require
420       special privileges, but not all network devices implement tcp or udp
421       echo.
422
423       Local hosts should normally respond to pings within milliseconds.
424       However, on a very congested network it may take up to 3 seconds or
425       longer to receive an echo packet from the remote host.  If the timeout
426       is set too low under these conditions, it will appear that the remote
427       host is not reachable (which is almost the truth).
428
429       Reachability doesn't necessarily mean that the remote host is actually
430       functioning beyond its ability to echo packets.  tcp is slightly better
431       at indicating the health of a system than icmp because it uses more of
432       the networking stack to respond.
433
434       Because of a lack of anything better, this module uses its own routines
435       to pack and unpack ICMP packets.  It would be better for a separate
436       module to be written which understands all of the different kinds of
437       ICMP packets.
438

INSTALL

440       The latest source tree is available via git:
441
442         git clone https://github.com/rurban/Net-Ping.git
443         cd Net-Ping
444
445       The tarball can be created as follows:
446
447         perl Makefile.PL ; make ; make dist
448
449       The latest Net::Ping releases are included in cperl and perl5.
450

BUGS

452       For a list of known issues, visit:
453
454       <https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net-Ping> and
455       <https://github.com/rurban/Net-Ping/issues>
456
457       To report a new bug, visit:
458
459       <https://github.com/rurban/Net-Ping/issues>
460

AUTHORS

462         Current maintainers:
463           perl11 (for cperl, with IPv6 support and more)
464           p5p    (for perl5)
465
466         Previous maintainers:
467           bbb@cpan.org (Rob Brown)
468           Steve Peters
469
470         External protocol:
471           colinm@cpan.org (Colin McMillen)
472
473         Stream protocol:
474           bronson@trestle.com (Scott Bronson)
475
476         Wake-on-lan:
477           1999-2003 Clinton Wong
478
479         Original pingecho():
480           karrer@bernina.ethz.ch (Andreas Karrer)
481           pmarquess@bfsec.bt.co.uk (Paul Marquess)
482
483         Original Net::Ping author:
484           mose@ns.ccsn.edu (Russell Mosemann)
485
487       Copyright (c) 2017-2020, Reini Urban.  All rights reserved.
488
489       Copyright (c) 2016, cPanel Inc.  All rights reserved.
490
491       Copyright (c) 2012, Steve Peters.  All rights reserved.
492
493       Copyright (c) 2002-2003, Rob Brown.  All rights reserved.
494
495       Copyright (c) 2001, Colin McMillen.  All rights reserved.
496
497       This program is free software; you may redistribute it and/or modify it
498       under the same terms as Perl itself.
499
500
501
502perl v5.38.0                      2023-07-21                      Net::Ping(3)
Impressum