diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Net::Ping.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Net::Ping.3pm | 649 |
1 files changed, 649 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Net::Ping.3pm b/upstream/mageia-cauldron/man3pm/Net::Ping.3pm new file mode 100644 index 00000000..0233a738 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Net::Ping.3pm @@ -0,0 +1,649 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Net::Ping 3pm" +.TH Net::Ping 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Net::Ping \- check a remote host for reachability +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Net::Ping; +\& +\& my $p = Net::Ping\->new(); +\& print "$host is alive.\en" if $p\->ping($host); +\& $p\->close(); +\& +\& my $p = Net::Ping\->new("icmp"); +\& $p\->bind($my_addr); # Specify source interface of pings +\& foreach my $host (@host_array) +\& { +\& print "$host is "; +\& print "NOT " unless $p\->ping($host, 2); +\& print "reachable.\en"; +\& sleep(1); +\& } +\& $p\->close(); +\& +\& my $p = Net::Ping\->new("icmpv6"); +\& my $ip = "[fd00:dead:beef::4e]"; +\& print "$ip is alive.\en" if $p\->ping($ip); +\& +\& my $p = Net::Ping\->new("tcp", 2); +\& # Try connecting to the www port instead of the echo port +\& $p\->port_number(scalar(getservbyname("http", "tcp"))); +\& while ($stop_time > time()) +\& { +\& print "$host not reachable ", scalar(localtime()), "\en" +\& unless $p\->ping($host); +\& sleep(300); +\& } +\& undef($p); +\& +\& # Like tcp protocol, but with many hosts +\& my $p = Net::Ping\->new("syn"); +\& $p\->port_number(getservbyname("http", "tcp")); +\& foreach my $host (@host_array) { +\& $p\->ping($host); +\& } +\& while (my ($host, $rtt, $ip) = $p\->ack) { +\& print "HOST: $host [$ip] ACKed in $rtt seconds.\en"; +\& } +\& +\& # High precision syntax (requires Time::HiRes) +\& my $p = Net::Ping\->new(); +\& $p\->hires(); +\& my ($ret, $duration, $ip) = $p\->ping($host, 5.5); +\& printf("$host [ip: $ip] is alive (packet return time: %.2f ms)\en", +\& 1000 * $duration) +\& if $ret; +\& $p\->close(); +\& +\& # For backward compatibility +\& print "$host is alive.\en" if pingecho($host); +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module contains methods to test the reachability of remote +hosts on a network. A ping object is first created with optional +parameters, a variable number of hosts may be pinged multiple +times and then the connection is closed. +.PP +You may choose one of six different protocols to use for the +ping. The "tcp" protocol is the default. Note that a live remote host +may still fail to be pingable by one or more of these protocols. For +example, www.microsoft.com is generally alive but not "icmp" pingable. +.PP +With the "tcp" protocol the \fBping()\fR method attempts to establish a +connection to the remote host's echo port. If the connection is +successfully established, the remote host is considered reachable. No +data is actually echoed. This protocol does not require any special +privileges but has higher overhead than the "udp" and "icmp" protocols. +.PP +Specifying the "udp" protocol causes the \fBping()\fR method to send a udp +packet to the remote host's echo port. If the echoed packet is +received from the remote host and the received packet contains the +same data as the packet that was sent, the remote host is considered +reachable. This protocol does not require any special privileges. +It should be borne in mind that, for a udp ping, a host +will be reported as unreachable if it is not running the +appropriate echo service. For Unix-like systems see \fBinetd\fR\|(8) +for more information. +.PP +If the "icmp" protocol is specified, the \fBping()\fR method sends an icmp +echo message to the remote host, which is what the UNIX ping program +does. If the echoed message is received from the remote host and +the echoed information is correct, the remote host is considered +reachable. Specifying the "icmp" protocol requires that the program +be run as root or that the program be setuid to root. +.PP +If the "external" protocol is specified, the \fBping()\fR method attempts to +use the \f(CW\*(C`Net::Ping::External\*(C'\fR module to ping the remote host. +\&\f(CW\*(C`Net::Ping::External\*(C'\fR interfaces with your system's default \f(CW\*(C`ping\*(C'\fR +utility to perform the ping, and generally produces relatively +accurate results. If \f(CW\*(C`Net::Ping::External\*(C'\fR if not installed on your +system, specifying the "external" protocol will result in an error. +.PP +If the "syn" protocol is specified, the "ping" method will only +send a TCP SYN packet to the remote host then immediately return. +If the syn packet was sent successfully, it will return a true value, +otherwise it will return false. NOTE: Unlike the other protocols, +the return value does NOT determine if the remote host is alive or +not since the full TCP three-way handshake may not have completed +yet. The remote host is only considered reachable if it receives +a TCP ACK within the timeout specified. To begin waiting for the +ACK packets, use the "ack" method as explained below. Use the +"syn" protocol instead the "tcp" protocol to determine reachability +of multiple destinations simultaneously by sending parallel TCP +SYN packets. It will not block while testing each remote host. +This protocol does not require any special privileges. +.SS Functions +.IX Subsection "Functions" +.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 +.IX Xref "new" +.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])" +Create a new ping object. All of the parameters are optional and can +be passed as hash ref. All options besides the first 7 must be passed +as hash ref. +.Sp +\&\f(CW\*(C`proto\*(C'\fR specifies the protocol to use when doing a ping. The current +choices are "tcp", "udp", "icmp", "icmpv6", "stream", "syn", or +"external". The default is "tcp". +.Sp +If a \f(CW\*(C`timeout\*(C'\fR in seconds is provided, it is used +when a timeout is not given to the \fBping()\fR method (below). The timeout +must be greater than 0 and the default, if not specified, is 5 seconds. +.Sp +If the number of data bytes (\f(CW\*(C`bytes\*(C'\fR) is given, that many data bytes +are included in the ping packet sent to the remote host. The number of +data bytes is ignored if the protocol is "tcp". The minimum (and +default) number of data bytes is 1 if the protocol is "udp" and 0 +otherwise. The maximum number of data bytes that can be specified is +65535, but staying below the MTU (1472 bytes for ICMP) is recommended. +Many small devices cannot deal with fragmented ICMP packets. +.Sp +If \f(CW\*(C`device\*(C'\fR is given, this device is used to bind the source endpoint +before sending the ping packet. I believe this only works with +superuser privileges and with udp and icmp protocols at this time. +.Sp +If <tos> is given, this ToS is configured into the socket. +.Sp +For icmp, \f(CW\*(C`ttl\*(C'\fR can be specified to set the TTL of the outgoing packet. +.Sp +Valid \f(CW\*(C`family\*(C'\fR values for IPv4: +.Sp +.Vb 1 +\& 4, v4, ip4, ipv4, AF_INET (constant) +.Ve +.Sp +Valid \f(CW\*(C`family\*(C'\fR values for IPv6: +.Sp +.Vb 1 +\& 6, v6, ip6, ipv6, AF_INET6 (constant) +.Ve +.Sp +The \f(CW\*(C`host\*(C'\fR argument implicitly specifies the family if the family +argument is not given. +.Sp +The \f(CW\*(C`port\*(C'\fR argument is only valid for a udp, tcp or stream ping, and will not +do what you think it does. ping returns true when we get a "Connection refused"! +The default is the echo port. +.Sp +The \f(CW\*(C`bind\*(C'\fR argument specifies the local_addr to bind to. +By specifying a bind argument you don't need the bind method. +.Sp +The \f(CW\*(C`gateway\*(C'\fR argument is only valid for IPv6, and requires a IPv6 +address. +.Sp +The \f(CW\*(C`retrans\*(C'\fR argument the exponential backoff rate, default 1.2. +It matches the \f(CW$def_factor\fR global. +.Sp +The \f(CW\*(C`dontfrag\*(C'\fR argument sets the IP_DONTFRAG bit, but note that +IP_DONTFRAG is not yet defined by Socket, and not available on many +systems. Then it is ignored. On linux it also sets IP_MTU_DISCOVER to +IP_PMTUDISC_DO but need we don't chunk oversized packets. You need to +set \f(CW$data_size\fR manually. +.ie n .IP "$p\->ping($host [, $timeout [, $family]]);" 4 +.el .IP "\f(CW$p\fR\->ping($host [, \f(CW$timeout\fR [, \f(CW$family\fR]]);" 4 +.IX Xref "ping" +.IX Item "$p->ping($host [, $timeout [, $family]]);" +Ping the remote host and wait for a response. \f(CW$host\fR can be either the +hostname or the IP number of the remote host. The optional timeout +must be greater than 0 seconds and defaults to whatever was specified +when the ping object was created. Returns a success flag. If the +hostname cannot be found or there is a problem with the IP number, the +success flag returned will be undef. Otherwise, the success flag will +be 1 if the host is reachable and 0 if it is not. For most practical +purposes, undef and 0 and can be treated as the same case. In array +context, the elapsed time as well as the string form of the ip the +host resolved to are also returned. The elapsed time value will +be a float, as returned by the \fBTime::HiRes::time()\fR function, if \fBhires()\fR +has been previously called, otherwise it is returned as an integer. +.ie n .IP "$p\->source_verify( { 0 | 1 } );" 4 +.el .IP "\f(CW$p\fR\->source_verify( { 0 | 1 } );" 4 +.IX Xref "source_verify" +.IX Item "$p->source_verify( { 0 | 1 } );" +Allows source endpoint verification to be enabled or disabled. +This is useful for those remote destinations with multiples +interfaces where the response may not originate from the same +endpoint that the original destination endpoint was sent to. +This only affects udp and icmp protocol pings. +.Sp +This is enabled by default. +.ie n .IP "$p\->service_check( { 0 | 1 } );" 4 +.el .IP "\f(CW$p\fR\->service_check( { 0 | 1 } );" 4 +.IX Xref "service_check" +.IX Item "$p->service_check( { 0 | 1 } );" +Set whether or not the connect behavior should enforce +remote service availability as well as reachability. Normally, +if the remote server reported ECONNREFUSED, it must have been +reachable because of the status packet that it reported. +With this option enabled, the full three-way tcp handshake +must have been established successfully before it will +claim it is reachable. NOTE: It still does nothing more +than connect and disconnect. It does not speak any protocol +(i.e., HTTP or FTP) to ensure the remote server is sane in +any way. The remote server CPU could be grinding to a halt +and unresponsive to any clients connecting, but if the kernel +throws the ACK packet, it is considered alive anyway. To +really determine if the server is responding well would be +application specific and is beyond the scope of Net::Ping. +For udp protocol, enabling this option demands that the +remote server replies with the same udp data that it was sent +as defined by the udp echo service. +.Sp +This affects the "udp", "tcp", and "syn" protocols. +.Sp +This is disabled by default. +.ie n .IP "$p\->tcp_service_check( { 0 | 1 } );" 4 +.el .IP "\f(CW$p\fR\->tcp_service_check( { 0 | 1 } );" 4 +.IX Xref "tcp_service_check" +.IX Item "$p->tcp_service_check( { 0 | 1 } );" +Deprecated method, but does the same as \fBservice_check()\fR method. +.ie n .IP "$p\->hires( { 0 | 1 } );" 4 +.el .IP "\f(CW$p\fR\->hires( { 0 | 1 } );" 4 +.IX Xref "hires" +.IX Item "$p->hires( { 0 | 1 } );" +With 1 causes this module to use Time::HiRes module, allowing milliseconds +to be returned by subsequent calls to \fBping()\fR. +.ie n .IP $p\->time 4 +.el .IP \f(CW$p\fR\->time 4 +.IX Xref "time" +.IX Item "$p->time" +The current time, hires or not. +.ie n .IP "$p\->socket_blocking_mode( $fh, $mode );" 4 +.el .IP "\f(CW$p\fR\->socket_blocking_mode( \f(CW$fh\fR, \f(CW$mode\fR );" 4 +.IX Xref "socket_blocking_mode" +.IX Item "$p->socket_blocking_mode( $fh, $mode );" +Sets or clears the O_NONBLOCK flag on a file handle. +.ie n .IP $p\->IPV6_USE_MIN_MTU 4 +.el .IP \f(CW$p\fR\->IPV6_USE_MIN_MTU 4 +.IX Xref "IPV6_USE_MIN_MTU" +.IX Item "$p->IPV6_USE_MIN_MTU" +With argument sets the option. +Without returns the option value. +.ie n .IP $p\->IPV6_RECVPATHMTU 4 +.el .IP \f(CW$p\fR\->IPV6_RECVPATHMTU 4 +.IX Xref "IPV6_RECVPATHMTU" +.IX Item "$p->IPV6_RECVPATHMTU" +Notify an according IPv6 MTU. +.Sp +With argument sets the option. +Without returns the option value. +.ie n .IP $p\->IPV6_HOPLIMIT 4 +.el .IP \f(CW$p\fR\->IPV6_HOPLIMIT 4 +.IX Xref "IPV6_HOPLIMIT" +.IX Item "$p->IPV6_HOPLIMIT" +With argument sets the option. +Without returns the option value. +.ie n .IP "$p\->IPV6_REACHCONF \fINYI\fR" 4 +.el .IP "\f(CW$p\fR\->IPV6_REACHCONF \fINYI\fR" 4 +.IX Xref "IPV6_REACHCONF" +.IX Item "$p->IPV6_REACHCONF NYI" +Sets ipv6 reachability +IPV6_REACHCONF was removed in RFC3542. ping6 \-R supports it. +IPV6_REACHCONF requires root/admin permissions. +.Sp +With argument sets the option. +Without returns the option value. +.Sp +Not yet implemented. +.ie n .IP $p\->bind($local_addr); 4 +.el .IP \f(CW$p\fR\->bind($local_addr); 4 +.IX Xref "bind" +.IX Item "$p->bind($local_addr);" +Sets the source address from which pings will be sent. This must be +the address of one of the interfaces on the local host. \f(CW$local_addr\fR +may be specified as a hostname or as a text IP address such as +"192.168.1.1". +.Sp +If the protocol is set to "tcp", this method may be called any +number of times, and each call to the \fBping()\fR method (below) will use +the most recent \f(CW$local_addr\fR. If the protocol is "icmp" or "udp", +then \fBbind()\fR must be called at most once per object, and (if it is +called at all) must be called before the first call to \fBping()\fR for that +object. +.Sp +The \fBbind()\fR call can be omitted when specifying the \f(CW\*(C`bind\*(C'\fR option to +\&\fBnew()\fR. +.ie n .IP $p\->message_type([$ping_type]); 4 +.el .IP \f(CW$p\fR\->message_type([$ping_type]); 4 +.IX Xref "message_type" +.IX Item "$p->message_type([$ping_type]);" +When you are using the "icmp" protocol, this call permit to change the +message type to 'echo' or 'timestamp' (only for IPv4, see RFC 792). +.Sp +Without argument, it returns the currently used icmp protocol message type. +By default, it returns 'echo'. +.ie n .IP $p\->open($host); 4 +.el .IP \f(CW$p\fR\->open($host); 4 +.IX Xref "open" +.IX Item "$p->open($host);" +When you are using the "stream" protocol, this call pre-opens the +tcp socket. It's only necessary to do this if you want to +provide a different timeout when creating the connection, or +remove the overhead of establishing the connection from the +first ping. If you don't call \f(CWopen()\fR, the connection is +automatically opened the first time \f(CWping()\fR is called. +This call simply does nothing if you are using any protocol other +than stream. +.Sp +The \f(CW$host\fR argument can be omitted when specifying the \f(CW\*(C`host\*(C'\fR option to +\&\fBnew()\fR. +.ie n .IP "$p\->ack( [ $host ] );" 4 +.el .IP "\f(CW$p\fR\->ack( [ \f(CW$host\fR ] );" 4 +.IX Xref "ack" +.IX Item "$p->ack( [ $host ] );" +When using the "syn" protocol, use this method to determine +the reachability of the remote host. This method is meant +to be called up to as many times as \fBping()\fR was called. Each +call returns the host (as passed to \fBping()\fR) that came back +with the TCP ACK. The order in which the hosts are returned +may not necessarily be the same order in which they were +SYN queued using the \fBping()\fR method. If the timeout is +reached before the TCP ACK is received, or if the remote +host is not listening on the port attempted, then the TCP +connection will not be established and \fBack()\fR will return +undef. In list context, the host, the ack time, the dotted ip +string, and the port number will be returned instead of just the host. +If the optional \f(CW$host\fR argument is specified, the return +value will be pertaining to that host only. +This call simply does nothing if you are using any protocol +other than "syn". +.Sp +When "new" had a host option, this host will be used. +Without \f(CW$host\fR argument, all hosts are scanned. +.ie n .IP "$p\->nack( $failed_ack_host );" 4 +.el .IP "\f(CW$p\fR\->nack( \f(CW$failed_ack_host\fR );" 4 +.IX Xref "nack" +.IX Item "$p->nack( $failed_ack_host );" +The reason that \f(CW\*(C`host $failed_ack_host\*(C'\fR did not receive a +valid ACK. Useful to find out why when \f(CWack($fail_ack_host)\fR +returns a false value. +.ie n .IP $p\->ack_unfork($host) 4 +.el .IP \f(CW$p\fR\->ack_unfork($host) 4 +.IX Xref "ack_unfork" +.IX Item "$p->ack_unfork($host)" +The variant called by "ack" with the "syn" protocol and \f(CW$syn_forking\fR +enabled. +.ie n .IP "$p\->ping_icmp([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_icmp([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_icmp" +.IX Item "$p->ping_icmp([$host, $timeout, $family])" +The "ping" method used with the icmp protocol. +.ie n .IP "$p\->ping_icmpv6([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_icmpv6([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_icmpv6" +.IX Item "$p->ping_icmpv6([$host, $timeout, $family])" +The "ping" method used with the icmpv6 protocol. +.ie n .IP "$p\->ping_stream([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_stream([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_stream" +.IX Item "$p->ping_stream([$host, $timeout, $family])" +The "ping" method used with the stream protocol. +.Sp +Perform a stream ping. If the tcp connection isn't +already open, it opens it. It then sends some data and waits for +a reply. It leaves the stream open on exit. +.ie n .IP "$p\->ping_syn([$host, $ip, $start_time, $stop_time])" 4 +.el .IP "\f(CW$p\fR\->ping_syn([$host, \f(CW$ip\fR, \f(CW$start_time\fR, \f(CW$stop_time\fR])" 4 +.IX Xref "ping_syn" +.IX Item "$p->ping_syn([$host, $ip, $start_time, $stop_time])" +The "ping" method used with the syn protocol. +Sends a TCP SYN packet to host specified. +.ie n .IP "$p\->ping_syn_fork([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_syn_fork([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_syn_fork" +.IX Item "$p->ping_syn_fork([$host, $timeout, $family])" +The "ping" method used with the forking syn protocol. +.ie n .IP "$p\->ping_tcp([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_tcp([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_tcp" +.IX Item "$p->ping_tcp([$host, $timeout, $family])" +The "ping" method used with the tcp protocol. +.ie n .IP "$p\->ping_udp([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_udp([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_udp" +.IX Item "$p->ping_udp([$host, $timeout, $family])" +The "ping" method used with the udp protocol. +.Sp +Perform a udp echo ping. Construct a message of +at least the one-byte sequence number and any additional data bytes. +Send the message out and wait for a message to come back. If we +get a message, make sure all of its parts match. If they do, we are +done. Otherwise go back and wait for the message until we run out +of time. Return the result of our efforts. +.ie n .IP "$p\->ping_external([$host, $timeout, $family])" 4 +.el .IP "\f(CW$p\fR\->ping_external([$host, \f(CW$timeout\fR, \f(CW$family\fR])" 4 +.IX Xref "ping_external" +.IX Item "$p->ping_external([$host, $timeout, $family])" +The "ping" method used with the external protocol. +Uses Net::Ping::External to do an external ping. +.ie n .IP "$p\->tcp_connect([$ip, $timeout])" 4 +.el .IP "\f(CW$p\fR\->tcp_connect([$ip, \f(CW$timeout\fR])" 4 +.IX Xref "tcp_connect" +.IX Item "$p->tcp_connect([$ip, $timeout])" +Initiates a TCP connection, for a tcp ping. +.ie n .IP "$p\->tcp_echo([$ip, $timeout, $pingstring])" 4 +.el .IP "\f(CW$p\fR\->tcp_echo([$ip, \f(CW$timeout\fR, \f(CW$pingstring\fR])" 4 +.IX Xref "tcp_echo" +.IX Item "$p->tcp_echo([$ip, $timeout, $pingstring])" +Performs a TCP echo. +It writes the given string to the socket and then reads it +back. It returns 1 on success, 0 on failure. +.ie n .IP $p\->\fBclose()\fR; 4 +.el .IP \f(CW$p\fR\->\fBclose()\fR; 4 +.IX Xref "close" +.IX Item "$p->close();" +Close the network connection for this ping object. The network +connection is also closed by "undef \f(CW$p\fR". The network connection is +automatically closed if the ping object goes out of scope (e.g. \f(CW$p\fR is +local to a subroutine and you leave the subroutine). +.ie n .IP $p\->port_number([$port_number]) 4 +.el .IP \f(CW$p\fR\->port_number([$port_number]) 4 +.IX Xref "port_number" +.IX Item "$p->port_number([$port_number])" +When called with a port number, the port number used to ping is set to +\&\f(CW$port_number\fR rather than using the echo port. It also has the effect +of calling \f(CW\*(C`$p\->service_check(1)\*(C'\fR causing a ping to return a successful +response only if that specific port is accessible. This function returns +the value of the port that "ping" will connect to. +.ie n .IP $p\->mselect 4 +.el .IP \f(CW$p\fR\->mselect 4 +.IX Xref "mselect" +.IX Item "$p->mselect" +A \f(CWselect()\fR wrapper that compensates for platform +peculiarities. +.ie n .IP $p\->ntop 4 +.el .IP \f(CW$p\fR\->ntop 4 +.IX Xref "ntop" +.IX Item "$p->ntop" +Platform abstraction over \f(CWinet_ntop()\fR +.ie n .IP $p\->checksum($msg) 4 +.el .IP \f(CW$p\fR\->checksum($msg) 4 +.IX Xref "checksum" +.IX Item "$p->checksum($msg)" +Do a checksum on the message. Basically sum all of +the short words and fold the high order bits into the low order bits. +.ie n .IP $p\->icmp_result 4 +.el .IP \f(CW$p\fR\->icmp_result 4 +.IX Xref "icmp_result" +.IX Item "$p->icmp_result" +Returns a list of addr, type, subcode. +.ie n .IP "pingecho($host [, $timeout]);" 4 +.el .IP "pingecho($host [, \f(CW$timeout\fR]);" 4 +.IX Xref "pingecho" +.IX Item "pingecho($host [, $timeout]);" +To provide backward compatibility with the previous version of +Net::Ping, a \f(CWpingecho()\fR subroutine is available with the same +functionality as before. \f(CWpingecho()\fR uses the tcp protocol. The +return values and parameters are the same as described for the "ping" +method. This subroutine is obsolete and may be removed in a future +version of Net::Ping. +.IP "wakeonlan($mac, [$host, [$port]])" 4 +.IX Xref "wakeonlan" +.IX Item "wakeonlan($mac, [$host, [$port]])" +Emit the popular wake-on-lan magic udp packet to wake up a local +device. See also Net::Wake, but this has the mac address as 1st arg. +\&\f(CW$host\fR should be the local gateway. Without it will broadcast. +.Sp +Default host: '255.255.255.255' +Default port: 9 +.Sp +.Vb 1 +\& perl \-MNet::Ping=wakeonlan \-e\*(Aqwakeonlan "e0:69:95:35:68:d2"\*(Aq +.Ve +.SH NOTES +.IX Header "NOTES" +There will be less network overhead (and some efficiency in your +program) if you specify either the udp or the icmp protocol. The tcp +protocol will generate 2.5 times or more traffic for each ping than +either udp or icmp. If many hosts are pinged frequently, you may wish +to implement a small wait (e.g. 25ms or more) between each ping to +avoid flooding your network with packets. +.PP +The icmp and icmpv6 protocols requires that the program be run as root +or that it be setuid to root. The other protocols do not require +special privileges, but not all network devices implement tcp or udp +echo. +.PP +Local hosts should normally respond to pings within milliseconds. +However, on a very congested network it may take up to 3 seconds or +longer to receive an echo packet from the remote host. If the timeout +is set too low under these conditions, it will appear that the remote +host is not reachable (which is almost the truth). +.PP +Reachability doesn't necessarily mean that the remote host is actually +functioning beyond its ability to echo packets. tcp is slightly better +at indicating the health of a system than icmp because it uses more +of the networking stack to respond. +.PP +Because of a lack of anything better, this module uses its own +routines to pack and unpack ICMP packets. It would be better for a +separate module to be written which understands all of the different +kinds of ICMP packets. +.SH INSTALL +.IX Header "INSTALL" +The latest source tree is available via git: +.PP +.Vb 2 +\& git clone https://github.com/rurban/Net\-Ping.git +\& cd Net\-Ping +.Ve +.PP +The tarball can be created as follows: +.PP +.Vb 1 +\& perl Makefile.PL ; make ; make dist +.Ve +.PP +The latest Net::Ping releases are included in cperl and perl5. +.SH BUGS +.IX Header "BUGS" +For a list of known issues, visit: +.PP +<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Net\-Ping> +and +<https://github.com/rurban/Net\-Ping/issues> +.PP +To report a new bug, visit: +.PP +<https://github.com/rurban/Net\-Ping/issues> +.SH AUTHORS +.IX Header "AUTHORS" +.Vb 3 +\& Current maintainers: +\& perl11 (for cperl, with IPv6 support and more) +\& p5p (for perl5) +\& +\& Previous maintainers: +\& bbb@cpan.org (Rob Brown) +\& Steve Peters +\& +\& External protocol: +\& colinm@cpan.org (Colin McMillen) +\& +\& Stream protocol: +\& bronson@trestle.com (Scott Bronson) +\& +\& Wake\-on\-lan: +\& 1999\-2003 Clinton Wong +\& +\& Original pingecho(): +\& karrer@bernina.ethz.ch (Andreas Karrer) +\& pmarquess@bfsec.bt.co.uk (Paul Marquess) +\& +\& Original Net::Ping author: +\& mose@ns.ccsn.edu (Russell Mosemann) +.Ve +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright (c) 2017\-2020, Reini Urban. All rights reserved. +.PP +Copyright (c) 2016, cPanel Inc. All rights reserved. +.PP +Copyright (c) 2012, Steve Peters. All rights reserved. +.PP +Copyright (c) 2002\-2003, Rob Brown. All rights reserved. +.PP +Copyright (c) 2001, Colin McMillen. All rights reserved. +.PP +This program is free software; you may redistribute it and/or +modify it under the same terms as Perl itself. |