| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Net::Ping 3perl" |
| 58 |
.TH Net::Ping 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Net::Ping \- check a remote host for reachability |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 1 |
| 68 |
\& use Net::Ping; |
| 69 |
\& |
| 70 |
\& my $p = Net::Ping\->new(); |
| 71 |
\& print "$host is alive.\en" if $p\->ping($host); |
| 72 |
\& $p\->close(); |
| 73 |
\& |
| 74 |
\& my $p = Net::Ping\->new("icmp"); |
| 75 |
\& $p\->bind($my_addr); # Specify source interface of pings |
| 76 |
\& foreach my $host (@host_array) |
| 77 |
\& { |
| 78 |
\& print "$host is "; |
| 79 |
\& print "NOT " unless $p\->ping($host, 2); |
| 80 |
\& print "reachable.\en"; |
| 81 |
\& sleep(1); |
| 82 |
\& } |
| 83 |
\& $p\->close(); |
| 84 |
\& |
| 85 |
\& my $p = Net::Ping\->new("icmpv6"); |
| 86 |
\& my $ip = "[fd00:dead:beef::4e]"; |
| 87 |
\& print "$ip is alive.\en" if $p\->ping($ip); |
| 88 |
\& |
| 89 |
\& my $p = Net::Ping\->new("tcp", 2); |
| 90 |
\& # Try connecting to the www port instead of the echo port |
| 91 |
\& $p\->port_number(scalar(getservbyname("http", "tcp"))); |
| 92 |
\& while ($stop_time > time()) |
| 93 |
\& { |
| 94 |
\& print "$host not reachable ", scalar(localtime()), "\en" |
| 95 |
\& unless $p\->ping($host); |
| 96 |
\& sleep(300); |
| 97 |
\& } |
| 98 |
\& undef($p); |
| 99 |
\& |
| 100 |
\& # Like tcp protocol, but with many hosts |
| 101 |
\& my $p = Net::Ping\->new("syn"); |
| 102 |
\& $p\->port_number(getservbyname("http", "tcp")); |
| 103 |
\& foreach my $host (@host_array) { |
| 104 |
\& $p\->ping($host); |
| 105 |
\& } |
| 106 |
\& while (my ($host, $rtt, $ip) = $p\->ack) { |
| 107 |
\& print "HOST: $host [$ip] ACKed in $rtt seconds.\en"; |
| 108 |
\& } |
| 109 |
\& |
| 110 |
\& # High precision syntax (requires Time::HiRes) |
| 111 |
\& my $p = Net::Ping\->new(); |
| 112 |
\& $p\->hires(); |
| 113 |
\& my ($ret, $duration, $ip) = $p\->ping($host, 5.5); |
| 114 |
\& printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\en", |
| 115 |
\& 1000 * $duration) |
| 116 |
\& if $ret; |
| 117 |
\& $p\->close(); |
| 118 |
\& |
| 119 |
\& # For backward compatibility |
| 120 |
\& print "$host is alive.\en" if pingecho($host); |
| 121 |
.Ve |
| 122 |
.SH DESCRIPTION |
| 123 |
.IX Header "DESCRIPTION" |
| 124 |
This module contains methods to test the reachability of remote |
| 125 |
hosts on a network. A ping object is first created with optional |
| 126 |
parameters, a variable number of hosts may be pinged multiple |
| 127 |
times and then the connection is closed. |
| 128 |
.PP |
| 129 |
You may choose one of six different protocols to use for the |
| 130 |
ping. The "tcp" protocol is the default. Note that a live remote host |
| 131 |
may still fail to be pingable by one or more of these protocols. For |
| 132 |
example, www.microsoft.com is generally alive but not "icmp" pingable. |
| 133 |
.PP |
| 134 |
With the "tcp" protocol the \fBping()\fR method attempts to establish a |
| 135 |
connection to the remote host's echo port. If the connection is |
| 136 |
successfully established, the remote host is considered reachable. No |
| 137 |
data is actually echoed. This protocol does not require any special |
| 138 |
privileges but has higher overhead than the "udp" and "icmp" protocols. |
| 139 |
.PP |
| 140 |
Specifying the "udp" protocol causes the \fBping()\fR method to send a udp |
| 141 |
packet to the remote host's echo port. If the echoed packet is |
| 142 |
received from the remote host and the received packet contains the |
| 143 |
same data as the packet that was sent, the remote host is considered |
| 144 |
reachable. This protocol does not require any special privileges. |
| 145 |
It should be borne in mind that, for a udp ping, a host |
| 146 |
will be reported as unreachable if it is not running the |
| 147 |
appropriate echo service. For Unix-like systems see \fBinetd\fR\|(8) |
| 148 |
for more information. |
| 149 |
.PP |
| 150 |
If the "icmp" protocol is specified, the \fBping()\fR method sends an icmp |
| 151 |
echo message to the remote host, which is what the UNIX ping program |
| 152 |
does. If the echoed message is received from the remote host and |
| 153 |
the echoed information is correct, the remote host is considered |
| 154 |
reachable. Specifying the "icmp" protocol requires that the program |
| 155 |
be run as root or that the program be setuid to root. |
| 156 |
.PP |
| 157 |
If the "external" protocol is specified, the \fBping()\fR method attempts to |
| 158 |
use the \f(CW\*(C`Net::Ping::External\*(C'\fR module to ping the remote host. |
| 159 |
\&\f(CW\*(C`Net::Ping::External\*(C'\fR interfaces with your system's default \f(CW\*(C`ping\*(C'\fR |
| 160 |
utility to perform the ping, and generally produces relatively |
| 161 |
accurate results. If \f(CW\*(C`Net::Ping::External\*(C'\fR if not installed on your |
| 162 |
system, specifying the "external" protocol will result in an error. |
| 163 |
.PP |
| 164 |
If the "syn" protocol is specified, the "ping" method will only |
| 165 |
send a TCP SYN packet to the remote host then immediately return. |
| 166 |
If the syn packet was sent successfully, it will return a true value, |
| 167 |
otherwise it will return false. NOTE: Unlike the other protocols, |
| 168 |
the return value does NOT determine if the remote host is alive or |
| 169 |
not since the full TCP three-way handshake may not have completed |
| 170 |
yet. The remote host is only considered reachable if it receives |
| 171 |
a TCP ACK within the timeout specified. To begin waiting for the |
| 172 |
ACK packets, use the "ack" method as explained below. Use the |
| 173 |
"syn" protocol instead the "tcp" protocol to determine reachability |
| 174 |
of multiple destinations simultaneously by sending parallel TCP |
| 175 |
SYN packets. It will not block while testing each remote host. |
| 176 |
This protocol does not require any special privileges. |
| 177 |
.SS Functions |
| 178 |
.IX Subsection "Functions" |
| 179 |
.IP "Net::Ping\->new([proto, timeout, bytes, device, tos, ttl, family, host, port, bind, gateway, retrans, pingstring, source_verify econnrefused dontfrag IPV6_USE_MIN_MTU IPV6_RECVPATHMTU])" 4 |
| 180 |
.IX Xref "new" |
| 181 |
.IX Item "Net::Ping->new([proto, timeout, bytes, device, tos, ttl, family, host, port, bind, gateway, retrans, pingstring, source_verify econnrefused dontfrag IPV6_USE_MIN_MTU IPV6_RECVPATHMTU])" |
| 182 |
Create a new ping object. All of the parameters are optional and can |
| 183 |
be passed as hash ref. All options besides the first 7 must be passed |
| 184 |
as hash ref. |
| 185 |
.Sp |
| 186 |
\&\f(CW\*(C`proto\*(C'\fR specifies the protocol to use when doing a ping. The current |
| 187 |
choices are "tcp", "udp", "icmp", "icmpv6", "stream", "syn", or |
| 188 |
"external". The default is "tcp". |
| 189 |
.Sp |
| 190 |
If a \f(CW\*(C`timeout\*(C'\fR in seconds is provided, it is used |
| 191 |
when a timeout is not given to the \fBping()\fR method (below). The timeout |
| 192 |
must be greater than 0 and the default, if not specified, is 5 seconds. |
| 193 |
.Sp |
| 194 |
If the number of data bytes (\f(CW\*(C`bytes\*(C'\fR) is given, that many data bytes |
| 195 |
are included in the ping packet sent to the remote host. The number of |
| 196 |
data bytes is ignored if the protocol is "tcp". The minimum (and |
| 197 |
default) number of data bytes is 1 if the protocol is "udp" and 0 |
| 198 |
otherwise. The maximum number of data bytes that can be specified is |
| 199 |
65535, but staying below the MTU (1472 bytes for ICMP) is recommended. |
| 200 |
Many small devices cannot deal with fragmented ICMP packets. |
| 201 |
.Sp |
| 202 |
If \f(CW\*(C`device\*(C'\fR is given, this device is used to bind the source endpoint |
| 203 |
before sending the ping packet. I believe this only works with |
| 204 |
superuser privileges and with udp and icmp protocols at this time. |
| 205 |
.Sp |
| 206 |
If <tos> is given, this ToS is configured into the socket. |
| 207 |
.Sp |
| 208 |
For icmp, \f(CW\*(C`ttl\*(C'\fR can be specified to set the TTL of the outgoing packet. |
| 209 |
.Sp |
| 210 |
Valid \f(CW\*(C`family\*(C'\fR values for IPv4: |
| 211 |
.Sp |
| 212 |
.Vb 1 |
| 213 |
\& 4, v4, ip4, ipv4, AF_INET (constant) |
| 214 |
.Ve |
| 215 |
.Sp |
| 216 |
Valid \f(CW\*(C`family\*(C'\fR values for IPv6: |
| 217 |
.Sp |
| 218 |
.Vb 1 |
| 219 |
\& 6, v6, ip6, ipv6, AF_INET6 (constant) |
| 220 |
.Ve |
| 221 |
.Sp |
| 222 |
The \f(CW\*(C`host\*(C'\fR argument implicitly specifies the family if the family |
| 223 |
argument is not given. |
| 224 |
.Sp |
| 225 |
The \f(CW\*(C`port\*(C'\fR argument is only valid for a udp, tcp or stream ping, and will not |
| 226 |
do what you think it does. ping returns true when we get a "Connection refused"! |
| 227 |
The default is the echo port. |
| 228 |
.Sp |
| 229 |
The \f(CW\*(C`bind\*(C'\fR argument specifies the local_addr to bind to. |
| 230 |
By specifying a bind argument you don't need the bind method. |
| 231 |
.Sp |
| 232 |
The \f(CW\*(C`gateway\*(C'\fR argument is only valid for IPv6, and requires a IPv6 |
| 233 |
address. |
| 234 |
.Sp |
| 235 |
The \f(CW\*(C`retrans\*(C'\fR argument the exponential backoff rate, default 1.2. |
| 236 |
It matches the \f(CW$def_factor\fR global. |
| 237 |
.Sp |
| 238 |
The \f(CW\*(C`dontfrag\*(C'\fR argument sets the IP_DONTFRAG bit, but note that |
| 239 |
IP_DONTFRAG is not yet defined by Socket, and not available on many |
| 240 |
systems. Then it is ignored. On linux it also sets IP_MTU_DISCOVER to |
| 241 |
IP_PMTUDISC_DO but need we don't chunk oversized packets. You need to |
| 242 |
set \f(CW$data_size\fR manually. |
| 243 |
.ie n .IP "$p\->ping($host [, $timeout [, $family]]);" 4 |
| 244 |
.el .IP "\f(CW$p\fR\->ping($host [, \f(CW$timeout\fR [, \f(CW$family\fR]]);" 4 |
| 245 |
.IX Xref "ping" |
| 246 |
.IX Item "$p->ping($host [, $timeout [, $family]]);" |
| 247 |
Ping the remote host and wait for a response. \f(CW$host\fR can be either the |
| 248 |
hostname or the IP number of the remote host. The optional timeout |
| 249 |
must be greater than 0 seconds and defaults to whatever was specified |
| 250 |
when the ping object was created. Returns a success flag. If the |
| 251 |
hostname cannot be found or there is a problem with the IP number, the |
| 252 |
success flag returned will be undef. Otherwise, the success flag will |
| 253 |
be 1 if the host is reachable and 0 if it is not. For most practical |
| 254 |
purposes, undef and 0 and can be treated as the same case. In array |
| 255 |
context, the elapsed time as well as the string form of the ip the |
| 256 |
host resolved to are also returned. The elapsed time value will |
| 257 |
be a float, as returned by the \fBTime::HiRes::time()\fR function, if \fBhires()\fR |
| 258 |
has been previously called, otherwise it is returned as an integer. |
| 259 |
.ie n .IP "$p\->source_verify( { 0 | 1 } );" 4 |
| 260 |
.el .IP "\f(CW$p\fR\->source_verify( { 0 | 1 } );" 4 |
| 261 |
.IX Xref "source_verify" |
| 262 |
.IX Item "$p->source_verify( { 0 | 1 } );" |
| 263 |
Allows source endpoint verification to be enabled or disabled. |
| 264 |
This is useful for those remote destinations with multiples |
| 265 |
interfaces where the response may not originate from the same |
| 266 |
endpoint that the original destination endpoint was sent to. |
| 267 |
This only affects udp and icmp protocol pings. |
| 268 |
.Sp |
| 269 |
This is enabled by default. |
| 270 |
.ie n .IP "$p\->service_check( { 0 | 1 } );" 4 |
| 271 |
.el .IP "\f(CW$p\fR\->service_check( { 0 | 1 } );" 4 |
| 272 |
.IX Xref "service_check" |
| 273 |
.IX Item "$p->service_check( { 0 | 1 } );" |
| 274 |
Set whether or not the connect behavior should enforce |
| 275 |
remote service availability as well as reachability. Normally, |
| 276 |
if the remote server reported ECONNREFUSED, it must have been |
| 277 |
reachable because of the status packet that it reported. |
| 278 |
With this option enabled, the full three-way tcp handshake |
| 279 |
must have been established successfully before it will |
| 280 |
claim it is reachable. NOTE: It still does nothing more |
| 281 |
than connect and disconnect. It does not speak any protocol |
| 282 |
(i.e., HTTP or FTP) to ensure the remote server is sane in |
| 283 |
any way. The remote server CPU could be grinding to a halt |
| 284 |
and unresponsive to any clients connecting, but if the kernel |
| 285 |
throws the ACK packet, it is considered alive anyway. To |
| 286 |
really determine if the server is responding well would be |
| 287 |
application specific and is beyond the scope of Net::Ping. |
| 288 |
For udp protocol, enabling this option demands that the |
| 289 |
remote server replies with the same udp data that it was sent |
| 290 |
as defined by the udp echo service. |
| 291 |
.Sp |
| 292 |
This affects the "udp", "tcp", and "syn" protocols. |
| 293 |
.Sp |
| 294 |
This is disabled by default. |
| 295 |
.ie n .IP "$p\->tcp_service_check( { 0 | 1 } );" 4 |
| 296 |
.el .IP "\f(CW$p\fR\->tcp_service_check( { 0 | 1 } );" 4 |
| 297 |
.IX Xref "tcp_service_check" |
| 298 |
.IX Item "$p->tcp_service_check( { 0 | 1 } );" |
| 299 |
Deprecated method, but does the same as \fBservice_check()\fR method. |
| 300 |
.ie n .IP "$p\->hires( { 0 | 1 } );" 4 |
| 301 |
.el .IP "\f(CW$p\fR\->hires( { 0 | 1 } );" 4 |
| 302 |
.IX Xref "hires" |
| 303 |
.IX Item "$p->hires( { 0 | 1 } );" |
| 304 |
With 1 causes this module to use Time::HiRes module, allowing milliseconds |
| 305 |
to be returned by subsequent calls to \fBping()\fR. |
| 306 |
.ie n .IP $p\->time 4 |
| 307 |
.el .IP \f(CW$p\fR\->time 4 |
| 308 |
.IX Xref "time" |
| 309 |
.IX Item "$p->time" |
| 310 |
The current time, hires or not. |
| 311 |
.ie n .IP "$p\->socket_blocking_mode( $fh, $mode );" 4 |
| 312 |
.el .IP "\f(CW$p\fR\->socket_blocking_mode( \f(CW$fh\fR, \f(CW$mode\fR );" 4 |
| 313 |
.IX Xref "socket_blocking_mode" |
| 314 |
.IX Item "$p->socket_blocking_mode( $fh, $mode );" |
| 315 |
Sets or clears the O_NONBLOCK flag on a file handle. |
| 316 |
.ie n .IP $p\->IPV6_USE_MIN_MTU 4 |
| 317 |
.el .IP \f(CW$p\fR\->IPV6_USE_MIN_MTU 4 |
| 318 |
.IX Xref "IPV6_USE_MIN_MTU" |
| 319 |
.IX Item "$p->IPV6_USE_MIN_MTU" |
| 320 |
With argument sets the option. |
| 321 |
Without returns the option value. |
| 322 |
.ie n .IP $p\->IPV6_RECVPATHMTU 4 |
| 323 |
.el .IP \f(CW$p\fR\->IPV6_RECVPATHMTU 4 |
| 324 |
.IX Xref "IPV6_RECVPATHMTU" |
| 325 |
.IX Item "$p->IPV6_RECVPATHMTU" |
| 326 |
Notify an according IPv6 MTU. |
| 327 |
.Sp |
| 328 |
With argument sets the option. |
| 329 |
Without returns the option value. |
| 330 |
.ie n .IP $p\->IPV6_HOPLIMIT 4 |
| 331 |
.el .IP \f(CW$p\fR\->IPV6_HOPLIMIT 4 |
| 332 |
.IX Xref "IPV6_HOPLIMIT" |
| 333 |
.IX Item "$p->IPV6_HOPLIMIT" |
| 334 |
With argument sets the option. |
| 335 |
Without returns the option value. |
| 336 |
.ie n .IP "$p\->IPV6_REACHCONF \fINYI\fR" 4 |
| 337 |
.el .IP "\f(CW$p\fR\->IPV6_REACHCONF \fINYI\fR" 4 |
| 338 |
.IX Xref "IPV6_REACHCONF" |
| 339 |
.IX Item "$p->IPV6_REACHCONF NYI" |
| 340 |
Sets ipv6 reachability |
| 341 |
IPV6_REACHCONF was removed in RFC3542. ping6 \-R supports it. |
| 342 |
IPV6_REACHCONF requires root/admin permissions. |
| 343 |
.Sp |
| 344 |
With argument sets the option. |
| 345 |
Without returns the option value. |
| 346 |
.Sp |
| 347 |
Not yet implemented. |
| 348 |
.ie n .IP $p\->bind($local_addr); 4 |
| 349 |
.el .IP \f(CW$p\fR\->bind($local_addr); 4 |
| 350 |
.IX Xref "bind" |
| 351 |
.IX Item "$p->bind($local_addr);" |
| 352 |
Sets the source address from which pings will be sent. This must be |
| 353 |
the address of one of the interfaces on the local host. \f(CW$local_addr\fR |
| 354 |
may be specified as a hostname or as a text IP address such as |
| 355 |
"192.168.1.1". |
| 356 |
.Sp |
| 357 |
If the protocol is set to "tcp", this method may be called any |
| 358 |
number of times, and each call to the \fBping()\fR method (below) will use |
| 359 |
the most recent \f(CW$local_addr\fR. If the protocol is "icmp" or "udp", |
| 360 |
then \fBbind()\fR must be called at most once per object, and (if it is |
| 361 |
called at all) must be called before the first call to \fBping()\fR for that |
| 362 |
object. |
| 363 |
.Sp |
| 364 |
The \fBbind()\fR call can be omitted when specifying the \f(CW\*(C`bind\*(C'\fR option to |
| 365 |
\&\fBnew()\fR. |
| 366 |
.ie n .IP $p\->message_type([$ping_type]); 4 |
| 367 |
.el .IP \f(CW$p\fR\->message_type([$ping_type]); 4 |
| 368 |
.IX Xref "message_type" |
| 369 |
.IX Item "$p->message_type([$ping_type]);" |
| 370 |
When you are using the "icmp" protocol, this call permit to change the |
| 371 |
message type to 'echo' or 'timestamp' (only for IPv4, see RFC 792). |
| 372 |
.Sp |
| 373 |
Without argument, it returns the currently used icmp protocol message type. |
| 374 |
By default, it returns 'echo'. |
| 375 |
.ie n .IP $p\->open($host); 4 |
| 376 |
.el .IP \f(CW$p\fR\->open($host); 4 |
| 377 |
.IX Xref "open" |
| 378 |
.IX Item "$p->open($host);" |
| 379 |
When you are using the "stream" protocol, this call pre-opens the |
| 380 |
tcp socket. It's only necessary to do this if you want to |
| 381 |
provide a different timeout when creating the connection, or |
| 382 |
remove the overhead of establishing the connection from the |
| 383 |
first ping. If you don't call \f(CWopen()\fR, the connection is |
| 384 |
automatically opened the first time \f(CWping()\fR is called. |
| 385 |
This call simply does nothing if you are using any protocol other |
| 386 |
than stream. |
| 387 |
.Sp |
| 388 |
The \f(CW$host\fR argument can be omitted when specifying the \f(CW\*(C`host\*(C'\fR option to |
| 389 |
\&\fBnew()\fR. |
| 390 |
.ie n .IP "$p\->ack( [ $host ] );" 4 |
| 391 |
.el .IP "\f(CW$p\fR\->ack( [ \f(CW$host\fR ] );" 4 |
| 392 |
.IX Xref "ack" |
| 393 |
.IX Item "$p->ack( [ $host ] );" |
| 394 |
When using the "syn" protocol, use this method to determine |
| 395 |
the reachability of the remote host. This method is meant |
| 396 |
to be called up to as many times as \fBping()\fR was called. Each |
| 397 |
call returns the host (as passed to \fBping()\fR) that came back |
| 398 |
with the TCP ACK. The order in which the hosts are returned |
| 399 |
may not necessarily be the same order in which they were |
| 400 |
SYN queued using the \fBping()\fR method. If the timeout is |
| 401 |
reached before the TCP ACK is received, or if the remote |
| 402 |
host is not listening on the port attempted, then the TCP |
| 403 |
connection will not be established and \fBack()\fR will return |
| 404 |
undef. In list context, the host, the ack time, the dotted ip |
| 405 |
string, and the port number will be returned instead of just the host. |
| 406 |
If the optional \f(CW$host\fR argument is specified, the return |
| 407 |
value will be pertaining to that host only. |
| 408 |
This call simply does nothing if you are using any protocol |
| 409 |
other than "syn". |
| 410 |
.Sp |
| 411 |
When "new" had a host option, this host will be used. |
| 412 |
Without \f(CW$host\fR argument, all hosts are scanned. |
| 413 |
.ie n .IP "$p\->nack( $failed_ack_host );" 4 |
| 414 |
.el .IP "\f(CW$p\fR\->nack( \f(CW$failed_ack_host\fR );" 4 |
| 415 |
.IX Xref "nack" |
| 416 |
.IX Item "$p->nack( $failed_ack_host );" |
| 417 |
The reason that \f(CW\*(C`host $failed_ack_host\*(C'\fR did not receive a |
| 418 |
valid ACK. Useful to find out why when \f(CWack($fail_ack_host)\fR |
| 419 |
returns a false value. |
| 420 |
.ie n .IP $p\->ack_unfork($host) 4 |
| 421 |
.el .IP \f(CW$p\fR\->ack_unfork($host) 4 |
| 422 |
.IX Xref "ack_unfork" |
| 423 |
.IX Item "$p->ack_unfork($host)" |
| 424 |
The variant called by "ack" with the "syn" protocol and \f(CW$syn_forking\fR |
| 425 |
enabled. |
| 426 |
.ie n .IP "$p\->ping_icmp([$host, $timeout, $family])" 4 |
| 427 |
.el .IP "\f(CW$p\fR\->ping_icmp([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 428 |
.IX Xref "ping_icmp" |
| 429 |
.IX Item "$p->ping_icmp([$host, $timeout, $family])" |
| 430 |
The "ping" method used with the icmp protocol. |
| 431 |
.ie n .IP "$p\->ping_icmpv6([$host, $timeout, $family])" 4 |
| 432 |
.el .IP "\f(CW$p\fR\->ping_icmpv6([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 433 |
.IX Xref "ping_icmpv6" |
| 434 |
.IX Item "$p->ping_icmpv6([$host, $timeout, $family])" |
| 435 |
The "ping" method used with the icmpv6 protocol. |
| 436 |
.ie n .IP "$p\->ping_stream([$host, $timeout, $family])" 4 |
| 437 |
.el .IP "\f(CW$p\fR\->ping_stream([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 438 |
.IX Xref "ping_stream" |
| 439 |
.IX Item "$p->ping_stream([$host, $timeout, $family])" |
| 440 |
The "ping" method used with the stream protocol. |
| 441 |
.Sp |
| 442 |
Perform a stream ping. If the tcp connection isn't |
| 443 |
already open, it opens it. It then sends some data and waits for |
| 444 |
a reply. It leaves the stream open on exit. |
| 445 |
.ie n .IP "$p\->ping_syn([$host, $ip, $start_time, $stop_time])" 4 |
| 446 |
.el .IP "\f(CW$p\fR\->ping_syn([$host, \f(CW$ip\fR, \f(CW$start_time\fR, \f(CW$stop_time\fR])" 4 |
| 447 |
.IX Xref "ping_syn" |
| 448 |
.IX Item "$p->ping_syn([$host, $ip, $start_time, $stop_time])" |
| 449 |
The "ping" method used with the syn protocol. |
| 450 |
Sends a TCP SYN packet to host specified. |
| 451 |
.ie n .IP "$p\->ping_syn_fork([$host, $timeout, $family])" 4 |
| 452 |
.el .IP "\f(CW$p\fR\->ping_syn_fork([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 453 |
.IX Xref "ping_syn_fork" |
| 454 |
.IX Item "$p->ping_syn_fork([$host, $timeout, $family])" |
| 455 |
The "ping" method used with the forking syn protocol. |
| 456 |
.ie n .IP "$p\->ping_tcp([$host, $timeout, $family])" 4 |
| 457 |
.el .IP "\f(CW$p\fR\->ping_tcp([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 458 |
.IX Xref "ping_tcp" |
| 459 |
.IX Item "$p->ping_tcp([$host, $timeout, $family])" |
| 460 |
The "ping" method used with the tcp protocol. |
| 461 |
.ie n .IP "$p\->ping_udp([$host, $timeout, $family])" 4 |
| 462 |
.el .IP "\f(CW$p\fR\->ping_udp([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 463 |
.IX Xref "ping_udp" |
| 464 |
.IX Item "$p->ping_udp([$host, $timeout, $family])" |
| 465 |
The "ping" method used with the udp protocol. |
| 466 |
.Sp |
| 467 |
Perform a udp echo ping. Construct a message of |
| 468 |
at least the one-byte sequence number and any additional data bytes. |
| 469 |
Send the message out and wait for a message to come back. If we |
| 470 |
get a message, make sure all of its parts match. If they do, we are |
| 471 |
done. Otherwise go back and wait for the message until we run out |
| 472 |
of time. Return the result of our efforts. |
| 473 |
.ie n .IP "$p\->ping_external([$host, $timeout, $family])" 4 |
| 474 |
.el .IP "\f(CW$p\fR\->ping_external([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 |
| 475 |
.IX Xref "ping_external" |
| 476 |
.IX Item "$p->ping_external([$host, $timeout, $family])" |
| 477 |
The "ping" method used with the external protocol. |
| 478 |
Uses Net::Ping::External to do an external ping. |
| 479 |
.ie n .IP "$p\->tcp_connect([$ip, $timeout])" 4 |
| 480 |
.el .IP "\f(CW$p\fR\->tcp_connect([$ip, \f(CW$timeout\fR])" 4 |
| 481 |
.IX Xref "tcp_connect" |
| 482 |
.IX Item "$p->tcp_connect([$ip, $timeout])" |
| 483 |
Initiates a TCP connection, for a tcp ping. |
| 484 |
.ie n .IP "$p\->tcp_echo([$ip, $timeout, $pingstring])" 4 |
| 485 |
.el .IP "\f(CW$p\fR\->tcp_echo([$ip, \f(CW$timeout\fR, \f(CW$pingstring\fR])" 4 |
| 486 |
.IX Xref "tcp_echo" |
| 487 |
.IX Item "$p->tcp_echo([$ip, $timeout, $pingstring])" |
| 488 |
Performs a TCP echo. |
| 489 |
It writes the given string to the socket and then reads it |
| 490 |
back. It returns 1 on success, 0 on failure. |
| 491 |
.ie n .IP $p\->\fBclose()\fR; 4 |
| 492 |
.el .IP \f(CW$p\fR\->\fBclose()\fR; 4 |
| 493 |
.IX Xref "close" |
| 494 |
.IX Item "$p->close();" |
| 495 |
Close the network connection for this ping object. The network |
| 496 |
connection is also closed by "undef \f(CW$p\fR". The network connection is |
| 497 |
automatically closed if the ping object goes out of scope (e.g. \f(CW$p\fR is |
| 498 |
local to a subroutine and you leave the subroutine). |
| 499 |
.ie n .IP $p\->port_number([$port_number]) 4 |
| 500 |
.el .IP \f(CW$p\fR\->port_number([$port_number]) 4 |
| 501 |
.IX Xref "port_number" |
| 502 |
.IX Item "$p->port_number([$port_number])" |
| 503 |
When called with a port number, the port number used to ping is set to |
| 504 |
\&\f(CW$port_number\fR rather than using the echo port. It also has the effect |
| 505 |
of calling \f(CW\*(C`$p\->service_check(1)\*(C'\fR causing a ping to return a successful |
| 506 |
response only if that specific port is accessible. This function returns |
| 507 |
the value of the port that "ping" will connect to. |
| 508 |
.ie n .IP $p\->mselect 4 |
| 509 |
.el .IP \f(CW$p\fR\->mselect 4 |
| 510 |
.IX Xref "mselect" |
| 511 |
.IX Item "$p->mselect" |
| 512 |
A \f(CWselect()\fR wrapper that compensates for platform |
| 513 |
peculiarities. |
| 514 |
.ie n .IP $p\->ntop 4 |
| 515 |
.el .IP \f(CW$p\fR\->ntop 4 |
| 516 |
.IX Xref "ntop" |
| 517 |
.IX Item "$p->ntop" |
| 518 |
Platform abstraction over \f(CWinet_ntop()\fR |
| 519 |
.ie n .IP $p\->checksum($msg) 4 |
| 520 |
.el .IP \f(CW$p\fR\->checksum($msg) 4 |
| 521 |
.IX Xref "checksum" |
| 522 |
.IX Item "$p->checksum($msg)" |
| 523 |
Do a checksum on the message. Basically sum all of |
| 524 |
the short words and fold the high order bits into the low order bits. |
| 525 |
.ie n .IP $p\->icmp_result 4 |
| 526 |
.el .IP \f(CW$p\fR\->icmp_result 4 |
| 527 |
.IX Xref "icmp_result" |
| 528 |
.IX Item "$p->icmp_result" |
| 529 |
Returns a list of addr, type, subcode. |
| 530 |
.ie n .IP "pingecho($host [, $timeout]);" 4 |
| 531 |
.el .IP "pingecho($host [, \f(CW$timeout\fR]);" 4 |
| 532 |
.IX Xref "pingecho" |
| 533 |
.IX Item "pingecho($host [, $timeout]);" |
| 534 |
To provide backward compatibility with the previous version of |
| 535 |
Net::Ping, a \f(CWpingecho()\fR subroutine is available with the same |
| 536 |
functionality as before. \f(CWpingecho()\fR uses the tcp protocol. The |
| 537 |
return values and parameters are the same as described for the "ping" |
| 538 |
method. This subroutine is obsolete and may be removed in a future |
| 539 |
version of Net::Ping. |
| 540 |
.IP "wakeonlan($mac, [$host, [$port]])" 4 |
| 541 |
.IX Xref "wakeonlan" |
| 542 |
.IX Item "wakeonlan($mac, [$host, [$port]])" |
| 543 |
Emit the popular wake-on-lan magic udp packet to wake up a local |
| 544 |
device. See also Net::Wake, but this has the mac address as 1st arg. |
| 545 |
\&\f(CW$host\fR should be the local gateway. Without it will broadcast. |
| 546 |
.Sp |
| 547 |
Default host: '255.255.255.255' |
| 548 |
Default port: 9 |
| 549 |
.Sp |
| 550 |
.Vb 1 |
| 551 |
\& perl \-MNet::Ping=wakeonlan \-e\*(Aqwakeonlan "e0:69:95:35:68:d2"\*(Aq |
| 552 |
.Ve |
| 553 |
.SH NOTES |
| 554 |
.IX Header "NOTES" |
| 555 |
There will be less network overhead (and some efficiency in your |
| 556 |
program) if you specify either the udp or the icmp protocol. The tcp |
| 557 |
protocol will generate 2.5 times or more traffic for each ping than |
| 558 |
either udp or icmp. If many hosts are pinged frequently, you may wish |
| 559 |
to implement a small wait (e.g. 25ms or more) between each ping to |
| 560 |
avoid flooding your network with packets. |
| 561 |
.PP |
| 562 |
The icmp and icmpv6 protocols requires that the program be run as root |
| 563 |
or that it be setuid to root. The other protocols do not require |
| 564 |
special privileges, but not all network devices implement tcp or udp |
| 565 |
echo. |
| 566 |
.PP |
| 567 |
Local hosts should normally respond to pings within milliseconds. |
| 568 |
However, on a very congested network it may take up to 3 seconds or |
| 569 |
longer to receive an echo packet from the remote host. If the timeout |
| 570 |
is set too low under these conditions, it will appear that the remote |
| 571 |
host is not reachable (which is almost the truth). |
| 572 |
.PP |
| 573 |
Reachability doesn't necessarily mean that the remote host is actually |
| 574 |
functioning beyond its ability to echo packets. tcp is slightly better |
| 575 |
at indicating the health of a system than icmp because it uses more |
| 576 |
of the networking stack to respond. |
| 577 |
.PP |
| 578 |
Because of a lack of anything better, this module uses its own |
| 579 |
routines to pack and unpack ICMP packets. It would be better for a |
| 580 |
separate module to be written which understands all of the different |
| 581 |
kinds of ICMP packets. |
| 582 |
.SH INSTALL |
| 583 |
.IX Header "INSTALL" |
| 584 |
The latest source tree is available via git: |
| 585 |
.PP |
| 586 |
.Vb 2 |
| 587 |
\& git clone https://github.com/rurban/Net\-Ping.git |
| 588 |
\& cd Net\-Ping |
| 589 |
.Ve |
| 590 |
.PP |
| 591 |
The tarball can be created as follows: |
| 592 |
.PP |
| 593 |
.Vb 1 |
| 594 |
\& perl Makefile.PL ; make ; make dist |
| 595 |
.Ve |
| 596 |
.PP |
| 597 |
The latest Net::Ping releases are included in cperl and perl5. |
| 598 |
.SH BUGS |
| 599 |
.IX Header "BUGS" |
| 600 |
For a list of known issues, visit: |
| 601 |
.PP |
| 602 |
<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net\-Ping> |
| 603 |
and |
| 604 |
<https://github.com/rurban/Net\-Ping/issues> |
| 605 |
.PP |
| 606 |
To report a new bug, visit: |
| 607 |
.PP |
| 608 |
<https://github.com/rurban/Net\-Ping/issues> |
| 609 |
.SH AUTHORS |
| 610 |
.IX Header "AUTHORS" |
| 611 |
.Vb 3 |
| 612 |
\& Current maintainers: |
| 613 |
\& perl11 (for cperl, with IPv6 support and more) |
| 614 |
\& p5p (for perl5) |
| 615 |
\& |
| 616 |
\& Previous maintainers: |
| 617 |
\& [email protected] (Rob Brown) |
| 618 |
\& Steve Peters |
| 619 |
\& |
| 620 |
\& External protocol: |
| 621 |
\& [email protected] (Colin McMillen) |
| 622 |
\& |
| 623 |
\& Stream protocol: |
| 624 |
\& [email protected] (Scott Bronson) |
| 625 |
\& |
| 626 |
\& Wake\-on\-lan: |
| 627 |
\& 1999\-2003 Clinton Wong |
| 628 |
\& |
| 629 |
\& Original pingecho(): |
| 630 |
\& [email protected] (Andreas Karrer) |
| 631 |
\& [email protected] (Paul Marquess) |
| 632 |
\& |
| 633 |
\& Original Net::Ping author: |
| 634 |
\& [email protected] (Russell Mosemann) |
| 635 |
.Ve |
| 636 |
.SH COPYRIGHT |
| 637 |
.IX Header "COPYRIGHT" |
| 638 |
Copyright (c) 2017\-2020, Reini Urban. All rights reserved. |
| 639 |
.PP |
| 640 |
Copyright (c) 2016, cPanel Inc. All rights reserved. |
| 641 |
.PP |
| 642 |
Copyright (c) 2012, Steve Peters. All rights reserved. |
| 643 |
.PP |
| 644 |
Copyright (c) 2002\-2003, Rob Brown. All rights reserved. |
| 645 |
.PP |
| 646 |
Copyright (c) 2001, Colin McMillen. All rights reserved. |
| 647 |
.PP |
| 648 |
This program is free software; you may redistribute it and/or |
| 649 |
modify it under the same terms as Perl itself. |