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 Ignore errors because a file or a directory is deleted
472 after reading the name from a directory.
473 This option does not affect errors occurring on starting points.
474 .It Ic -ilname Ar pattern
477 but the match is case insensitive.
478 This is a GNU find extension.
479 .It Ic -iname Ar pattern
482 but the match is case insensitive.
484 True if the file has inode number
486 .It Ic -ipath Ar pattern
489 but the match is case insensitive.
490 .It Ic -iregex Ar pattern
493 but the match is case insensitive.
494 .It Ic -iwholename Ar pattern
497 for GNU find compatibility.
502 .It Ic -lname Ar pattern
505 but the contents of the symbolic link are matched instead of the file
507 Note that this only matches broken symbolic links
508 if symbolic links are being followed.
509 This is a GNU find extension.
511 This primary always evaluates to true.
512 The following information for the current file is written to standard output:
513 its inode number, size in 512-byte blocks, file permissions, number of hard
514 links, owner, group, size in bytes, last modification time, and pathname.
515 If the file is a block or character special file, the major and minor numbers
516 will be displayed instead of the size in bytes.
517 If the file is a symbolic link, the pathname of the linked-to file will be
518 displayed preceded by
520 The format is identical to that produced by
524 .It Ic -maxdepth Ar n
525 Always true; descend at most
527 directory levels below the command line arguments.
530 primary is specified, it applies to the entire expression even if it would
531 not normally be evaluated.
532 .Dq Ic -maxdepth Li 0
533 limits the whole search to the command line arguments.
534 .It Ic -mindepth Ar n
535 Always true; do not apply any tests or actions at levels less than
539 primary is specified, it applies to the entire expression even if it would
540 not normally be evaluated.
541 .Dq Ic -mindepth Li 1
542 processes all but the command line arguments.
544 True if the difference between the file last modification time and the time
546 was started, rounded up to the next full minute, is
549 .It Ic -mnewer Ar file
555 for GNU find compatibility.
556 .It Ic -mtime Ar n Ns Op Cm smhdw
557 If no units are specified, this primary evaluates to
558 true if the difference between the file last modification time and the time
560 was started, rounded up to the next full 24-hour period, is
564 If units are specified, this primary evaluates to
565 true if the difference between the file last modification time and the time
567 was started is exactly
572 primary description for information on supported time units.
573 .It Ic -name Ar pattern
574 True if the last component of the pathname being examined matches
576 Special shell pattern matching characters
582 may be used as part of
584 These characters may be matched explicitly by escaping them with a
587 .It Ic -newer Ar file
588 True if the current file has a more recent last modification time than
590 .It Ic -newer Ns Ar X Ns Ar Y Ar file
591 True if the current file has a more recent last access time
592 .Pq Ar X Ns = Ns Cm a ,
594 .Pq Ar X Ns = Ns Cm B ,
596 .Pq Ar X Ns = Ns Cm c ,
598 .Pq Ar X Ns = Ns Cm m
599 than the last access time
600 .Pq Ar Y Ns = Ns Cm a ,
602 .Pq Ar Y Ns = Ns Cm B ,
604 .Pq Ar Y Ns = Ns Cm c ,
606 .Pq Ar Y Ns = Ns Cm m
613 is instead interpreted as a direct date specification of the form
621 True if the file belongs to an unknown group.
622 .It Ic -noignore_readdir_race
623 Turn off the effect of
624 .Ic -ignore_readdir_race .
625 This is default behaviour.
627 This option is for GNU find compatibility.
628 In GNU find it disables an optimization not relevant to
632 True if the file belongs to an unknown user.
633 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
636 primary is identical to the
638 primary with the exception that
640 requests user affirmation for the execution of the
643 a message to the terminal and reading a response.
644 If the response is not affirmative
649 the command is not executed and the
653 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
656 primary is identical to the
658 primary with the same exception as described for the
661 .It Ic -path Ar pattern
662 True if the pathname being examined matches
664 Special shell pattern matching characters
670 may be used as part of
672 These characters may be matched explicitly by escaping them with a
677 are treated as normal characters and do not have to be
679 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
682 may be either symbolic (see
687 is symbolic, a starting value of zero is assumed and the
689 sets or clears permissions without regard to the process' file mode
693 is octal, only bits 07777
694 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
695 of the file's mode bits participate
699 is preceded by a dash
701 this primary evaluates to true
702 if at least all of the bits in the
704 are set in the file's mode bits.
707 is preceded by a plus
709 this primary evaluates to true
710 if any of the bits in the
712 are set in the file's mode bits.
713 Otherwise, this primary evaluates to true if
716 exactly match the file's mode bits.
717 Note, the first character of a symbolic mode may not be a dash
720 This primary always evaluates to true.
721 It prints the pathname of the current file to standard output.
723 .Ic -exec , -ls , -print0 ,
726 is specified, the given expression shall be effectively replaced by
727 .Cm \&( Ar "given expression" Cm \&) Ic -print .
729 This primary always evaluates to true.
730 It prints the pathname of the current file to standard output, followed by an
733 character (character code 0).
735 This primary always evaluates to true.
738 to not descend into the current file.
741 primary has no effect if the
743 option was specified.
747 to immediately terminate.
748 .It Ic -regex Ar pattern
749 True if the whole path of the file matches
751 using regular expression.
752 To match a file named
754 you can use the regular expression
762 .It Ic -samefile Ar name
763 True if the file is a hard link to
765 If the command option
767 is specified, it is also true if the file is a symbolic link and
770 .It Ic -size Ar n Ns Op Cm ckMGTP
771 True if the file's size, rounded up, in 512-byte blocks is
777 then the primary is true if the
783 is followed by a scale indicator then the file's size is compared to
787 .Bl -tag -width indent -compact
789 kilobytes (1024 bytes)
791 megabytes (1024 kilobytes)
793 gigabytes (1024 megabytes)
795 terabytes (1024 gigabytes)
797 petabytes (1024 terabytes)
800 True if the file is of the specified type.
801 Possible file types are as follows:
803 .Bl -tag -width indent -compact
822 for compatibility with GNU find.
823 GNU find imposes a restriction that
828 .It Ic -user Ar uname
829 True if the file belongs to the user
833 is numeric and there is no such user name, then
835 is treated as a user ID.
836 .It Ic -wholename Ar pattern
839 for GNU find compatibility.
842 The primaries may be combined using the following operators.
843 The operators are listed in order of decreasing precedence.
845 .Bl -tag -width indent -compact
846 .It Cm \&( Ar expression Cm \&)
847 This evaluates to true if the parenthesized expression evaluates to
850 .It Cm \&! Ar expression
851 .It Cm -not Ar expression
855 It evaluates to true if the expression is false.
862 .It Ar expression Cm -and Ar expression
863 .It Ar expression expression
866 operator is the logical
869 As it is implied by the juxtaposition of two expressions it does not
870 have to be specified.
871 The expression evaluates to true if both expressions are true.
872 The second expression is not evaluated if the first expression is false.
874 .It Ar expression Cm -or Ar expression
877 operator is the logical
880 The expression evaluates to true if either the first or the second expression
882 The second expression is not evaluated if the first expression is true.
885 All operands and primaries must be separate arguments to
887 Primaries which themselves take arguments expect each argument
888 to be a separate argument to
892 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
895 environment variables affect the execution of the
897 utility as described in
900 The following examples are shown as given to the shell:
901 .Bl -tag -width indent
902 .It Li "find / \e! -name \*q*.c\*q -print"
903 Print out a list of all the files whose names do not end in
905 .It Li "find / -newer ttt -user wnj -print"
906 Print out a list of all the files owned by user
911 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
912 Print out a list of all the files which are not both newer than
916 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
917 Print out a list of all the files that are either owned by
919 or that are newer than
921 .It Li "find / -newerct '1 minute ago' -print"
922 Print out a list of all the files whose inode change time is more
923 recent than the current time minus one minute.
924 .It Li "find / -type f -exec echo {} \e;"
927 command to print out a list of all the files.
928 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
929 Delete all broken symbolic links in
930 .Pa /usr/ports/packages .
931 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
932 Find files and directories that are at least seven levels deep
933 in the working directory
935 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
936 Is not equivalent to the previous example, since
938 is not evaluated below level seven.
943 primary is deprecated; the
945 option should be used instead.
948 section below for details.
969 utility syntax is a superset of the syntax specified by the
973 All the single character options except
978 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
979 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
980 .Ic -path , -print0 , -regex
983 birthtime related primaries are extensions to
990 options were implemented using the primaries
991 .Ic -depth , -follow ,
994 These primaries always evaluated to true.
995 As they were really global variables that took effect before the traversal
996 began, some legal expressions could have unexpected results.
997 An example is the expression
998 .Ic -print Cm -o Ic -depth .
1001 always evaluates to true, the standard order of evaluation
1004 would never be evaluated.
1005 This is not the case.
1016 Historic implementations of the
1020 primaries did not replace the string
1022 in the utility name or the
1023 utility arguments if it had preceding or following non-whitespace characters.
1024 This version replaces it no matter where in the utility name or arguments
1029 option was inspired by the equivalent
1040 The special characters used by
1042 are also special characters to many shell programs.
1043 In particular, the characters
1054 may have to be escaped from the shell.
1056 As there is no delimiter separating options and file names or file
1059 it is difficult to specify files named
1063 These problems are handled by the
1072 primary does not interact well with other options that cause the file system
1073 tree traversal options to be changed.
1079 primaries are actually global options (as documented above).
1081 probably be replaced by options which look like options.