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
159 All primaries which take a numeric argument allow the number to be
160 preceded by a plus sign
164 A preceding plus sign means
166 a preceding minus sign means
170 .Bl -tag -width indent
172 True if the difference between the time of a file's inode creation
175 was started, rounded up to the next full minute, is
178 .It Ic -Bnewer Ar file
181 .It Ic -Btime Ar n Ns Op Cm smhdw
182 If no units are specified, this primary evaluates to
183 true if the difference between the time of a file's inode creation
186 was started, rounded up to the next full 24-hour period, is
190 If units are specified, this primary evaluates to
191 true if the difference between the time of a file's inode creation
194 was started is exactly
199 primary description for information on supported time units.
201 May be used in conjunction with other primaries to locate
202 files with extended ACLs.
205 for more information.
206 .It Ic -amin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
207 True if the difference between the file last access time and the time
209 was started, rounded up to the next full minute, is
219 .It Ic -anewer Ar file
222 .It Ic -atime Ar n Ns Op Cm smhdw
223 If no units are specified, this primary evaluates to
224 true if the difference between the file last access time and the time
226 was started, rounded up to the next full 24-hour period, is
230 If units are specified, this primary evaluates to
231 true if the difference between the file last access time and the time
233 was started is exactly
236 Possible time units are as follows:
238 .Bl -tag -width indent -compact
251 Any number of units may be combined in one
253 argument, for example,
254 .Dq Li "-atime -1h30m" .
255 Units are probably only useful when used in conjunction with the
260 .It Ic -cmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
261 True if the difference between the time of last change of file status
262 information and the time
264 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.
297 Non-portable, BSD-specific version of
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.
317 primary will fail to delete a directory if it is not empty.
318 Following symlinks is incompatible with this option.
321 same as the non-portable
326 to perform a depth-first traversal, i.e., directories
327 are visited in post-order and all entries in a directory will be acted
328 on before the directory itself.
331 visits directories in pre-order, i.e., before their contents.
334 a breadth-first traversal.
343 to process files that are contained in directories with unusual permissions.
344 It ensures that you have write permission while you are placing files in a
345 directory, then sets the directory's permissions as the last thing.
347 True if the depth of the file relative to the starting point of the traversal
351 True if the current file or directory is empty.
352 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
353 True if the program named
355 returns a zero value as its exit status.
358 may be passed to the utility.
359 The expression must be terminated by a semicolon
363 from a shell you may need to quote the semicolon if the shell would
364 otherwise treat it as a control operator.
367 appears anywhere in the utility name or the
368 arguments it is replaced by the pathname of the current file.
370 will be executed from the directory from which
376 are not subject to the further expansion of shell patterns
378 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
383 is replaced with as many pathnames as possible for each invocation of
385 This behaviour is similar to that of
387 The primary always returns true;
388 if at least one invocation of
390 returns a non-zero exit status,
392 will return a non-zero exit status.
393 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
396 primary is identical to the
398 primary with the exception that
400 will be executed from the directory that holds
402 The filename substituted for
406 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
411 is replaced with as many pathnames as possible for each invocation of
413 This behaviour is similar to that of
415 The primary always returns true;
416 if at least one invocation of
418 returns a non-zero exit status,
420 will return a non-zero exit status.
421 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
422 The flags are specified using symbolic names (see
432 are checked to be set, and flags in
434 are checked to be not set.
435 Note that this is different from
437 which only allows the user to specify mode bits that are set.
439 If flags are preceded by a dash
441 this primary evaluates to true
442 if at least all of the bits in
444 and none of the bits in
446 are set in the file's flags bits.
447 If flags are preceded by a plus
449 this primary evaluates to true
450 if any of the bits in
452 is set in the file's flags bits,
453 or any of the bits in
455 is not set in the file's flags bits.
457 this primary evaluates to true
460 exactly match the file's flags bits,
465 .It Ic -fstype Ar type
466 True if the file is contained in a file system of type
470 command can be used to find out the types of file systems
471 that are available on the system.
472 In addition, there are two pseudo-types,
476 The former matches any file system physically mounted on the system where
479 is being executed and the latter matches any file system which is
484 for compatibility with GNU find.
485 GNU find imposes a restriction that
490 .It Ic -group Ar gname
491 True if the file belongs to the group
495 is numeric and there is no such group name, then
497 is treated as a group ID.
498 .It Ic -ignore_readdir_race
499 Ignore errors because a file or a directory is deleted
500 after reading the name from a directory.
501 This option does not affect errors occurring on starting points.
502 .It Ic -ilname Ar pattern
505 but the match is case insensitive.
506 This is a GNU find extension.
507 .It Ic -iname Ar pattern
510 but the match is case insensitive.
512 True if the file has inode number
514 .It Ic -ipath Ar pattern
517 but the match is case insensitive.
518 .It Ic -iregex Ar pattern
521 but the match is case insensitive.
522 .It Ic -iwholename Ar pattern
525 for GNU find compatibility.
530 .It Ic -lname Ar pattern
533 but the contents of the symbolic link are matched instead of the file
535 Note that this only matches broken symbolic links
536 if symbolic links are being followed.
537 This is a GNU find extension.
539 This primary always evaluates to true.
540 The following information for the current file is written to standard output:
541 its inode number, size in 512-byte blocks, file permissions, number of hard
542 links, owner, group, size in bytes, last modification time, and pathname.
543 If the file is a block or character special file, the device number
544 will be displayed instead of the size in bytes.
545 If the file is a symbolic link, the pathname of the linked-to file will be
546 displayed preceded by
548 The format is identical to that produced by
552 .It Ic -maxdepth Ar n
553 Always true; descend at most
555 directory levels below the command line arguments.
558 primary is specified, it applies to the entire expression even if it would
559 not normally be evaluated.
560 .Dq Ic -maxdepth Li 0
561 limits the whole search to the command line arguments.
562 .It Ic -mindepth Ar n
563 Always true; do not apply any tests or actions at levels less than
567 primary is specified, it applies to the entire expression even if it would
568 not normally be evaluated.
569 .Dq Ic -mindepth Li 1
570 processes all but the command line arguments.
571 .It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
572 True if the difference between the file last modification time and the time
574 was started, rounded up to the next full minute, is
583 .It Ic -mnewer Ar file
589 for GNU find compatibility.
590 .It Ic -mtime Ar n Ns Op Cm smhdw
591 If no units are specified, this primary evaluates to
592 true if the difference between the file last modification time and the time
594 was started, rounded up to the next full 24-hour period, is
598 If units are specified, this primary evaluates to
599 true if the difference between the file last modification time and the time
601 was started is exactly
606 primary description for information on supported time units.
607 .It Ic -name Ar pattern
608 True if the last component of the pathname being examined matches
610 Special shell pattern matching characters
616 may be used as part of
618 These characters may be matched explicitly by escaping them with a
621 .It Ic -newer Ar file
622 True if the current file has a more recent last modification time than
624 .It Ic -newer Ns Ar X Ns Ar Y Ar file
625 True if the current file has a more recent last access time
626 .Pq Ar X Ns = Ns Cm a ,
628 .Pq Ar X Ns = Ns Cm B ,
630 .Pq Ar X Ns = Ns Cm c ,
632 .Pq Ar X Ns = Ns Cm m
633 than the last access time
634 .Pq Ar Y Ns = Ns Cm a ,
636 .Pq Ar Y Ns = Ns Cm B ,
638 .Pq Ar Y Ns = Ns Cm c ,
640 .Pq Ar Y Ns = Ns Cm m
647 is instead interpreted as a direct date specification of the form
655 True if the file belongs to an unknown group.
656 .It Ic -noignore_readdir_race
657 Turn off the effect of
658 .Ic -ignore_readdir_race .
659 This is default behaviour.
661 This option is for GNU find compatibility.
662 In GNU find it disables an optimization not relevant to
666 True if the file belongs to an unknown user.
667 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
670 primary is identical to the
672 primary with the exception that
674 requests user affirmation for the execution of the
677 a message to the terminal and reading a response.
678 If the response is not affirmative
683 the command is not executed and the
687 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
690 primary is identical to the
692 primary with the same exception as described for the
695 .It Ic -path Ar pattern
696 True if the pathname being examined matches
698 Special shell pattern matching characters
704 may be used as part of
706 These characters may be matched explicitly by escaping them with a
711 are treated as normal characters and do not have to be
713 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
716 may be either symbolic (see
721 is symbolic, a starting value of zero is assumed and the
723 sets or clears permissions without regard to the process' file mode
727 is octal, only bits 07777
728 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
729 of the file's mode bits participate
733 is preceded by a dash
735 this primary evaluates to true
736 if at least all of the bits in the
738 are set in the file's mode bits.
741 is preceded by a plus
743 this primary evaluates to true
744 if any of the bits in the
746 are set in the file's mode bits.
747 Otherwise, this primary evaluates to true if
750 exactly match the file's mode bits.
751 Note, the first character of a symbolic mode may not be a dash
754 This primary always evaluates to true.
755 It prints the pathname of the current file to standard output.
757 .Ic -exec , -ls , -print0 ,
760 is specified, the given expression shall be effectively replaced by
761 .Cm \&( Ar "given expression" Cm \&) Ic -print .
763 This primary always evaluates to true.
764 It prints the pathname of the current file to standard output, followed by an
767 character (character code 0).
769 This primary always evaluates to true.
772 to not descend into the current file.
775 primary has no effect if the
777 option was specified.
781 to terminate immediately.
782 .It Ic -regex Ar pattern
783 True if the whole path of the file matches
785 using regular expression.
786 To match a file named
788 you can use the regular expression
796 .It Ic -samefile Ar name
797 True if the file is a hard link to
799 If the command option
801 is specified, it is also true if the file is a symbolic link and
804 .It Ic -size Ar n Ns Op Cm ckMGTP
805 True if the file's size, rounded up, in 512-byte blocks is
811 then the primary is true if the
817 is followed by a scale indicator then the file's size is compared to
821 .Bl -tag -width indent -compact
823 kilobytes (1024 bytes)
825 megabytes (1024 kilobytes)
827 gigabytes (1024 megabytes)
829 terabytes (1024 gigabytes)
831 petabytes (1024 terabytes)
834 True if the current file is sparse,
835 i.e. has fewer blocks allocated than expected based on its size in bytes.
836 This might also match files that have been compressed by the filesystem.
838 True if the file is of the specified type.
839 Possible file types are as follows:
841 .Bl -tag -width indent -compact
860 for compatibility with GNU find.
861 GNU find imposes a restriction that
866 .It Ic -user Ar uname
867 True if the file belongs to the user
871 is numeric and there is no such user name, then
873 is treated as a user ID.
874 .It Ic -wholename Ar pattern
877 for GNU find compatibility.
880 The primaries may be combined using the following operators.
881 The operators are listed in order of decreasing precedence.
883 .Bl -tag -width indent -compact
884 .It Cm \&( Ar expression Cm \&)
885 This evaluates to true if the parenthesized expression evaluates to
888 .It Cm \&! Ar expression
889 .It Cm -not Ar expression
893 It evaluates to true if the expression is false.
900 .It Ar expression Cm -and Ar expression
901 .It Ar expression expression
904 operator is the logical
907 As it is implied by the juxtaposition of two expressions it does not
908 have to be specified.
909 The expression evaluates to true if both expressions are true.
910 The second expression is not evaluated if the first expression is false.
912 .It Ar expression Cm -or Ar expression
915 operator is the logical
918 The expression evaluates to true if either the first or the second expression
920 The second expression is not evaluated if the first expression is true.
923 All operands and primaries must be separate arguments to
925 Primaries which themselves take arguments expect each argument
926 to be a separate argument to
930 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
933 environment variables affect the execution of the
935 utility as described in
938 The following examples are shown as given to the shell:
939 .Bl -tag -width indent
940 .It Li "find / \e! -name \*q*.c\*q -print"
941 Print out a list of all the files whose names do not end in
943 .It Li "find / -newer ttt -user wnj -print"
944 Print out a list of all the files owned by user
949 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
950 Print out a list of all the files which are not both newer than
954 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
955 Print out a list of all the files that are either owned by
957 or that are newer than
959 .It Li "find / -newerct '1 minute ago' -print"
960 Print out a list of all the files whose inode change time is more
961 recent than the current time minus one minute.
962 .It Li "find / -type f -exec echo {} \e;"
965 command to print out a list of all the files.
966 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
967 Delete all broken symbolic links in
968 .Pa /usr/ports/packages .
969 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
970 Find files and directories that are at least seven levels deep
971 in the working directory
973 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
974 Is not equivalent to the previous example, since
976 is not evaluated below level seven.
981 primary is deprecated; the
983 option should be used instead.
986 section below for details.
1007 utility syntax is a superset of the syntax specified by the
1011 All the single character options except
1016 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
1017 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
1018 .Ic -path , -print0 , -regex , -sparse
1021 birthtime related primaries are extensions to
1028 options were implemented using the primaries
1029 .Ic -depth , -follow ,
1032 These primaries always evaluated to true.
1033 As they were really global variables that took effect before the traversal
1034 began, some legal expressions could have unexpected results.
1035 An example is the expression
1036 .Ic -print Cm -o Ic -depth .
1039 always evaluates to true, the standard order of evaluation
1042 would never be evaluated.
1043 This is not the case.
1054 Historic implementations of the
1058 primaries did not replace the string
1060 in the utility name or the
1061 utility arguments if it had preceding or following non-whitespace characters.
1062 This version replaces it no matter where in the utility name or arguments
1067 option was inspired by the equivalent
1078 The special characters used by
1080 are also special characters to many shell programs.
1081 In particular, the characters
1092 may have to be escaped from the shell.
1094 As there is no delimiter separating options and file names or file
1097 it is difficult to specify files named
1101 These problems are handled by the
1110 primary does not interact well with other options that cause the file system
1111 tree traversal options to be changed.
1117 primaries are actually global options (as documented above).
1119 probably be replaced by options which look like options.