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
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 the list of paths that will be recursed into.
144 begins with a character that would otherwise be interpreted as an
154 to traverse the file hierarchies in lexicographical order,
155 i.e., alphabetical order within each directory.
160 may give different results.
166 with all its contents before a directory
170 puts the directory name
172 before any string like
179 In locales other than
181 results may vary more due to collation differences.
185 from descending into directories that have a device number different
186 than that of the file from which the descent began.
188 This option is equivalent to the deprecated
193 All primaries which take a numeric argument allow the number to be
194 preceded by a plus sign
198 A preceding plus sign means
200 a preceding minus sign means
204 .Bl -tag -width indent
206 True if the difference between the time of a file's inode creation
209 was started, rounded up to the next full minute, is
212 .It Ic -Bnewer Ar file
215 .It Ic -Btime Ar n Ns Op Cm smhdw
216 If no units are specified, this primary evaluates to
217 true if the difference between the time of a file's inode creation
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 time of a file's inode creation
228 was started is exactly
233 primary description for information on supported time units.
235 May be used in conjunction with other primaries to locate
236 files with extended ACLs.
239 for more information.
240 .It Ic -amin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
241 True if the difference between the file last access time and the time
243 was started, rounded up to the next full minute, is
253 .It Ic -anewer Ar file
256 .It Ic -atime Ar n Ns Op Cm smhdw
257 If no units are specified, this primary evaluates to
258 true if the difference between the file last access time and the time
260 was started, rounded up to the next full 24-hour period, is
264 If units are specified, this primary evaluates to
265 true if the difference between the file last access time and the time
267 was started is exactly
270 Possible time units are as follows:
272 .Bl -tag -width indent -compact
285 Any number of units may be combined in one
287 argument, for example,
288 .Dq Li "-atime -1h30m" .
289 Units are probably only useful when used in conjunction with the
294 .It Ic -cmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
295 True if the difference between the time of last change of file status
296 information and the time
298 was started, rounded up to the next full minute, is
308 .It Ic -cnewer Ar file
311 .It Ic -ctime Ar n Ns Op Cm smhdw
312 If no units are specified, this primary evaluates to
313 true if the difference between the time of last change of file status
314 information and the time
316 was started, rounded up to the next full 24-hour period, is
320 If units are specified, this primary evaluates to
321 true if the difference between the time of last change of file status
322 information and the time
324 was started is exactly
329 primary description for information on supported time units.
331 Non-portable, BSD-specific version of
333 GNU find implements this as a primary in mistaken emulation of
337 Delete found files and/or directories.
340 from the current working directory as
342 recurses down the tree.
343 It will not attempt to delete a filename with a
345 character in its pathname relative to
347 for security reasons.
348 Depth-first traversal processing is implied by this option.
351 primary will fail to delete a directory if it is not empty.
352 Following symlinks is incompatible with this option.
355 same as the non-portable
360 to perform a depth-first traversal, i.e., directories
361 are visited in post-order and all entries in a directory will be acted
362 on before the directory itself.
365 visits directories in pre-order, i.e., before their contents.
368 a breadth-first traversal.
377 to process files that are contained in directories with unusual permissions.
378 It ensures that you have write permission while you are placing files in a
379 directory, then sets the directory's permissions as the last thing.
381 True if the depth of the file relative to the starting point of the traversal
385 True if the current file or directory is empty.
386 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
387 True if the program named
389 returns a zero value as its exit status.
392 may be passed to the utility.
393 The expression must be terminated by a semicolon
397 from a shell you may need to quote the semicolon if the shell would
398 otherwise treat it as a control operator.
401 appears anywhere in the utility name or the
402 arguments it is replaced by the pathname of the current file.
404 will be executed from the directory from which
410 are not subject to the further expansion of shell patterns
412 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
417 is replaced with as many pathnames as possible for each invocation of
419 This behaviour is similar to that of
421 The primary always returns true;
422 if at least one invocation of
424 returns a non-zero exit status,
426 will return a non-zero exit status.
427 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
430 primary is identical to the
432 primary with the exception that
434 will be executed from the directory that holds
436 The filename substituted for
440 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
445 is replaced with as many pathnames as possible for each invocation of
447 This behaviour is similar to that of
449 The primary always returns true;
450 if at least one invocation of
452 returns a non-zero exit status,
454 will return a non-zero exit status.
455 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
456 The flags are specified using symbolic names (see
466 are checked to be set, and flags in
468 are checked to be not set.
469 Note that this is different from
471 which only allows the user to specify mode bits that are set.
473 If flags are preceded by a dash
475 this primary evaluates to true
476 if at least all of the bits in
478 and none of the bits in
480 are set in the file's flags bits.
481 If flags are preceded by a plus
483 this primary evaluates to true
484 if any of the bits in
486 is set in the file's flags bits,
487 or any of the bits in
489 is not set in the file's flags bits.
491 this primary evaluates to true
494 exactly match the file's flags bits,
499 .It Ic -fstype Ar type
500 True if the file is contained in a file system of type
504 command can be used to find out the types of file systems
505 that are available on the system.
506 In addition, there are two pseudo-types,
510 The former matches any file system physically mounted on the system where
513 is being executed and the latter matches any file system which is
518 for compatibility with GNU find.
519 GNU find imposes a restriction that
524 .It Ic -group Ar gname
525 True if the file belongs to the group
529 is numeric and there is no such group name, then
531 is treated as a group ID.
532 .It Ic -ignore_readdir_race
533 Ignore errors because a file or a directory is deleted
534 after reading the name from a directory.
535 This option does not affect errors occurring on starting points.
536 .It Ic -ilname Ar pattern
539 but the match is case insensitive.
540 This is a GNU find extension.
541 .It Ic -iname Ar pattern
544 but the match is case insensitive.
546 True if the file has inode number
548 .It Ic -ipath Ar pattern
551 but the match is case insensitive.
552 .It Ic -iregex Ar pattern
555 but the match is case insensitive.
556 .It Ic -iwholename Ar pattern
559 for GNU find compatibility.
564 .It Ic -lname Ar pattern
567 but the contents of the symbolic link are matched instead of the file
569 Note that this only matches broken symbolic links
570 if symbolic links are being followed.
571 This is a GNU find extension.
573 This primary always evaluates to true.
574 The following information for the current file is written to standard output:
575 its inode number, size in 512-byte blocks, file permissions, number of hard
576 links, owner, group, size in bytes, last modification time, and pathname.
577 If the file is a block or character special file, the device number
578 will be displayed instead of the size in bytes.
579 If the file is a symbolic link, the pathname of the linked-to file will be
580 displayed preceded by
582 The format is identical to that produced by
586 .It Ic -maxdepth Ar n
587 Always true; descend at most
589 directory levels below the command line arguments.
592 primary is specified, it applies to the entire expression even if it would
593 not normally be evaluated.
594 .Dq Ic -maxdepth Li 0
595 limits the whole search to the command line arguments.
596 .It Ic -mindepth Ar n
597 Always true; do not apply any tests or actions at levels less than
601 primary is specified, it applies to the entire expression even if it would
602 not normally be evaluated.
603 .Dq Ic -mindepth Li 1
604 processes all but the command line arguments.
605 .It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
606 True if the difference between the file last modification time and the time
608 was started, rounded up to the next full minute, is
618 .It Ic -mnewer Ar file
624 for GNU find compatibility.
625 .It Ic -mtime Ar n Ns Op Cm smhdw
626 If no units are specified, this primary evaluates to
627 true if the difference between the file last modification time and the time
629 was started, rounded up to the next full 24-hour period, is
633 If units are specified, this primary evaluates to
634 true if the difference between the file last modification time and the time
636 was started is exactly
641 primary description for information on supported time units.
642 .It Ic -name Ar pattern
643 True if the last component of the pathname being examined matches
645 Special shell pattern matching characters
651 may be used as part of
653 These characters may be matched explicitly by escaping them with a
656 .It Ic -newer Ar file
657 True if the current file has a more recent last modification time than
659 .It Ic -newer Ns Ar X Ns Ar Y Ar file
660 True if the current file has a more recent last access time
661 .Pq Ar X Ns = Ns Cm a ,
663 .Pq Ar X Ns = Ns Cm B ,
665 .Pq Ar X Ns = Ns Cm c ,
667 .Pq Ar X Ns = Ns Cm m
668 than the last access time
669 .Pq Ar Y Ns = Ns Cm a ,
671 .Pq Ar Y Ns = Ns Cm B ,
673 .Pq Ar Y Ns = Ns Cm c ,
675 .Pq Ar Y Ns = Ns Cm m
682 is instead interpreted as a direct date specification of the form
683 understood by ISO8601 or RFC822.
689 True if the file belongs to an unknown group.
690 .It Ic -noignore_readdir_race
691 Turn off the effect of
692 .Ic -ignore_readdir_race .
693 This is default behaviour.
695 This option is for GNU find compatibility.
696 In GNU find it disables an optimization not relevant to
700 True if the file belongs to an unknown user.
701 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
704 primary is identical to the
706 primary with the exception that
708 requests user affirmation for the execution of the
711 a message to the terminal and reading a response.
712 If the response is not affirmative
717 the command is not executed and the
721 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
724 primary is identical to the
726 primary with the same exception as described for the
729 .It Ic -path Ar pattern
730 True if the pathname being examined matches
732 Special shell pattern matching characters
738 may be used as part of
740 These characters may be matched explicitly by escaping them with a
745 are treated as normal characters and do not have to be
747 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
750 may be either symbolic (see
755 is symbolic, a starting value of zero is assumed and the
757 sets or clears permissions without regard to the process' file mode
761 is octal, only bits 07777
762 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
763 of the file's mode bits participate
767 is preceded by a dash
769 this primary evaluates to true
770 if at least all of the bits in the
772 are set in the file's mode bits.
775 is preceded by a plus
777 this primary evaluates to true
778 if any of the bits in the
780 are set in the file's mode bits.
781 Otherwise, this primary evaluates to true if
784 exactly match the file's mode bits.
785 Note, the first character of a symbolic mode may not be a dash
788 This primary always evaluates to true.
789 It prints the pathname of the current file to standard output.
791 .Ic -exec , -ls , -print0 ,
794 is specified, the given expression shall be effectively replaced by
795 .Cm \&( Ar "given expression" Cm \&) Ic -print .
797 This primary always evaluates to true.
798 It prints the pathname of the current file to standard output, followed by an
801 character (character code 0).
803 This primary always evaluates to true.
806 to not descend into the current file.
809 primary has no effect if the
811 option was specified.
815 to terminate immediately.
816 .It Ic -regex Ar pattern
817 True if the whole path of the file matches
819 using regular expression.
820 To match a file named
822 you can use the regular expression
830 .It Ic -samefile Ar name
831 True if the file is a hard link to
833 If the command option
835 is specified, it is also true if the file is a symbolic link and
838 .It Ic -size Ar n Ns Op Cm ckMGTP
839 True if the file's size, rounded up, in 512-byte blocks is
845 then the primary is true if the
851 is followed by a scale indicator then the file's size is compared to
855 .Bl -tag -width indent -compact
857 kilobytes (1024 bytes)
859 megabytes (1024 kilobytes)
861 gigabytes (1024 megabytes)
863 terabytes (1024 gigabytes)
865 petabytes (1024 terabytes)
868 True if the current file is sparse,
869 i.e. has fewer blocks allocated than expected based on its size in bytes.
870 This might also match files that have been compressed by the filesystem.
872 True if the file is of the specified type.
873 Possible file types are as follows:
875 .Bl -tag -width indent -compact
894 for compatibility with GNU find.
895 GNU find imposes a restriction that
900 .It Ic -user Ar uname
901 True if the file belongs to the user
905 is numeric and there is no such user name, then
907 is treated as a user ID.
908 .It Ic -wholename Ar pattern
911 for GNU find compatibility.
914 The primaries may be combined using the following operators.
915 The operators are listed in order of decreasing precedence.
917 .Bl -tag -width indent -compact
918 .It Cm \&( Ar expression Cm \&)
919 This evaluates to true if the parenthesized expression evaluates to
922 .It Cm \&! Ar expression
923 .It Cm -not Ar expression
927 It evaluates to true if the expression is false.
934 .It Ar expression Cm -and Ar expression
935 .It Ar expression expression
938 operator is the logical
941 As it is implied by the juxtaposition of two expressions it does not
942 have to be specified.
943 The expression evaluates to true if both expressions are true.
944 The second expression is not evaluated if the first expression is false.
946 .It Ar expression Cm -or Ar expression
949 operator is the logical
952 The expression evaluates to true if either the first or the second expression
954 The second expression is not evaluated if the first expression is true.
957 All operands and primaries must be separate arguments to
959 Primaries which themselves take arguments expect each argument
960 to be a separate argument to
964 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
967 environment variables affect the execution of the
969 utility as described in
972 The following examples are shown as given to the shell:
973 .Bl -tag -width indent
974 .It Li "find / \e! -name \*q*.c\*q -print"
975 Print out a list of all the files whose names do not end in
977 .It Li "find / -newer ttt -user wnj -print"
978 Print out a list of all the files owned by user
983 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
984 Print out a list of all the files which are not both newer than
988 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
989 Print out a list of all the files that are either owned by
991 or that are newer than
993 .It Li "find / -newerct '1 minute ago' -print"
994 Print out a list of all the files whose inode change time is more
995 recent than the current time minus one minute.
996 .It Li "find / -type f -exec echo {} \e;"
999 command to print out a list of all the files.
1000 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
1001 Delete all broken symbolic links in
1002 .Pa /usr/ports/packages .
1003 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
1004 Find files and directories that are at least seven levels deep
1005 in the working directory
1007 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
1008 Is not equivalent to the previous example, since
1010 is not evaluated below level seven.
1015 primary is deprecated; the
1017 option should be used instead.
1020 section below for details.
1041 utility syntax is a superset of the syntax specified by the
1045 All the single character options except
1050 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
1051 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
1052 .Ic -not , -path , -print0 , -regex , -sparse
1055 birthtime related primaries are extensions to
1062 options were implemented using the primaries
1063 .Ic -depth , -follow ,
1066 These primaries always evaluated to true.
1067 As they were really global variables that took effect before the traversal
1068 began, some legal expressions could have unexpected results.
1069 An example is the expression
1070 .Ic -print Cm -o Ic -depth .
1073 always evaluates to true, the standard order of evaluation
1076 would never be evaluated.
1077 This is not the case.
1088 Historic implementations of the
1092 primaries did not replace the string
1094 in the utility name or the
1095 utility arguments if it had preceding or following non-whitespace characters.
1096 This version replaces it no matter where in the utility name or arguments
1101 option was inspired by the equivalent
1113 It was rewritten for
1115 and later be enhanced for the Programmer's Workbench (PWB).
1116 These changes were later incorporated in
1119 The special characters used by
1121 are also special characters to many shell programs.
1122 In particular, the characters
1133 may have to be escaped from the shell.
1135 As there is no delimiter separating options and file names or file
1138 it is difficult to specify files named
1142 These problems are handled by the
1151 primary does not interact well with other options that cause the file system
1152 tree traversal options to be changed.
1158 primaries are actually global options (as documented above).
1160 probably be replaced by options which look like options.