home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _8123a252338fc56007bd9d3b6777a9ac < prev    next >
Text File  |  2000-03-23  |  8KB  |  188 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>Net::Ping - check a remote host for reachability</TITLE>
  5. <LINK REL="stylesheet" HREF="../../../Active.css" TYPE="text/css">
  6. <LINK REV="made" HREF="mailto:">
  7. </HEAD>
  8.  
  9. <BODY>
  10. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  11. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  12. <STRONG><P CLASS=block> Net::Ping - check a remote host for reachability</P></STRONG>
  13. </TD></TR>
  14. </TABLE>
  15.  
  16. <A NAME="__index__"></A>
  17. <!-- INDEX BEGIN -->
  18.  
  19. <UL>
  20.  
  21.     <LI><A HREF="#name">NAME</A></LI><LI><A HREF="#supportedplatforms">SUPPORTED PLATFORMS</A></LI>
  22.  
  23.     <LI><A HREF="#synopsis">SYNOPSIS</A></LI>
  24.     <LI><A HREF="#description">DESCRIPTION</A></LI>
  25.     <UL>
  26.  
  27.         <LI><A HREF="#functions">Functions</A></LI>
  28.     </UL>
  29.  
  30.     <LI><A HREF="#warning">WARNING</A></LI>
  31.     <LI><A HREF="#notes">NOTES</A></LI>
  32. </UL>
  33. <!-- INDEX END -->
  34.  
  35. <HR>
  36. <P>
  37. <H1><A NAME="name">NAME</A></H1>
  38. <P>Net::Ping - check a remote host for reachability</P>
  39. <P>
  40. <HR>
  41. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  42. <UL>
  43. <LI>Linux</LI>
  44. <LI>Solaris</LI>
  45. <LI>Windows</LI>
  46. </UL>
  47. <HR>
  48. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  49. <PRE>
  50.     use Net::Ping;</PRE>
  51. <PRE>
  52.     $p = Net::Ping->new();
  53.     print "$host is alive.\n" if $p->ping($host);
  54.     $p->close();</PRE>
  55. <PRE>
  56.     $p = Net::Ping->new("icmp");
  57.     foreach $host (@host_array)
  58.     {
  59.         print "$host is ";
  60.         print "NOT " unless $p->ping($host, 2);
  61.         print "reachable.\n";
  62.         sleep(1);
  63.     }
  64.     $p->close();
  65. </PRE>
  66. <PRE>
  67.  
  68.     $p = Net::Ping->new("tcp", 2);
  69.     while ($stop_time > time())
  70.     {
  71.         print "$host not reachable ", scalar(localtime()), "\n"
  72.             unless $p->ping($host);
  73.         sleep(300);
  74.     }
  75.     undef($p);</PRE>
  76. <PRE>
  77.  
  78.     # For backward compatibility
  79.     print "$host is alive.\n" if pingecho($host);</PRE>
  80. <P>
  81. <HR>
  82. <H1><A NAME="description">DESCRIPTION</A></H1>
  83. <P>This module contains methods to test the reachability of remote
  84. hosts on a network.  A ping object is first created with optional
  85. parameters, a variable number of hosts may be pinged multiple
  86. times and then the connection is closed.</P>
  87. <P>You may choose one of three different protocols to use for the ping.
  88. With the ``tcp'' protocol the <A HREF="#item_ping"><CODE>ping()</CODE></A> method attempts to establish a
  89. connection to the remote host's echo port.  If the connection is
  90. successfully established, the remote host is considered reachable.  No
  91. data is actually echoed.  This protocol does not require any special
  92. privileges but has higher overhead than the other two protocols.</P>
  93. <P>Specifying the ``udp'' protocol causes the <A HREF="#item_ping"><CODE>ping()</CODE></A> method to send a udp
  94. packet to the remote host's echo port.  If the echoed packet is
  95. received from the remote host and the received packet contains the
  96. same data as the packet that was sent, the remote host is considered
  97. reachable.  This protocol does not require any special privileges.</P>
  98. <P>If the ``icmp'' protocol is specified, the <A HREF="#item_ping"><CODE>ping()</CODE></A> method sends an icmp
  99. echo message to the remote host, which is what the UNIX ping program
  100. does.  If the echoed message is received from the remote host and
  101. the echoed information is correct, the remote host is considered
  102. reachable.  Specifying the ``icmp'' protocol requires that the program
  103. be run as root or that the program be setuid to root.</P>
  104. <P>
  105. <H2><A NAME="functions">Functions</A></H2>
  106. <DL>
  107. <DT><STRONG><A NAME="item_new">Net::Ping->new([$proto [, $def_timeout [, $bytes]]]);</A></STRONG><BR>
  108. <DD>
  109. Create a new ping object.  All of the parameters are optional.  $proto
  110. specifies the protocol to use when doing a ping.  The current choices
  111. are ``tcp'', ``udp'' or ``icmp''.  The default is ``udp''.
  112. <P>If a default timeout ($def_timeout) in seconds is provided, it is used
  113. when a timeout is not given to the <A HREF="#item_ping"><CODE>ping()</CODE></A> method (below).  The timeout
  114. must be greater than 0 and the default, if not specified, is 5 seconds.</P>
  115. <P>If the number of data bytes ($bytes) is given, that many data bytes
  116. are included in the ping packet sent to the remote host. The number of
  117. data bytes is ignored if the protocol is ``tcp''.  The minimum (and
  118. default) number of data bytes is 1 if the protocol is ``udp'' and 0
  119. otherwise.  The maximum number of data bytes that can be specified is
  120. 1024.</P>
  121. <P></P>
  122. <DT><STRONG><A NAME="item_ping">$p->ping($host [, $timeout]);</A></STRONG><BR>
  123. <DD>
  124. Ping the remote host and wait for a response.  $host can be either the
  125. hostname or the IP number of the remote host.  The optional timeout
  126. must be greater than 0 seconds and defaults to whatever was specified
  127. when the ping object was created.  If the hostname cannot be found or
  128. there is a problem with the IP number, undef is returned.  Otherwise,
  129. 1 is returned if the host is reachable and 0 if it is not.  For all
  130. practical purposes, undef and 0 and can be treated as the same case.
  131. <P></P>
  132. <DT><STRONG><A NAME="item_close">$p->close();</A></STRONG><BR>
  133. <DD>
  134. Close the network connection for this ping object.  The network
  135. connection is also closed by ``undef $p''.  The network connection is
  136. automatically closed if the ping object goes out of scope (e.g. $p is
  137. local to a subroutine and you leave the subroutine).
  138. <P></P>
  139. <DT><STRONG><A NAME="item_pingecho">pingecho($host [, $timeout]);</A></STRONG><BR>
  140. <DD>
  141. To provide backward compatibility with the previous version of
  142. Net::Ping, a <A HREF="#item_pingecho"><CODE>pingecho()</CODE></A> subroutine is available with the same
  143. functionality as before.  <A HREF="#item_pingecho"><CODE>pingecho()</CODE></A> uses the tcp protocol.  The
  144. return values and parameters are the same as described for the <A HREF="#item_ping"><CODE>ping()</CODE></A>
  145. method.  This subroutine is obsolete and may be removed in a future
  146. version of Net::Ping.
  147. <P></P></DL>
  148. <P>
  149. <HR>
  150. <H1><A NAME="warning">WARNING</A></H1>
  151. <P><A HREF="#item_pingecho"><CODE>pingecho()</CODE></A> or a ping object with the tcp protocol use <A HREF="../../../lib/Pod/perlfunc.html#item_alarm"><CODE>alarm()</CODE></A> to
  152. implement the timeout.  So, don't use <A HREF="../../../lib/Pod/perlfunc.html#item_alarm"><CODE>alarm()</CODE></A> in your program while
  153. you are using <A HREF="#item_pingecho"><CODE>pingecho()</CODE></A> or a ping object with the tcp protocol.  The
  154. udp and icmp protocols do not use <A HREF="../../../lib/Pod/perlfunc.html#item_alarm"><CODE>alarm()</CODE></A> to implement the timeout.</P>
  155. <P>
  156. <HR>
  157. <H1><A NAME="notes">NOTES</A></H1>
  158. <P>There will be less network overhead (and some efficiency in your
  159. program) if you specify either the udp or the icmp protocol.  The tcp
  160. protocol will generate 2.5 times or more traffic for each ping than
  161. either udp or icmp.  If many hosts are pinged frequently, you may wish
  162. to implement a small wait (e.g. 25ms or more) between each ping to
  163. avoid flooding your network with packets.</P>
  164. <P>The icmp protocol requires that the program be run as root or that it
  165. be setuid to root.  The tcp and udp protocols do not require special
  166. privileges, but not all network devices implement the echo protocol
  167. for tcp or udp.</P>
  168. <P>Local hosts should normally respond to pings within milliseconds.
  169. However, on a very congested network it may take up to 3 seconds or
  170. longer to receive an echo packet from the remote host.  If the timeout
  171. is set too low under these conditions, it will appear that the remote
  172. host is not reachable (which is almost the truth).</P>
  173. <P>Reachability doesn't necessarily mean that the remote host is actually
  174. functioning beyond its ability to echo packets.</P>
  175. <P>Because of a lack of anything better, this module uses its own
  176. routines to pack and unpack ICMP packets.  It would be better for a
  177. separate module to be written which understands all of the different
  178. kinds of ICMP packets.</P>
  179. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  180. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  181. <STRONG><P CLASS=block> Net::Ping - check a remote host for reachability</P></STRONG>
  182. </TD></TR>
  183. </TABLE>
  184.  
  185. </BODY>
  186.  
  187. </HTML>
  188.