Debian Codegraph @

upstream/mageia-cauldron/man3pm/Net::Ping.3pm

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