


File::Find(3p)   Perl Programmers Reference Guide  File::Find(3p)


NAME
       find - traverse a file tree

       finddepth - traverse a directory structure depth-first

SYNOPSIS
           use File::Find;
           find(\&wanted, '/foo', '/bar');
           sub wanted { ... }

           use File::Find;
           finddepth(\&wanted, '/foo', '/bar');
           sub wanted { ... }

           use File::Find;
           find({ wanted => \&process, follow => 1 }, '.');


DESCRIPTION
       The first argument to find() is either a hash reference
       describing the operations to be performed for each file,
       or a code reference.

       Here are the possible keys for the hash:

       ""wanted""
          The value should be a code reference.  This code refer-
          ence is called the wanted() function below.

       ""bydepth""
          Reports the name of a directory only AFTER all its
          entries have been reported.  Entry point finddepth() is
          a shortcut for specifying "{ bydepth =" 1 }> in the
          first argument of find().

       ""preprocess""
          The value should be a code reference.  This code refer-
          ence is used to preprocess a directory; it is called
          after readdir() but before the loop that calls the
          wanted() function.  It is called with a list of strings
          and is expected to return a list of strings.  The code
          can be used to sort the strings alphabetically, numeri-
          cally, or to filter out directory entries based on
          their name alone.

       ""postprocess""
          The value should be a code reference.  It is invoked
          just before leaving the current directory.  It is
          called in void context with no arguments.  The name of
          the current directory is in $File::Find::dir.  This
          hook is handy for summarizing a directory, such as cal-
          culating its disk usage.





2001-05-24                 perl v5.6.1                          1





File::Find(3p)   Perl Programmers Reference Guide  File::Find(3p)


       ""follow""
          Causes symbolic links to be followed. Since directory
          trees with symbolic links (followed) may contain files
          more than once and may even have cycles, a hash has to
          be built up with an entry for each file.  This might be
          expensive both in space and time for a large directory
          tree. See follow_fast and follow_skip below.  If either
          follow or follow_fast is in effect:

          o     It is guaranteed that an lstat has been called
                before the user's wanted() function is called.
                This enables fast file checks involving  _.

          o     There is a variable "$File::Find::fullname" which
                holds the absolute pathname of the file with all
                symbolic links resolved

       ""follow_fast""
          This is similar to follow except that it may report
          some files more than once.  It does detect cycles, how-
          ever.  Since only symbolic links have to be hashed,
          this is much cheaper both in space and time.  If pro-
          cessing a file more than once (by the user's wanted()
          function) is worse than just taking time, the option
          follow should be used.

       ""follow_skip""
          "follow_skip==1", which is the default, causes all
          files which are neither directories nor symbolic links
          to be ignored if they are about to be processed a sec-
          ond time. If a directory or a symbolic link are about
          to be processed a second time, File::Find dies.  "fol-
          low_skip==0" causes File::Find to die if any file is
          about to be processed a second time.  "follow_skip==2"
          causes File::Find to ignore any duplicate files and
          dirctories but to proceed normally otherwise.

       ""no_chdir""
          Does not "chdir()" to each directory as it recurses.
          The wanted() function will need to be aware of this, of
          course. In this case, "$_" will be the same as
          "$File::Find::name".

       ""untaint""
          If find is used in taint-mode (-T command line switch
          or if EUID != UID or if EGID != GID) then internally
          directory names have to be untainted before they can be
          cd'ed to. Therefore they are checked against a regular
          expression untaint_pattern.  Note that all names passed
          to the user's wanted() function are still tainted.

       ""untaint_pattern""
          See above. This should be set using the "qr" quoting
          operator.  The default is set to  "qr|^([-+@\w./]+)$|".



2001-05-24                 perl v5.6.1                          2





File::Find(3p)   Perl Programmers Reference Guide  File::Find(3p)


          Note that the parantheses are vital.

       ""untaint_skip""
          If set, directories (subtrees) which fail the
          untaint_pattern are skipped. The default is to 'die' in
          such a case.

       The wanted() function does whatever verifications you
       want.  "$File::Find::dir" contains the current directory
       name, and "$_" the current filename within that directory.
       "$File::Find::name" contains the complete pathname to the
       file. You are chdir()'d to "$File::Find::dir" when the
       function is called, unless "no_chdir" was specified.  When
       <follow> or <follow_fast> are in effect, there is also a
       "$File::Find::fullname".  The function may set
       "$File::Find::prune" to prune the tree unless "bydepth"
       was specified.  Unless "follow" or "follow_fast" is speci-
       fied, for compatibility reasons (find.pl, find2perl) there
       are in addition the following globals available:
       "$File::Find::topdir", "$File::Find::topdev",
       "$File::Find::topino", "$File::Find::topmode" and
       "$File::Find::topnlink".

       This library is useful for the "find2perl" tool, which
       when fed,

           find2perl / -name .nfs\* -mtime +7 \
               -exec rm -f {} \; -o -fstype nfs -prune

       produces something like:

           sub wanted {
               /^\.nfs.*\z/s &&
               (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_)) &&
               int(-M _) > 7 &&
               unlink($_)
               ||
               ($nlink || (($dev, $ino, $mode, $nlink, $uid, $gid) = lstat($_))) &&
               $dev < 0 &&
               ($File::Find::prune = 1);
           }

       Set the variable "$File::Find::dont_use_nlink" if you're
       using AFS, since AFS cheats.

       Here's another interesting wanted function.  It will find
       all symlinks that don't resolve:

           sub wanted {
                -l && !-e && print "bogus link: $File::Find::name\n";
           }

       See also the script "pfind" on CPAN for a nice application
       of this module.



2001-05-24                 perl v5.6.1                          3





File::Find(3p)   Perl Programmers Reference Guide  File::Find(3p)


CAVEAT
       Be aware that the option to follow symbolic links can be
       dangerous.  Depending on the structure of the directory
       tree (including symbolic links to directories) you might
       traverse a given (physical) directory more than once (only
       if "follow_fast" is in effect).  Furthermore, deleting or
       changing files in a symbolically linked directory might
       cause very unpleasant surprises, since you delete or
       change files in an unknown directory.
















































2001-05-24                 perl v5.6.1                          4


