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