home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / doc / find.man < prev    next >
Text File  |  1993-06-13  |  21KB  |  661 lines
  1.  
  2.  
  3.  
  4. FIND(1L)                                                 FIND(1L)
  5.  
  6.  
  7. NAME
  8.        find - search for files in a directory hierarchy
  9.  
  10. SYNOPSIS
  11.        find [path...] [expression]
  12.  
  13. DESCRIPTION
  14.        This  manual page documents the GNU version of find.  find
  15.        searches the directory tree rooted at each given file name
  16.        by  evaluating  the  given  expression from left to right,
  17.        according to the rules of precedence (see  section  OPERA-
  18.        TORS),  until  the outcome is known (the left hand side is
  19.        false for and operations, true for  or),  at  which  point
  20.        find moves on to the next file name.
  21.  
  22.        The first argument that begins with `-', `(', `)', `,', or
  23.        `!' is taken to be the beginning of  the  expression;  any
  24.        arguments before it are paths to search, and any arguments
  25.        after it are the rest of the expression.  If no paths  are
  26.        given, the current directory is used.  If no expression is
  27.        given, the expression `-print' is used.
  28.  
  29.        find exits with status 0 if all files are  processed  suc-
  30.        cessfully, greater than 0 if errors occur.
  31.  
  32. EXPRESSIONS
  33.        The expression is made up of options (which affect overall
  34.        operation rather than the processing of a  specific  file,
  35.        and  always  return  true),  tests (which return a true or
  36.        false value), and actions (which  have  side  effects  and
  37.        return a true or false value), all separated by operators.
  38.        -and is assumed where the operator  is  omitted.   If  the
  39.        expression  contains  no actions other than -prune, -print
  40.        is performed on all files  for  which  the  expression  is
  41.        true.
  42.  
  43.    OPTIONS
  44.        All options always return true.
  45.  
  46.        -daystart
  47.               Measure  times  (for  -amin, -atime, -cmin, -ctime,
  48.               -mmin, and -mtime)  from  the  beginning  of  today
  49.               rather than from 24 hours ago.
  50.  
  51.        -depth Process each directory's contents before the direc-
  52.               tory itself.
  53.  
  54.        -follow
  55.               Dereference symbolic links.  Implies -noleaf.
  56.  
  57.        -maxdepth levels
  58.               Descend at most  levels  (a  non-negative  integer)
  59.               levels  of directories below the command line argu-
  60.               ments.  `-maxdepth 0' means only  apply  the  tests
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. FIND(1L)                                                 FIND(1L)
  71.  
  72.  
  73.               and actions to the command line arguments.
  74.  
  75.        -mindepth levels
  76.               Do  not  apply  any tests or actions at levels less
  77.               than levels (a non-negative  integer).   `-mindepth
  78.               1'  means process all files except the command line
  79.               arguments.
  80.  
  81.        -noleaf
  82.               Do not optimize by assuming that  directories  con-
  83.               tain  2  fewer  subdirectories than their hard link
  84.               count.   This  option  is  needed  when   searching
  85.               filesystems  that do not follow the Unix directory-
  86.               link convention, such as CD-ROM or MS-DOS  filesys-
  87.               tems or AFS volume mount points.  Each directory on
  88.               a normal Unix filesystem has at least 2 hard links:
  89.               its  name  and  its  `.'  entry.  Additionally, its
  90.               subdirectories (if any) each  have  a  `..'   entry
  91.               linked to that directory.  When find is examining a
  92.               directory, after it has statted 2 fewer subdirecto-
  93.               ries than the directory's link count, it knows that
  94.               the rest of the entries in the directory  are  non-
  95.               directories  (`leaf'  files in the directory tree).
  96.               If only the files' names need to be examined, there
  97.               is  no  need to stat them; this gives a significant
  98.               increase in search speed.
  99.  
  100.        -version
  101.               Print find version number on standard error.
  102.  
  103.        -xdev  Don't descend directories on other filesystems.
  104.  
  105.    TESTS
  106.        Numeric arguments can be specified as
  107.  
  108.        +n     for greater than n,
  109.  
  110.        -n     for less than n,
  111.  
  112.        n      for exactly n.
  113.  
  114.        -amin n
  115.               File was last accessed n minutes ago.
  116.  
  117.        -anewer file
  118.               File was last accessed more recently than file  was
  119.               modified.   -anewer  is affected by -follow only if
  120.               -follow comes before -anewer on the command line.
  121.  
  122.        -atime n
  123.               File was last accessed n*24 hours ago.
  124.  
  125.        -cmin n
  126.               File's status was last changed n minutes ago.
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. FIND(1L)                                                 FIND(1L)
  137.  
  138.  
  139.        -cnewer file
  140.               File's status was last changed more  recently  than
  141.               file  was modified.  -cnewer is affected by -follow
  142.               only if -follow comes before -cnewer on the command
  143.               line.
  144.  
  145.        -ctime n
  146.               File's status was last changed n*24 hours ago.
  147.  
  148.        -empty File  is  empty  and  is either a regular file or a
  149.               directory.
  150.  
  151.        -false Always false.
  152.  
  153.        -fstype type
  154.               File is on a filesystem of type  type.   The  valid
  155.               filesystem  types  vary among different versions of
  156.               Unix; an incomplete list of filesystem  types  that
  157.               are accepted on some version of Unix or another is:
  158.               ufs, 4.2, 4.3, nfs, tmp, mfs, S51K, S52K.  You  can
  159.               use  -printf with the %F directive to see the types
  160.               of your filesystems.
  161.  
  162.        -gid n File's numeric group ID is n.
  163.  
  164.        -group gname
  165.               File belongs  to  group  gname  (numeric  group  ID
  166.               allowed).
  167.  
  168.        -ilname pattern
  169.               Like -lname, but the match is case insensitive.
  170.  
  171.        -iname pattern
  172.               Like -name, but the match is case insensitive.  For
  173.               example, the patterns `fo*'  and  `F??'  match  the
  174.               file names `Foo', `FOO', `foo', `fOo', etc.
  175.  
  176.        -inum n
  177.               File has inode number n.
  178.  
  179.        -ipath pattern
  180.               Like -path, but the match is case insensitive.
  181.  
  182.        -iregex pattern
  183.               Like -regex, but the match is case insensitive.
  184.  
  185.        -links n
  186.               File has n links.
  187.  
  188.        -lname pattern
  189.               File  is a symbolic link whose contents match shell
  190.               pattern pattern.  The metacharacters do  not  treat
  191.               `/' or `.' specially.
  192.  
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. FIND(1L)                                                 FIND(1L)
  203.  
  204.  
  205.        -mmin n
  206.               File's data was last modified n minutes ago.
  207.  
  208.        -mtime n
  209.               File's data was last modified n*24 hours ago.
  210.  
  211.        -name pattern
  212.               Base of file name (the path with the leading direc-
  213.               tories removed) matches shell pattern pattern.  The
  214.               metacharacters  (`*', `?', and `[]') do not match a
  215.               `.' at the start of the base  name.   To  ignore  a
  216.               directory  and  the files under it, use -prune; see
  217.               an example in the description of -path.
  218.  
  219.        -newer file
  220.               File was modified more recently than file.   -newer
  221.               is affected by -follow only if -follow comes before
  222.               -newer on the command line.
  223.  
  224.        -nouser
  225.               No user corresponds to file's numeric user ID.
  226.  
  227.        -nogroup
  228.               No group corresponds to file's numeric group ID.
  229.  
  230.        -path pattern
  231.               File  name  matches  shell  pattern  pattern.   The
  232.               metacharacters  do  not treat `/' or `.' specially;
  233.               so, for example,
  234.                         find . -path './sr*sc'
  235.               will  print  an  entry  for  a   directory   called
  236.               './src/misc'  (if  one  exists).  To ignore a whole
  237.               directory tree, use  -prune  rather  than  checking
  238.               every  file  in the tree.  For example, to skip the
  239.               directory `src/emacs' and all files and directories
  240.               under  it,  and  print the names of the other files
  241.               found, do something like this:
  242.                         find  .  -path  './src/emacs'  -prune  -o
  243.                         -print
  244.  
  245.        -perm mode
  246.               File's  permission  bits are exactly mode (octal or
  247.               symbolic).  Symbolic modes use mode 0 as a point of
  248.               departure.
  249.  
  250.        -perm -mode
  251.               All  of  the  permission  bits mode are set for the
  252.               file.
  253.  
  254.        -perm +mode
  255.               Any of the permission bits mode  are  set  for  the
  256.               file.
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                                                                 4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. FIND(1L)                                                 FIND(1L)
  269.  
  270.  
  271.        -regex pattern
  272.               File name matches regular expression pattern.  This
  273.               is a match on the whole path, not  a  search.   For
  274.               example,  to match a file named `./fubar3', you can
  275.               use the regular expression  `.*bar.'  or  `.*b.*3',
  276.               but not `b.*r3'.
  277.  
  278.        -size n[ck]
  279.               File  uses  n 512-byte blocks (bytes if `c' follows
  280.               n, kilobytes if `k' follows n).  The size does  not
  281.               count  indirect  blocks,  and  does count blocks in
  282.               sparse files that are not actually allocated.
  283.  
  284.        -true  Always true.
  285.  
  286.        -type c
  287.               File is of type c:
  288.  
  289.               b      block (buffered) special
  290.  
  291.               c      character (unbuffered) special
  292.  
  293.               d      directory
  294.  
  295.               p      named pipe (FIFO)
  296.  
  297.               f      regular file
  298.  
  299.               l      symbolic link
  300.  
  301.               s      socket
  302.  
  303.        -uid n File's numeric user ID is n.
  304.  
  305.        -used n
  306.               File was last accessed n days after its status  was
  307.               last changed.
  308.  
  309.        -user uname
  310.               File  is  owned  by  user  uname  (numeric  user ID
  311.               allowed).
  312.  
  313.        -xtype c
  314.               The same as -type unless the  file  is  a  symbolic
  315.               link.   For symbolic links, if -follow has not been
  316.               given, true if the file is a link to a file of type
  317.               c;  if  -follow  has  been given, true if c is `l'.
  318.               For symbolic links, -xtype checks the type  of  the
  319.               file that -type does not check.
  320.  
  321.    ACTIONS
  322.        -exec command ;
  323.               Execute command; true if 0 status is returned.  All
  324.               following  arguments  to  find  are  taken  to   be
  325.  
  326.  
  327.  
  328.                                                                 5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. FIND(1L)                                                 FIND(1L)
  335.  
  336.  
  337.               arguments to the command until an argument consist-
  338.               ing of `;' is  encountered.   The  string  `{}'  is
  339.               replaced  by  the current file name being processed
  340.               everywhere it occurs in the arguments to  the  com-
  341.               mand,  not  just in arguments where it is alone, as
  342.               in some versions of find.  Both of these  construc-
  343.               tions  might  need  to  be  escaped (with a `\') or
  344.               quoted to protect them from expansion by the shell.
  345.  
  346.        -fprint file
  347.               True;  print the full file name into file file.  If
  348.               file does not exist when find is run,  it  is  cre-
  349.               ated;  if it does exist, it is truncated.  The file
  350.               names ``/dev/stdout'' and ``/dev/stderr'' are  han-
  351.               dled  specially;  they refer to the standard output
  352.               and standard error output, respectively.
  353.  
  354.        -fprint0 file
  355.               True; like -print0 but write to file like  -fprint.
  356.  
  357.        -fprintf file format
  358.               True;  like -printf but write to file like -fprint.
  359.  
  360.        -ok command ;
  361.               Like -exec but ask the user first (on the  standard
  362.               input);  if the response does not start with `y' or
  363.               `Y', do not run the command, and return false.
  364.  
  365.        -print True; print the full file name on the standard out-
  366.               put, followed by a newline.
  367.  
  368.        -print0
  369.               True; print the full file name on the standard out-
  370.               put, followed by a  null  character.   This  allows
  371.               file  names  that  contain newlines to be correctly
  372.               interpreted by programs that process the find  out-
  373.               put.
  374.  
  375.        -printf format
  376.               True;  print  format on the standard output, inter-
  377.               preting `\'  escapes  and  `%'  directives.   Field
  378.               widths  and precisions can be specified as with the
  379.               `printf' C function.  Unlike -print,  -printf  does
  380.               not  add  a  newline at the end of the string.  The
  381.               escapes and directives are:
  382.  
  383.               \a     Alarm bell.
  384.  
  385.               \b     Backspace.
  386.  
  387.               \c     Stop printing from this format  immediately.
  388.  
  389.               \f     Form feed.
  390.  
  391.  
  392.  
  393.  
  394.                                                                 6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. FIND(1L)                                                 FIND(1L)
  401.  
  402.  
  403.               \n     Newline.
  404.  
  405.               \r     Carriage return.
  406.  
  407.               \t     Horizontal tab.
  408.  
  409.               \v     Vertical tab.
  410.  
  411.               \\     A literal backslash (`\').
  412.  
  413.               A  `\' character followed by any other character is
  414.               treated as an ordinary character, so they both  are
  415.               printed.
  416.  
  417.               %%     A literal percent sign.
  418.  
  419.               %a     File's   last  access  time  in  the  format
  420.                      returned by the C `ctime' function.
  421.  
  422.               %Ak    File's last access time in the format speci-
  423.                      fied  by  k, which is either `@' or a direc-
  424.                      tive for the  C  `strftime'  function.   The
  425.                      possible values for k are listed below; some
  426.                      of them might not be available on  all  sys-
  427.                      tems,   due  to  differences  in  `strftime'
  428.                      between systems.
  429.  
  430.                       @      seconds since Jan.  1,  1970,  00:00
  431.                              GMT.
  432.  
  433.                      Time fields:
  434.  
  435.                       H      hour (00..23)
  436.  
  437.                       I      hour (01..12)
  438.  
  439.                       k      hour ( 0..23)
  440.  
  441.                       l      hour ( 1..12)
  442.  
  443.                       M      minute (00..59)
  444.  
  445.                       p      locale's AM or PM
  446.  
  447.                       r      time, 12-hour (hh:mm:ss [AP]M)
  448.  
  449.                       S      second (00..61)
  450.  
  451.                       T      time, 24-hour (hh:mm:ss)
  452.  
  453.                       X      locale's time representation (H:M:S)
  454.  
  455.                       Z      time zone (e.g., EDT), or nothing if
  456.                              no time zone is determinable
  457.  
  458.  
  459.  
  460.                                                                 7
  461.  
  462.  
  463.  
  464.  
  465.  
  466. FIND(1L)                                                 FIND(1L)
  467.  
  468.  
  469.                      Date fields:
  470.  
  471.                       a      locale's  abbreviated  weekday  name
  472.                              (Sun..Sat)
  473.  
  474.                       A      locale's full weekday name, variable
  475.                              length (Sunday..Saturday)
  476.  
  477.                       b      locale's   abbreviated   month  name
  478.                              (Jan..Dec)
  479.  
  480.                       B      locale's full month  name,  variable
  481.                              length (January..December)
  482.  
  483.                       c      locale's  date  and time (Sat Nov 04
  484.                              12:02:33 EST 1989)
  485.  
  486.                       d      day of month (01..31)
  487.  
  488.                       D      date (mm/dd/yy)
  489.  
  490.                       h      same as b
  491.  
  492.                       j      day of year (001..366)
  493.  
  494.                       m      month (01..12)
  495.  
  496.                       U      week number of year with  Sunday  as
  497.                              first day of week (00..53)
  498.  
  499.                       w      day of week (0..6)
  500.  
  501.                       W      week  number  of year with Monday as
  502.                              first day of week (00..53)
  503.  
  504.                       x      locale's     date     representation
  505.                              (mm/dd/yy)
  506.  
  507.                       y      last two digits of year (00..99)
  508.  
  509.                       Y      year (1970...)
  510.  
  511.               %b     File's size in 512-byte blocks (rounded up).
  512.  
  513.               %c     File's last status change time in the format
  514.                      returned by the C `ctime' function.
  515.  
  516.               %Ck    File's last status change time in the format
  517.                      specified by k, which is the same as for %A.
  518.  
  519.               %d     File's  depth in the directory tree; 0 means
  520.                      the file is a command line argument.
  521.  
  522.               %f     File's name  with  any  leading  directories
  523.  
  524.  
  525.  
  526.                                                                 8
  527.  
  528.  
  529.  
  530.  
  531.  
  532. FIND(1L)                                                 FIND(1L)
  533.  
  534.  
  535.                      removed.
  536.  
  537.               %F     Type  of the filesystem the file is on; this
  538.                      value can be used for -fstype.
  539.  
  540.               %g     File's group name, or numeric  group  ID  if
  541.                      the group has no name.
  542.  
  543.               %G     File's numeric group ID.
  544.  
  545.               %h     Leading directories of file's name.
  546.  
  547.               %H     Command  line  argument under which file was
  548.                      found.
  549.  
  550.               %i     File's inode number (in decimal).
  551.  
  552.               %k     File's size in 1K blocks (rounded up).
  553.  
  554.               %l     Object of symbolic  link  (empty  string  if
  555.                      file is not a symbolic link).
  556.  
  557.               %m     File's permission bits (in octal).
  558.  
  559.               %n     Number of hard links to file.
  560.  
  561.               %p     File's name.
  562.  
  563.               %P     File's  name  with  the  name of the command
  564.                      line  argument  under  which  it  was  found
  565.                      removed.
  566.  
  567.               %s     File's size in bytes.
  568.  
  569.               %t     File's  last modification time in the format
  570.                      returned by the C `ctime' function.
  571.  
  572.               %Tk    File's last modification time in the  format
  573.                      specified by k, which is the same as for %A.
  574.  
  575.               %u     File's user name, or numeric user ID if  the
  576.                      user has no name.
  577.  
  578.               %U     File's numeric user ID.
  579.  
  580.               A  `%' character followed by any other character is
  581.               discarded (but the other character is printed).
  582.  
  583.        -prune If -depth is not given, true; do  not  descend  the
  584.               current directory.
  585.               If -depth is given, false; no effect.
  586.  
  587.        -ls    True;  list  current  file  in `ls -dils' format on
  588.               standard  output.   The  block  counts  are  of  1K
  589.  
  590.  
  591.  
  592.                                                                 9
  593.  
  594.  
  595.  
  596.  
  597.  
  598. FIND(1L)                                                 FIND(1L)
  599.  
  600.  
  601.               blocks,    unless    the    environment    variable
  602.               POSIXLY_CORRECT is  set,  in  which  case  512-byte
  603.               blocks are used.
  604.  
  605.    OPERATORS
  606.        Listed in order of decreasing precedence:
  607.  
  608.        ( expr )
  609.               Force precedence.
  610.  
  611.        ! expr True if expr is false.
  612.  
  613.        -not expr
  614.               Same as ! expr.
  615.  
  616.        expr1 expr2
  617.               And  (implied);  expr2 is not evaluated if expr1 is
  618.               false.
  619.  
  620.        expr1 -a expr2
  621.               Same as expr1 expr2.
  622.  
  623.        expr1 -and expr2
  624.               Same as expr1 expr2.
  625.  
  626.        expr1 -o expr2
  627.               Or; expr2 is not evaluated if expr1 is true.
  628.  
  629.        expr1 -or expr2
  630.               Same as expr1 -o expr2.
  631.  
  632.        expr1 , expr2
  633.               List; both expr1 and expr2  are  always  evaluated.
  634.               The  value  of expr1 is discarded; the value of the
  635.               list is the value of expr2.
  636.  
  637.  
  638.  
  639.  
  640.  
  641.  
  642.  
  643.  
  644.  
  645.  
  646.  
  647.  
  648.  
  649.  
  650.  
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.                                                                10
  659.  
  660.  
  661.