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.
164 from descending into directories that have a device number different
165 than that of the file from which the descent began.
167 This option is equivalent to the deprecated
172 All primaries which take a numeric argument allow the number to be
173 preceded by a plus sign
177 A preceding plus sign means
179 a preceding minus sign means
183 .Bl -tag -width indent
185 True if the difference between the time of a file's inode creation
188 was started, rounded up to the next full minute, is
191 .It Ic -Bnewer Ar file
194 .It Ic -Btime Ar n Ns Op Cm smhdw
195 If no units are specified, this primary evaluates to
196 true if the difference between the time of a file's inode creation
199 was started, rounded up to the next full 24-hour period, is
203 If units are specified, this primary evaluates to
204 true if the difference between the time of a file's inode creation
207 was started is exactly
212 primary description for information on supported time units.
214 May be used in conjunction with other primaries to locate
215 files with extended ACLs.
218 for more information.
219 .It Ic -amin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
220 True if the difference between the file last access time and the time
222 was started, rounded up to the next full minute, is
232 .It Ic -anewer Ar file
235 .It Ic -atime Ar n Ns Op Cm smhdw
236 If no units are specified, this primary evaluates to
237 true if the difference between the file last access time and the time
239 was started, rounded up to the next full 24-hour period, is
243 If units are specified, this primary evaluates to
244 true if the difference between the file last access time and the time
246 was started is exactly
249 Possible time units are as follows:
251 .Bl -tag -width indent -compact
264 Any number of units may be combined in one
266 argument, for example,
267 .Dq Li "-atime -1h30m" .
268 Units are probably only useful when used in conjunction with the
273 .It Ic -cmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
274 True if the difference between the time of last change of file status
275 information and the time
277 was started, rounded up to the next full minute, is
287 .It Ic -cnewer Ar file
290 .It Ic -ctime Ar n Ns Op Cm smhdw
291 If no units are specified, this primary evaluates to
292 true if the difference between the time of last change of file status
293 information and the time
295 was started, rounded up to the next full 24-hour period, is
299 If units are specified, this primary evaluates to
300 true if the difference between the time of last change of file status
301 information and the time
303 was started is exactly
308 primary description for information on supported time units.
310 Non-portable, BSD-specific version of
312 GNU find implements this as a primary in mistaken emulation of
316 Delete found files and/or directories.
319 from the current working directory as
321 recurses down the tree.
322 It will not attempt to delete a filename with a
324 character in its pathname relative to
326 for security reasons.
327 Depth-first traversal processing is implied by this option.
330 primary will fail to delete a directory if it is not empty.
331 Following symlinks is incompatible with this option.
334 same as the non-portable
339 to perform a depth-first traversal, i.e., directories
340 are visited in post-order and all entries in a directory will be acted
341 on before the directory itself.
344 visits directories in pre-order, i.e., before their contents.
347 a breadth-first traversal.
356 to process files that are contained in directories with unusual permissions.
357 It ensures that you have write permission while you are placing files in a
358 directory, then sets the directory's permissions as the last thing.
360 True if the depth of the file relative to the starting point of the traversal
364 True if the current file or directory is empty.
365 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
366 True if the program named
368 returns a zero value as its exit status.
371 may be passed to the utility.
372 The expression must be terminated by a semicolon
376 from a shell you may need to quote the semicolon if the shell would
377 otherwise treat it as a control operator.
380 appears anywhere in the utility name or the
381 arguments it is replaced by the pathname of the current file.
383 will be executed from the directory from which
389 are not subject to the further expansion of shell patterns
391 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
396 is replaced with as many pathnames as possible for each invocation of
398 This behaviour is similar to that of
400 The primary always returns true;
401 if at least one invocation of
403 returns a non-zero exit status,
405 will return a non-zero exit status.
406 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
409 primary is identical to the
411 primary with the exception that
413 will be executed from the directory that holds
415 The filename substituted for
419 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
424 is replaced with as many pathnames as possible for each invocation of
426 This behaviour is similar to that of
428 The primary always returns true;
429 if at least one invocation of
431 returns a non-zero exit status,
433 will return a non-zero exit status.
434 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
435 The flags are specified using symbolic names (see
445 are checked to be set, and flags in
447 are checked to be not set.
448 Note that this is different from
450 which only allows the user to specify mode bits that are set.
452 If flags are preceded by a dash
454 this primary evaluates to true
455 if at least all of the bits in
457 and none of the bits in
459 are set in the file's flags bits.
460 If flags are preceded by a plus
462 this primary evaluates to true
463 if any of the bits in
465 is set in the file's flags bits,
466 or any of the bits in
468 is not set in the file's flags bits.
470 this primary evaluates to true
473 exactly match the file's flags bits,
478 .It Ic -fstype Ar type
479 True if the file is contained in a file system of type
483 command can be used to find out the types of file systems
484 that are available on the system.
485 In addition, there are two pseudo-types,
489 The former matches any file system physically mounted on the system where
492 is being executed and the latter matches any file system which is
497 for compatibility with GNU find.
498 GNU find imposes a restriction that
503 .It Ic -group Ar gname
504 True if the file belongs to the group
508 is numeric and there is no such group name, then
510 is treated as a group ID.
511 .It Ic -ignore_readdir_race
512 Ignore errors because a file or a directory is deleted
513 after reading the name from a directory.
514 This option does not affect errors occurring on starting points.
515 .It Ic -ilname Ar pattern
518 but the match is case insensitive.
519 This is a GNU find extension.
520 .It Ic -iname Ar pattern
523 but the match is case insensitive.
525 True if the file has inode number
527 .It Ic -ipath Ar pattern
530 but the match is case insensitive.
531 .It Ic -iregex Ar pattern
534 but the match is case insensitive.
535 .It Ic -iwholename Ar pattern
538 for GNU find compatibility.
543 .It Ic -lname Ar pattern
546 but the contents of the symbolic link are matched instead of the file
548 Note that this only matches broken symbolic links
549 if symbolic links are being followed.
550 This is a GNU find extension.
552 This primary always evaluates to true.
553 The following information for the current file is written to standard output:
554 its inode number, size in 512-byte blocks, file permissions, number of hard
555 links, owner, group, size in bytes, last modification time, and pathname.
556 If the file is a block or character special file, the device number
557 will be displayed instead of the size in bytes.
558 If the file is a symbolic link, the pathname of the linked-to file will be
559 displayed preceded by
561 The format is identical to that produced by
565 .It Ic -maxdepth Ar n
566 Always true; descend at most
568 directory levels below the command line arguments.
571 primary is specified, it applies to the entire expression even if it would
572 not normally be evaluated.
573 .Dq Ic -maxdepth Li 0
574 limits the whole search to the command line arguments.
575 .It Ic -mindepth Ar n
576 Always true; do not apply any tests or actions at levels less than
580 primary is specified, it applies to the entire expression even if it would
581 not normally be evaluated.
582 .Dq Ic -mindepth Li 1
583 processes all but the command line arguments.
584 .It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
585 True if the difference between the file last modification time and the time
587 was started, rounded up to the next full minute, is
597 .It Ic -mnewer Ar file
603 for GNU find compatibility.
604 .It Ic -mtime Ar n Ns Op Cm smhdw
605 If no units are specified, this primary evaluates to
606 true if the difference between the file last modification time and the time
608 was started, rounded up to the next full 24-hour period, is
612 If units are specified, this primary evaluates to
613 true if the difference between the file last modification time and the time
615 was started is exactly
620 primary description for information on supported time units.
621 .It Ic -name Ar pattern
622 True if the last component of the pathname being examined matches
624 Special shell pattern matching characters
630 may be used as part of
632 These characters may be matched explicitly by escaping them with a
635 .It Ic -newer Ar file
636 True if the current file has a more recent last modification time than
638 .It Ic -newer Ns Ar X Ns Ar Y Ar file
639 True if the current file has a more recent last access time
640 .Pq Ar X Ns = Ns Cm a ,
642 .Pq Ar X Ns = Ns Cm B ,
644 .Pq Ar X Ns = Ns Cm c ,
646 .Pq Ar X Ns = Ns Cm m
647 than the last access time
648 .Pq Ar Y Ns = Ns Cm a ,
650 .Pq Ar Y Ns = Ns Cm B ,
652 .Pq Ar Y Ns = Ns Cm c ,
654 .Pq Ar Y Ns = Ns Cm m
661 is instead interpreted as a direct date specification of the form
662 understood by ISO8601 or RFC822.
668 True if the file belongs to an unknown group.
669 .It Ic -noignore_readdir_race
670 Turn off the effect of
671 .Ic -ignore_readdir_race .
672 This is default behaviour.
674 This option is for GNU find compatibility.
675 In GNU find it disables an optimization not relevant to
679 True if the file belongs to an unknown user.
680 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
683 primary is identical to the
685 primary with the exception that
687 requests user affirmation for the execution of the
690 a message to the terminal and reading a response.
691 If the response is not affirmative
696 the command is not executed and the
700 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
703 primary is identical to the
705 primary with the same exception as described for the
708 .It Ic -path Ar pattern
709 True if the pathname being examined matches
711 Special shell pattern matching characters
717 may be used as part of
719 These characters may be matched explicitly by escaping them with a
724 are treated as normal characters and do not have to be
726 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
729 may be either symbolic (see
734 is symbolic, a starting value of zero is assumed and the
736 sets or clears permissions without regard to the process' file mode
740 is octal, only bits 07777
741 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
742 of the file's mode bits participate
746 is preceded by a dash
748 this primary evaluates to true
749 if at least all of the bits in the
751 are set in the file's mode bits.
754 is preceded by a plus
756 this primary evaluates to true
757 if any of the bits in the
759 are set in the file's mode bits.
760 Otherwise, this primary evaluates to true if
763 exactly match the file's mode bits.
764 Note, the first character of a symbolic mode may not be a dash
767 This primary always evaluates to true.
768 It prints the pathname of the current file to standard output.
770 .Ic -exec , -ls , -print0 ,
773 is specified, the given expression shall be effectively replaced by
774 .Cm \&( Ar "given expression" Cm \&) Ic -print .
776 This primary always evaluates to true.
777 It prints the pathname of the current file to standard output, followed by an
780 character (character code 0).
782 This primary always evaluates to true.
785 to not descend into the current file.
788 primary has no effect if the
790 option was specified.
794 to terminate immediately.
795 .It Ic -regex Ar pattern
796 True if the whole path of the file matches
798 using regular expression.
799 To match a file named
801 you can use the regular expression
809 .It Ic -samefile Ar name
810 True if the file is a hard link to
812 If the command option
814 is specified, it is also true if the file is a symbolic link and
817 .It Ic -size Ar n Ns Op Cm ckMGTP
818 True if the file's size, rounded up, in 512-byte blocks is
824 then the primary is true if the
830 is followed by a scale indicator then the file's size is compared to
834 .Bl -tag -width indent -compact
836 kilobytes (1024 bytes)
838 megabytes (1024 kilobytes)
840 gigabytes (1024 megabytes)
842 terabytes (1024 gigabytes)
844 petabytes (1024 terabytes)
847 True if the current file is sparse,
848 i.e. has fewer blocks allocated than expected based on its size in bytes.
849 This might also match files that have been compressed by the filesystem.
851 True if the file is of the specified type.
852 Possible file types are as follows:
854 .Bl -tag -width indent -compact
873 for compatibility with GNU find.
874 GNU find imposes a restriction that
879 .It Ic -user Ar uname
880 True if the file belongs to the user
884 is numeric and there is no such user name, then
886 is treated as a user ID.
887 .It Ic -wholename Ar pattern
890 for GNU find compatibility.
893 The primaries may be combined using the following operators.
894 The operators are listed in order of decreasing precedence.
896 .Bl -tag -width indent -compact
897 .It Cm \&( Ar expression Cm \&)
898 This evaluates to true if the parenthesized expression evaluates to
901 .It Cm \&! Ar expression
902 .It Cm -not Ar expression
906 It evaluates to true if the expression is false.
913 .It Ar expression Cm -and Ar expression
914 .It Ar expression expression
917 operator is the logical
920 As it is implied by the juxtaposition of two expressions it does not
921 have to be specified.
922 The expression evaluates to true if both expressions are true.
923 The second expression is not evaluated if the first expression is false.
925 .It Ar expression Cm -or Ar expression
928 operator is the logical
931 The expression evaluates to true if either the first or the second expression
933 The second expression is not evaluated if the first expression is true.
936 All operands and primaries must be separate arguments to
938 Primaries which themselves take arguments expect each argument
939 to be a separate argument to
943 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
946 environment variables affect the execution of the
948 utility as described in
951 The following examples are shown as given to the shell:
952 .Bl -tag -width indent
953 .It Li "find / \e! -name \*q*.c\*q -print"
954 Print out a list of all the files whose names do not end in
956 .It Li "find / -newer ttt -user wnj -print"
957 Print out a list of all the files owned by user
962 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
963 Print out a list of all the files which are not both newer than
967 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
968 Print out a list of all the files that are either owned by
970 or that are newer than
972 .It Li "find / -newerct '1 minute ago' -print"
973 Print out a list of all the files whose inode change time is more
974 recent than the current time minus one minute.
975 .It Li "find / -type f -exec echo {} \e;"
978 command to print out a list of all the files.
979 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
980 Delete all broken symbolic links in
981 .Pa /usr/ports/packages .
982 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
983 Find files and directories that are at least seven levels deep
984 in the working directory
986 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
987 Is not equivalent to the previous example, since
989 is not evaluated below level seven.
994 primary is deprecated; the
996 option should be used instead.
999 section below for details.
1019 utility syntax is a superset of the syntax specified by the
1023 All the single character options except
1028 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
1029 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
1030 .Ic -not , -path , -print0 , -regex , -sparse
1033 birthtime related primaries are extensions to
1040 options were implemented using the primaries
1041 .Ic -depth , -follow ,
1044 These primaries always evaluated to true.
1045 As they were really global variables that took effect before the traversal
1046 began, some legal expressions could have unexpected results.
1047 An example is the expression
1048 .Ic -print Cm -o Ic -depth .
1051 always evaluates to true, the standard order of evaluation
1054 would never be evaluated.
1055 This is not the case.
1066 Historic implementations of the
1070 primaries did not replace the string
1072 in the utility name or the
1073 utility arguments if it had preceding or following non-whitespace characters.
1074 This version replaces it no matter where in the utility name or arguments
1079 option was inspired by the equivalent
1091 It was rewritten for
1093 and later be enhanced for the Programmer's Workbench (PWB).
1094 These changes were later incorporated in
1097 The special characters used by
1099 are also special characters to many shell programs.
1100 In particular, the characters
1111 may have to be escaped from the shell.
1113 As there is no delimiter separating options and file names or file
1116 it is difficult to specify files named
1120 These problems are handled by the
1129 primary does not interact well with other options that cause the file system
1130 tree traversal options to be changed.
1136 primaries are actually global options (as documented above).
1138 probably be replaced by options which look like options.