Debian Codegraph @

upstream/debian-unstable/man3/Net::Ping.3perl

raw
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.