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 .\" 4. 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
31 .\" @(#)find.1 8.7 (Berkeley) 5/9/95
39 .Nd walk a file hierarchy
42 .Op Fl H | Fl L | Fl P
48 .Op Fl H | Fl L | Fl P
56 utility recursively descends the directory tree for each
64 listed below) in terms
65 of each file in the tree.
67 The options are as follows:
68 .Bl -tag -width indent
70 Interpret regular expressions followed by
74 primaries as extended (modern) regular expressions rather than basic
75 regular expressions (BRE's).
78 manual page fully describes both formats.
80 Cause the file information and file type (see
82 returned for each symbolic link specified on the command line to be
83 those of the file referenced by the link, not the link itself.
84 If the referenced file does not exist, the file information and type will
85 be for the link itself.
86 File information of all symbolic links not on
87 the command line is that of the link itself.
89 Cause the file information and file type (see
91 returned for each symbolic link to be those of the file referenced by the
92 link, not the link itself.
93 If the referenced file does not exist, the file information and type will
94 be for the link itself.
96 This option is equivalent to the deprecated
100 Cause the file information and file type (see
102 returned for each symbolic link to be those of the link itself.
107 to be safely used in conjunction with
109 If a file name contains any of the delimiting characters used by
111 a diagnostic message is displayed on standard error, and the file
113 The delimiting characters include single
119 space, tab and newline characters.
121 However, you may wish to consider the
123 primary in conjunction with
125 as an effective alternative.
129 to perform a depth-first traversal.
131 This option is a BSD-specific equivalent of the
135 Refer to its description under
137 for more information.
141 to traverse the file hierarchies in lexicographical order,
142 i.e., alphabetical order within each directory.
147 may give different results.
151 from descending into directories that have a device number different
152 than that of the file from which the descent began.
154 This option is equivalent to the deprecated
160 All primaries which take a numeric argument allow the number to be
161 preceded by a plus sign
165 A preceding plus sign means
167 a preceding minus sign means
171 .Bl -tag -width indent
173 True if the difference between the time of a file's inode creation
176 was started, rounded up to the next full minute, is
179 .It Ic -Bnewer Ar file
182 .It Ic -Btime Ar n Ns Op Cm smhdw
183 If no units are specified, this primary evaluates to
184 true if the difference between the time of a file's inode creation
187 was started, rounded up to the next full 24-hour period, is
191 If units are specified, this primary evaluates to
192 true if the difference between the time of a file's inode creation
195 was started is exactly
200 primary description for information on supported time units.
202 May be used in conjunction with other primaries to locate
203 files with extended ACLs.
206 for more information.
208 True if the difference between the file last access time and the time
210 was started, rounded up to the next full minute, is
213 .It Ic -anewer Ar file
216 .It Ic -atime Ar n Ns Op Cm smhdw
217 If no units are specified, this primary evaluates to
218 true if the difference between the file last access time and the time
220 was started, rounded up to the next full 24-hour period, is
224 If units are specified, this primary evaluates to
225 true if the difference between the file last access time and the time
227 was started is exactly
230 Possible time units are as follows:
232 .Bl -tag -width indent -compact
245 Any number of units may be combined in one
247 argument, for example,
248 .Dq Li "-atime -1h30m" .
249 Units are probably only useful when used in conjunction with the
255 True if the difference between the time of last change of file status
256 information and the time
258 was started, rounded up to the next full minute, is
261 .It Ic -cnewer Ar file
264 .It Ic -ctime Ar n Ns Op Cm smhdw
265 If no units are specified, this primary evaluates to
266 true if the difference between the time of last change of file status
267 information and the time
269 was started, rounded up to the next full 24-hour period, is
273 If units are specified, this primary evaluates to
274 true if the difference between the time of last change of file status
275 information and the time
277 was started is exactly
282 primary description for information on supported time units.
284 Non-portable, BSD-specific version of
286 GNU find implements this as a primary in mistaken emulation of
290 Delete found files and/or directories.
293 from the current working directory as
295 recurses down the tree.
296 It will not attempt to delete a filename with a
298 character in its pathname relative to
300 for security reasons.
301 Depth-first traversal processing is implied by this option.
302 Following symlinks is incompatible with this option.
305 same as the non-portable
310 to perform a depth-first traversal, i.e., directories
311 are visited in post-order and all entries in a directory will be acted
312 on before the directory itself.
315 visits directories in pre-order, i.e., before their contents.
318 a breadth-first traversal.
327 to process files that are contained in directories with unusual permissions.
328 It ensures that you have write permission while you are placing files in a
329 directory, then sets the directory's permissions as the last thing.
331 True if the depth of the file relative to the starting point of the traversal
335 True if the current file or directory is empty.
336 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
337 True if the program named
339 returns a zero value as its exit status.
342 may be passed to the utility.
343 The expression must be terminated by a semicolon
347 from a shell you may need to quote the semicolon if the shell would
348 otherwise treat it as a control operator.
351 appears anywhere in the utility name or the
352 arguments it is replaced by the pathname of the current file.
354 will be executed from the directory from which
360 are not subject to the further expansion of shell patterns
362 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
367 is replaced with as many pathnames as possible for each invocation of
369 This behaviour is similar to that of
371 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
374 primary is identical to the
376 primary with the exception that
378 will be executed from the directory that holds
380 The filename substituted for
384 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
389 is replaced with as many pathnames as possible for each invocation of
391 This behaviour is similar to that of
393 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
394 The flags are specified using symbolic names (see
404 are checked to be set, and flags in
406 are checked to be not set.
407 Note that this is different from
409 which only allows the user to specify mode bits that are set.
411 If flags are preceded by a dash
413 this primary evaluates to true
414 if at least all of the bits in
416 and none of the bits in
418 are set in the file's flags bits.
419 If flags are preceded by a plus
421 this primary evaluates to true
422 if any of the bits in
424 is set in the file's flags bits,
425 or any of the bits in
427 is not set in the file's flags bits.
429 this primary evaluates to true
432 exactly match the file's flags bits,
437 .It Ic -fstype Ar type
438 True if the file is contained in a file system of type
442 command can be used to find out the types of file systems
443 that are available on the system.
444 In addition, there are two pseudo-types,
448 The former matches any file system physically mounted on the system where
451 is being executed and the latter matches any file system which is
456 for compatibility with GNU find.
457 GNU find imposes a restriction that
462 .It Ic -group Ar gname
463 True if the file belongs to the group
467 is numeric and there is no such group name, then
469 is treated as a group ID.
470 .It Ic -ignore_readdir_race
471 This option is for GNU find compatibility and is ignored.
472 .It Ic -ilname Ar pattern
475 but the match is case insensitive.
476 This is a GNU find extension.
477 .It Ic -iname Ar pattern
480 but the match is case insensitive.
482 True if the file has inode number
484 .It Ic -ipath Ar pattern
487 but the match is case insensitive.
488 .It Ic -iregex Ar pattern
491 but the match is case insensitive.
492 .It Ic -iwholename Ar pattern
495 for GNU find compatibility.
500 .It Ic -lname Ar pattern
503 but the contents of the symbolic link are matched instead of the file
505 This is a GNU find extension.
507 This primary always evaluates to true.
508 The following information for the current file is written to standard output:
509 its inode number, size in 512-byte blocks, file permissions, number of hard
510 links, owner, group, size in bytes, last modification time, and pathname.
511 If the file is a block or character special file, the major and minor numbers
512 will be displayed instead of the size in bytes.
513 If the file is a symbolic link, the pathname of the linked-to file will be
514 displayed preceded by
516 The format is identical to that produced by
520 .It Ic -maxdepth Ar n
521 Always true; descend at most
523 directory levels below the command line arguments.
526 primary is specified, it applies to the entire expression even if it would
527 not normally be evaluated.
528 .Dq Ic -maxdepth Li 0
529 limits the whole search to the command line arguments.
530 .It Ic -mindepth Ar n
531 Always true; do not apply any tests or actions at levels less than
535 primary is specified, it applies to the entire expression even if it would
536 not normally be evaluated.
537 .Dq Ic -mindepth Li 1
538 processes all but the command line arguments.
540 True if the difference between the file last modification time and the time
542 was started, rounded up to the next full minute, is
545 .It Ic -mnewer Ar file
551 for GNU find compatibility.
552 .It Ic -mtime Ar n Ns Op Cm smhdw
553 If no units are specified, this primary evaluates to
554 true if the difference between the file last modification time and the time
556 was started, rounded up to the next full 24-hour period, is
560 If units are specified, this primary evaluates to
561 true if the difference between the file last modification time and the time
563 was started is exactly
568 primary description for information on supported time units.
569 .It Ic -name Ar pattern
570 True if the last component of the pathname being examined matches
572 Special shell pattern matching characters
578 may be used as part of
580 These characters may be matched explicitly by escaping them with a
583 .It Ic -newer Ar file
584 True if the current file has a more recent last modification time than
586 .It Ic -newer Ns Ar X Ns Ar Y Ar file
587 True if the current file has a more recent last access time
588 .Pq Ar X Ns = Ns Cm a ,
590 .Pq Ar X Ns = Ns Cm B ,
592 .Pq Ar X Ns = Ns Cm c ,
594 .Pq Ar X Ns = Ns Cm m
595 than the last access time
596 .Pq Ar Y Ns = Ns Cm a ,
598 .Pq Ar Y Ns = Ns Cm B ,
600 .Pq Ar Y Ns = Ns Cm c ,
602 .Pq Ar Y Ns = Ns Cm m
609 is instead interpreted as a direct date specification of the form
617 True if the file belongs to an unknown group.
618 .It Ic -noignore_readdir_race
619 This option is for GNU find compatibility and is ignored.
621 This option is for GNU find compatibility.
622 In GNU find it disables an optimization not relevant to
626 True if the file belongs to an unknown user.
627 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
630 primary is identical to the
632 primary with the exception that
634 requests user affirmation for the execution of the
637 a message to the terminal and reading a response.
638 If the response is not affirmative
643 the command is not executed and the
647 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
650 primary is identical to the
652 primary with the same exception as described for the
655 .It Ic -path Ar pattern
656 True if the pathname being examined matches
658 Special shell pattern matching characters
664 may be used as part of
666 These characters may be matched explicitly by escaping them with a
671 are treated as normal characters and do not have to be
673 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
676 may be either symbolic (see
681 is symbolic, a starting value of zero is assumed and the
683 sets or clears permissions without regard to the process' file mode
687 is octal, only bits 07777
688 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
689 of the file's mode bits participate
693 is preceded by a dash
695 this primary evaluates to true
696 if at least all of the bits in the
698 are set in the file's mode bits.
701 is preceded by a plus
703 this primary evaluates to true
704 if any of the bits in the
706 are set in the file's mode bits.
707 Otherwise, this primary evaluates to true if
710 exactly match the file's mode bits.
711 Note, the first character of a symbolic mode may not be a dash
714 This primary always evaluates to true.
715 It prints the pathname of the current file to standard output.
717 .Ic -exec , -ls , -print0 ,
720 is specified, the given expression shall be effectively replaced by
721 .Cm \&( Ar "given expression" Cm \&) Ic -print .
723 This primary always evaluates to true.
724 It prints the pathname of the current file to standard output, followed by an
727 character (character code 0).
729 This primary always evaluates to true.
732 to not descend into the current file.
735 primary has no effect if the
737 option was specified.
741 to immediately terminate.
742 .It Ic -regex Ar pattern
743 True if the whole path of the file matches
745 using regular expression.
746 To match a file named
748 you can use the regular expression
756 .It Ic -samefile Ar name
757 True if the file is a hard link to
759 If the command option
761 is specified, it is also true if the file is a symbolic link and
764 .It Ic -size Ar n Ns Op Cm ckMGTP
765 True if the file's size, rounded up, in 512-byte blocks is
771 then the primary is true if the
777 is followed by a scale indicator then the file's size is compared to
781 .Bl -tag -width indent -compact
783 kilobytes (1024 bytes)
785 megabytes (1024 kilobytes)
787 gigabytes (1024 megabytes)
789 terabytes (1024 gigabytes)
791 petabytes (1024 terabytes)
794 True if the file is of the specified type.
795 Possible file types are as follows:
797 .Bl -tag -width indent -compact
816 for compatibility with GNU find.
817 GNU find imposes a restriction that
822 .It Ic -user Ar uname
823 True if the file belongs to the user
827 is numeric and there is no such user name, then
829 is treated as a user ID.
830 .It Ic -wholename Ar pattern
833 for GNU find compatibility.
836 The primaries may be combined using the following operators.
837 The operators are listed in order of decreasing precedence.
839 .Bl -tag -width indent -compact
840 .It Cm \&( Ar expression Cm \&)
841 This evaluates to true if the parenthesized expression evaluates to
844 .It Cm \&! Ar expression
845 .It Cm -not Ar expression
849 It evaluates to true if the expression is false.
856 .It Ar expression Cm -and Ar expression
857 .It Ar expression expression
860 operator is the logical
863 As it is implied by the juxtaposition of two expressions it does not
864 have to be specified.
865 The expression evaluates to true if both expressions are true.
866 The second expression is not evaluated if the first expression is false.
868 .It Ar expression Cm -or Ar expression
871 operator is the logical
874 The expression evaluates to true if either the first or the second expression
876 The second expression is not evaluated if the first expression is true.
879 All operands and primaries must be separate arguments to
881 Primaries which themselves take arguments expect each argument
882 to be a separate argument to
886 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
889 environment variables affect the execution of the
891 utility as described in
894 The following examples are shown as given to the shell:
895 .Bl -tag -width indent
896 .It Li "find / \e! -name \*q*.c\*q -print"
897 Print out a list of all the files whose names do not end in
899 .It Li "find / -newer ttt -user wnj -print"
900 Print out a list of all the files owned by user
905 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
906 Print out a list of all the files which are not both newer than
910 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
911 Print out a list of all the files that are either owned by
913 or that are newer than
915 .It Li "find / -newerct '1 minute ago' -print"
916 Print out a list of all the files whose inode change time is more
917 recent than the current time minus one minute.
918 .It Li "find / -type f -exec echo {} \e;"
921 command to print out a list of all the files.
922 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
923 Delete all broken symbolic links in
924 .Pa /usr/ports/packages .
925 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
926 Find files and directories that are at least seven levels deep
927 in the working directory
929 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
930 Is not equivalent to the previous example, since
932 is not evaluated below level seven.
937 primary is deprecated; the
939 option should be used instead.
942 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.