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
32 .\" $FreeBSD: head/usr.bin/find/find.1 247730 2013-03-03 20:10:56Z dwmalone $
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 file last access time and the time
174 was started, rounded up to the next full minute, is
177 .It Ic -anewer Ar file
180 .It Ic -atime Ar n Ns Op Cm smhdw
181 If no units are specified, this primary evaluates to
182 true if the difference between the file last access time and the time
184 was started, rounded up to the next full 24-hour period, is
188 If units are specified, this primary evaluates to
189 true if the difference between the file last access time and the time
191 was started is exactly
194 Possible time units are as follows:
196 .Bl -tag -width indent -compact
209 Any number of units may be combined in one
211 argument, for example,
212 .Dq Li "-atime -1h30m" .
213 Units are probably only useful when used in conjunction with the
218 .It Ic -cmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
219 True if the difference between the time of last change of file status
220 information and the time
222 was started, rounded up to the next full minute, is
231 .It Ic -cnewer Ar file
234 .It Ic -ctime Ar n Ns Op Cm smhdw
235 If no units are specified, this primary evaluates to
236 true if the difference between the time of last change of file status
237 information 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 time of last change of file status
245 information and the time
247 was started is exactly
252 primary description for information on supported time units.
254 Non-portable, BSD-specific version of
256 GNU find implements this as a primary in mistaken emulation of
260 Delete found files and/or directories.
263 from the current working directory as
265 recurses down the tree.
266 It will not attempt to delete a filename with a
268 character in its pathname relative to
270 for security reasons.
271 Depth-first traversal processing is implied by this option.
274 primary will fail to delete a directory if it is not empty.
275 Following symlinks is incompatible with this option.
278 same as the non-portable
283 to perform a depth-first traversal, i.e., directories
284 are visited in post-order and all entries in a directory will be acted
285 on before the directory itself.
288 visits directories in pre-order, i.e., before their contents.
291 a breadth-first traversal.
300 to process files that are contained in directories with unusual permissions.
301 It ensures that you have write permission while you are placing files in a
302 directory, then sets the directory's permissions as the last thing.
304 True if the depth of the file relative to the starting point of the traversal
308 True if the current file or directory is empty.
309 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
310 True if the program named
312 returns a zero value as its exit status.
315 may be passed to the utility.
316 The expression must be terminated by a semicolon
320 from a shell you may need to quote the semicolon if the shell would
321 otherwise treat it as a control operator.
324 appears anywhere in the utility name or the
325 arguments it is replaced by the pathname of the current file.
327 will be executed from the directory from which
333 are not subject to the further expansion of shell patterns
335 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
340 is replaced with as many pathnames as possible for each invocation of
342 This behaviour is similar to that of
344 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
347 primary is identical to the
349 primary with the exception that
351 will be executed from the directory that holds
353 The filename substituted for
357 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
362 is replaced with as many pathnames as possible for each invocation of
364 This behaviour is similar to that of
366 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
367 The flags are specified using symbolic names (see
377 are checked to be set, and flags in
379 are checked to be not set.
380 Note that this is different from
382 which only allows the user to specify mode bits that are set.
384 If flags are preceded by a dash
386 this primary evaluates to true
387 if at least all of the bits in
389 and none of the bits in
391 are set in the file's flags bits.
392 If flags are preceded by a plus
394 this primary evaluates to true
395 if any of the bits in
397 is set in the file's flags bits,
398 or any of the bits in
400 is not set in the file's flags bits.
402 this primary evaluates to true
405 exactly match the file's flags bits,
410 .It Ic -fstype Ar type
411 True if the file is contained in a file system of type
415 command can be used to find out the types of file systems
416 that are available on the system.
417 In addition, there are two pseudo-types,
421 The former matches any file system physically mounted on the system where
424 is being executed and the latter matches any file system which is
429 for compatibility with GNU find.
430 GNU find imposes a restriction that
435 .It Ic -group Ar gname
436 True if the file belongs to the group
440 is numeric and there is no such group name, then
442 is treated as a group ID.
443 .It Ic -ignore_readdir_race
444 Ignore errors because a file or a directory is deleted
445 after reading the name from a directory.
446 This option does not affect errors occurring on starting points.
447 .It Ic -ilname Ar pattern
450 but the match is case insensitive.
451 This is a GNU find extension.
452 .It Ic -iname Ar pattern
455 but the match is case insensitive.
457 True if the file has inode number
459 .It Ic -ipath Ar pattern
462 but the match is case insensitive.
463 .It Ic -iregex Ar pattern
466 but the match is case insensitive.
467 .It Ic -iwholename Ar pattern
470 for GNU find compatibility.
475 .It Ic -lname Ar pattern
478 but the contents of the symbolic link are matched instead of the file
480 This is a GNU find extension.
482 This primary always evaluates to true.
483 The following information for the current file is written to standard output:
484 its inode number, size in 512-byte blocks, file permissions, number of hard
485 links, owner, group, size in bytes, last modification time, and pathname.
486 If the file is a block or character special file, the device number
487 will be displayed instead of the size in bytes.
488 If the file is a symbolic link, the pathname of the linked-to file will be
489 displayed preceded by
491 The format is identical to that produced by
495 .It Ic -maxdepth Ar n
496 Always true; descend at most
498 directory levels below the command line arguments.
501 primary is specified, it applies to the entire expression even if it would
502 not normally be evaluated.
503 .Dq Ic -maxdepth Li 0
504 limits the whole search to the command line arguments.
505 .It Ic -mindepth Ar n
506 Always true; do not apply any tests or actions at levels less than
510 primary is specified, it applies to the entire expression even if it would
511 not normally be evaluated.
512 .Dq Ic -mindepth Li 1
513 processes all but the command line arguments.
514 .It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
515 True if the difference between the file last modification time and the time
517 was started, rounded up to the next full minute, is
526 .It Ic -mnewer Ar file
532 for GNU find compatibility.
533 .It Ic -mtime Ar n Ns Op Cm smhdw
534 If no units are specified, this primary evaluates to
535 true if the difference between the file last modification time and the time
537 was started, rounded up to the next full 24-hour period, is
541 If units are specified, this primary evaluates to
542 true if the difference between the file last modification time and the time
544 was started is exactly
549 primary description for information on supported time units.
550 .It Ic -name Ar pattern
551 True if the last component of the pathname being examined matches
553 Special shell pattern matching characters
559 may be used as part of
561 These characters may be matched explicitly by escaping them with a
564 .It Ic -newer Ar file
565 True if the current file has a more recent last modification time than
567 .It Ic -newer Ns Ar X Ns Ar Y Ar file
568 True if the current file has a more recent last access time
569 .Pq Ar X Ns = Ns Cm a ,
571 .Pq Ar X Ns = Ns Cm c ,
573 .Pq Ar X Ns = Ns Cm m
574 than the last access time
575 .Pq Ar Y Ns = Ns Cm a ,
577 .Pq Ar Y Ns = Ns Cm c ,
579 .Pq Ar Y Ns = Ns Cm m
586 is instead interpreted as a direct date specification of the form
594 True if the file belongs to an unknown group.
595 .It Ic -noignore_readdir_race
596 Turn off the effect of
597 .Ic -ignore_readdir_race .
598 This is default behaviour.
600 This option is for GNU find compatibility.
601 In GNU find it disables an optimization not relevant to
605 True if the file belongs to an unknown user.
606 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
609 primary is identical to the
611 primary with the exception that
613 requests user affirmation for the execution of the
616 a message to the terminal and reading a response.
617 If the response is not affirmative
622 the command is not executed and the
626 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
629 primary is identical to the
631 primary with the same exception as described for the
634 .It Ic -path Ar pattern
635 True if the pathname being examined matches
637 Special shell pattern matching characters
643 may be used as part of
645 These characters may be matched explicitly by escaping them with a
650 are treated as normal characters and do not have to be
652 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
655 may be either symbolic (see
660 is symbolic, a starting value of zero is assumed and the
662 sets or clears permissions without regard to the process' file mode
666 is octal, only bits 07777
667 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
668 of the file's mode bits participate
672 is preceded by a dash
674 this primary evaluates to true
675 if at least all of the bits in the
677 are set in the file's mode bits.
680 is preceded by a plus
682 this primary evaluates to true
683 if any of the bits in the
685 are set in the file's mode bits.
686 Otherwise, this primary evaluates to true if
689 exactly match the file's mode bits.
690 Note, the first character of a symbolic mode may not be a dash
693 This primary always evaluates to true.
694 It prints the pathname of the current file to standard output.
696 .Ic -exec , -ls , -print0 ,
699 is specified, the given expression shall be effectively replaced by
700 .Cm \&( Ar "given expression" Cm \&) Ic -print .
702 This primary always evaluates to true.
703 It prints the pathname of the current file to standard output, followed by an
706 character (character code 0).
708 This primary always evaluates to true.
711 to not descend into the current file.
714 primary has no effect if the
716 option was specified.
720 to immediately terminate successfully.
721 .It Ic -regex Ar pattern
722 True if the whole path of the file matches
724 using regular expression.
725 To match a file named
727 you can use the regular expression
735 .It Ic -samefile Ar name
736 True if the file is a hard link to
738 If the command option
740 is specified, it is also true if the file is a symbolic link and
743 .It Ic -size Ar n Ns Op Cm ckMGTP
744 True if the file's size, rounded up, in 512-byte blocks is
750 then the primary is true if the
756 is followed by a scale indicator then the file's size is compared to
760 .Bl -tag -width indent -compact
762 kilobytes (1024 bytes)
764 megabytes (1024 kilobytes)
766 gigabytes (1024 megabytes)
768 terabytes (1024 gigabytes)
770 petabytes (1024 terabytes)
773 True if the current file is sparse,
774 i.e. has fewer blocks allocated than expected based on its size in bytes.
775 This might also match files that have been compressed by the filesystem.
777 True if the file is of the specified type.
778 Possible file types are as follows:
780 .Bl -tag -width indent -compact
799 for compatibility with GNU find.
800 GNU find imposes a restriction that
805 .It Ic -user Ar uname
806 True if the file belongs to the user
810 is numeric and there is no such user name, then
812 is treated as a user ID.
813 .It Ic -wholename Ar pattern
816 for GNU find compatibility.
819 The primaries may be combined using the following operators.
820 The operators are listed in order of decreasing precedence.
822 .Bl -tag -width indent -compact
823 .It Cm \&( Ar expression Cm \&)
824 This evaluates to true if the parenthesized expression evaluates to
827 .It Cm \&! Ar expression
828 .It Cm -not Ar expression
832 It evaluates to true if the expression is false.
839 .It Ar expression Cm -and Ar expression
840 .It Ar expression expression
843 operator is the logical
846 As it is implied by the juxtaposition of two expressions it does not
847 have to be specified.
848 The expression evaluates to true if both expressions are true.
849 The second expression is not evaluated if the first expression is false.
851 .It Ar expression Cm -or Ar expression
854 operator is the logical
857 The expression evaluates to true if either the first or the second expression
859 The second expression is not evaluated if the first expression is true.
862 All operands and primaries must be separate arguments to
864 Primaries which themselves take arguments expect each argument
865 to be a separate argument to
869 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
872 environment variables affect the execution of the
874 utility as described in
877 The following examples are shown as given to the shell:
878 .Bl -tag -width indent
879 .It Li "find / \e! -name \*q*.c\*q -print"
880 Print out a list of all the files whose names do not end in
882 .It Li "find / -newer ttt -user wnj -print"
883 Print out a list of all the files owned by user
888 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
889 Print out a list of all the files which are not both newer than
893 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
894 Print out a list of all the files that are either owned by
896 or that are newer than
898 .It Li "find / -newerct '1 minute ago' -print"
899 Print out a list of all the files whose inode change time is more
900 recent than the current time minus one minute.
901 .It Li "find / -type f -exec echo {} \e;"
904 command to print out a list of all the files.
905 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
906 Delete all broken symbolic links in
907 .Pa /usr/ports/packages .
908 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
909 Find files and directories that are at least seven levels deep
910 in the working directory
912 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
913 Is not equivalent to the previous example, since
915 is not evaluated below level seven.
920 primary is deprecated; the
922 option should be used instead.
925 section below for details.
945 utility syntax is a superset of the syntax specified by the
949 All the single character options except
954 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
955 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
956 .Ic -path , -print0 , -regex , -sparse
964 options were implemented using the primaries
965 .Ic -depth , -follow ,
968 These primaries always evaluated to true.
969 As they were really global variables that took effect before the traversal
970 began, some legal expressions could have unexpected results.
971 An example is the expression
972 .Ic -print Cm -o Ic -depth .
975 always evaluates to true, the standard order of evaluation
978 would never be evaluated.
979 This is not the case.
990 Historic implementations of the
994 primaries did not replace the string
996 in the utility name or the
997 utility arguments if it had preceding or following non-whitespace characters.
998 This version replaces it no matter where in the utility name or arguments
1003 option was inspired by the equivalent
1014 The special characters used by
1016 are also special characters to many shell programs.
1017 In particular, the characters
1028 may have to be escaped from the shell.
1030 As there is no delimiter separating options and file names or file
1033 it is difficult to specify files named
1037 These problems are handled by the
1046 primary does not interact well with other options that cause the file system
1047 tree traversal options to be changed.
1053 primaries are actually global options (as documented above).
1055 probably be replaced by options which look like options.