home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / perl5 / Net::Ping.z / Net::Ping
Encoding:
Text File  |  1998-10-30  |  7.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))                                                      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Net::Ping - check a remote host for reachability
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.          use Net::Ping;
  13.  
  14.          $p = Net::Ping->new();
  15.          print "$host is alive.\n" if $p->ping($host);
  16.          $p->close();
  17.  
  18.          $p = Net::Ping->new("icmp");
  19.          foreach $host (@host_array)
  20.          {
  21.              print "$host is ";
  22.              print "NOT " unless $p->ping($host, 2);
  23.              print "reachable.\n";
  24.              sleep(1);
  25.          }
  26.          $p->close();
  27.  
  28.          $p = Net::Ping->new("tcp", 2);
  29.          while ($stop_time > time())
  30.          {
  31.              print "$host not reachable ", scalar(localtime()), "\n"
  32.                  unless $p->ping($host);
  33.              sleep(300);
  34.          }
  35.          undef($p);
  36.  
  37.          # For backward compatibility
  38.          print "$host is alive.\n" if pingecho($host);
  39.  
  40.  
  41. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  42.      This module contains methods to test the reachability of remote hosts on
  43.      a network.  A ping object is first created with optional parameters, a
  44.      variable number of hosts may be pinged multiple times and then the
  45.      connection is closed.
  46.  
  47.      You may choose one of three different protocols to use for the ping.
  48.      With the "tcp" protocol the _p_i_n_g() method attempts to establish a
  49.      connection to the remote host's echo port.  If the connection is
  50.      successfully established, the remote host is considered reachable.  No
  51.      data is actually echoed.  This protocol does not require any special
  52.      privileges but has higher overhead than the other two protocols.
  53.  
  54.      Specifying the "udp" protocol causes the _p_i_n_g() method to send a udp
  55.      packet to the remote host's echo port.  If the echoed packet is received
  56.      from the remote host and the received packet contains the same data as
  57.      the packet that was sent, the remote host is considered reachable.  This
  58.      protocol does not require any special privileges.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))                                                      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  71.  
  72.  
  73.  
  74.      If the "icmp" protocol is specified, the _p_i_n_g() method sends an icmp echo
  75.      message to the remote host, which is what the UNIX ping program does.  If
  76.      the echoed message is received from the remote host and the echoed
  77.      information is correct, the remote host is considered reachable.
  78.      Specifying the "icmp" protocol requires that the program be run as root
  79.      or that the program be setuid to root.
  80.  
  81.      FFFFuuuunnnnccccttttiiiioooonnnnssss
  82.  
  83.      Net::Ping->new([$proto [, $def_timeout [, $bytes]]]);
  84.          Create a new ping object.  All of the parameters are optional.
  85.          $proto specifies the protocol to use when doing a ping.  The current
  86.          choices are "tcp", "udp" or "icmp".  The default is "udp".
  87.  
  88.          If a default timeout ($def_timeout) in seconds is provided, it is
  89.          used when a timeout is not given to the _p_i_n_g() method (below).  The
  90.          timeout must be greater than 0 and the default, if not specified, is
  91.          5 seconds.
  92.  
  93.          If the number of data bytes ($bytes) is given, that many data bytes
  94.          are included in the ping packet sent to the remote host. The number
  95.          of data bytes is ignored if the protocol is "tcp".  The minimum (and
  96.          default) number of data bytes is 1 if the protocol is "udp" and 0
  97.          otherwise.  The maximum number of data bytes that can be specified is
  98.          1024.
  99.  
  100.      $p->ping($host [, $timeout]);
  101.          Ping the remote host and wait for a response.  $host can be either
  102.          the hostname or the IP number of the remote host.  The optional
  103.          timeout must be greater than 0 seconds and defaults to whatever was
  104.          specified when the ping object was created.  If the hostname cannot
  105.          be found or there is a problem with the IP number, undef is returned.
  106.          Otherwise, 1 is returned if the host is reachable and 0 if it is not.
  107.          For all practical purposes, undef and 0 and can be treated as the
  108.          same case.
  109.  
  110.      $p->close();
  111.          Close the network connection for this ping object.  The network
  112.          connection is also closed by "undef $p".  The network connection is
  113.          automatically closed if the ping object goes out of scope (e.g. $p is
  114.          local to a subroutine and you leave the subroutine).
  115.  
  116.      pingecho($host [, $timeout]);
  117.          To provide backward compatibility with the previous version of
  118.          Net::Ping, a _p_i_n_g_e_c_h_o() subroutine is available with the same
  119.          functionality as before.  _p_i_n_g_e_c_h_o() uses the tcp protocol.  The
  120.          return values and parameters are the same as described for the _p_i_n_g()
  121.          method.  This subroutine is obsolete and may be removed in a future
  122.          version of Net::Ping.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))                                                      NNNNeeeetttt::::::::PPPPiiiinnnngggg((((3333))))
  137.  
  138.  
  139.  
  140. WWWWAAAARRRRNNNNIIIINNNNGGGG
  141.      _p_i_n_g_e_c_h_o() or a ping object with the tcp protocol use _a_l_a_r_m() to
  142.      implement the timeout.  So, don't use _a_l_a_r_m() in your program while you
  143.      are using _p_i_n_g_e_c_h_o() or a ping object with the tcp protocol.  The udp and
  144.      icmp protocols do not use _a_l_a_r_m() to implement the timeout.
  145.  
  146. NNNNOOOOTTTTEEEESSSS
  147.      There will be less network overhead (and some efficiency in your program)
  148.      if you specify either the udp or the icmp protocol.  The tcp protocol
  149.      will generate 2.5 times or more traffic for each ping than either udp or
  150.      icmp.  If many hosts are pinged frequently, you may wish to implement a
  151.      small wait (e.g. 25ms or more) between each ping to avoid flooding your
  152.      network with packets.
  153.  
  154.      The icmp protocol requires that the program be run as root or that it be
  155.      setuid to root.  The tcp and udp protocols do not require special
  156.      privileges, but not all network devices implement the echo protocol for
  157.      tcp or udp.
  158.  
  159.      Local hosts should normally respond to pings within milliseconds.
  160.      However, on a very congested network it may take up to 3 seconds or
  161.      longer to receive an echo packet from the remote host.  If the timeout is
  162.      set too low under these conditions, it will appear that the remote host
  163.      is not reachable (which is almost the truth).
  164.  
  165.      Reachability doesn't necessarily mean that the remote host is actually
  166.      functioning beyond its ability to echo packets.
  167.  
  168.      Because of a lack of anything better, this module uses its own routines
  169.      to pack and unpack ICMP packets.  It would be better for a separate
  170.      module to be written which understands all of the different kinds of ICMP
  171.      packets.
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.