home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _1fce4fd280e8e99975594117f2359fd6 < prev    next >
Text File  |  2000-03-23  |  8KB  |  193 lines
  1.  
  2. <HTML>
  3. <HEAD>
  4. <TITLE>find - traverse a file tree</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> find - traverse a file tree</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.     <LI><A HREF="#caveat">CAVEAT</A></LI>
  26. </UL>
  27. <!-- INDEX END -->
  28.  
  29. <HR>
  30. <P>
  31. <H1><A NAME="name">NAME</A></H1>
  32. <P>find - traverse a file tree</P>
  33. <P>finddepth - traverse a directory structure depth-first</P>
  34. <P>
  35. <HR>
  36. <H1><A NAME="supportedplatforms">SUPPORTED PLATFORMS</A></H1>
  37. <UL>
  38. <LI>Linux</LI>
  39. <LI>Solaris</LI>
  40. <LI>Windows</LI>
  41. </UL>
  42. <HR>
  43. <H1><A NAME="synopsis">SYNOPSIS</A></H1>
  44. <PRE>
  45.     use File::Find;
  46.     find(\&wanted, '/foo', '/bar');
  47.     sub wanted { ... }</PRE>
  48. <PRE>
  49.     use File::Find;
  50.     finddepth(\&wanted, '/foo', '/bar');
  51.     sub wanted { ... }</PRE>
  52. <PRE>
  53.     use File::Find;
  54.     find({ wanted => \&process, follow => 1 }, '.');</PRE>
  55. <P>
  56. <HR>
  57. <H1><A NAME="description">DESCRIPTION</A></H1>
  58. <P>The first argument to <CODE>find()</CODE> is either a hash reference describing the
  59. operations to be performed for each file, or a code reference.</P>
  60. <P>Here are the possible keys for the hash:</P>
  61. <DL>
  62. <DT><STRONG><A NAME="item_wanted"><CODE>wanted</CODE></A></STRONG><BR>
  63. <DD>
  64. The value should be a code reference.  This code reference is called
  65. <EM>the wanted() function</EM> below.
  66. <P></P>
  67. <DT><STRONG><A NAME="item_bydepth"><CODE>bydepth</CODE></A></STRONG><BR>
  68. <DD>
  69. Reports the name of a directory only AFTER all its entries
  70. have been reported.  Entry point <CODE>finddepth()</CODE> is a shortcut for
  71. specifying <CODE>{ bydepth =</CODE> 1 }> in the first argument of find().
  72. <P></P>
  73. <DT><STRONG><A NAME="item_follow"><CODE>follow</CODE></A></STRONG><BR>
  74. <DD>
  75. Causes symbolic links to be followed. Since directory trees with symbolic
  76. links (followed) may contain files more than once and may even have
  77. cycles, a hash has to be built up with an entry for each file.
  78. This might be expensive both in space and time for a large
  79. directory tree. See <EM>follow_fast</EM> and <EM>follow_skip</EM> below.
  80. If either <EM>follow</EM> or <EM>follow_fast</EM> is in effect:
  81. <UL>
  82. <LI>
  83. It is guarantueed that an <EM>lstat</EM> has been called before the user's
  84. <EM>wanted()</EM> function is called. This enables fast file checks involving  _.
  85. <P></P>
  86. <LI>
  87. There is a variable <CODE>$File::Find::fullname</CODE> which holds the absolute
  88. pathname of the file with all symbolic links resolved
  89. <P></P></UL>
  90. <DT><STRONG><A NAME="item_follow_fast"><CODE>follow_fast</CODE></A></STRONG><BR>
  91. <DD>
  92. This is similar to <EM>follow</EM> except that it may report some files
  93. more than once. It does detect cycles however.
  94. Since only symbolic links have to be hashed, this is
  95. much cheaper both in space and time.
  96. If processing a file more than once (by the user's <EM>wanted()</EM> function)
  97. is worse than just taking time, the option <EM>follow</EM> should be used.
  98. <P></P>
  99. <DT><STRONG><A NAME="item_follow_skip"><CODE>follow_skip</CODE></A></STRONG><BR>
  100. <DD>
  101. <CODE>follow_skip==1</CODE>, which is the default, causes all files which are
  102. neither directories nor symbolic links to be ignored if they are about
  103. to be processed a second time. If a directory or a symbolic link 
  104. are about to be processed a second time, File::Find dies.
  105. <CODE>follow_skip==0</CODE> causes File::Find to die if any file is about to be
  106. processed a second time.
  107. <CODE>follow_skip==2</CODE> causes File::Find to ignore any duplicate files and
  108. dirctories but to proceed normally otherwise.
  109. <P></P>
  110. <DT><STRONG><A NAME="item_no_chdir"><CODE>no_chdir</CODE></A></STRONG><BR>
  111. <DD>
  112. Does not <A HREF="../../lib/Pod/perlfunc.html#item_chdir"><CODE>chdir()</CODE></A> to each directory as it recurses. The <A HREF="#item_wanted"><CODE>wanted()</CODE></A>
  113. function will need to be aware of this, of course. In this case,
  114. <CODE>$_</CODE> will be the same as <CODE>$File::Find::name</CODE>.
  115. <P></P>
  116. <DT><STRONG><A NAME="item_untaint"><CODE>untaint</CODE></A></STRONG><BR>
  117. <DD>
  118. If find is used in taint-mode (-T command line switch or if EUID != UID
  119. or if EGID != GID) then internally directory names have to be untainted
  120. before they can be cd'ed to. Therefore they are checked against a regular
  121. expression <EM>untaint_pattern</EM>. Note, that all names passed to the
  122. user's <EM>wanted()</EM> function are still tainted.
  123. <P></P>
  124. <DT><STRONG><A NAME="item_untaint_pattern"><CODE>untaint_pattern</CODE></A></STRONG><BR>
  125. <DD>
  126. See above. This should be set using the <A HREF="../../lib/Pod/perlfunc.html#item_qr"><CODE>qr</CODE></A> quoting operator.
  127. The default is set to  <CODE>qr|^([-+@\w./]+)$|</CODE>. 
  128. Note that the paranthesis which are vital.
  129. <P></P>
  130. <DT><STRONG><A NAME="item_untaint_skip"><CODE>untaint_skip</CODE></A></STRONG><BR>
  131. <DD>
  132. If set, directories (subtrees) which fail the <EM>untaint_pattern</EM>
  133. are skipped. The default is to 'die' in such a case.
  134. <P></P></DL>
  135. <P>The <A HREF="#item_wanted"><CODE>wanted()</CODE></A> function does whatever verifications you want.
  136. <CODE>$File::Find::dir</CODE> contains the current directory name, and <CODE>$_</CODE> the
  137. current filename within that directory.  <CODE>$File::Find::name</CODE> contains
  138. the complete pathname to the file. You are chdir()'d to <CODE>$File::Find::dir</CODE> when
  139. the function is called, unless <A HREF="#item_no_chdir"><CODE>no_chdir</CODE></A> was specified.
  140. When <follow> or <follow_fast> are in effect there is also a
  141. <CODE>$File::Find::fullname</CODE>.
  142. The function may set <CODE>$File::Find::prune</CODE> to prune the tree
  143. unless <A HREF="#item_bydepth"><CODE>bydepth</CODE></A> was specified.
  144. Unless <A HREF="#item_follow"><CODE>follow</CODE></A> or <A HREF="#item_follow_fast"><CODE>follow_fast</CODE></A> is specified, for compatibility
  145. reasons (find.pl, find2perl) there are in addition the following globals
  146. available: <CODE>$File::Find::topdir</CODE>, <CODE>$File::Find::topdev</CODE>, <CODE>$File::Find::topino</CODE>,
  147. <CODE>$File::Find::topmode</CODE> and <CODE>$File::Find::topnlink</CODE>.</P>
  148. <P>This library is useful for the <CODE>find2perl</CODE> tool, which when fed,</P>
  149. <PRE>
  150.     find2perl / -name .nfs\* -mtime +7 \
  151.         -exec rm -f {} \; -o -fstype nfs -prune</PRE>
  152. <P>produces something like:</P>
  153. <PRE>
  154.     sub wanted {
  155.         /^\.nfs.*\z/s &&
  156.         (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
  157.         int(-M _) > 7 &&
  158.         unlink($_)
  159.         ||
  160.         ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
  161.         $dev < 0 &&
  162.         ($File::Find::prune = 1);
  163.     }</PRE>
  164. <P>Set the variable <CODE>$File::Find::dont_use_nlink</CODE> if you're using AFS,
  165. since AFS cheats.</P>
  166. <P>Here's another interesting wanted function.  It will find all symlinks
  167. that don't resolve:</P>
  168. <PRE>
  169.     sub wanted {
  170.          -l && !-e && print "bogus link: $File::Find::name\n";
  171.     }</PRE>
  172. <P>See also the script <CODE>pfind</CODE> on CPAN for a nice application of this
  173. module.</P>
  174. <P>
  175. <HR>
  176. <H1><A NAME="caveat">CAVEAT</A></H1>
  177. <P>Be aware that the option to follow symblic links can be dangerous.
  178. Depending on the structure of the directory tree (including symbolic
  179. links to directories) you might traverse a given (physical) directory
  180. more than once (only if <A HREF="#item_follow_fast"><CODE>follow_fast</CODE></A> is in effect). 
  181. Furthermore, deleting or changing files in a symbolically linked directory
  182. might cause very unpleasant surprises, since you delete or change files
  183. in an unknown directory.</P>
  184. <TABLE BORDER=0 CELLPADDING=0 CELLSPACING=0 WIDTH=100%>
  185. <TR><TD CLASS=block VALIGN=MIDDLE WIDTH=100% BGCOLOR="#cccccc">
  186. <STRONG><P CLASS=block> find - traverse a file tree</P></STRONG>
  187. </TD></TR>
  188. </TABLE>
  189.  
  190. </BODY>
  191.  
  192. </HTML>
  193.