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
32 .\" $FreeBSD: src/usr.bin/find/find.1,v 1.91 2011/09/28 18:53:36 ed Exp $
34 .Dd September 28, 2011
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, i.e., directories
130 are visited in post-order and all entries in a directory will be acted
131 on before the directory itself.
134 visits directories in pre-order, i.e., before their contents.
137 a breadth-first traversal.
139 This option is equivalent to the
150 to process files that are contained in directories with unusual permissions.
151 It ensures that you have write permission while you are placing files in a
152 directory, then sets the directory's permissions as the last thing.
154 Specify a file hierarchy for
157 File hierarchies may also be specified as the operands immediately
158 following the options.
162 to traverse the file hierarchies in lexicographical order,
163 i.e., alphabetical order within each directory.
168 may give different results.
172 from descending into directories that have a device number different
173 than that of the file from which the descent began.
175 This option is equivalent to the deprecated
181 All primaries which take a numeric argument allow the number to be
182 preceded by a plus sign
186 A preceding plus sign means
188 a preceding minus sign means
192 .Bl -tag -width indent
194 True if the difference between the time of a file's inode creation
197 was started, rounded up to the next full minute, is
200 .It Ic -Bnewer Ar file
203 .It Ic -Btime Ar n Ns Op Cm smhdw
204 If no units are specified, this primary evaluates to
205 true if the difference between the time of a file's inode creation
208 was started, rounded up to the next full 24-hour period, is
212 If units are specified, this primary evaluates to
213 true if the difference between the time of a file's inode creation
216 was started is exactly
221 primary description for information on supported time units.
223 May be used in conjunction with other primaries to locate
224 files with extended ACLs.
227 for more information.
229 True if the difference between the file last access time and the time
231 was started, rounded up to the next full minute, is
234 .It Ic -anewer Ar file
237 .It Ic -atime Ar n Ns Op Cm smhdw
238 If no units are specified, this primary evaluates to
239 true if the difference between the file last access time and the time
241 was started, rounded up to the next full 24-hour period, is
245 If units are specified, this primary evaluates to
246 true if the difference between the file last access time and the time
248 was started is exactly
251 Possible time units are as follows:
253 .Bl -tag -width indent -compact
266 Any number of units may be combined in one
268 argument, for example,
269 .Dq Li "-atime -1h30m" .
270 Units are probably only useful when used in conjunction with the
276 True if the difference between the time of last change of file status
277 information and the time
279 was started, rounded up to the next full minute, is
282 .It Ic -cnewer Ar file
285 .It Ic -ctime Ar n Ns Op Cm smhdw
286 If no 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, rounded up to the next full 24-hour period, is
294 If units are specified, this primary evaluates to
295 true if the difference between the time of last change of file status
296 information and the time
298 was started is exactly
303 primary description for information on supported time units.
307 GNU find implements this as a primary in mistaken emulation of
311 Delete found files and/or directories.
314 from the current working directory as
316 recurses down the tree.
317 It will not attempt to delete a filename with a
319 character in its pathname relative to
321 for security reasons.
322 Depth-first traversal processing is implied by this option.
323 Following symlinks is incompatible with this option.
330 True if the depth of the file relative to the starting point of the traversal
334 True if the current file or directory is empty.
335 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
336 True if the program named
338 returns a zero value as its exit status.
341 may be passed to the utility.
342 The expression must be terminated by a semicolon
346 from a shell you may need to quote the semicolon if the shell would
347 otherwise treat it as a control operator.
350 appears anywhere in the utility name or the
351 arguments it is replaced by the pathname of the current file.
353 will be executed from the directory from which
359 are not subject to the further expansion of shell patterns
361 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
366 is replaced with as many pathnames as possible for each invocation of
368 This behaviour is similar to that of
370 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
373 primary is identical to the
375 primary with the exception that
377 will be executed from the directory that holds
379 The filename substituted for
383 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
388 is replaced with as many pathnames as possible for each invocation of
390 This behaviour is similar to that of
392 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
393 The flags are specified using symbolic names (see
403 are checked to be set, and flags in
405 are checked to be not set.
406 Note that this is different from
408 which only allows the user to specify mode bits that are set.
410 If flags are preceded by a dash
412 this primary evaluates to true
413 if at least all of the bits in
415 and none of the bits in
417 are set in the file's flags bits.
418 If flags are preceded by a plus
420 this primary evaluates to true
421 if any of the bits in
423 is set in the file's flags bits,
424 or any of the bits in
426 is not set in the file's flags bits.
428 this primary evaluates to true
431 exactly match the file's flags bits,
436 .It Ic -fstype Ar type
437 True if the file is contained in a file system of type
441 command can be used to find out the types of file systems
442 that are available on the system.
443 In addition, there are two pseudo-types,
447 The former matches any file system physically mounted on the system where
450 is being executed and the latter matches any file system which is
455 for compatibility with GNU find.
456 GNU find imposes a restriction that
461 .It Ic -group Ar gname
462 True if the file belongs to the group
466 is numeric and there is no such group name, then
468 is treated as a group ID.
469 .It Ic -ignore_readdir_race
470 This option is for GNU find compatibility and is ignored.
471 .It Ic -ilname Ar pattern
474 but the match is case insensitive.
475 This is a GNU find extension.
476 .It Ic -iname Ar pattern
479 but the match is case insensitive.
481 True if the file has inode number
483 .It Ic -ipath Ar pattern
486 but the match is case insensitive.
487 .It Ic -iregex Ar pattern
490 but the match is case insensitive.
491 .It Ic -iwholename Ar pattern
494 for GNU find compatibility.
499 .It Ic -lname Ar pattern
502 but the contents of the symbolic link are matched instead of the file
504 Note that this only matches broken symbolic links
505 if symbolic links are being followed.
506 This is a GNU find extension.
508 This primary always evaluates to true.
509 The following information for the current file is written to standard output:
510 its inode number, size in 512-byte blocks, file permissions, number of hard
511 links, owner, group, size in bytes, last modification time, and pathname.
512 If the file is a block or character special file, the device number
513 will be displayed instead of the size in bytes.
514 If the file is a symbolic link, the pathname of the linked-to file will be
515 displayed preceded by
517 The format is identical to that produced by
521 .It Ic -maxdepth Ar n
522 Always true; descend at most
524 directory levels below the command line arguments.
527 primary is specified, it applies to the entire expression even if it would
528 not normally be evaluated.
529 .Dq Ic -maxdepth Li 0
530 limits the whole search to the command line arguments.
531 .It Ic -mindepth Ar n
532 Always true; do not apply any tests or actions at levels less than
536 primary is specified, it applies to the entire expression even if it would
537 not normally be evaluated.
538 .Dq Ic -mindepth Li 1
539 processes all but the command line arguments.
541 True if the difference between the file last modification time and the time
543 was started, rounded up to the next full minute, is
546 .It Ic -mnewer Ar file
552 for GNU find compatibility.
553 .It Ic -mtime Ar n Ns Op Cm smhdw
554 If no units are specified, this primary evaluates to
555 true if the difference between the file last modification time and the time
557 was started, rounded up to the next full 24-hour period, is
561 If units are specified, this primary evaluates to
562 true if the difference between the file last modification time and the time
564 was started is exactly
569 primary description for information on supported time units.
570 .It Ic -name Ar pattern
571 True if the last component of the pathname being examined matches
573 Special shell pattern matching characters
579 may be used as part of
581 These characters may be matched explicitly by escaping them with a
584 .It Ic -newer Ar file
585 True if the current file has a more recent last modification time than
587 .It Ic -newer Ns Ar X Ns Ar Y Ar file
588 True if the current file has a more recent last access time
589 .Pq Ar X Ns = Ns Cm a ,
591 .Pq Ar X Ns = Ns Cm B ,
593 .Pq Ar X Ns = Ns Cm c ,
595 .Pq Ar X Ns = Ns Cm m
596 than the last access time
597 .Pq Ar Y Ns = Ns Cm a ,
599 .Pq Ar Y Ns = Ns Cm B ,
601 .Pq Ar Y Ns = Ns Cm c ,
603 .Pq Ar Y Ns = Ns Cm m
610 is instead interpreted as a direct date specification of the form
618 True if the file belongs to an unknown group.
619 .It Ic -noignore_readdir_race
620 This option is for GNU find compatibility and is ignored.
622 This option is for GNU find compatibility.
623 In GNU find it disables an optimization not relevant to
627 True if the file belongs to an unknown user.
628 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
631 primary is identical to the
633 primary with the exception that
635 requests user affirmation for the execution of the
638 a message to the terminal and reading a response.
639 If the response is not affirmative
644 the command is not executed and the
648 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
651 primary is identical to the
653 primary with the same exception as described for the
656 .It Ic -path Ar pattern
657 True if the pathname being examined matches
659 Special shell pattern matching characters
665 may be used as part of
667 These characters may be matched explicitly by escaping them with a
672 are treated as normal characters and do not have to be
674 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
677 may be either symbolic (see
682 is symbolic, a starting value of zero is assumed and the
684 sets or clears permissions without regard to the process' file mode
688 is octal, only bits 07777
689 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
690 of the file's mode bits participate
694 is preceded by a dash
696 this primary evaluates to true
697 if at least all of the bits in the
699 are set in the file's mode bits.
702 is preceded by a plus
704 this primary evaluates to true
705 if any of the bits in the
707 are set in the file's mode bits.
708 Otherwise, this primary evaluates to true if
711 exactly match the file's mode bits.
712 Note, the first character of a symbolic mode may not be a dash
715 This primary always evaluates to true.
716 It prints the pathname of the current file to standard output.
719 .Ic -exec , -ls , -print , -print0 ,
722 is specified, the given expression shall be effectively replaced by
723 .Cm \&( Ar "given expression" Cm \&) Ic -print .
725 This primary always evaluates to true.
726 It prints the pathname of the current file to standard output, followed by an
729 character (character code 0).
731 This primary always evaluates to true.
734 to not descend into the current file.
737 primary has no effect if the
739 option was specified.
740 .It Ic -regex Ar pattern
741 True if the whole path of the file matches
743 using regular expression.
744 To match a file named
746 you can use the regular expression
754 .It Ic -samefile Ar name
755 True if the file is a hard link to
757 If the command option
759 is specified, it is also true if the file is a symbolic link and
762 .It Ic -size Ar n Ns Op Cm ckMGTP
763 True if the file's size, rounded up, in 512-byte blocks is
769 then the primary is true if the
775 is followed by a scale indicator then the file's size is compared to
779 .Bl -tag -width indent -compact
781 kilobytes (1024 bytes)
783 megabytes (1024 kilobytes)
785 gigabytes (1024 megabytes)
787 terabytes (1024 gigabytes)
789 petabytes (1024 terabytes)
792 True if the file is of the specified type.
793 Possible file types are as follows:
795 .Bl -tag -width indent -compact
814 for compatibility with GNU find.
815 GNU find imposes a restriction that
820 .It Ic -user Ar uname
821 True if the file belongs to the user
825 is numeric and there is no such user name, then
827 is treated as a user ID.
828 .It Ic -wholename Ar pattern
831 for GNU find compatibility.
833 True if the file has any extended attributes.
834 .It Ic -xattrname Ar name
835 True if the file has an extended attribute with the specified
839 The primaries may be combined using the following operators.
840 The operators are listed in order of decreasing precedence.
842 .Bl -tag -width indent -compact
843 .It Cm \&( Ar expression Cm \&)
844 This evaluates to true if the parenthesized expression evaluates to
847 .It Cm \&! Ar expression
848 .It Cm -not Ar expression
852 It evaluates to true if the expression is false.
859 .It Ar expression Cm -and Ar expression
860 .It Ar expression expression
863 operator is the logical
866 As it is implied by the juxtaposition of two expressions it does not
867 have to be specified.
868 The expression evaluates to true if both expressions are true.
869 The second expression is not evaluated if the first expression is false.
871 .It Ar expression Cm -or Ar expression
874 operator is the logical
877 The expression evaluates to true if either the first or the second expression
879 The second expression is not evaluated if the first expression is true.
882 All operands and primaries must be separate arguments to
884 Primaries which themselves take arguments expect each argument
885 to be a separate argument to
889 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
892 environment variables affect the execution of the
894 utility as described in
897 The following examples are shown as given to the shell:
898 .Bl -tag -width indent
899 .It Li "find / \e! -name \*q*.c\*q -print"
900 Print out a list of all the files whose names do not end in
902 .It Li "find / -newer ttt -user wnj -print"
903 Print out a list of all the files owned by user
908 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
909 Print out a list of all the files which are not both newer than
913 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
914 Print out a list of all the files that are either owned by
916 or that are newer than
918 .It Li "find / -newerct '1 minute ago' -print"
919 Print out a list of all the files whose inode change time is more
920 recent than the current time minus one minute.
921 .It Li "find / -type f -exec echo {} \e;"
924 command to print out a list of all the files.
925 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
926 Delete all broken symbolic links in
927 .Pa /usr/ports/packages .
928 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
929 Find files and directories that are at least seven levels deep
930 in the working directory
932 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
933 Is not equivalent to the previous example, since
935 is not evaluated below level seven.
940 primary is deprecated; the
942 option should be used instead.
945 section below for details.
966 utility syntax is a superset of the syntax specified by the
970 All the single character options except
975 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
976 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
977 .Ic -path , -print0 , -regex
980 birthtime related primaries are extensions to
987 options were implemented using the primaries
988 .Ic -depth , -follow ,
991 These primaries always evaluated to true.
992 As they were really global variables that took effect before the traversal
993 began, some legal expressions could have unexpected results.
994 An example is the expression
995 .Ic -print Cm -o Ic -depth .
998 always evaluates to true, the standard order of evaluation
1001 would never be evaluated.
1002 This is not the case.
1013 Historic implementations of the
1017 primaries did not replace the string
1019 in the utility name or the
1020 utility arguments if it had preceding or following non-whitespace characters.
1021 This version replaces it no matter where in the utility name or arguments
1026 option was inspired by the equivalent
1037 The special characters used by
1039 are also special characters to many shell programs.
1040 In particular, the characters
1051 may have to be escaped from the shell.
1053 As there is no delimiter separating options and file names or file
1056 it is difficult to specify files named
1060 These problems are handled by the
1069 primary does not interact well with other options that cause the file system
1070 tree traversal options to be changed.
1076 primaries are actually global options (as documented above).
1078 probably be replaced by options which look like options.