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. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" @(#)find.1 8.7 (Berkeley) 5/9/95
43 .Nd walk a file hierarchy
46 .Op Fl H | Fl L | Fl P
52 .Op Fl H | Fl L | Fl P
60 utility recursively descends the directory tree for each
68 listed below) in terms
69 of each file in the tree.
71 The options are as follows:
72 .Bl -tag -width indent
74 Interpret regular expressions followed by
78 primaries as extended (modern) regular expressions rather than basic
79 regular expressions (BRE's).
82 manual page fully describes both formats.
84 Cause the file information and file type (see
86 returned for each symbolic link specified on the command line to be
87 those of the file referenced by the link, not the link itself.
88 If the referenced file does not exist, the file information and type will
89 be for the link itself.
90 File information of all symbolic links not on
91 the command line is that of the link itself.
93 Cause the file information and file type (see
95 returned for each symbolic link to be those of the file referenced by the
96 link, not the link itself.
97 If the referenced file does not exist, the file information and type will
98 be for the link itself.
100 This option is equivalent to the deprecated
104 Cause the file information and file type (see
106 returned for each symbolic link to be those of the link itself.
111 to be safely used in conjunction with
113 If a file name contains any of the delimiting characters used by
115 a diagnostic message is displayed on standard error, and the file
117 The delimiting characters include single
123 space, tab and newline characters.
125 However, you may wish to consider the
127 primary in conjunction with
129 as an effective alternative.
133 to perform a depth-first traversal, i.e., directories
134 are visited in post-order and all entries in a directory will be acted
135 on before the directory itself.
138 visits directories in pre-order, i.e., before their contents.
141 a breadth-first traversal.
143 This option is equivalent to the
154 to process files that are contained in directories with unusual permissions.
155 It ensures that you have write permission while you are placing files in a
156 directory, then sets the directory's permissions as the last thing.
158 Specify a file hierarchy for
161 File hierarchies may also be specified as the operands immediately
162 following the options.
166 to traverse the file hierarchies in lexicographical order,
167 i.e., alphabetical order within each directory.
172 may give different results.
176 from descending into directories that have a device number different
177 than that of the file from which the descent began.
179 This option is equivalent to the deprecated
185 All primaries which take a numeric argument allow the number to be
186 preceded by a plus sign
190 A preceding plus sign means
192 a preceding minus sign means
196 .Bl -tag -width indent
198 True if the difference between the time of a file's inode creation
201 was started, rounded up to the next full minute, is
204 .It Ic -Bnewer Ar file
207 .It Ic -Btime Ar n Ns Op Cm smhdw
208 If no units are specified, this primary evaluates to
209 true if the difference between the time of a file's inode creation
212 was started, rounded up to the next full 24-hour period, is
216 If units are specified, this primary evaluates to
217 true if the difference between the time of a file's inode creation
220 was started is exactly
225 primary description for information on supported time units.
227 May be used in conjunction with other primaries to locate
228 files with extended ACLs.
231 for more information.
233 True if the difference between the file last access time and the time
235 was started, rounded up to the next full minute, is
238 .It Ic -anewer Ar file
241 .It Ic -atime Ar n Ns Op Cm smhdw
242 If no units are specified, this primary evaluates to
243 true if the difference between the file last access time and the time
245 was started, rounded up to the next full 24-hour period, is
249 If units are specified, this primary evaluates to
250 true if the difference between the file last access time and the time
252 was started is exactly
255 Possible time units are as follows:
257 .Bl -tag -width indent -compact
270 Any number of units may be combined in one
272 argument, for example,
273 .Dq Li "-atime -1h30m" .
274 Units are probably only useful when used in conjunction with the
280 True if the difference between the time of last change of file status
281 information and the time
283 was started, rounded up to the next full minute, is
286 .It Ic -cnewer Ar file
289 .It Ic -ctime Ar n Ns Op Cm smhdw
290 If no units are specified, this primary evaluates to
291 true if the difference between the time of last change of file status
292 information and the time
294 was started, rounded up to the next full 24-hour period, is
298 If units are specified, this primary evaluates to
299 true if the difference between the time of last change of file status
300 information and the time
302 was started is exactly
307 primary description for information on supported time units.
311 GNU find implements this as a primary in mistaken emulation of
315 Delete found files and/or directories.
318 from the current working directory as
320 recurses down the tree.
321 It will not attempt to delete a filename with a
323 character in its pathname relative to
325 for security reasons.
326 Depth-first traversal processing is implied by this option.
327 Following symlinks is incompatible with this option.
334 True if the depth of the file relative to the starting point of the traversal
338 True if the current file or directory is empty.
339 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
340 True if the program named
342 returns a zero value as its exit status.
345 may be passed to the utility.
346 The expression must be terminated by a semicolon
350 from a shell you may need to quote the semicolon if the shell would
351 otherwise treat it as a control operator.
354 appears anywhere in the utility name or the
355 arguments it is replaced by the pathname of the current file.
357 will be executed from the directory from which
363 are not subject to the further expansion of shell patterns
365 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
370 is replaced with as many pathnames as possible for each invocation of
372 This behaviour is similar to that of
374 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
377 primary is identical to the
379 primary with the exception that
381 will be executed from the directory that holds
383 The filename substituted for
387 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
392 is replaced with as many pathnames as possible for each invocation of
394 This behaviour is similar to that of
396 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
397 The flags are specified using symbolic names (see
407 are checked to be set, and flags in
409 are checked to be not set.
410 Note that this is different from
412 which only allows the user to specify mode bits that are set.
414 If flags are preceded by a dash
416 this primary evaluates to true
417 if at least all of the bits in
419 and none of the bits in
421 are set in the file's flags bits.
422 If flags are preceded by a plus
424 this primary evaluates to true
425 if any of the bits in
427 is set in the file's flags bits,
428 or any of the bits in
430 is not set in the file's flags bits.
432 this primary evaluates to true
435 exactly match the file's flags bits,
440 .It Ic -fstype Ar type
441 True if the file is contained in a file system of type
445 command can be used to find out the types of file systems
446 that are available on the system:
450 In addition, there are two pseudo-types,
454 The former matches any file system physically mounted on the system where
457 is being executed and the latter matches any file system which is
462 for compatibility with GNU find.
463 GNU find imposes a restriction that
468 .It Ic -group Ar gname
469 True if the file belongs to the group
473 is numeric and there is no such group name, then
475 is treated as a group ID.
476 .It Ic -ignore_readdir_race
477 This option is for GNU find compatibility and is ignored.
478 .It Ic -ilname Ar pattern
481 but the match is case insensitive.
482 This is a GNU find extension.
483 .It Ic -iname Ar pattern
486 but the match is case insensitive.
488 True if the file has inode number
490 .It Ic -ipath Ar pattern
493 but the match is case insensitive.
494 .It Ic -iregex Ar pattern
497 but the match is case insensitive.
498 .It Ic -iwholename Ar pattern
501 for GNU find compatibility.
506 .It Ic -lname Ar pattern
509 but the contents of the symbolic link are matched instead of the file
511 This is a GNU find extension.
513 This primary always evaluates to true.
514 The following information for the current file is written to standard output:
515 its inode number, size in 512-byte blocks, file permissions, number of hard
516 links, owner, group, size in bytes, last modification time, and pathname.
517 If the file is a block or character special file, the major and minor numbers
518 will be displayed instead of the size in bytes.
519 If the file is a symbolic link, the pathname of the linked-to file will be
520 displayed preceded by
522 The format is identical to that produced by
526 .It Ic -maxdepth Ar n
527 Always true; descend at most
529 directory levels below the command line arguments.
532 primary is specified, it applies to the entire expression even if it would
533 not normally be evaluated.
534 .Dq Ic -maxdepth Li 0
535 limits the whole search to the command line arguments.
536 .It Ic -mindepth Ar n
537 Always true; do not apply any tests or actions at levels less than
541 primary is specified, it applies to the entire expression even if it would
542 not normally be evaluated.
543 .Dq Ic -mindepth Li 1
544 processes all but the command line arguments.
546 True if the difference between the file last modification time and the time
548 was started, rounded up to the next full minute, is
551 .It Ic -mnewer Ar file
557 for GNU find compatibility.
558 .It Ic -mtime Ar n Ns Op Cm smhdw
559 If no units are specified, this primary evaluates to
560 true if the difference between the file last modification time and the time
562 was started, rounded up to the next full 24-hour period, is
566 If units are specified, this primary evaluates to
567 true if the difference between the file last modification time and the time
569 was started is exactly
574 primary description for information on supported time units.
575 .It Ic -name Ar pattern
576 True if the last component of the pathname being examined matches
578 Special shell pattern matching characters
584 may be used as part of
586 These characters may be matched explicitly by escaping them with a
589 .It Ic -newer Ar file
590 True if the current file has a more recent last modification time than
592 .It Ic -newer Ns Ar X Ns Ar Y Ar file
593 True if the current file has a more recent last access time
594 .Pq Ar X Ns = Ns Cm a ,
596 .Pq Ar X Ns = Ns Cm B ,
598 .Pq Ar X Ns = Ns Cm c ,
600 .Pq Ar X Ns = Ns Cm m
601 than the last access time
602 .Pq Ar Y Ns = Ns Cm a ,
604 .Pq Ar Y Ns = Ns Cm B ,
606 .Pq Ar Y Ns = Ns Cm c ,
608 .Pq Ar Y Ns = Ns Cm m
615 is instead interpreted as a direct date specification of the form
623 True if the file belongs to an unknown group.
624 .It Ic -noignore_readdir_race
625 This option is for GNU find compatibility and is ignored.
627 This option is for GNU find compatibility.
628 In GNU find it disables an optimization not relevant to
632 True if the file belongs to an unknown user.
633 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
636 primary is identical to the
638 primary with the exception that
640 requests user affirmation for the execution of the
643 a message to the terminal and reading a response.
644 If the response is not affirmative
649 the command is not executed and the
653 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
656 primary is identical to the
658 primary with the same exception as described for the
661 .It Ic -path Ar pattern
662 True if 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
677 are treated as normal characters and do not have to be
679 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
682 may be either symbolic (see
687 is symbolic, a starting value of zero is assumed and the
689 sets or clears permissions without regard to the process' file mode
693 is octal, only bits 07777
694 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
695 of the file's mode bits participate
699 is preceded by a dash
701 this primary evaluates to true
702 if at least all of the bits in the
704 are set in the file's mode bits.
707 is preceded by a plus
709 this primary evaluates to true
710 if any of the bits in the
712 are set in the file's mode bits.
713 Otherwise, this primary evaluates to true if
716 exactly match the file's mode bits.
717 Note, the first character of a symbolic mode may not be a dash
720 This primary always evaluates to true.
721 It prints the pathname of the current file to standard output.
723 .Ic -exec , -ls , -print0 ,
726 is specified, the given expression shall be effectively replaced by
727 .Cm \&( Ar "given expression" Cm \&) Ic -print .
729 This primary always evaluates to true.
730 It prints the pathname of the current file to standard output, followed by an
733 character (character code 0).
735 This primary always evaluates to true.
738 to not descend into the current file.
741 primary has no effect if the
743 option was specified.
744 .It Ic -regex Ar pattern
745 True if the whole path of the file matches
747 using regular expression.
748 To match a file named
750 you can use the regular expression
758 .It Ic -samefile Ar name
759 True if the file is a hard link to
761 If the command option
763 is specified, it is also true if the file is a symbolic link and
766 .It Ic -size Ar n Ns Op Cm ckMGTP
767 True if the file's size, rounded up, in 512-byte blocks is
773 then the primary is true if the
779 is followed by a scale indicator then the file's size is compared to
783 .Bl -tag -width indent -compact
785 kilobytes (1024 bytes)
787 megabytes (1024 kilobytes)
789 gigabytes (1024 megabytes)
791 terabytes (1024 gigabytes)
793 petabytes (1024 terabytes)
796 True if the file is of the specified type.
797 Possible file types are as follows:
799 .Bl -tag -width indent -compact
818 for compatibility with GNU find.
819 GNU find imposes a restriction that
824 .It Ic -user Ar uname
825 True if the file belongs to the user
829 is numeric and there is no such user name, then
831 is treated as a user ID.
832 .It Ic -wholename Ar pattern
835 for GNU find compatibility.
838 The primaries may be combined using the following operators.
839 The operators are listed in order of decreasing precedence.
841 .Bl -tag -width indent -compact
842 .It Cm \&( Ar expression Cm \&)
843 This evaluates to true if the parenthesized expression evaluates to
846 .It Cm \&! Ar expression
847 .It Cm -not Ar expression
851 It evaluates to true if the expression is false.
858 .It Ar expression Cm -and Ar expression
859 .It Ar expression expression
862 operator is the logical
865 As it is implied by the juxtaposition of two expressions it does not
866 have to be specified.
867 The expression evaluates to true if both expressions are true.
868 The second expression is not evaluated if the first expression is false.
870 .It Ar expression Cm -or Ar expression
873 operator is the logical
876 The expression evaluates to true if either the first or the second expression
878 The second expression is not evaluated if the first expression is true.
881 All operands and primaries must be separate arguments to
883 Primaries which themselves take arguments expect each argument
884 to be a separate argument to
888 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
891 environment variables affect the execution of the
893 utility as described in
896 The following examples are shown as given to the shell:
897 .Bl -tag -width indent
898 .It Li "find / \e! -name \*q*.c\*q -print"
899 Print out a list of all the files whose names do not end in
901 .It Li "find / -newer ttt -user wnj -print"
902 Print out a list of all the files owned by user
907 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
908 Print out a list of all the files which are not both newer than
912 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
913 Print out a list of all the files that are either owned by
915 or that are newer than
917 .It Li "find / -newerct '1 minute ago' -print"
918 Print out a list of all the files whose inode change time is more
919 recent than the current time minus one minute.
920 .It Li "find / -type f -exec echo {} \e;"
923 command to print out a list of all the files.
924 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
925 Delete all broken symbolic links in
926 .Pa /usr/ports/packages .
927 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
928 Find files and directories that are at least seven levels deep
929 in the working directory
931 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
932 Is not equivalent to the previous example, since
934 is not evaluated below level seven.
939 primary is deprecated; the
941 option should be used instead.
944 section below for details.
964 utility syntax is a superset of the syntax specified by the
968 All the single character options except
973 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
974 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
975 .Ic -path , -print0 , -regex
978 birthtime related primaries are extensions to
985 options were implemented using the primaries
986 .Ic -depth , -follow ,
989 These primaries always evaluated to true.
990 As they were really global variables that took effect before the traversal
991 began, some legal expressions could have unexpected results.
992 An example is the expression
993 .Ic -print Cm -o Ic -depth .
996 always evaluates to true, the standard order of evaluation
999 would never be evaluated.
1000 This is not the case.
1011 Historic implementations of the
1015 primaries did not replace the string
1017 in the utility name or the
1018 utility arguments if it had preceding or following non-whitespace characters.
1019 This version replaces it no matter where in the utility name or arguments
1024 option was inspired by the equivalent
1035 The special characters used by
1037 are also special characters to many shell programs.
1038 In particular, the characters
1049 may have to be escaped from the shell.
1051 As there is no delimiter separating options and file names or file
1054 it is difficult to specify files named
1058 These problems are handled by the
1067 primary does not interact well with other options that cause the file system
1068 tree traversal options to be changed.
1074 primaries are actually global options (as documented above).
1076 probably be replaced by options which look like options.