home *** CD-ROM | disk | FTP | other *** search
/ Chip 2000 May / Chip_2000-05_cd1.bin / zkuste / Perl / ActivePerl-5.6.0.613.msi / 䆊䌷䈹䈙䏵-䞅䞆䞀㡆䞃䄦䠥 / _396802fb37eeba9c4b5a3233737308a5 < prev    next >
Text File  |  2000-03-24  |  57KB  |  1,883 lines
  1. @rem = '--*-Perl-*--
  2. @echo off
  3. if "%OS%" == "Windows_NT" goto WinNT
  4. perl -x -S "%0" %1 %2 %3 %4 %5 %6 %7 %8 %9
  5. goto endofperl
  6. :WinNT
  7. perl -x -S "%0" %*
  8. if NOT "%COMSPEC%" == "%SystemRoot%\system32\cmd.exe" goto endofperl
  9. if %errorlevel% == 9009 echo You do not have Perl in your PATH.
  10. if errorlevel 1 goto script_failed_so_exit_with_non_zero_val 2>nul
  11. goto endofperl
  12. @rem ';
  13. #!/usr/local/bin/perl -w
  14. #line 15
  15. 'di';
  16. 'ig00';
  17. ##############################################################################
  18. ##
  19. ## search
  20. ##
  21. ## Jeffrey Friedl (jfriedl@omron.co.jp), Dec 1994.
  22. ## Copyright 19.... ah hell, just take it.
  23. ##
  24. ## BLURB:
  25. ## A combo of find and grep -- more or less do a 'grep' on a whole
  26. ## directory tree. Fast, with lots of options. Much more powerful than
  27. ## the simple "find ... | xargs grep ....". Has a full man page.
  28. ## Powerfully customizable.
  29. ##
  30. ## This file is big, but mostly comments and man page.
  31. ##
  32. ## See man page for usage info.
  33. ## Return value: 2=error, 1=nothing found, 0=something found.
  34. ##
  35.  
  36. $version = "950918.5";
  37. ##
  38. ## "950918.5";
  39. ##    Changed all 'sysread' to 'read' because Linux perl's don't seem
  40. ##    to like sysread()
  41. ##
  42. ## "941227.4";
  43. ##    Added -n, -u
  44. ##
  45. ## "941222.3"
  46. ##      Added -nice (due to Lionel Cons <Lionel.Cons@cern.ch>)
  47. ##    Removed any leading "./" from name.
  48. ##      Added default flags for ~/.search, including TTY, -nice, -list, etc.
  49. ##    Program name now has path removed when printed in diagnostics.
  50. ##    Added simple tilde-expansion to -dir arg.
  51. ##    Added -dskip, etc. Fixed -iregex bug.
  52. ##    Changed -dir to be additive, adding -ddir.
  53. ##    Now screen out devices, pipes, and sockets.
  54. ##    More tidying and lots of expanding of the man page
  55. ##
  56. ##
  57. ## "941217.2";
  58. ##    initial release.
  59.  
  60. $stripped=0;
  61.  
  62. &init;
  63. $rc_file = join('/', $ENV{'HOME'}, ".search");
  64.  
  65. &check_args;
  66.  
  67. ## Make sure we've got a regex.
  68. ## Don't need one if -find or -showrc was specified.
  69. $!=2, die "expecting regex arguments.\n"
  70.     if $FIND_ONLY == 0 && $showrc == 0 && @ARGV == 0;
  71.  
  72. &prepare_to_search($rc_file);
  73.  
  74. &import_program if !defined &dodir; ## BIG key to speed.
  75.  
  76. ## do search while there are directories to be done.
  77. &dodir(shift(@todo)) while @todo;
  78.  
  79. &clear_message if $VERBOSE && $STDERR_IS_TTY;
  80. exit($retval);
  81. ###############################################################################
  82.  
  83. sub init
  84. {
  85.   ## initialize variables that might be reset by command-line args
  86.   $DOREP=0;         ## set true by -dorep (redo multi-hardlink files)
  87.   $DOREP=1 if $^O eq 'MSWin32';
  88.   $DO_SORT=0;           ## set by -sort (sort files in a dir before checking)
  89.   $FIND_ONLY=0;         ## set by -find (don't search files)
  90.   $LIST_ONLY=0;        ## set true by -l (list filenames only)
  91.   $NEWER=0;             ## set by -newer, "-mtime -###"
  92.   $NICE=0;              ## set by -nice (print human-readable output)
  93.   $NOLINKS=0;         ## set true by -nolinks (don't follow symlinks)
  94.   $OLDER=0;             ## set by -older, "-mtime  ###"
  95.   $PREPEND_FILENAME=1;  ## set false by -h (don't prefix lines with filename)
  96.   $REPORT_LINENUM=0;    ## set true by -n (show line numbers)
  97.   $VERBOSE=0;        ## set to a value by -v, -vv, etc. (verbose messages)
  98.   $WHY=0;        ## set true by -why, -vvv+ (report why skipped)
  99.   $XDEV=0;        ## set true by -xdev (stay on one filesystem)
  100.   $all=0;        ## set true by -all (don't skip many kinds of files)
  101.   $iflag = '';        ## set to 'i' by -i (ignore case);
  102.   $norc=0;              ## set by -norc (don't load rc file)
  103.   $showrc=0;            ## set by -showrc (show what happens with rc file)
  104.   $underlineOK=0;       ## set true by -u (watch for underline stuff)
  105.   $words=0;             ## set true by -w (match whole-words only)
  106.   $DELAY=0;        ## inter-file delay (seconds)
  107.   $retval=1;            ## will set to 0 if we find anything.
  108.  
  109.   ## various elements of stat() that we might access
  110.   $STAT_DEV   = 1;
  111.   $STAT_INODE = 2;
  112.   $STAT_MTIME = 9;
  113.  
  114.   $VV_PRINT_COUNT = 50;  ## with -vv, print every VV_PRINT_COUNT files, or...
  115.   $VV_SIZE = 1024*1024;  ## ...every VV_SIZE bytes searched
  116.   $vv_print = $vv_size = 0; ## running totals.
  117.  
  118.   ## set default options, in case the rc file wants them
  119.   $opt{'TTY'}= 1 if -t STDOUT;
  120.   
  121.   ## want to know this for debugging message stuff
  122.   $STDERR_IS_TTY = -t STDERR ? 1 : 0;
  123.   $STDERR_SCREWS_STDOUT = ($STDERR_IS_TTY && -t STDOUT) ? 1 : 0;
  124.  
  125.   $0 =~ s,.*/,,;  ## clean up $0 for any diagnostics we'll be printing.
  126. }
  127.  
  128. ##
  129. ## Check arguments.
  130. ##
  131. sub check_args
  132. {
  133.   while (@ARGV && $ARGV[0] =~ m/^-/)
  134.   {
  135.       $arg = shift(@ARGV);
  136.  
  137.       if ($arg eq '-version' || ($VERBOSE && $arg eq '-help')) {
  138.       print qq/Jeffrey's file search, version "$version".\n/;
  139.       exit(0) unless $arg eq '-help';
  140.       }
  141.       if ($arg eq '-help') {
  142.       print <<INLINE_LITERAL_TEXT;
  143. usage: $0 [options] [-e] [PerlRegex ....]
  144. OPTIONS TELLING *WHERE* TO SEARCH:
  145.   -dir DIR       start search at the named directory (default is current dir).
  146.   -xdev          stay on starting file system.
  147.   -sort          sort the files in each directory before processing.
  148.   -nolinks       don't follow symbolic links.
  149. OPTIONS TELLING WHICH FILES TO EVEN CONSIDER:
  150.   -mtime #       consider files modified > # days ago (-# for < # days old)
  151.   -newer FILE    consider files modified more recently than FILE (also -older)
  152.   -name GLOB     consider files whose name matches pattern (also -regex).
  153.   -skip GLOB     opposite of -name: identifies files to not consider.
  154.   -path GLOB     like -name, but for files whose whole path is described.
  155.   -dpath/-dregex/-dskip versions for selecting or pruning directories.
  156.   -all           don't skip any files marked to be skipped by the startup file.
  157.   -x<SPECIAL>    (see manual, and/or try -showrc).
  158.   -why           report why a file isn't checked (also implied by -vvvv).
  159. OPTIONS TELLING WHAT TO DO WITH FILES THAT WILL BE CONSIDERED:
  160.   -f  | -find    just list files (PerlRegex ignored). Default is to grep them.
  161.   -ff | -ffind   Does a faster -find (implies -find -all -dorep)
  162. OPTIONS CONTROLLING HOW THE SEARCH IS DONE (AND WHAT IS PRINTED):
  163.   -l | -list     only list files with matches, not the lines themselves.
  164.   -nice | -nnice print more "human readable" output.
  165.   -n             prefix each output line with its line number in the file.
  166.   -h             don't prefix output lines with file name.
  167.   -u             also look "inside" manpage-style underlined text
  168.   -i             do case-insensitive searching.
  169.   -w             match words only (as defined by perl's \\b).
  170. OTHER OPTIONS:
  171.   -v, -vv, -vvv  various levels of message verbosity.
  172.   -e             end of options (in case a regex looks like an option).
  173.   -showrc        show what the rc file sets, then exit.
  174.   -norc          don't load the rc file.
  175.   -dorep         check files with multiple hard links multiple times.
  176. INLINE_LITERAL_TEXT
  177.     print "Use -v -help for more verbose help.\n" unless $VERBOSE;
  178.     print "This script file is also a man page.\n" unless $stripped;
  179.     print <<INLINE_LITERAL_TEXT if $VERBOSE;
  180.  
  181. If -f (or -find) given, PerlRegex is optional and ignored.
  182. Otherwise, will search for files with lines matching any of the given regexes.
  183.  
  184. Combining things like -name and -mtime implies boolean AND.
  185. However, duplicating things (such as -name '*.c' -name '*.txt') implies OR.
  186.  
  187. -mtime may be given floating point (i.e. 1.5 is a day and a half).
  188. -iskip/-idskip/-ipath/... etc are case-insensitive versions.
  189.  
  190. If any letter in -newer/-older is upper case, "or equal" is
  191. inserted into the test.
  192.  
  193. You can always find the latest version on the World Wide Web in
  194.    http://www.wg.omron.co.jp/~jfriedl/perl/
  195. INLINE_LITERAL_TEXT
  196.       exit(0);
  197.       }
  198.       $DOREP=1,             next if $arg eq '-dorep';   ## do repeats
  199.       $DO_SORT=1,           next if $arg eq '-sort';    ## sort files
  200.       $NOLINKS=1,           next if $arg eq '-nolinks'; ## no sym. links
  201.       $PREPEND_FILENAME=0,  next if $arg eq '-h';       ## no filename prefix
  202.       $REPORT_LINENUM=1,    next if $arg eq '-n';       ## show line numbers
  203.       $WHY=1,               next if $arg eq '-why';     ## tell why skipped
  204.       $XDEV=1,              next if $arg eq '-xdev';    ## don't leave F.S.
  205.       $all=1,$opt{'-all'}=1,next if $arg eq '-all';     ## don't skip *.Z, etc
  206.       $iflag='i',           next if $arg eq '-i';       ## ignore case
  207.       $norc=1,              next if $arg eq '-norc';    ## don't load rc file
  208.       $showrc=1,            next if $arg eq '-showrc';  ## show rc file
  209.       $underlineOK=1,       next if $arg eq '-u';       ## look throuh underln.
  210.       $words=1,             next if $arg eq '-w';       ## match "words" only
  211.       &strip                     if $arg eq '-strip';   ## dump this program
  212.       last                       if $arg eq '-e';
  213.       $DELAY=$1,            next if $arg =~ m/-delay(\d+)/;
  214.  
  215.       $FIND_ONLY=1,         next if $arg =~/^-f(ind)?$/;## do "find" only
  216.  
  217.       $FIND_ONLY=1, $DOREP=1, $all=1,
  218.                             next if $arg =~/^-ff(ind)?$/;## fast -find
  219.       $LIST_ONLY=1,$opt{'-list'}=1,
  220.                     next if $arg =~/^-l(ist)?$/;## only list files
  221.  
  222.       if ($arg =~ m/^-(v+)$/) { ## verbosity
  223.     $VERBOSE =length($1);
  224.     foreach $len (1..$VERBOSE) { $opt{'-'.('v' x $len)}=1 }
  225.     next;
  226.       }
  227.       if ($arg =~ m/^-(n+)ice$/) { ## "nice" output
  228.         $NICE =length($1);
  229.     foreach $len (1..$NICE) { $opt{'-'.('n' x $len).'ice'}=1 }
  230.     next;
  231.       }
  232.  
  233.       if ($arg =~ m/^-(i?)(d?)skip$/) {
  234.       local($i) = $1 eq 'i';
  235.       local($d) = $2 eq 'd';
  236.       $! = 2, die qq/$0: expecting glob arg to -$arg\n/ unless @ARGV;
  237.       foreach (split(/\s+/, shift @ARGV)) {
  238.           if ($d) {
  239.           $idskip{$_}=1 if $i;
  240.            $dskip{$_}=1;
  241.           } else {
  242.           $iskip{$_}=1 if $i;
  243.            $skip{$_}=1;
  244.           }
  245.       }
  246.       next;
  247.       }
  248.  
  249.  
  250.       if ($arg =~ m/^-(i?)(d?)(regex|path|name)$/) {
  251.       local($i) = $1 eq 'i';
  252.       $! = 2, die qq/$0: expecting arg to -$arg\n/ unless @ARGV;
  253.       foreach (split(/\s+/, shift @ARGV)) {
  254.           $iname{join(',', $arg, $_)}=1 if $i;
  255.            $name{join(',', $arg, $_)}=1;
  256.       }
  257.       next;
  258.       }
  259.  
  260.       if ($arg =~ m/^-d?dir$/) {
  261.       $opt{'-dir'}=1;
  262.       $! = 2, die qq/$0: expecting filename arg to -$arg\n/ unless @ARGV;
  263.       $start = shift(@ARGV);
  264.       $start =~ s#^~(/+|$)#$ENV{'HOME'}$1# if defined $ENV{'HOME'};
  265.       $! = 2, die qq/$0: can't find ${arg}'s "$start"\n/ unless -e $start;
  266.       $! = 2, die qq/$0: ${arg}'s "$start" not a directory.\n/ unless -d _;
  267.       undef(@todo), $opt{'-ddir'}=1 if $arg eq '-ddir';
  268.       push(@todo, $start);
  269.       next;
  270.       }
  271.  
  272.       if ($arg =~ m/^-(new|old)er$/i) {
  273.       $! = 2, die "$0: expecting filename arg to -$arg\n" unless @ARGV;
  274.       local($file, $time) = shift(@ARGV);
  275.       $! = 2, die qq/$0: can't stat -${arg}'s "$file"./
  276.           unless $time = (stat($file))[$STAT_MTIME];
  277.       local($upper) = $arg =~ tr/A-Z//;
  278.       if ($arg =~ m/new/i) {
  279.          $time++ unless $upper;
  280.          $NEWER = $time if $NEWER < $time;
  281.       } else {
  282.          $time-- unless $upper;
  283.          $OLDER = $time if $OLDER == 0 || $OLDER > $time;
  284.       }
  285.       next;
  286.       }
  287.  
  288.       if ($arg =~ m/-mtime/) {
  289.       $! = 2, die "$0: expecting numerical arg to -$arg\n" unless @ARGV;
  290.       local($days) = shift(@ARGV);
  291.       $! = 2, die qq/$0: inappropriate arg ($days) to $arg\n/ if $days==0;
  292.       $days *= 3600 * 24;
  293.       if ($days < 0) {
  294.           local($time) = $^T + $days;
  295.           $NEWER = $time if $NEWER < $time;
  296.       } else {
  297.           local($time) = $^T - $days;
  298.             $OLDER = $time if $OLDER == 0 || $OLDER > $time;
  299.       }
  300.       next;
  301.       }
  302.  
  303.       ## special user options
  304.       if ($arg =~ m/^-x(.+)/) {
  305.       foreach (split(/[\s,]+/, $1)) {  $user_opt{$_} = $opt{$_}= 1;  }
  306.       next;
  307.       }
  308.  
  309.       $! = 2, die "$0: unknown arg [$arg]\n";
  310.   }
  311. }
  312.  
  313. ##
  314. ## Given a filename glob, return a regex.
  315. ## If the glob has no globbing chars (no * ? or [..]), then
  316. ## prepend an effective '*' to it.
  317. ##
  318. sub glob_to_regex
  319. {
  320.     local($glob) = @_;
  321.     local(@parts) = $glob =~ m/\\.|[*?]|\[]?[^]]*]|[^[\\*?]+/g;
  322.     local($trueglob)=0;
  323.     foreach (@parts) {
  324.     if ($_ eq '*' || $_ eq '?') {
  325.         $_ = ".$_";
  326.         $trueglob=1;  ## * and ? are a real glob
  327.     } elsif (substr($_, 0, 1) eq '[') {
  328.         $trueglob=1;  ## [..] is a real glob
  329.     } else {
  330.         s/^\\//;     ## remove any leading backslash;
  331.         s/\W/\\$&/g; ## now quote anything dangerous;
  332.     }
  333.     }
  334.     unshift(@parts, '.*') unless $trueglob;
  335.     join('', '^', @parts, '$');
  336. }
  337.  
  338. sub prepare_to_search
  339. {
  340.   local($rc_file) = @_;
  341.  
  342.   $HEADER_BYTES=0;          ## Might be set nonzero in &read_rc;
  343.   $last_message_length = 0; ## For &message and &clear_message.
  344.  
  345.   &read_rc($rc_file, $showrc) unless $norc;
  346.   exit(0) if $showrc;
  347.  
  348.   $NEXT_DIR_ENTRY = $DO_SORT ? 'shift @files' : 'readdir(DIR)';
  349.   $WHY = 1 if $VERBOSE > 3; ## Arg -vvvv or above implies  -why.
  350.   @todo = ('.') if @todo == 0; ## Where we'll start looking
  351.  
  352.   ## see if any user options were specified that weren't accounted for
  353.   foreach $opt (keys %user_opt) {
  354.       next if defined $seen_opt{$opt};
  355.       warn "warning: -x$opt never considered.\n";
  356.   }
  357.  
  358.   die "$0: multiple time constraints exclude all possible files.\n"
  359.       if ($NEWER && $OLDER) && ($NEWER > $OLDER);
  360.  
  361.   ##
  362.   ## Process any -skip/-iskip args that had been given
  363.   ##
  364.   local(@skip_test);
  365.   foreach $glob (keys %skip) {
  366.       $i = defined($iskip{$glob}) ? 'i': '';
  367.       push(@skip_test, '$name =~ m/'. &glob_to_regex($glob). "/$i");
  368.   }
  369.   if (@skip_test) {
  370.       $SKIP_TEST = join('||',@skip_test);
  371.       $DO_SKIP_TEST = 1;
  372.   } else {
  373.       $DO_SKIP_TEST = $SKIP_TEST = 0;
  374.   }
  375.  
  376.   ##
  377.   ## Process any -dskip/-idskip args that had been given
  378.   ##
  379.   local(@dskip_test);
  380.   foreach $glob (keys %dskip) {
  381.       $i = defined($idskip{$glob}) ? 'i': '';
  382.       push(@dskip_test, '$name =~ m/'. &glob_to_regex($glob). "/$i");
  383.   }
  384.   if (@dskip_test) {
  385.       $DSKIP_TEST = join('||',@dskip_test);
  386.       $DO_DSKIP_TEST = 1;
  387.   } else {
  388.       $DO_DSKIP_TEST = $DSKIP_TEST = 0;
  389.   }
  390.  
  391.  
  392.   ##
  393.   ## Process any -name, -path, -regex, etc. args that had been given.
  394.   ##
  395.   undef @name_test;
  396.   undef @dname_test;
  397.   foreach $key (keys %name) {
  398.       local($type, $pat) = split(/,/, $key, 2);
  399.       local($i) = defined($iname{$key}) ? 'i' : '';
  400.       if ($type =~ /regex/) {
  401.       $pat =~ s/!/\\!/g;
  402.       $test = "\$name =~ m!^$pat\$!$i";
  403.       } else {
  404.       local($var) = $type eq 'name' ? '$name' : '$file';
  405.       $test = "$var =~ m/". &glob_to_regex($pat). "/$i";
  406.       }
  407.       if ($type =~ m/^-i?d/) {
  408.       push(@dname_test, $test);
  409.       } else {
  410.       push(@name_test, $test);
  411.       }
  412.   }
  413.   if (@name_test) {
  414.       $GLOB_TESTS = join('||', @name_test);
  415.  
  416.       $DO_GLOB_TESTS = 1;
  417.   } else {
  418.       $GLOB_TESTS = $DO_GLOB_TESTS = 0;
  419.   }
  420.   if (@dname_test) {
  421.       $DGLOB_TESTS = join('||', @dname_test);
  422.       $DO_DGLOB_TESTS = 1;
  423.   } else {
  424.       $DGLOB_TESTS = $DO_DGLOB_TESTS = 0;
  425.   }
  426.  
  427.  
  428.   ##
  429.   ## Process any 'magic' things from the startup file.
  430.   ##
  431.   if (@magic_tests && $HEADER_BYTES) {
  432.       ## the $magic' one is for when &dodir is not inlined
  433.       $tests = join('||',@magic_tests);
  434.       $MAGIC_TESTS = " { package magic; \$val = ($tests) }";
  435.       $DO_MAGIC_TESTS = 1;
  436.   } else {
  437.       $MAGIC_TESTS = 1;
  438.       $DO_MAGIC_TESTS = 0;
  439.   }
  440.  
  441.   ##
  442.   ## Prepare regular expressions.
  443.   ##
  444.   {
  445.       local(@regex_tests);
  446.  
  447.       if ($LIST_ONLY) {
  448.      $mflag = '';
  449.      ## need to have $* set, but perl5 just won''t shut up about it.
  450.      if ($] >= 5) {
  451.           $mflag = 'm';
  452.      } else {
  453.           eval ' $* = 1 ';
  454.      }
  455.       }
  456.  
  457.       ##
  458.       ## Until I figure out a better way to deal with it,
  459.       ## We have to worry about a regex like [^xyz] when doing $LIST_ONLY.
  460.       ## Such a regex *will* match \n, and if I'm pulling in multiple
  461.       ## lines, it can allow lines to match that would otherwise not match.
  462.       ##
  463.       ## Therefore, if there is a '[^' in a regex, we can NOT take a chance
  464.       ## an use the fast listonly.
  465.       ##
  466.       $CAN_USE_FAST_LISTONLY = $LIST_ONLY;
  467.  
  468.       local(@extra);
  469.       local($underline_glue) = ($] >= 5) ? '(:?_\cH)?' : '(_\cH)?';
  470.       while (@ARGV) {
  471.           $regex = shift(@ARGV);
  472.       ##
  473.       ## If watching for underlined things too, add another regex.
  474.       ##
  475.       if ($underlineOK) {
  476.          if ($regex =~ m/[?*+{}()\\.|^\$[]/) {
  477.         warn "$0: warning, can't underline-safe ``$regex''.\n";
  478.          } else {
  479.         $regex = join($underline_glue, split(//, $regex));
  480.          }
  481.       }
  482.  
  483.       ## If nothing special in the regex, just use index...
  484.       ## is quite a bit faster.
  485.       if (($iflag eq '') && ($words == 0) &&
  486.             $regex !~ m/[?*+{}()\\.|^\$[]/)
  487.       {
  488.           push(@regex_tests, "(index(\$_, q+$regex+)>=0)");
  489.  
  490.       } else {
  491.           $regex =~ s#[\$\@\/]\w#\\$&#;
  492.           if ($words) {
  493.           if ($regex =~ m/\|/) {
  494.               ## could be dangerous -- see if we can wrap in parens.
  495.               if ($regex =~ m/\\\d/) {
  496.               warn "warning: -w and a | in a regex is dangerous.\n"
  497.               } else {
  498.               $regex = join($regex, '(', ')');
  499.               }
  500.           }
  501.           $regex = join($regex, '\b', '\b');
  502.           }
  503.           $CAN_USE_FAST_LISTONLY = 0 if substr($regex, "[^") >= 0;
  504.           push(@regex_tests, "m/$regex/$iflag$mflag");
  505.       }
  506.  
  507.       ## If we're done, but still have @extra to do, get set for that.
  508.       if (@ARGV == 0 && @extra) {
  509.           @ARGV = @extra;   ## now deal with the extra stuff.
  510.           $underlineOK = 0; ## but no more of this.
  511.           undef @extra;     ## or this.
  512.       }
  513.       }
  514.       if (@regex_tests) {
  515.       $REGEX_TEST = join('||', @regex_tests);
  516.       ## print STDERR $REGEX_TEST, "\n"; exit;
  517.       } else {
  518.       ## must be doing -find -- just give something syntactically correct.
  519.       $REGEX_TEST = 1;
  520.       }
  521.   }
  522.  
  523.   ##
  524.   ## Make sure we can read the first item(s).
  525.   ##
  526.   foreach $start (@todo) {
  527.       $! = 2, die qq/$0: can't stat "$start"\n/
  528.       unless ($dev,$inode) = (stat($start))[$STAT_DEV,$STAT_INODE];
  529.  
  530.       if (defined $dir_done{"$dev,$inode"}) {
  531.       ## ignore the repeat.
  532.       warn(qq/ignoring "$start" (same as "$dir_done{"$dev,$inode"}").\n/)
  533.         if $VERBOSE;
  534.       next;
  535.       }
  536.  
  537.       ## if -xdev was given, remember the device.
  538.       $xdev{$dev} = 1 if $XDEV;
  539.  
  540.       ## Note that we won't want to do it again
  541.       $dir_done{"$dev,$inode"} = $start;
  542.   }
  543. }
  544.  
  545.  
  546. ##
  547. ## See the comment above the __END__ above the 'sub dodir' below.
  548. ##
  549. sub import_program
  550. {
  551.     sub bad {
  552.     print STDERR "$0: internal error (@_)\n";
  553.     exit 2;
  554.     }
  555.  
  556.     ## Read from data, up to next __END__. This will be &dodir.
  557.     local($/) = "\n__END__";
  558.     $prog = <DATA>;
  559.     close(DATA);
  560.  
  561.     $prog =~ s/\beval\b//g;       ## remove any 'eval'
  562.  
  563.     ## Inline uppercase $-variables by their current values.
  564.     if ($] >= 5) {
  565.     $prog =~ s/\$([A-Z][A-Z0-9_]{2,}\b)/
  566.             &bad($1) if !defined ${$main::{$1}}; ${$main::{$1}};/eg;
  567.     } else {
  568.     $prog =~ s/\$([A-Z][A-Z0-9_]{2,}\b)/local(*VAR) = $_main{$1};
  569.             &bad($1) if !defined $VAR; $VAR;/eg;
  570.     }
  571.  
  572.     eval $prog;  ## now do it. This will define &dodir;
  573.     $!=2, die "$0 internal error: $@\n" if $@;
  574. }
  575.  
  576. ###########################################################################
  577.  
  578. ##
  579. ## Read the .search file:
  580. ##    Blank lines and lines that are only #-comments ignored.
  581. ##    Newlines may be escaped to create long lines
  582. ##    Other lines are directives.
  583. ##
  584. ##    A directive may begin with an optional tag in the form <...>
  585. ##    Things inside the <...> are evaluated as with:
  586. ##       <(this || that) && must>
  587. ##    will be true if
  588. ##       -xmust -xthis   or   -xmust -xthat
  589. ##    were specified on the command line (order doesn't matter, though)
  590. ##    A directive is not done if there is a tag and it's false.
  591. ##    Any characters but whitespace and &|()>,! may appear after an -x
  592. ##    (although "-xdev" is special).  -xmust,this is the same as -xmust -xthis.
  593. ##    Something like -x~ would make <~> true, and <!~> false.
  594. ##
  595. ##    Directives are in the form:
  596. ##      option: STRING
  597. ##    magic : NUMBYTES : EXPR
  598. ##
  599. ##    With option:
  600. ##      The STRING is parsed like a Bourne shell command line, and the
  601. ##      options are used as if given on the command line.
  602. ##      No comments are allowed on 'option' lines.
  603. ##    Examples:
  604. ##        # skip objects and libraries
  605. ##        option: -skip '.o .a'
  606. ##        # skip emacs *~ and *# files, unless -x~ given:
  607. ##        <!~> option: -skip '~ #'
  608. ##
  609. ##    With magic:
  610. ##    EXPR can be pretty much any perl (comments allowed!).
  611. ##      If it evaluates to true for any particular file, it is skipped.
  612. ##      The only info you'll have about a file is the variable $H, which
  613. ##      will have at least the first NUMBYTES of the file (less if the file
  614. ##      is shorter than that, of course, and maybe more). You'll also have
  615. ##      any variables you set in previous 'magic' lines.
  616. ##    Examples:
  617. ##        magic: 6 : ($x6 = substr($H, 0, 6)) eq 'GIF87a'
  618. ##        magic: 6 :  $x6                     eq 'GIF89a'
  619. ##
  620. ##          magic: 6 : (($x6 = substr($H, 0, 6)) eq 'GIF87a' ## old gif \
  621. ##                                 || $x6  eq 'GIF89a' ## new gif
  622. ##    (the above two sets are the same)
  623. ##        ## Check the first 32 bytes for "binarish" looking bytes.
  624. ##        ## Don't blindly dump on any high-bit set, as non-ASCII text
  625. ##        ## often has them set. \x80 and \xff seem to be special, though.
  626. ##        ## Require two in a row to not get things like perl's $^T.
  627. ##        ## This is known to get *.Z, *.gz, pkzip, *.elc and about any
  628. ##        ## executable you'll find.
  629. ##        magic: 32 : $H =~ m/[\x00-\x06\x10-\x1a\x1c-\x1f\x80\xff]{2}/
  630. ##
  631. sub read_rc
  632. {
  633.     local($file, $show) = @_;
  634.     local($line_num, $ln, $tag) = 0;
  635.     local($use_default, @default) = 0;
  636.  
  637.     { package magic; $ = 0; } ## turn off warnings for when we run EXPR's
  638.  
  639.     unless (open(RC, "$file")) {
  640.     $use_default=1;
  641.     $file = "<internal default startup file>";
  642.     ## no RC file -- use this default.
  643.     @default = split(/\n/,<<'--------INLINE_LITERAL_TEXT');
  644.             magic: 32 : $H =~ m/[\x00-\x06\x10-\x1a\x1c-\x1f\x80\xff]{2}/
  645.         option: -skip '.a .COM .elc .EXE .gz .o .pbm .xbm .dvi'
  646.         option: -iskip '.tarz .zip .z .lzh .jpg .jpeg .gif .uu'
  647.         <!~> option: -skip '~ #'
  648. --------INLINE_LITERAL_TEXT
  649.     }
  650.  
  651.     ##
  652.     ## Make an eval error pretty.
  653.     ##
  654.     sub clean_eval_error {
  655.     local($_) = @_;
  656.     s/ in file \(eval\) at line \d+,//g; ## perl4-style error
  657.     s/ at \(eval \d+\) line \d+,//g;     ## perl5-style error
  658.     $_ = $` if m/\n/;                    ## remove all but first line
  659.     "$_\n";
  660.     }
  661.  
  662.     print "reading RC file: $file\n" if $show;
  663.  
  664.     while (defined($_ = ($use_default ? shift(@default) : <RC>))) {
  665.     $ln = ++$line_num;                 ## note starting line num.
  666.         $_ .= <RC>, $line_num++ while s/\\\n?$/\n/;  ## allow continuations
  667.     next if /^\s*(#.*)?$/;          ## skip blank or comment-only lines.
  668.         $do = '';
  669.     
  670.     ## look for an initial <...> tag.
  671.     if (s/^\s*<([^>]*)>//) {
  672.         ## This simple s// will make the tag ready to eval.
  673.         ($tag = $msg = $1) =~
  674.         s/[^\s&|(!)]+/
  675.             $seen_opt{$&}=1;         ## note seen option
  676.             "defined(\$opt{q>$&>})"  ## (q>> is safe quoting here)
  677.         /eg;
  678.         
  679.         ## see if the tag is true or not, abort this line if not.
  680.         $dothis = (eval $tag);
  681.         $!=2, die "$file $ln <$msg>: $_".&clean_eval_error($@) if $@;
  682.  
  683.         if ($show) {
  684.             $msg =~ s/[^\s&|(!)]+/-x$&/;
  685.             $msg =~ s/\s*!\s*/ no /g;
  686.             $msg =~ s/\s*&&\s*/ and /g;
  687.             $msg =~ s/\s*\|\|\s*/ or /g;
  688.         $msg =~ s/^\s+//; $msg =~ s/\s+$//;
  689.         $do = $dothis ? "(doing because $msg)" :
  690.                 "(do if $msg)";
  691.         } elsif (!$dothis) {
  692.             next;
  693.         }
  694.     }
  695.  
  696.     if (m/^\s*option\s*:\s*/) {
  697.         next if $all && !$show; ## -all turns off these checks;
  698.         local($_) = $';
  699.             s/\n$//;
  700.         local($orig) = $_;
  701.         print " $do option: $_\n" if $show;
  702.         local($0) = "$0 ($file)"; ## for any error message.
  703.         local(@ARGV);
  704.         local($this);
  705.         ##
  706.         ## Parse $_ as a Bourne shell line -- fill @ARGV
  707.         ##
  708.         while (length) {
  709.         if (s/^\s+//) {
  710.             push(@ARGV, $this) if defined $this;
  711.             undef $this;
  712.             next;
  713.         }
  714.         $this = '' if !defined $this;
  715.         $this .= $1 while s/^'([^']*)'// ||
  716.                   s/^"([^"]*)"// ||
  717.                   s/^([^'"\s\\]+)//||
  718.                   s/^(\\[\D\d])//;
  719.         die "$file $ln: error parsing $orig at $_\n" if m/^\S/;
  720.         }
  721.         push(@ARGV, $this) if defined $this;
  722.         &check_args;
  723.         die qq/$file $ln: unused arg "@ARGV".\n/ if @ARGV;
  724.         next;
  725.     }
  726.  
  727.     if (m/^\s*magic\s*:\s*(\d+)\s*:\s*/) {
  728.         next if $all && !$show; ## -all turns off these checks;
  729.         local($bytes, $check) = ($1, $');
  730.  
  731.         if ($show) {
  732.         $check =~ s/\n?$/\n/;
  733.         print " $do contents: $check";
  734.         }
  735.         ## Check to make sure the thing at least compiles.
  736.         eval  "package magic; (\$H = '1'x \$main'bytes) && (\n$check\n)\n";
  737.         $! = 2, die "$file $ln: ".&clean_eval_error($@) if $@;
  738.  
  739.         $HEADER_BYTES = $bytes if $bytes > $HEADER_BYTES;
  740.         push(@magic_tests, "(\n$check\n)");
  741.         next;
  742.     }
  743.     $! = 2, die "$file $ln: unknown command\n";
  744.     }
  745.     close(RC);
  746. }
  747.  
  748. sub message
  749. {
  750.     if (!$STDERR_IS_TTY) {
  751.     print STDERR $_[0], "\n";
  752.     } else {
  753.     local($text) = @_;
  754.     $thislength = length($text);
  755.     if ($thislength >= $last_message_length) {
  756.         print STDERR $text, "\r";
  757.     } else {
  758.         print STDERR $text, ' 'x ($last_message_length-$thislength),"\r";
  759.     }    
  760.     $last_message_length = $thislength;
  761.     }
  762. }
  763.  
  764. sub clear_message
  765. {
  766.     print STDERR ' ' x $last_message_length, "\r" if $last_message_length;
  767.     $vv_print = $vv_size = $last_message_length = 0;
  768. }
  769.  
  770. ##
  771. ## Output a copy of this program with comments, extra whitespace, and
  772. ## the trailing man page removed. On an ultra slow machine, such a copy
  773. ## might load faster (but I can't tell any difference on my machine).
  774. ##
  775. sub strip {
  776.     seek(DATA, 0, 0) || die "$0: can't reset internal pointer.\n";
  777.     while(<DATA>) {
  778.       print, next if /INLINE_LITERAL_TEXT/.../INLINE_LITERAL_TEXT/;
  779.       ## must mention INLINE_LITERAL_TEXT on this line!
  780.       s/\#\#.*|^\s+|\s+$//; ## remove cruft
  781.       last if $_ eq '.00;';
  782.       next if ($_ eq '') || ($_ eq "'di'") || ($_ eq "'ig00'");
  783.       s/\$stripped=0;/\$stripped=1;/;
  784.       s/\s\s+/ /;  ## squish multiple whitespaces down to one.
  785.       print $_, "\n";
  786.     }
  787.     exit(0);
  788. }
  789.  
  790. ##
  791. ## Just to shut up -w. Never executed.
  792. ##
  793. sub dummy {
  794.  
  795.     1 || &dummy || &dir_done || &bad || &message || $NEXT_DIR_ENTRY ||
  796.     $DELAY || $VV_SIZE || $VV_PRINT_COUNT || $STDERR_SCREWS_STDOUT ||
  797.     @files || @files || $magic'H || $magic'H || $xdev{''} || &clear_message;
  798.  
  799. }
  800.  
  801. ##
  802. ## If the following __END__ is in place, what follows will be
  803. ## inlined when the program first starts up. Any $ variable name
  804. ## all in upper case, specifically, any string matching
  805. ##    \$([A-Z][A-Z0-9_]{2,}\b
  806. ## will have the true value for that variable inlined. Also, any 'eval' is
  807. ## removed
  808. ##
  809. ## The idea is that when the whole thing is then eval'ed to define &dodir,
  810. ## the perl optimizer will make all the decisions that are based upon
  811. ## command-line options (such as $VERBOSE), since they'll be inlined as
  812. ## constants
  813. ##
  814. ## Also, and here's the big win, the tests for matching the regex, and a
  815. ## few others, are all inlined. Should be blinding speed here.
  816. ##
  817. ## See the read from <DATA> above for where all this takes place.
  818. ## But all-in-all, you *want* the __END__ here. Comment it out only for
  819. ## debugging....
  820. ##
  821.  
  822. __END__
  823.  
  824. ##
  825. ## Given a directory, check all "appropriate" files in it.
  826. ## Shove any subdirectories into the global @todo, so they'll be done
  827. ## later.
  828. ##
  829. ## Be careful about adding any upper-case variables, as they are subject
  830. ## to being inlined. See comments above the __END__ above.
  831. ##
  832. sub dodir
  833. {
  834.   local($dir) = @_;
  835.   $dir =~ s,/+$,,; ## remove any trailing slash.
  836.   unless (opendir(DIR, "$dir/.")) {
  837.       &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  838.       warn qq($0: can't opendir "$dir/".\n);
  839.       return;
  840.   }
  841.  
  842.   if ($VERBOSE) {
  843.       &message($dir);
  844.       $vv_print = $vv_size = 0;
  845.   }
  846.  
  847.   @files = sort readdir(DIR) if $DO_SORT;
  848.  
  849.   while (defined($name = eval $NEXT_DIR_ENTRY))
  850.   {
  851.     next if $name eq '.' || $name eq '..'; ## never follow these.
  852.  
  853.     ## create full relative pathname.
  854.     $file = $dir eq '.' ? $name : "$dir/$name";
  855.  
  856.     ## if link and skipping them, do so.
  857.     if ($NOLINKS && -l $file) {
  858.     warn qq/skip (symlink): $file\n/ if $WHY;
  859.     next;
  860.     }
  861.  
  862.     ## skip things unless files or directories
  863.     unless (-f $file || -d _) {
  864.     if ($WHY) {
  865.         $why = (-S _ && "socket")       ||
  866.            (-p _ && "pipe")         ||
  867.            (-b _ && "block special")||
  868.            (-c _ && "char special") || "somekinda special";
  869.         warn qq/skip ($why): $file\n/;
  870.     }
  871.     next;
  872.     }
  873.  
  874.     ## skip things we can't read
  875.     unless (-r _) {
  876.     if ($WHY) {
  877.         $why = (-l $file) ? "follow" : "read";
  878.         warn qq/skip (can't $why): $file\n/;
  879.     }
  880.     next;
  881.     }
  882.  
  883.     ## skip things that are empty
  884.     unless (-s _ || -d _) {
  885.     warn qq/skip (empty): $file\n/ if $WHY;
  886.     next;
  887.     }
  888.  
  889.     ## Note file device & inode. If -xdev, skip if appropriate.
  890.     ($dev, $inode) = (stat(_))[$STAT_DEV, $STAT_INODE];
  891.     if ($XDEV && defined $xdev{$dev}) {
  892.     warn qq/skip (other device): $file\n/ if $WHY;
  893.     next;
  894.     }
  895.     $id = "$dev,$inode";
  896.  
  897.     ## special work for a directory
  898.     if (-d _) {
  899.     ## Do checks for directory file endings.
  900.     if ($DO_DSKIP_TEST && (eval $DSKIP_TEST)) {
  901.         warn qq/skip (-dskip): $file\n/ if $WHY;
  902.         next;
  903.     }
  904.     ## do checks for -name/-regex/-path tests
  905.     if ($DO_DGLOB_TESTS && !(eval $DGLOB_TESTS)) {
  906.         warn qq/skip (dirname): $file\n/ if $WHY;
  907.         next;
  908.     }
  909.  
  910.     ## _never_ redo a directory
  911.     if (defined $dir_done{$id} and $^O ne 'MSWin32') {
  912.         warn qq/skip (did as "$dir_done{$id}"): $file\n/ if $WHY;
  913.         next;
  914.     }
  915.     $dir_done{$id} = $file;     ## mark it done.
  916.     unshift(@todo, $file);        ## add to the list to do.
  917.     next;
  918.     }
  919.     if ($WHY == 0  && $VERBOSE > 1) {
  920.       if ($VERBOSE>2||$vv_print++>$VV_PRINT_COUNT||($vv_size+=-s _)>$VV_SIZE){
  921.       &message($file);
  922.       $vv_print = $vv_size = 0;
  923.       }
  924.     }
  925.  
  926.     ## do time-related tests
  927.     if ($NEWER || $OLDER) {
  928.     $_ = (stat(_))[$STAT_MTIME];
  929.     if ($NEWER && $_ < $NEWER) {
  930.         warn qq/skip (too old): $file\n/ if $WHY;
  931.         next;
  932.     }
  933.     if ($OLDER && $_ > $OLDER) {
  934.         warn qq/skip (too new): $file\n/ if $WHY;
  935.         next;
  936.     }
  937.     }
  938.  
  939.     ## do checks for file endings
  940.     if ($DO_SKIP_TEST && (eval $SKIP_TEST)) {
  941.     warn qq/skip (-skip): $file\n/ if $WHY;
  942.     next;
  943.     }
  944.  
  945.     ## do checks for -name/-regex/-path tests
  946.     if ($DO_GLOB_TESTS && !(eval $GLOB_TESTS)) {
  947.     warn qq/skip (filename): $file\n/ if $WHY;
  948.     next;
  949.     }
  950.  
  951.  
  952.     ## If we're not repeating files,
  953.     ##    skip this one if we've done it, or note we're doing it.
  954.     unless ($DOREP) {
  955.     if (defined $file_done{$id}) {
  956.         warn qq/skip (did as "$file_done{$id}"): $file\n/ if $WHY;
  957.         next;
  958.     }
  959.     $file_done{$id} = $file;
  960.     }
  961.  
  962.     if ($DO_MAGIC_TESTS) {
  963.     if (!open(FILE_IN, $file)) {
  964.         &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  965.         warn qq/$0: can't open: $file\n/;
  966.         next;
  967.     }
  968.     unless (read(FILE_IN, $magic'H, $HEADER_BYTES)) {
  969.         &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  970.         warn qq/$0: can't read from "$file"\n"/;
  971.         close(FILE_IN);
  972.         next;
  973.     }
  974.  
  975.     eval $MAGIC_TESTS;
  976.     if ($magic'val) {
  977.         close(FILE_IN);
  978.         warn qq/skip (magic): $file\n/ if $WHY;
  979.         next;
  980.     }
  981.     seek(FILE_IN, 0, 0);  ## reset for later <FILE_IN>
  982.     }
  983.  
  984.     if ($WHY != 0  && $VERBOSE > 1) {
  985.       if ($VERBOSE>2||$vv_print++>$VV_PRINT_COUNT||($vv_size+=-s _)>$VV_SIZE){
  986.       &message($file);
  987.       $vv_print = $vv_size = 0;
  988.       }
  989.     }
  990.  
  991.     if ($DELAY) {
  992.     sleep($DELAY);
  993.     }
  994.  
  995.     if ($FIND_ONLY) {
  996.     &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  997.     print $file, "\n";
  998.     $retval=0; ## we've found something
  999.     close(FILE_IN) if $DO_MAGIC_TESTS;
  1000.     next;
  1001.     } else {
  1002.     ## if we weren't doing magic tests, file won't be open yet...
  1003.     if (!$DO_MAGIC_TESTS && !open(FILE_IN, $file)) {
  1004.         &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  1005.         warn qq/$0: can't open: $file\n/;
  1006.         next;
  1007.     }
  1008.     if ($LIST_ONLY && $CAN_USE_FAST_LISTONLY) {
  1009.         ##
  1010.         ## This is rather complex, but buys us a LOT when we're just
  1011.         ## listing files and not the individual internal lines.
  1012.         ##
  1013.         local($size) = 4096;  ## block-size in which to do reads
  1014.         local($nl);           ## will point to $_'s ending newline.
  1015.         local($read);      ## will be how many bytes read.
  1016.         local($_) = '';       ## Starts out empty
  1017.         local($hold);      ## (see below)
  1018.  
  1019.         while (($read = read(FILE_IN,$_,$size,length($_)))||length($_))
  1020.         {
  1021.         undef @parts;
  1022.         ## if read a full block, but no newline, need to read more.
  1023.         while ($read == $size && ($nl = rindex($_, "\n")) < 0) {
  1024.             push(@parts, $_);                    ## save that part
  1025.             $read = read(FILE_IN, $_, $size); ## keep trying
  1026.         }
  1027.  
  1028.         ##
  1029.         ## If we had to save parts, must now combine them together.
  1030.         ## adjusting $nl to reflect the now-larger $_. This should
  1031.         ## be a lot more efficient than using any kind of .= in the
  1032.         ## loop above.
  1033.         ##
  1034.         if (@parts) {
  1035.             local($lastlen) = length($_); #only need if $nl >= 0
  1036.             $_ = join('', @parts, $_);
  1037.             $nl = length($_) - ($lastlen - $nl) if $nl >= 0;
  1038.         }
  1039.  
  1040.         ##
  1041.         ## If we're at the end of the file, then we can use $_ as
  1042.         ## is.  Otherwise, we need to remove the final partial-line
  1043.         ## and save it so that it'll be at the beginning of the
  1044.         ## next read (where the rest of the line will be layed in
  1045.         ## right after it).  $hold will be what we should save
  1046.         ## until next time.
  1047.         ##
  1048.         if ($read != $size || $nl < 0) {
  1049.             $hold = '';
  1050.         } else {
  1051.             $hold = substr($_, $nl + 1);
  1052.             substr($_, $nl + 1) = '';
  1053.         }
  1054.  
  1055.         ##
  1056.         ## Now have a bunch of full lines in $_. Use it.
  1057.         ##
  1058.         if (eval $REGEX_TEST) {
  1059.             &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  1060.             print $file, "\n";
  1061.             $retval=0; ## we've found something
  1062.  
  1063.             last;
  1064.         }
  1065.  
  1066.         ## Prepare for next read....
  1067.         $_ = $hold;
  1068.         }
  1069.  
  1070.     } else {  ## else not using faster block scanning.....
  1071.  
  1072.             $lines_printed = 0 if $NICE;
  1073.         while (<FILE_IN>) {
  1074.         study;
  1075.         next unless (eval $REGEX_TEST);
  1076.  
  1077.         ##
  1078.         ## We found a matching line.
  1079.         ##
  1080.         $retval=0;
  1081.         &clear_message if $VERBOSE && $STDERR_SCREWS_STDOUT;
  1082.         if ($LIST_ONLY) {
  1083.             print $file, "\n";
  1084.             last;
  1085.         } else {
  1086.             ## prepare to print line.
  1087.             if ($NICE && $lines_printed++ == 0) {
  1088.             print '-' x 70, "\n" if $NICE > 1;
  1089.             print $file, ":\n";
  1090.             }
  1091.  
  1092.             ##
  1093.             ## Print all the prelim stuff. This looks less efficient
  1094.             ## than it needs to be, but that's so that when the eval
  1095.             ## is compiled (and the tests are optimized away), the
  1096.             ## result will be less actual PRINTs than the more natural
  1097.             ## way of doing these tests....
  1098.             ##
  1099.             if ($NICE) {
  1100.             if ($REPORT_LINENUM) {
  1101.                 print " line $.:  ";
  1102.             } else {
  1103.                 print "  ";
  1104.             }
  1105.             } elsif ($REPORT_LINENUM && $PREPEND_FILENAME) {
  1106.             print "$file,:$.: ";
  1107.             } elsif ($PREPEND_FILENAME) {
  1108.             print "$file: ";
  1109.             } elsif ($REPORT_LINENUM) {
  1110.             print "$.: ";
  1111.             }
  1112.             print $_;
  1113.             print "\n" unless m/\n$/;
  1114.         }
  1115.         }
  1116.         print "\n" if ($NICE > 1) && $lines_printed;
  1117.     }
  1118.     close(FILE_IN);
  1119.     }
  1120.   }
  1121.   closedir(DIR);
  1122. }
  1123.  
  1124. __END__
  1125. .00;            ## finish .ig
  1126.  
  1127. 'di            \" finish diversion--previous line must be blank
  1128. .nr nl 0-1        \" fake up transition to first page again
  1129. .nr % 0            \" start at page 1
  1130. .\"__________________NORMAL_MAN_PAGE_BELOW_________________
  1131. .ll+10n
  1132. .TH search 1 "Dec 17, 1994"
  1133. .SH SEARCH
  1134. search \- search files (a'la grep) in a whole directory tree.
  1135. .SH SYNOPSIS
  1136. search [ grep-like and find-like options] [regex ....]
  1137. .SH DESCRIPTION
  1138. .I Search
  1139. is more or less a combo of 'find' and 'grep' (although the regular
  1140. expression flavor is that of the perl being used, which is closer to
  1141. egrep's than grep's).
  1142.  
  1143. .I Search
  1144. does generally the same kind of thing that
  1145. .nf
  1146.    find <blah blah> | xargs egrep <blah blah>
  1147. .fi
  1148. does, but is
  1149. .I much
  1150. more powerful and efficient (and intuitive, I think).
  1151.  
  1152. This manual describes
  1153. .I search
  1154. as of version "941227.4". You can always find the latest version at
  1155. .nf
  1156.    http://www.wg.omron.co.jp/~jfriedl/perl/index.html
  1157. .fi
  1158.  
  1159. .SH "QUICK EXAMPLE"
  1160. Basic use is simple:
  1161. .nf
  1162.     % search jeff
  1163. .fi
  1164. will search files in the current directory, and all sub directories, for
  1165. files that have "jeff" in them. The lines will be listed with the
  1166. containing file's name prepended.
  1167. .PP
  1168. If you list more than one regex, such as with
  1169. .nf
  1170.     % search jeff Larry Randal+ 'Stoc?k' 'C.*son'
  1171. .fi
  1172. then a line containing any of the regexes will be listed.
  1173. This makes it effectively the same as
  1174. .nf
  1175.     % search 'jeff|Larry|Randal+|Stoc?k|C.*son'
  1176. .fi
  1177. However, listing them separately is much more efficient (and is easier
  1178. to type).
  1179. .PP
  1180. Note that in the case of these examples, the
  1181. .B \-w
  1182. (list whole-words only) option would be useful.
  1183. .PP
  1184. Normally, various kinds of files are automatically removed from consideration.
  1185. If it has has a certain ending (such as ".tar", ".Z", ".o", .etc), or if
  1186. the beginning of the file looks like a binary, it'll be excluded.
  1187. You can control exactly how this works -- see below. One quick way to
  1188. override this is to use the
  1189. .B \-all
  1190. option, which means to consider all the files that would normally be
  1191. automatically excluded.
  1192. Or, if you're curious, you can use
  1193. .B \-why
  1194. to have notes about what files are skipped (and why) printed to stderr.
  1195.  
  1196. .SH "BASIC OVERVIEW"
  1197. Normally, the search starts in the current directory, considering files in
  1198. all subdirectories.
  1199.  
  1200. You can use the
  1201. .I ~/.search
  1202. file to control ways to automatically exclude files.
  1203. If you don't have this file, a default one will kick in, which automatically
  1204. add
  1205. .nf
  1206.     -skip .o .Z .gif
  1207. .fi
  1208. (among others) to exclude those kinds of files (which you probably want to
  1209. skip when searching for text, as is normal).
  1210. Files that look to be be binary will also be excluded.
  1211.  
  1212. Files ending with "#" and "~" will also be excluded unless the
  1213. .B -x~
  1214. option is given. 
  1215.  
  1216. You can use
  1217. .B -showrc
  1218. to show what kinds of files will normally be skipped.
  1219. See the section on the startup file
  1220. for more info.
  1221.  
  1222. You can use the
  1223. .B -all
  1224. option to indicate you want to consider all files that would otherwise be
  1225. skipped by the startup file.
  1226.  
  1227. Based upon various other flags (see "WHICH FILES TO CONSIDER" below),
  1228. more files might be removed from consideration. For example
  1229. .nf
  1230.     -mtime 3
  1231. .fi
  1232. will exclude files that aren't at least three days old (change the 3 to -3
  1233. to exclude files that are more than three days old), while
  1234. .nf
  1235.     -skip .*
  1236. .fi
  1237. would exclude any file beginning with a dot (of course, '.' and '..'  are
  1238. special and always excluded).
  1239.  
  1240. If you'd like to see what files are being excluded, and why, you can get the
  1241. list via the
  1242. .B \-why
  1243. option.
  1244.  
  1245. If a file makes it past all the checks, it is then "considered".
  1246. This usually means it is greped for the regular expressions you gave
  1247. on the command line.
  1248.  
  1249. If any of the regexes match a line, the line is printed.
  1250. However, if
  1251. .B -list
  1252. is given, just the filename is printed. Or, if
  1253. .B -nice
  1254. is given, a somewhat more (human-)readable output is generated.
  1255.  
  1256. If you're searching a huge tree and want to keep informed about how
  1257. the search is progressing,
  1258. .B -v
  1259. will print (to stderr) the current directory being searched.
  1260. Using
  1261. .B -vv
  1262. will also print the current file "every so often", which could be useful
  1263. if a directory is huge. Using
  1264. .B -vvv
  1265. will print the update with every file.
  1266.  
  1267. Below is the full listing of options.
  1268.  
  1269. .SH "OPTIONS TELLING *WHERE* TO SEARCH"
  1270. .TP
  1271. .BI -dir " DIR"
  1272. Start searching at the named directory instead of the current directory.
  1273. If multiple
  1274. .B -dir
  1275. arguments are given, multiple trees will be searched.
  1276. .TP
  1277. .BI -ddir " DIR"
  1278. Like
  1279. .B -dir
  1280. except it flushes any previous
  1281. .B -dir
  1282. directories (i.e. "-dir A -dir B -dir C" will search A, B, and C, while
  1283. "-dir A -ddir B -dir C" will search only B and C. This might be of use
  1284. in the startup file (see that section below).
  1285. .TP
  1286. .B -xdev
  1287. Stay on the same filesystem as the starting directory/directories.
  1288. .TP
  1289. .B -sort
  1290. Sort the items in a directory before processing them.
  1291. Normally they are processed in whatever order they happen to be read from
  1292. the directory.
  1293. .TP
  1294. .B -nolinks
  1295. Don't follow symbolic links. Normally they're followed.
  1296.  
  1297. .SH "OPTIONS CONTROLLING WHICH FILES TO CONSIDER AND EXCLUDE"
  1298. .TP
  1299. .BI -mtime " NUM"
  1300. Only consider files that were last changed more than
  1301. .I NUM
  1302. days ago
  1303. (less than
  1304. .I NUM
  1305. days if
  1306. .I NUM
  1307. has '-' prepended, i.e. "-mtime -2.5" means to consider files that
  1308. have been changed in the last two and a half days).
  1309. .TP
  1310. .B -older FILE
  1311. Only consider files that have not changed since
  1312. .I FILE
  1313. was last changed.
  1314. If there is any upper case in the "-older", "or equal" is added to the sense
  1315. of the test.  Therefore, "search -older ./file regex" will never consider
  1316. "./file", while "search -Older ./file regex" will.
  1317.  
  1318. If a file is a symbolic link, the time used is that of the file and not the
  1319. link.
  1320. .TP
  1321. .BI -newer " FILE"
  1322. Opposite of
  1323. .BR -older .
  1324. .TP
  1325. .BI -name " GLOB"
  1326. Only consider files that match the shell filename pattern
  1327. .IR GLOB .
  1328. The check is only done on a file's name (use
  1329. .B -path
  1330. to check the whole path, and use
  1331. .B -dname
  1332. to check directory names).
  1333.  
  1334. Multiple specifications can be given by separating them with spaces, a'la
  1335. .nf
  1336.     -name '*.c *.h'
  1337. .fi
  1338. to consider C source and header files.
  1339. If
  1340. .I GLOB
  1341. doesn't contain any special pattern characters, a '*' is prepended.
  1342. This last example could have been given as
  1343. .nf
  1344.    -name '.c .h'
  1345. .fi
  1346. It could also be given as
  1347. .nf
  1348.     -name .c -name .h
  1349. .fi
  1350. or
  1351. .nf
  1352.     -name '*.c' -name '*.h'
  1353. .fi
  1354. or
  1355. .nf
  1356.     -name '*.[ch]'
  1357. .fi
  1358. (among others)
  1359. but in this last case, you have to be sure to supply the leading '*'.
  1360. .TP
  1361. .BI -path " GLOB"
  1362. Like
  1363. .B -name
  1364. except the entire path is checked against the pattern.
  1365. .TP
  1366. .B -regex " REGEX"
  1367. Considers files whose names (not paths) match the given perl regex
  1368. exactly.
  1369. .TP
  1370. .BI -iname " GLOB"
  1371. Case-insensitive version of
  1372. .BR -name .
  1373. .TP
  1374. .BI -ipath " GLOB"
  1375. Case-insensitive version of
  1376. .BR -path .
  1377. .TP
  1378. .BI -iregex " REGEX"
  1379. Case-insensitive version of
  1380. .BR -regex .
  1381.  
  1382. .TP
  1383. .BI -dpath " GLOB"
  1384. Only search down directories whose path matches the given pattern (this
  1385. doesn't apply to the initial directory given by
  1386. .BI -dir ,
  1387. of course).
  1388. Something like
  1389. .nf
  1390.     -dir /usr/man -dpath /usr/man/man*
  1391. .fi
  1392. would completely skip
  1393. "/usr/man/cat1", "/usr/man/cat2", etc.
  1394. .TP
  1395. .BI -dskip " GLOB"
  1396. Skips directories whose name (not path) matches the given pattern.
  1397. Something like
  1398. .nf
  1399.     -dir /usr/man -dskip cat*
  1400. .fi
  1401. would completely skip any directory in the tree whose name begins with "cat"
  1402. (including "/usr/man/cat1", "/usr/man/cat2", etc.).
  1403. .TP
  1404. .BI -dregex " REGEX"
  1405. Like
  1406. .BI -dpath ,
  1407. but the pattern is a full perl regex. Note that this quite different
  1408. from
  1409. .B -regex
  1410. which considers only file names (not paths). This option considers
  1411. full directory paths (not just names). It's much more useful this way.
  1412. Sorry if it's confusing.
  1413. .TP
  1414. .BI -dpath " GLOB"
  1415. This option exists, but is probably not very useful. It probably wants to
  1416. be like the '-below' or something I mention in the "TODO" section.
  1417. .TP
  1418. .BI -idpath " GLOB"
  1419. Case-insensitive version of
  1420. .BR -dpath .
  1421. .TP
  1422. .BI -idskip " GLOB"
  1423. Case-insensitive version of
  1424. .BR -dskip .
  1425. .TP
  1426. .BI -idregex " REGEX"
  1427. Case-insensitive version of
  1428. .BR -dregex .
  1429. .TP
  1430. .B -all
  1431. Ignore any 'magic' or 'option' lines in the startup file.
  1432. The effect is that all files that would otherwise be automatically
  1433. excluded are considered.
  1434. .TP
  1435. .BI -x SPECIAL
  1436. Arguments starting with
  1437. .B -x
  1438. (except
  1439. .BR -xdev ,
  1440. explained elsewhere) do special interaction with the
  1441. .I ~/.search
  1442. startup file. Something like
  1443. .nf
  1444.     -xflag1 -xflag2
  1445. .fi
  1446. will turn on "flag1" and "flag2" in the startup file (and is
  1447. the same as "-xflag1,flag2"). You can use this to write your own
  1448. rules for what kinds of files are to be considered.
  1449.  
  1450. For example, the internal-default startup file contains the line
  1451. .nf
  1452.     <!~> option: -skip '~ #'
  1453. .fi
  1454. This means that if the
  1455. .B -x~
  1456. flag is
  1457. .I not
  1458. seen, the option
  1459. .nf
  1460.     -skip '~ #'
  1461. .fi
  1462. should be done.
  1463. The effect is that emacs temp and backup files are not normally
  1464. considered, but you can included them with the -x~ flag.
  1465.  
  1466. You can write your own rules to customize
  1467. .I search
  1468. in powerful ways. See the STARTUP FILE section below.
  1469. .TP
  1470. .B -why
  1471. Print a message (to stderr) when and why a file is not considered.
  1472.  
  1473. .SH "OPTIONS TELLING WHAT TO DO WITH FILES THAT WILL BE CONSIDERED"
  1474. .TP
  1475. .B -find
  1476. (you can use
  1477. .B -f
  1478. as well).
  1479. This option changes the basic action of
  1480. .IR search .
  1481.  
  1482. Normally, if a file is considered, it is searched
  1483. for the regular expressions as described earlier. However, if this option
  1484. is given, the filename is printed and no searching takes place. This turns
  1485. .I search
  1486. into a 'find' of some sorts.
  1487.  
  1488. In this case, no regular expressions are needed on the command line
  1489. (any that are there are silently ignored).
  1490.  
  1491. This is not intended to be a replacement for the 'find' program,
  1492. but to aid
  1493. you in understanding just what files are getting past the exclusion checks.
  1494. If you really want to use it as a sort of replacement for the 'find' program,
  1495. you might want to use
  1496. .B -all
  1497. so that it doesn't waste time checking to see if the file is binary, etc
  1498. (unless you really want that, of course).
  1499.  
  1500. If you use
  1501. .BR -find ,
  1502. none of the "GREP-LIKE OPTIONS" (below) matter.
  1503.  
  1504. As a replacement for 'find',
  1505. .I search
  1506. is probably a bit slower (or in the case of GNU find, a lot slower --
  1507. GNU find is
  1508. .I unbelievably
  1509. fast).
  1510. However, "search -ffind"
  1511. might be more useful than 'find' when options such as
  1512. .B -skip
  1513. are used (at least until 'find' gets such functionality).
  1514. .TP
  1515. .B -ffind
  1516. (or
  1517. .BR -ff )
  1518. A faster more 'find'-like find. Does
  1519. .nf
  1520.     -find  -all -dorep
  1521. .fi
  1522. .SH "GREP-LIKE OPTIONS"
  1523. These options control how a searched file is accessed,
  1524. and how things are printed.
  1525. .TP
  1526. .B -i
  1527. Ignore letter case when matching.
  1528. .TP
  1529. .B -w
  1530. Consider only whole-word matches ("whole word" as defined by perl's "\\b"
  1531. regex).
  1532. .TP
  1533. .B -u
  1534. If the regex(es) is/are simple, try to modify them so that they'll work
  1535. in manpage-like underlined text (i.e. like _^Ht_^Hh_^Hi_^Hs).
  1536. This is very rudimentary at the moment.
  1537. .TP
  1538. .B -list
  1539. (you can use
  1540. .B -l
  1541. too).
  1542. Don't print matching lines, but the names of files that contain matching
  1543. lines. This will likely be *much* faster, as special optimizations are
  1544. made -- particularly with large files.
  1545. .TP
  1546. .B -n
  1547. Pepfix each line by its line number.
  1548. .TP
  1549. .B -nice
  1550. Not a grep-like option, but similar to
  1551. .BR -list ,
  1552. so included here.
  1553. .B -nice
  1554. will have the output be a bit more human-readable, with matching lines printed
  1555. slightly indented after the filename, a'la
  1556. .nf
  1557.  
  1558.    % search foo
  1559.    somedir/somefile: line with foo in it
  1560.    somedir/somefile: some food for thought
  1561.    anotherdir/x: don't be a buffoon!
  1562.    %
  1563.  
  1564. .fi
  1565. will become
  1566. .nf
  1567.  
  1568.    % search -nice foo
  1569.    somedir/somefile:
  1570.      line with foo in it
  1571.      some food for thought
  1572.    anotherdir/x:
  1573.      don't be a buffoon!
  1574.    %
  1575.  
  1576. .fi
  1577. This option due to Lionel Cons.
  1578. .TP
  1579. .B -nnice
  1580. Be a bit nicer than
  1581. .BR -nice .
  1582. Prefix each file's output by a rule line, and follow with an extra blank line.
  1583. .TP
  1584. .B -h
  1585. Don't prepend each output line with the name of the file
  1586. (meaningless when
  1587. .B -find
  1588. or
  1589. .B -l
  1590. are given).
  1591.  
  1592. .SH "OTHER OPTIONS"
  1593. .TP
  1594. .B -help
  1595. Print the usage information.
  1596. .TP
  1597. .B -version
  1598. Print the version information and quit.
  1599. .TP
  1600. .B -v
  1601. Set the level of message verbosity.
  1602. .B -v
  1603. will print a note whenever a new directory is entered.
  1604. .B -vv
  1605. will also print a note "every so often". This can be useful to see
  1606. what's happening when searching huge directories.
  1607. .B -vvv
  1608. will print a new with every file.
  1609. .B -vvvv
  1610. is
  1611. -vvv
  1612. plus
  1613. .BR -why .
  1614. .TP
  1615. .B -e
  1616. This ends the options, and can be useful if the regex begins with '-'.
  1617. .TP
  1618. .B -showrc
  1619. Shows what is being considered in the startup file, then exits.
  1620. .TP
  1621. .B -dorep
  1622. Normally, an identical file won't be checked twice (even with multiple
  1623. hard or symbolic links). If you're just trying to do a fast
  1624. .BR -find ,
  1625. the bookkeeping to remember which files have been seen is not desirable,
  1626. so you can eliminate the bookkeeping with this flag.
  1627.  
  1628. .SH "STARTUP FILE"
  1629. When
  1630. .I search
  1631. starts up, it processes the directives in
  1632. .IR ~/.search .
  1633. If no such file exists, a default
  1634. internal version is used.
  1635.  
  1636. The internal version looks like:
  1637. .nf
  1638.  
  1639.    magic: 32 : $H =~ m/[\ex00-\ex06\ex10-\ex1a\ex1c-\ex1f\ex80\exff]{2}/
  1640.    option: -skip '.a .COM .elc .EXE .gz .o .pbm .xbm .dvi'
  1641.    option: -iskip '.tarz .zip .z .lzh .jpg .jpeg .gif .uu'
  1642.    <!~> option: -skip '~ #'
  1643.  
  1644. .fi
  1645. If you wish to create your own "~/.search",
  1646. you might consider copying the above, and then working from there.
  1647.  
  1648. There are two kinds of directives in a startup file: "magic" and "option".
  1649. .RS 0n
  1650. .TP
  1651. OPTION
  1652. Option lines will automatically do the command-line options given.
  1653. For example, the line
  1654. .nf
  1655.     option: -v
  1656. .fi
  1657. in you startup file will turn on -v every time, without needing to type it
  1658. on the command line.
  1659.  
  1660. The text on the line after the "option:" directive is processed
  1661. like the Bourne shell, so make sure to pay attention to quoting.
  1662. .nf
  1663.     option: -skip .exe .com
  1664. .fi
  1665. will give an error (".com" by itself isn't a valid option), while
  1666. .nf
  1667.     option: -skip ".exe .com"
  1668. .fi
  1669. will properly include it as part of -skip's argument.
  1670.  
  1671. .TP
  1672. MAGIC
  1673. Magic lines are used to determine if a file should be considered a binary
  1674. or not (the term "magic" refers to checking a file's magic number).  These
  1675. are described in more detail below.
  1676. .RE
  1677.  
  1678. Blank lines and comments (lines beginning with '#') are allowed.
  1679.  
  1680. If a line begins with  <...>, then it's a check to see if the
  1681. directive on the line should be done or not. The stuff inside the <...>
  1682. can contain perl's && (and), || (or), ! (not), and parens for grouping,
  1683. along with "flags" that might be indicated by the user with
  1684. .BI -x flag
  1685. options.
  1686.  
  1687. For example, using "-xfoo" will cause "foo" to be true inside the <...>
  1688. blocks. Therefore, a line beginning with "<foo>" would be done only when
  1689. "-xfoo" had been specified, while a line beginning with "<!foo>" would be
  1690. done only when "-xfoo" is not specified (of course, a line without any <...>
  1691. is done in either case).
  1692.  
  1693. A realistic example might be
  1694. .nf
  1695.     <!v> -vv
  1696. .fi
  1697. This will cause -vv messages to be the default, but allow "-xv" to override.
  1698.  
  1699. There are a few flags that are set automatically:
  1700. .RS
  1701. .TP
  1702. .B TTY
  1703. true if the output is to the screen (as opposed to being redirected to a file).
  1704. You can force this (as with all the other automatic flags) with -xTTY.
  1705. .TP
  1706. .B -v
  1707. True if -v was specified. If -vv was specified, both 
  1708. .B -v
  1709. and
  1710. .B -vv
  1711. flags are true (and so on).
  1712. .TP
  1713. .B -nice
  1714. True if -nice was specified. Same thing about -nnice as for -vv.
  1715. .PP
  1716. .TP
  1717. .B -list
  1718. true if -list (or -l) was given.
  1719. .TP
  1720. .B -dir
  1721. true if -dir was given.
  1722. .RE
  1723.  
  1724. Using this info, you might change the last example to
  1725. .nf
  1726.  
  1727.     <!v && !-v> option: -vv
  1728.  
  1729. .fi
  1730. The added "&& !-v" means "and if the '-v' option not given".
  1731. This will allow you to use "-v" alone on the command line, and not
  1732. have this directive add the more verbose "-vv" automatically.
  1733.  
  1734. .RS 0
  1735. Some other examples:
  1736. .TP
  1737. <!-dir && !here> option: -dir ~/
  1738. Effectively make the default directory your home directory (instead of the
  1739. current directory). Using -dir or -xhere will undo this.
  1740. .TP
  1741. <tex> option: -name .tex -dir ~/pub
  1742. Create '-xtex' to search only "*.tex" files in your ~/pub directory tree.
  1743. Actually, this could be made a bit better. If you combine '-xtex' and '-dir'
  1744. on the command line, this directive will add ~/pub to the list, when you
  1745. probably want to use the -dir directory only. You could do
  1746. .nf
  1747.  
  1748.    <tex> option: -name .tex
  1749.    <tex && !-dir> option: -dir ~/pub
  1750. .fi
  1751.  
  1752. to will allow '-xtex' to work as before, but allow a command-line "-dir"
  1753. to take precedence with respect to ~/pub.
  1754. .TP
  1755. <fluff> option: -nnice -sort -i -vvv
  1756. Combine a few user-friendly options into one '-xfluff' option.
  1757. .TP
  1758. <man> option: -ddir /usr/man -v -w
  1759. When the '-xman' option is given, search "/usr/man" for whole-words
  1760. (of whatever regex or regexes are given on the command line), with -v.
  1761. .RE
  1762.  
  1763. The lines in the startup file are executed from top to bottom, so something
  1764. like
  1765. .nf
  1766.  
  1767.    <both> option: -xflag1 -xflag2
  1768.    <flag1> option: ...whatever...
  1769.    <flag2> option: ...whatever...
  1770.  
  1771. .fi
  1772. will allow '-xboth' to be the same as '-xflag1 -xflag2' (or '-xflag1,flag2'
  1773. for that matter). However, if you put the "<both>" line below the others,
  1774. they will not be true when encountered, so the result would be different
  1775. (and probably undesired).
  1776.  
  1777. The "magic" directives are used to determine if a file looks to be binary
  1778. or not. The form of a magic line is
  1779. .nf
  1780.     magic: \fISIZE\fP : \fIPERLCODE\fP
  1781. .fi
  1782. where
  1783. .I SIZE
  1784. is the number of bytes of the file you need to check, and
  1785. .I PERLCODE
  1786. is the code to do the check. Within
  1787. .IR PERLCODE ,
  1788. the variable $H will hold at least the first
  1789. .I SIZE
  1790. bytes of the file (unless the file is shorter than that, of course).
  1791. It might hold more bytes. The perl should evaluate to true if the file
  1792. should be considered a binary.
  1793.  
  1794. An example might be
  1795. .nf
  1796.     magic: 6 : substr($H, 0, 6) eq 'GIF87a'
  1797. .fi
  1798. to test for a GIF ("-iskip .gif" is better, but this might be useful
  1799. if you have images in files without the ".gif" extension).
  1800.  
  1801. Since the startup file is checked from top to bottom, you can be a bit
  1802. efficient:
  1803. .nf
  1804.     magic: 6 : ($x6 = substr($H, 0, 6)) eq 'GIF87a'
  1805.     magic: 6 :  $x6                     eq 'GIF89a'
  1806. .fi
  1807. You could also write the same thing as
  1808. .nf
  1809.   magic: 6 : (($x6 = substr($H, 0, 6)) eq 'GIF87a') || ## an old gif, or.. \e
  1810.            $x6                     eq 'GIF89a'     ## .. a new one.
  1811. .fi
  1812. since newlines may be escaped.
  1813.  
  1814. The default internal startup file includes
  1815. .nf
  1816.    magic: 32 : $H =~ m/[\ex00-\ex06\ex10-\ex1a\ex1c-\ex1f\ex80\exff]{2}/
  1817. .fi
  1818. which checks for certain non-printable characters, and catches a large
  1819. number of binary files, including most system's executables, linkable
  1820. objects, compressed, tarred, and otherwise folded, spindled, and mutilated
  1821. files.
  1822.  
  1823. Another example might be
  1824. .nf
  1825.     ## an archive library
  1826.     magic: 17 : substr($H, 0, 17) eq "!<arch>\en__.SYMDEF"
  1827. .fi
  1828.  
  1829. .SH "RETURN VALUE"
  1830. .I Search
  1831. returns zero if lines (or files, if appropriate) were found,
  1832. or if no work was requested (such as with
  1833. .BR -help ).
  1834. Returns 1 if no lines (or files) were found.
  1835. Returns 2 on error.
  1836.  
  1837. .SH TODO
  1838. Things I'd like to add some day:
  1839. .nf
  1840.   + show surrounding lines (context).
  1841.   + highlight matched portions of lines.
  1842.   + add '-and', which can go between regexes to override
  1843.     the default logical or of the regexes.
  1844.   + add something like
  1845.       -below GLOB
  1846.     which will examine a tree and only consider files that
  1847.     lie in a directory deeper than one named by the pattern.
  1848.   + add 'warning' and 'error' directives.
  1849.   + add 'help' directive.
  1850. .fi
  1851. .SH BUGS
  1852. If -xdev and multiple -dir arguments are given, any file in any of the
  1853. target filesystems are allowed. It would be better to allow each filesystem
  1854. for each separate tree.
  1855.  
  1856. Multiple -dir args might also cause some confusing effects. Doing
  1857. .nf
  1858.    -dir some/dir -dir other
  1859. .fi
  1860. will search "some/dir" completely, then search "other" completely. This
  1861. is good. However, something like
  1862. .nf
  1863.    -dir some/dir -dir some/dir/more/specific
  1864. .fi
  1865. will search "some/dir" completely *except for* "some/dir/more/specific",
  1866. after which it will return and be searched. Not really a bug, but just sort
  1867. of odd.
  1868.  
  1869. File times (for -newer, etc.) of symbolic links are for the file, not the
  1870. link. This could cause some misunderstandings.
  1871.  
  1872. Probably more. Please let me know.
  1873. .SH AUTHOR
  1874. Jeffrey Friedl, Omron Corp (jfriedl@omron.co.jp)
  1875. .br
  1876. http://www.wg.omron.co.jp/cgi-bin/j-e/jfriedl.html
  1877.  
  1878. .SH "LATEST SOURCE"
  1879. See http://www.wg.omron.co.jp/~jfriedl/perl/index.html
  1880.  
  1881. __END__
  1882. :endofperl
  1883.