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
184 .Bl -tag -width indent
186 True if the difference between the time of a file's inode creation
189 was started, rounded up to the next full minute, is
192 .It Ic -Bnewer Ar file
195 .It Ic -Btime Ar n Ns Op Cm smhdw
196 If no units are specified, this primary evaluates to
197 true if the difference between the time of a file's inode creation
200 was started, rounded up to the next full 24-hour period, is
204 If units are specified, this primary evaluates to
205 true if the difference between the time of a file's inode creation
208 was started is exactly
213 primary description for information on supported time units.
215 May be used in conjunction with other primaries to locate
216 files with extended ACLs.
219 for more information.
221 True if the difference between the file last access time and the time
223 was started, rounded up to the next full minute, is
226 .It Ic -anewer Ar file
229 .It Ic -atime Ar n Ns Op Cm smhdw
230 If no units are specified, this primary evaluates to
231 true if the difference between the file last access time and the time
233 was started, rounded up to the next full 24-hour period, is
237 If units are specified, this primary evaluates to
238 true if the difference between the file last access time and the time
240 was started is exactly
243 Possible time units are as follows:
245 .Bl -tag -width indent -compact
258 Any number of units may be combined in one
260 argument, for example,
261 .Dq Li "-atime -1h30m" .
262 Units are probably only useful when used in conjunction with the
268 True if the difference between the time of last change of file status
269 information and the time
271 was started, rounded up to the next full minute, is
274 .It Ic -cnewer Ar file
277 .It Ic -ctime Ar n Ns Op Cm smhdw
278 If no units are specified, this primary evaluates to
279 true if the difference between the time of last change of file status
280 information and the time
282 was started, rounded up to the next full 24-hour period, is
286 If units are specified, this primary evaluates to
287 true if the difference between the time of last change of file status
288 information and the time
290 was started is exactly
295 primary description for information on supported time units.
299 GNU find implements this as a primary in mistaken emulation of
303 Delete found files and/or directories.
306 from the current working directory as
308 recurses down the tree.
309 It will not attempt to delete a filename with a
311 character in its pathname relative to
313 for security reasons.
314 Depth-first traversal processing is implied by this option.
321 True if the depth of the file relative to the starting point of the traversal
325 True if the current file or directory is empty.
326 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
327 True if the program named
329 returns a zero value as its exit status.
332 may be passed to the utility.
333 The expression must be terminated by a semicolon
337 from a shell you may need to quote the semicolon if the shell would
338 otherwise treat it as a control operator.
341 appears anywhere in the utility name or the
342 arguments it is replaced by the pathname of the current file.
344 will be executed from the directory from which
350 are not subject to the further expansion of shell patterns
352 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
357 is replaced with as many pathnames as possible for each invocation of
359 This behaviour is similar to that of
361 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
364 primary is identical to the
366 primary with the exception that
368 will be executed from the directory that holds
370 The filename substituted for
374 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
379 is replaced with as many pathnames as possible for each invocation of
381 This behaviour is similar to that of
383 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
384 The flags are specified using symbolic names (see
394 are checked to be set, and flags in
396 are checked to be not set.
397 Note that this is different from
399 which only allows the user to specify mode bits that are set.
401 If flags are preceded by a dash
403 this primary evaluates to true
404 if at least all of the bits in
406 and none of the bits in
408 are set in the file's flags bits.
409 If flags are preceded by a plus
411 this primary evaluates to true
412 if any of the bits in
414 is set in the file's flags bits,
415 or any of the bits in
417 is not set in the file's flags bits.
419 this primary evaluates to true
422 exactly match the file's flags bits,
427 .It Ic -fstype Ar type
428 True if the file is contained in a file system of type
432 command can be used to find out the types of file systems
433 that are available on the system:
437 In addition, there are two pseudo-types,
441 The former matches any file system physically mounted on the system where
444 is being executed and the latter matches any file system which is
449 for compatibility with GNU find.
450 GNU find imposes a restriction that
455 .It Ic -group Ar gname
456 True if the file belongs to the group
460 is numeric and there is no such group name, then
462 is treated as a group ID.
463 .It Ic -ignore_readdir_race
464 This option is for GNU find compatibility and is ignored.
465 .It Ic -ilname Ar pattern
468 but the match is case insensitive.
469 This is a GNU find extension.
470 .It Ic -iname Ar pattern
473 but the match is case insensitive.
475 True if the file has inode number
477 .It Ic -ipath Ar pattern
480 but the match is case insensitive.
481 .It Ic -iregex Ar pattern
484 but the match is case insensitive.
485 .It Ic -iwholename Ar pattern
488 for GNU find compatibility.
493 .It Ic -lname Ar pattern
496 but the contents of the symbolic link are matched instead of the file
498 This is a GNU find extension.
500 This primary always evaluates to true.
501 The following information for the current file is written to standard output:
502 its inode number, size in 512-byte blocks, file permissions, number of hard
503 links, owner, group, size in bytes, last modification time, and pathname.
504 If the file is a block or character special file, the major and minor numbers
505 will be displayed instead of the size in bytes.
506 If the file is a symbolic link, the pathname of the linked-to file will be
507 displayed preceded by
509 The format is identical to that produced by
513 .It Ic -maxdepth Ar n
514 Always true; descend at most
516 directory levels below the command line arguments.
519 primary is specified, it applies to the entire expression even if it would
520 not normally be evaluated.
521 .Dq Ic -maxdepth Li 0
522 limits the whole search to the command line arguments.
523 .It Ic -mindepth Ar n
524 Always true; do not apply any tests or actions at levels less than
528 primary is specified, it applies to the entire expression even if it would
529 not normally be evaluated.
530 .Dq Ic -mindepth Li 1
531 processes all but the command line arguments.
533 True if the difference between the file last modification time and the time
535 was started, rounded up to the next full minute, is
538 .It Ic -mnewer Ar file
544 for GNU find compatibility.
545 .It Ic -mtime Ar n Ns Op Cm smhdw
546 If no units are specified, this primary evaluates to
547 true if the difference between the file last modification time and the time
549 was started, rounded up to the next full 24-hour period, is
553 If units are specified, this primary evaluates to
554 true if the difference between the file last modification time and the time
556 was started is exactly
561 primary description for information on supported time units.
562 .It Ic -name Ar pattern
563 True if the last component of the pathname being examined matches
565 Special shell pattern matching characters
571 may be used as part of
573 These characters may be matched explicitly by escaping them with a
576 .It Ic -newer Ar file
577 True if the current file has a more recent last modification time than
579 .It Ic -newer Ns Ar X Ns Ar Y Ar file
580 True if the current file has a more recent last access time
581 .Pq Ar X Ns = Ns Cm a ,
583 .Pq Ar X Ns = Ns Cm B ,
585 .Pq Ar X Ns = Ns Cm c ,
587 .Pq Ar X Ns = Ns Cm m
588 than the last access time
589 .Pq Ar Y Ns = Ns Cm a ,
591 .Pq Ar Y Ns = Ns Cm B ,
593 .Pq Ar Y Ns = Ns Cm c ,
595 .Pq Ar Y Ns = Ns Cm m
602 is instead interpreted as a direct date specification of the form
610 True if the file belongs to an unknown group.
611 .It Ic -noignore_readdir_race
612 This option is for GNU find compatibility and is ignored.
614 This option is for GNU find compatibility.
615 In GNU find it disables an optimization not relevant to
619 True if the file belongs to an unknown user.
620 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
623 primary is identical to the
625 primary with the exception that
627 requests user affirmation for the execution of the
630 a message to the terminal and reading a response.
631 If the response is not affirmative
636 the command is not executed and the
640 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
643 primary is identical to the
645 primary with the same exception as described for the
648 .It Ic -path Ar pattern
649 True if the pathname being examined matches
651 Special shell pattern matching characters
657 may be used as part of
659 These characters may be matched explicitly by escaping them with a
664 are treated as normal characters and do not have to be
666 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
669 may be either symbolic (see
674 is symbolic, a starting value of zero is assumed and the
676 sets or clears permissions without regard to the process' file mode
680 is octal, only bits 07777
681 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
682 of the file's mode bits participate
686 is preceded by a dash
688 this primary evaluates to true
689 if at least all of the bits in the
691 are set in the file's mode bits.
694 is preceded by a plus
696 this primary evaluates to true
697 if any of the bits in the
699 are set in the file's mode bits.
700 Otherwise, this primary evaluates to true if
703 exactly match the file's mode bits.
704 Note, the first character of a symbolic mode may not be a dash
707 This primary always evaluates to true.
708 It prints the pathname of the current file to standard output.
710 .Ic -exec , -ls , -print0 ,
713 is specified, the given expression shall be effectively replaced by
714 .Cm \&( Ar "given expression" Cm \&) Ic -print .
716 This primary always evaluates to true.
717 It prints the pathname of the current file to standard output, followed by an
720 character (character code 0).
722 This primary always evaluates to true.
725 to not descend into the current file.
728 primary has no effect if the
730 option was specified.
731 .It Ic -regex Ar pattern
732 True if the whole path of the file matches
734 using regular expression.
735 To match a file named
737 you can use the regular expression
745 .It Ic -samefile Ar name
746 True if the file is a hard link to
748 If the command option
750 is specified, it is also true if the file is a symbolic link and
753 .It Ic -size Ar n Ns Op Cm ckMGTP
754 True if the file's size, rounded up, in 512-byte blocks is
760 then the primary is true if the
766 is followed by a scale indicator then the file's size is compared to
770 .Bl -tag -width indent -compact
772 kilobytes (1024 bytes)
774 megabytes (1024 kilobytes)
776 gigabytes (1024 megabytes)
778 terabytes (1024 gigabytes)
780 petabytes (1024 terabytes)
783 True if the file is of the specified type.
784 Possible file types are as follows:
786 .Bl -tag -width indent -compact
805 for compatibility with GNU find.
806 GNU find imposes a restriction that
811 .It Ic -user Ar uname
812 True if the file belongs to the user
816 is numeric and there is no such user name, then
818 is treated as a user ID.
819 .It Ic -wholename Ar pattern
822 for GNU find compatibility.
825 All primaries which take a numeric argument allow the number to be
826 preceded by a plus sign
830 A preceding plus sign means
832 a preceding minus sign means
837 The primaries may be combined using the following operators.
838 The operators are listed in order of decreasing precedence.
840 .Bl -tag -width indent -compact
841 .It Cm \&( Ar expression Cm \&)
842 This evaluates to true if the parenthesized expression evaluates to
845 .It Cm \&! Ar expression
846 .It Cm -not Ar expression
850 It evaluates to true if the expression is false.
857 .It Ar expression Cm -and Ar expression
858 .It Ar expression expression
861 operator is the logical
864 As it is implied by the juxtaposition of two expressions it does not
865 have to be specified.
866 The expression evaluates to true if both expressions are true.
867 The second expression is not evaluated if the first expression is false.
869 .It Ar expression Cm -or Ar expression
872 operator is the logical
875 The expression evaluates to true if either the first or the second expression
877 The second expression is not evaluated if the first expression is true.
880 All operands and primaries must be separate arguments to
882 Primaries which themselves take arguments expect each argument
883 to be a separate argument to
887 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
890 environment variables affect the execution of the
892 utility as described in
895 The following examples are shown as given to the shell:
896 .Bl -tag -width indent
897 .It Li "find / \e! -name \*q*.c\*q -print"
898 Print out a list of all the files whose names do not end in
900 .It Li "find / -newer ttt -user wnj -print"
901 Print out a list of all the files owned by user
906 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
907 Print out a list of all the files which are not both newer than
911 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
912 Print out a list of all the files that are either owned by
914 or that are newer than
916 .It Li "find / -newerct '1 minute ago' -print"
917 Print out a list of all the files whose inode change time is more
918 recent than the current time minus one minute.
919 .It Li "find / -type f -exec echo {} \e;"
922 command to print out a list of all the files.
923 .It Li "find -L /usr/ports/packages -type l -delete"
924 Delete all broken symbolic links in
925 .Pa /usr/ports/packages .
926 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
927 Find files and directories that are at least seven levels deep
928 in the working directory
930 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
931 Is not equivalent to the previous example, since
933 is not evaluated below level seven.
938 primary is deprecated; the
940 option should be used instead.
943 section below for details.
963 utility syntax is a superset of the syntax specified by the
967 All the single character options except
972 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
973 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
974 .Ic -path , -print0 , -regex
977 birthtime related primaries are extensions to
984 options were implemented using the primaries
985 .Ic -depth , -follow ,
988 These primaries always evaluated to true.
989 As they were really global variables that took effect before the traversal
990 began, some legal expressions could have unexpected results.
991 An example is the expression
992 .Ic -print Cm -o Ic -depth .
995 always evaluates to true, the standard order of evaluation
998 would never be evaluated.
999 This is not the case.
1010 Historic implementations of the
1014 primaries did not replace the string
1016 in the utility name or the
1017 utility arguments if it had preceding or following non-whitespace characters.
1018 This version replaces it no matter where in the utility name or arguments
1023 option was inspired by the equivalent
1034 The special characters used by
1036 are also special characters to many shell programs.
1037 In particular, the characters
1048 may have to be escaped from the shell.
1050 As there is no delimiter separating options and file names or file
1053 it is difficult to specify files named
1057 These problems are handled by the
1066 primary does not interact well with other options that cause the file system
1067 tree traversal options to be changed.
1073 primaries are actually global options (as documented above).
1075 probably be replaced by options which look like options.