1 .\" Copyright (c) 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the Institute of Electrical and Electronics Engineers, Inc.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36 .Nd walk a file hierarchy
39 .Op Fl H | Fl L | Fl P
45 .Op Fl H | Fl L | Fl P
53 utility recursively descends the directory tree for each
61 listed below) in terms
62 of each file in the tree.
64 The options are as follows:
65 .Bl -tag -width indent
67 Interpret regular expressions following the
71 primaries as extended (modern) regular expressions rather than basic
72 regular expressions (BRE's).
75 manual page fully describes both formats.
77 Cause the file information and file type (see
79 returned for each symbolic link specified on the command line to be
80 those of the file referenced by the link, not the link itself.
81 If the referenced file does not exist, the file information and type will
82 be for the link itself.
83 File information of all symbolic links not on
84 the command line is that of the link itself.
86 Cause the file information and file type (see
88 returned for each symbolic link to be those of the file referenced by the
89 link, not the link itself.
90 If the referenced file does not exist, the file information and type will
91 be for the link itself.
93 This option is equivalent to the deprecated
97 Cause the file information and file type (see
99 returned for each symbolic link to be those of the link itself.
104 to be safely used in conjunction with
106 If a file name contains any of the delimiting characters used by
108 a diagnostic message is displayed on standard error, and the file
110 The delimiting characters include single
116 space, tab and newline characters.
118 However, you may wish to consider the
120 primary in conjunction with
122 as an effective alternative.
126 to perform a depth-first traversal.
128 This option is a BSD-specific equivalent of the
132 Refer to its description under
134 for more information.
138 to the list of paths that will be recursed into.
141 begins with a character that would otherwise be interpreted as an
151 to traverse the file hierarchies in lexicographical order,
152 i.e., alphabetical order within each directory.
157 may give different results.
163 with all its contents before a directory
167 puts the directory name
169 before any string like
176 In locales other than
178 results may vary more due to collation differences.
182 from descending into directories that have a device number different
183 than that of the file from which the descent began.
185 This option is equivalent to the deprecated
190 All primaries which take a numeric argument allow the number to be
191 preceded by a plus sign
195 A preceding plus sign means
197 a preceding minus sign means
201 .Bl -tag -width indent
203 True if the difference between the time of a file's inode creation
206 was started, rounded up to the next full minute, is
209 .It Ic -Bnewer Ar file
212 .It Ic -Btime Ar n Ns Op Cm smhdw
213 If no units are specified, this primary evaluates to
214 true if the difference between the time of a file's inode creation
217 was started, rounded up to the next full 24-hour period, is
221 If units are specified, this primary evaluates to
222 true if the difference between the time of a file's inode creation
225 was started is exactly
230 primary description for information on supported time units.
232 May be used in conjunction with other primaries to locate
233 files with extended ACLs.
236 for more information.
237 .It Ic -amin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
238 True if the difference between the file last access time and the time
240 was started, rounded up to the next full minute, is
250 .It Ic -anewer Ar file
253 .It Ic -atime Ar n Ns Op Cm smhdw
254 If no units are specified, this primary evaluates to
255 true if the difference between the file last access time and the time
257 was started, rounded up to the next full 24-hour period, is
261 If units are specified, this primary evaluates to
262 true if the difference between the file last access time and the time
264 was started is exactly
267 Possible time units are as follows:
269 .Bl -tag -width indent -compact
282 Any number of units may be combined in one
284 argument, for example,
285 .Dq Li "-atime -1h30m" .
286 Units are probably only useful when used in conjunction with the
291 .It Ic -cmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
292 True if the difference between the time of last change of file status
293 information and the time
295 was started, rounded up to the next full minute, is
305 .It Ic -cnewer Ar file
308 .It Ic -ctime Ar n Ns Op Cm smhdw
309 If no units are specified, this primary evaluates to
310 true if the difference between the time of last change of file status
311 information and the time
313 was started, rounded up to the next full 24-hour period, is
317 If units are specified, this primary evaluates to
318 true if the difference between the time of last change of file status
319 information and the time
321 was started is exactly
326 primary description for information on supported time units.
328 Non-portable, BSD-specific version of
330 GNU find implements this as a primary in mistaken emulation of
334 Delete found files and/or directories.
337 from the current working directory as
339 recurses down the tree.
340 It will not attempt to delete a filename with a
342 character in its pathname relative to
344 for security reasons.
345 Depth-first traversal processing is implied by this option.
348 primary will fail to delete a directory if it is not empty.
349 Following symlinks is incompatible with this option.
354 primary will immediately attempt to delete the current path when
356 Be mindful of its place in the expression; as a general rule, it
357 should almost always come last.
358 If in doubt, try running with
365 below for additional information on the order of evaluation.
368 same as the non-portable
373 to perform a depth-first traversal, i.e., directories
374 are visited in post-order and all entries in a directory will be acted
375 on before the directory itself.
378 visits directories in pre-order, i.e., before their contents.
381 a breadth-first traversal.
390 to process files that are contained in directories with unusual permissions.
391 It ensures that you have write permission while you are placing files in a
392 directory, then sets the directory's permissions as the last thing.
394 True if the depth of the file relative to the starting point of the traversal
398 True if the current file or directory is empty.
399 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
400 True if the program named
402 returns a zero value as its exit status.
405 may be passed to the utility.
406 The expression must be terminated by a semicolon
410 from a shell you may need to quote the semicolon if the shell would
411 otherwise treat it as a control operator.
414 appears anywhere in the utility name or the
415 arguments it is replaced by the pathname of the current file.
417 will be executed from the directory from which
423 are not subject to the further expansion of shell patterns
425 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
430 is replaced with as many pathnames as possible for each invocation of
432 This behaviour is similar to that of
434 The primary always returns true;
435 if at least one invocation of
437 returns a non-zero exit status,
439 will return a non-zero exit status.
440 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
443 primary is identical to the
445 primary with the exception that
447 will be executed from the directory that holds
449 The filename substituted for
453 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
458 is replaced with as many pathnames as possible for each invocation of
460 This behaviour is similar to that of
462 The primary always returns true;
463 if at least one invocation of
465 returns a non-zero exit status,
467 will return a non-zero exit status.
469 Matches files which are executable by the current user.
470 This test makes use of the
472 system call, and so can be fooled by NFS servers which do UID mapping (or root-squashing).
473 This is a GNU find extension.
474 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
475 The flags are specified using symbolic names (see
485 are checked to be set, and flags in
487 are checked to be not set.
488 Note that this is different from
490 which only allows the user to specify mode bits that are set.
492 If flags are preceded by a dash
494 this primary evaluates to true
495 if at least all of the bits in
497 and none of the bits in
499 are set in the file's flags bits.
500 If flags are preceded by a plus
502 this primary evaluates to true
503 if any of the bits in
505 is set in the file's flags bits,
506 or any of the bits in
508 is not set in the file's flags bits.
510 this primary evaluates to true
513 exactly match the file's flags bits,
518 .It Ic -fstype Ar type
519 True if the file is contained in a file system of type
523 command can be used to find out the types of file systems
524 that are available on the system.
525 In addition, there are two pseudo-types,
529 The former matches any file system physically mounted on the system where
532 is being executed and the latter matches any file system which is
537 for compatibility with GNU find.
538 GNU find imposes a restriction that
543 .It Ic -group Ar gname
544 True if the file belongs to the group
548 is numeric and there is no such group name, then
550 is treated as a group ID.
551 .It Ic -ignore_readdir_race
552 Ignore errors because a file or a directory is deleted
553 after reading the name from a directory.
554 This option does not affect errors occurring on starting points.
555 .It Ic -ilname Ar pattern
558 but the match is case insensitive.
559 This is a GNU find extension.
560 .It Ic -iname Ar pattern
563 but the match is case insensitive.
565 True if the file has inode number
567 .It Ic -ipath Ar pattern
570 but the match is case insensitive.
571 .It Ic -iregex Ar pattern
574 but the match is case insensitive.
575 .It Ic -iwholename Ar pattern
578 for GNU find compatibility.
583 .It Ic -lname Ar pattern
586 but the contents of the symbolic link are matched instead of the file
588 Note that this only matches broken symbolic links
589 if symbolic links are being followed.
590 This is a GNU find extension.
592 This primary always evaluates to true.
593 The following information for the current file is written to standard output:
594 its inode number, size in 512-byte blocks, file permissions, number of hard
595 links, owner, group, size in bytes, last modification time, and pathname.
596 If the file is a block or character special file, the device number
597 will be displayed instead of the size in bytes.
598 If the file is a symbolic link, the pathname of the linked-to file will be
599 displayed preceded by
601 The format is identical to that produced by
605 .It Ic -maxdepth Ar n
606 Always true; descend at most
608 directory levels below the command line arguments.
611 primary is specified, it applies to the entire expression even if it would
612 not normally be evaluated.
613 .Dq Ic -maxdepth Li 0
614 limits the whole search to the command line arguments.
615 .It Ic -mindepth Ar n
616 Always true; do not apply any tests or actions at levels less than
620 primary is specified, it applies to the entire expression even if it would
621 not normally be evaluated.
622 .Dq Ic -mindepth Li 1
623 processes all but the command line arguments.
624 .It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
625 True if the difference between the file last modification time and the time
627 was started, rounded up to the next full minute, is
637 .It Ic -mnewer Ar file
643 for GNU find compatibility.
644 .It Ic -mtime Ar n Ns Op Cm smhdw
645 If no units are specified, this primary evaluates to
646 true if the difference between the file last modification time and the time
648 was started, rounded up to the next full 24-hour period, is
652 If units are specified, this primary evaluates to
653 true if the difference between the file last modification time and the time
655 was started is exactly
660 primary description for information on supported time units.
661 .It Ic -name Ar pattern
662 True if the last component of the pathname being examined matches
664 Special shell pattern matching characters
670 may be used as part of
672 These characters may be matched explicitly by escaping them with a
675 .It Ic -newer Ar file
676 True if the current file has a more recent last modification time than
678 .It Ic -newer Ns Ar X Ns Ar Y Ar file
679 True if the current file has a more recent last access time
680 .Pq Ar X Ns = Ns Cm a ,
682 .Pq Ar X Ns = Ns Cm B ,
684 .Pq Ar X Ns = Ns Cm c ,
686 .Pq Ar X Ns = Ns Cm m
687 than the last access time
688 .Pq Ar Y Ns = Ns Cm a ,
690 .Pq Ar Y Ns = Ns Cm B ,
692 .Pq Ar Y Ns = Ns Cm c ,
694 .Pq Ar Y Ns = Ns Cm m
701 is instead interpreted as a direct date specification of the form
702 understood by ISO8601 or RFC822.
708 True if the file belongs to an unknown group.
709 .It Ic -noignore_readdir_race
710 Turn off the effect of
711 .Ic -ignore_readdir_race .
712 This is default behaviour.
714 This option is for GNU find compatibility.
715 In GNU find it disables an optimization not relevant to
719 True if the file belongs to an unknown user.
720 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
723 primary is identical to the
725 primary with the exception that
727 requests user affirmation for the execution of the
730 a message to the terminal and reading a response.
731 If the response is not affirmative
736 the command is not executed and the
740 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
743 primary is identical to the
745 primary with the same exception as described for the
748 .It Ic -path Ar pattern
749 True if the pathname being examined matches
751 Special shell pattern matching characters
757 may be used as part of
759 These characters may be matched explicitly by escaping them with a
764 are treated as normal characters and do not have to be
766 .It Ic -perm Oo Cm - Ns | Ns Cm + Ns | Ns Cm / Oc Ns Ar mode
769 may be either symbolic (see
774 is symbolic, a starting value of zero is assumed and the
776 sets or clears permissions without regard to the process' file mode
780 is octal, only bits 07777
781 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
782 of the file's mode bits participate
786 is preceded by a dash
788 this primary evaluates to true
789 if at least all of the bits in the
791 are set in the file's mode bits.
794 is preceded by a plus
796 this primary evaluates to true
797 if any of the bits in the
799 are set in the file's mode bits.
802 is also accepted with the same meaning as plus for compatibility with GNU find.
803 Otherwise, this primary evaluates to true if
806 exactly match the file's mode bits.
807 Note, the first character of a symbolic mode may not be a dash
810 This primary always evaluates to true.
811 It prints the pathname of the current file to standard output.
813 .Ic -exec , -ls , -print0 ,
816 is specified, the given expression shall be effectively replaced by
817 .Cm \&( Ar "given expression" Cm \&) Ic -print .
819 This primary always evaluates to true.
820 It prints the pathname of the current file to standard output, followed by an
823 character (character code 0).
825 This primary always evaluates to true.
828 to not descend into the current file.
831 primary has no effect if the
833 option was specified.
837 to terminate immediately.
839 Matches files which are readable by the current user.
840 This test makes use of the
842 system call, and so can be fooled by NFS servers which do UID mapping (or root-squashing).
843 This is a GNU find extension.
844 .It Ic -regex Ar pattern
845 True if the whole path of the file matches
847 using regular expression.
848 To match a file named
850 you can use the regular expression
858 .It Ic -samefile Ar name
859 True if the file is a hard link to
861 If the command option
863 is specified, it is also true if the file is a symbolic link and
866 .It Ic -size Ar n Ns Op Cm ckMGTP
867 True if the file's size, rounded up, in 512-byte blocks is
873 then the primary is true if the
879 is followed by a scale indicator then the file's size is compared to
883 .Bl -tag -width indent -compact
885 kilobytes (1024 bytes)
887 megabytes (1024 kilobytes)
889 gigabytes (1024 megabytes)
891 terabytes (1024 gigabytes)
893 petabytes (1024 terabytes)
896 True if the current file is sparse,
897 i.e. has fewer blocks allocated than expected based on its size in bytes.
898 This might also match files that have been compressed by the filesystem.
900 True if the file is of the specified type.
901 Possible file types are as follows:
903 .Bl -tag -width indent -compact
922 for compatibility with GNU find.
923 GNU find imposes a restriction that
928 .It Ic -user Ar uname
929 True if the file belongs to the user
933 is numeric and there is no such user name, then
935 is treated as a user ID.
936 .It Ic -wholename Ar pattern
939 for GNU find compatibility.
941 Matches files which are writable by the current user.
942 This test makes use of the
944 system call, and so can be fooled by NFS servers which do UID mapping (or root-squashing).
945 This is a GNU find extension.
948 The primaries may be combined using the following operators.
949 The operators are listed in order of decreasing precedence.
951 .Bl -tag -width indent -compact
952 .It Cm \&( Ar expression Cm \&)
953 This evaluates to true if the parenthesized expression evaluates to
956 .It Cm \&! Ar expression
957 .It Cm -not Ar expression
961 It evaluates to true if the expression is false.
968 .It Ar expression Cm -and Ar expression
969 .It Ar expression expression
972 operator is the logical
975 As it is implied by the juxtaposition of two expressions it does not
976 have to be specified.
977 The expression evaluates to true if both expressions are true.
978 The second expression is not evaluated if the first expression is false.
980 .It Ar expression Cm -or Ar expression
983 operator is the logical
986 The expression evaluates to true if either the first or the second expression
988 The second expression is not evaluated if the first expression is true.
991 All operands and primaries must be separate arguments to
993 Primaries which themselves take arguments expect each argument
994 to be a separate argument to
998 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
1001 environment variables affect the execution of the
1003 utility as described in
1006 The following examples are shown as given to the shell:
1007 .Bl -tag -width indent
1008 .It Li "find / \e! -name \*q*.c\*q -print"
1009 Print out a list of all the files whose names do not end in
1011 .It Li "find / -newer ttt -user wnj -print"
1012 Print out a list of all the files owned by user
1017 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
1018 Print out a list of all the files which are not both newer than
1022 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
1023 Print out a list of all the files that are either owned by
1025 or that are newer than
1027 .It Li "find / -newerct '1 minute ago' -print"
1028 Print out a list of all the files whose inode change time is more
1029 recent than the current time minus one minute.
1030 .It Li "find / -type f -exec echo {} \e;"
1033 command to print out a list of all the files.
1034 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
1035 Delete all broken symbolic links in
1036 .Pa /usr/ports/packages .
1037 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
1038 Find files and directories that are at least seven levels deep
1039 in the working directory
1041 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
1042 Is not equivalent to the previous example, since
1044 is not evaluated below level seven.
1049 primary is deprecated; the
1051 option should be used instead.
1054 section below for details.
1075 utility syntax is a superset of the syntax specified by the
1079 All the single character options except
1084 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
1085 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
1086 .Ic -not , -path , -print0 , -regex , -sparse
1089 birthtime related primaries are extensions to
1096 options were implemented using the primaries
1097 .Ic -depth , -follow ,
1100 These primaries always evaluated to true.
1101 As they were really global variables that took effect before the traversal
1102 began, some legal expressions could have unexpected results.
1103 An example is the expression
1104 .Ic -print Cm -o Ic -depth .
1107 always evaluates to true, the standard order of evaluation
1110 would never be evaluated.
1111 This is not the case.
1122 Historic implementations of the
1126 primaries did not replace the string
1128 in the utility name or the
1129 utility arguments if it had preceding or following non-whitespace characters.
1130 This version replaces it no matter where in the utility name or arguments
1135 option was inspired by the equivalent
1143 primary accepts a leading slash
1145 as an alias for a leading plus
1147 for its argument as an extension of
1149 to be compatible with GNU find.
1157 It was rewritten for
1159 and later be enhanced for the Programmer's Workbench (PWB).
1160 These changes were later incorporated in
1163 The special characters used by
1165 are also special characters to many shell programs.
1166 In particular, the characters
1177 may have to be escaped from the shell.
1179 As there is no delimiter separating options and file names or file
1182 it is difficult to specify files named
1186 These problems are handled by the
1195 primary does not interact well with other options that cause the file system
1196 tree traversal options to be changed.
1202 primaries are actually global options (as documented above).
1204 probably be replaced by options which look like options.