Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 665 insertions, 0 deletions

diff --git a/upstream/debian-bookworm/man3/Net::Ping.3perl b/upstream/debian-bookworm/man3/Net::Ping.3perl
new file mode 100644
index 00000000..a1745062
--- /dev/null
+++ b/upstream/debian-bookworm/man3/Net::Ping.3perl
@@ -0,0 +1,665 @@
+.\" Automatically generated by Pod::Man 4.14 (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
+..
+.\" Set up some character translations and predefined strings.  \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
+.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+.    ds -- \(*W-
+.    ds PI pi
+.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
+.    ds L" ""
+.    ds R" ""
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds -- \|\(em\|
+.    ds PI \(*p
+.    ds L" ``
+.    ds R" ''
+.    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 3perl"
+.TH Net::Ping 3perl "2023-11-25" "perl v5.36.0" "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;
+\&
+\&    $p = Net::Ping\->new();
+\&    print "$host is alive.\en" if $p\->ping($host);
+\&    $p\->close();
+\&
+\&    $p = Net::Ping\->new("icmp");
+\&    $p\->bind($my_addr); # Specify source interface of pings
+\&    foreach $host (@host_array)
+\&    {
+\&        print "$host is ";
+\&        print "NOT " unless $p\->ping($host, 2);
+\&        print "reachable.\en";
+\&        sleep(1);
+\&    }
+\&    $p\->close();
+\&
+\&    $p = Net::Ping\->new("icmpv6");
+\&    $ip = "[fd00:dead:beef::4e]";
+\&    print "$ip is alive.\en" if $p\->ping($ip);
+\&
+\&    $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
+\&    $p = Net::Ping\->new("syn");
+\&    $p\->port_number(getservbyname("http", "tcp"));
+\&    foreach $host (@host_array) {
+\&      $p\->ping($host);
+\&    }
+\&    while (($host,$rtt,$ip) = $p\->ack) {
+\&      print "HOST: $host [$ip] ACKed in $rtt seconds.\en";
+\&    }
+\&
+\&    # High precision syntax (requires Time::HiRes)
+\&    $p = Net::Ping\->new();
+\&    $p\->hires();
+\&    ($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 \*(L"tcp\*(R" 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 \*(L"icmp\*(R" pingable.
+.PP
+With the \*(L"tcp\*(R" 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 \*(L"udp\*(R" and \*(L"icmp\*(R" protocols.
+.PP
+Specifying the \*(L"udp\*(R" 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 \*(L"icmp\*(R" protocol is specified, the \fBping()\fR method sends an icmp
+echo message to the remote host, which is what the \s-1UNIX\s0 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 \*(L"icmp\*(R" protocol requires that the program
+be run as root or that the program be setuid to root.
+.PP
+If the \*(L"external\*(R" 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 \*(L"external\*(R" protocol will result in an error.
+.PP
+If the \*(L"syn\*(R" protocol is specified, the \*(L"ping\*(R" method will only
+send a \s-1TCP SYN\s0 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.  \s-1NOTE:\s0 Unlike the other protocols,
+the return value does \s-1NOT\s0 determine if the remote host is alive or
+not since the full \s-1TCP\s0 three-way handshake may not have completed
+yet.  The remote host is only considered reachable if it receives
+a \s-1TCP ACK\s0 within the timeout specified.  To begin waiting for the
+\&\s-1ACK\s0 packets, use the \*(L"ack\*(R" method as explained below.  Use the
+\&\*(L"syn\*(R" protocol instead the \*(L"tcp\*(R" protocol to determine reachability
+of multiple destinations simultaneously by sending parallel \s-1TCP
+SYN\s0 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 \s-1IPV6_USE_MIN_MTU IPV6_RECVPATHMTU\s0])" 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 \*(L"tcp\*(R", \*(L"udp\*(R", \*(L"icmp\*(R", \*(L"icmpv6\*(R", \*(L"stream\*(R", \*(L"syn\*(R", or
+\&\*(L"external\*(R".  The default is \*(L"tcp\*(R".
+.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 \*(L"tcp\*(R".  The minimum (and
+default) number of data bytes is 1 if the protocol is \*(L"udp\*(R" and 0
+otherwise.  The maximum number of data bytes that can be specified is
+65535, but staying below the \s-1MTU\s0 (1472 bytes for \s-1ICMP\s0) is recommended.
+Many small devices cannot deal with fragmented \s-1ICMP\s0 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 \s-1TTL\s0 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 \*(L"Connection refused\*(R"!
+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 \s-1IP_DONTFRAG\s0 bit, but note that
+\&\s-1IP_DONTFRAG\s0 is not yet defined by Socket, and not available on many
+systems. Then it is ignored. On linux it also sets \s-1IP_MTU_DISCOVER\s0 to
+\&\s-1IP_PMTUDISC_DO\s0 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 \s-1IP\s0 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 \s-1IP\s0 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 \s-1ECONNREFUSED,\s0 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.  \s-1NOTE:\s0  It still does nothing more
+than connect and disconnect.  It does not speak any protocol
+(i.e., \s-1HTTP\s0 or \s-1FTP\s0) to ensure the remote server is sane in
+any way.  The remote server \s-1CPU\s0 could be grinding to a halt
+and unresponsive to any clients connecting, but if the kernel
+throws the \s-1ACK\s0 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 \*(L"udp\*(R", \*(L"tcp\*(R", and \*(L"syn\*(R" 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\->\s-1IPV6_USE_MIN_MTU\s0" 4
+.el .IP "\f(CW$p\fR\->\s-1IPV6_USE_MIN_MTU\s0" 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\->\s-1IPV6_RECVPATHMTU\s0" 4
+.el .IP "\f(CW$p\fR\->\s-1IPV6_RECVPATHMTU\s0" 4
+.IX Xref "IPV6_RECVPATHMTU"
+.IX Item "$p->IPV6_RECVPATHMTU"
+Notify an according IPv6 \s-1MTU.\s0
+.Sp
+With argument sets the option.
+Without returns the option value.
+.ie n .IP "$p\->\s-1IPV6_HOPLIMIT\s0" 4
+.el .IP "\f(CW$p\fR\->\s-1IPV6_HOPLIMIT\s0" 4
+.IX Xref "IPV6_HOPLIMIT"
+.IX Item "$p->IPV6_HOPLIMIT"
+With argument sets the option.
+Without returns the option value.
+.ie n .IP "$p\->\s-1IPV6_REACHCONF\s0 \fI\s-1NYI\s0\fR" 4
+.el .IP "\f(CW$p\fR\->\s-1IPV6_REACHCONF\s0 \fI\s-1NYI\s0\fR" 4
+.IX Xref "IPV6_REACHCONF"
+.IX Item "$p->IPV6_REACHCONF NYI"
+Sets ipv6 reachability
+\&\s-1IPV6_REACHCONF\s0 was removed in \s-1RFC3542.\s0 ping6 \-R supports it.
+\&\s-1IPV6_REACHCONF\s0 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 \s-1IP\s0 address such as
+\&\*(L"192.168.1.1\*(R".
+.Sp
+If the protocol is set to \*(L"tcp\*(R", 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 \*(L"icmp\*(R" or \*(L"udp\*(R",
+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 \*(L"icmp\*(R" protocol, this call permit to change the
+message type to 'echo' or 'timestamp' (only for IPv4, see \s-1RFC 792\s0).
+.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 \*(L"stream\*(R" 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(CW\*(C`open()\*(C'\fR, the connection is
+automatically opened the first time \f(CW\*(C`ping()\*(C'\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 \*(L"syn\*(R" 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 \s-1TCP ACK.\s0  The order in which the hosts are returned
+may not necessarily be the same order in which they were
+\&\s-1SYN\s0 queued using the \fBping()\fR method.  If the timeout is
+reached before the \s-1TCP ACK\s0 is received, or if the remote
+host is not listening on the port attempted, then the \s-1TCP\s0
+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 \*(L"syn\*(R".
+.Sp
+When \*(L"new\*(R" 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 \s-1ACK.\s0  Useful to find out why when \f(CW\*(C`ack($fail_ack_host)\*(C'\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 \*(L"ack\*(R" with the \*(L"syn\*(R" 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 \*(L"ping\*(R" 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 \*(L"ping\*(R" 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 \*(L"ping\*(R" 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 \*(L"ping\*(R" method used with the syn protocol.
+Sends a \s-1TCP SYN\s0 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 \*(L"ping\*(R" 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 \*(L"ping\*(R" 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 \*(L"ping\*(R" 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 \*(L"ping\*(R" 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 \s-1TCP\s0 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 \s-1TCP\s0 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 \*(L"undef \f(CW$p\fR\*(R".  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 \*(L"ping\*(R" 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(CW\*(C`select()\*(C'\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(CW\*(C`inet_ntop()\*(C'\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(CW\*(C`pingecho()\*(C'\fR subroutine is available with the same
+functionality as before.  \f(CW\*(C`pingecho()\*(C'\fR uses the tcp protocol.  The
+return values and parameters are the same as described for the \*(L"ping\*(R"
+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 \s-1ICMP\s0 packets.  It would be better for a
+separate module to be written which understands all of the different
+kinds of \s-1ICMP\s0 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.