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. All advertising materials mentioning features or use of this software
16 .\" must display the following acknowledgement:
17 .\" This product includes software developed by the University of
18 .\" California, Berkeley and its contributors.
19 .\" 4. Neither the name of the University nor the names of its contributors
20 .\" may be used to endorse or promote products derived from this software
21 .\" without specific prior written permission.
23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .\" @(#)find.1 8.7 (Berkeley) 5/9/95
43 .Nd walk a file hierarchy
46 .Op Fl H | Fl L | Fl P
52 .Op Fl H | Fl L | Fl P
60 utility recursively descends the directory tree for each
68 listed below) in terms
69 of each file in the tree.
71 The options are as follows:
72 .Bl -tag -width indent
74 Interpret regular expressions followed by
78 options as extended (modern) regular expressions rather than basic
79 regular expressions (BRE's).
82 manual page fully describes both formats.
84 Cause the file information and file type (see
86 returned for each symbolic link specified on the command line to be
87 those of the file referenced by the link, not the link itself.
88 If the referenced file does not exist, the file information and type will
89 be for the link itself.
90 File information of all symbolic links not on
91 the command line is that of the link itself.
93 Cause the file information and file type (see
95 returned for each symbolic link to be those of the file referenced by the
96 link, not the link itself.
97 If the referenced file does not exist, the file information and type will
98 be for the link itself.
100 This option is equivalent to the deprecated
104 Cause the file information and file type (see
106 returned for each symbolic link to be those of the link itself.
111 to be safely used in conjunction with
113 If a file name contains any of the delimiting characters used by
115 a diagnostic message is displayed on standard error, and the file
117 The delimiting characters include single
123 space, tab and newline characters.
125 However, you may wish to consider the
127 primary in conjunction with
129 as an effective alternative.
133 to perform a depth-first traversal, i.e., directories
134 are visited in post-order and all entries in a directory will be acted
135 on before the directory itself.
138 visits directories in pre-order, i.e., before their contents.
141 a breadth-first traversal.
143 This option is equivalent to the
152 to process files that are contained in directories with unusual permissions.
153 It ensures that you have write permission while you are placing files in a
154 directory, then sets the directory's permissions as the last thing.
156 Specify a file hierarchy for
159 File hierarchies may also be specified as the operands immediately
160 following the options.
164 to traverse the file hierarchies in lexicographical order,
165 i.e., alphabetical order within each directory.
170 may give different results.
174 from descending into directories that have a device number different
175 than that of the file from which the descent began.
177 This option is equivalent to the deprecated
182 .Bl -tag -width indent
184 True if the difference between the time of a file's inode creation
187 was started, rounded up to the next full minute, is
190 .It Ic -Bnewer Ar file
193 .It Ic -Btime Ar n Ns Op Cm smhdw
194 If no units are specified, this primary evaluates to
195 true if the difference between the time of a file's inode creation
198 was started, rounded up to the next full 24-hour period, is
202 If units are specified, this primary evaluates to
203 true if the difference between the time of last change of file status
204 information and the time
206 was started is exactly
211 primary description for information on supported time units.
213 May be used in conjunction with other options to locate
214 files with extended ACLs.
217 for more information.
219 True if the difference between the file last access time and the time
221 was started, rounded up to the next full minute, is
224 .It Ic -anewer Ar file
227 .It Ic -atime Ar n Ns Op Cm smhdw
228 If no units are specified, this primary evaluates to
229 true if the difference between the file last access time and the time
231 was started, rounded up to the next full 24-hour period, is
235 If units are specified, this primary evaluates to
236 true if the difference between the file last access time and the time
238 was started is exactly
241 Possible time units are as follows:
243 .Bl -tag -width indent -compact
256 Any number of units may be combined in one
258 argument, for example,
259 .Dq Li "-atime -1h30m" .
260 Units are probably only useful when used in conjunction with the
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 minute, is
272 .It Ic -cnewer Ar file
275 .It Ic -ctime Ar n Ns Op Cm smhdw
276 If no units are specified, this primary evaluates to
277 true if the difference between the time of last change of file status
278 information and the time
280 was started, rounded up to the next full 24-hour period, is
284 If units are specified, this primary evaluates to
285 true if the difference between the time of last change of file status
286 information and the time
288 was started is exactly
293 primary description for information on supported time units.
295 Delete found files and/or directories.
298 from the current working directory as
300 recurses down the tree.
301 It will not attempt to delete a filename with a
303 character in its pathname relative to
305 for security reasons.
306 Depth-first traversal processing is implied by this option.
313 True if the depth of the file relative to the starting point of the traversal
317 True if the current file or directory is empty.
318 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
319 True if the program named
321 returns a zero value as its exit status.
324 may be passed to the utility.
325 The expression must be terminated by a semicolon
329 from a shell you may need to quote the semicolon if the shell would
330 otherwise treat it as a control operator.
333 appears anywhere in the utility name or the
334 arguments it is replaced by the pathname of the current file.
336 will be executed from the directory from which
342 are not subject to the further expansion of shell patterns
344 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
349 is replaced with as many pathnames as possible for each invocation of
351 This behaviour is similar to that of
353 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
356 primary is identical to the
358 primary with the exception that
360 will be executed from the directory that holds
362 The filename substituted for
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:
420 In addition, there are two pseudo-types,
424 The former matches any file system physically mounted on the system where
427 is being executed and the latter matches any file system which is
429 .It Ic -group Ar gname
430 True if the file belongs to the group
434 is numeric and there is no such group name, then
436 is treated as a group ID.
437 .It Ic -iname Ar pattern
440 but the match is case insensitive.
442 True if the file has inode number
444 .It Ic -ipath Ar pattern
447 but the match is case insensitive.
448 .It Ic -iregex Ar pattern
451 but the match is case insensitive.
457 This primary always evaluates to true.
458 The following information for the current file is written to standard output:
459 its inode number, size in 512-byte blocks, file permissions, number of hard
460 links, owner, group, size in bytes, last modification time, and pathname.
461 If the file is a block or character special file, the major and minor numbers
462 will be displayed instead of the size in bytes.
463 If the file is a symbolic link, the pathname of the linked-to file will be
464 displayed preceded by
466 The format is identical to that produced by
470 .It Ic -maxdepth Ar n
471 Always true; descend at most
473 directory levels below the command line arguments.
476 primary is specified, it applies to the entire expression even if it would
477 not normally be evaluated.
479 limits the whole search to the command line arguments.
480 .It Ic -mindepth Ar n
481 Always true; do not apply any tests or actions at levels less than
485 primary is specified, it applies to the entire expression even if it would
486 not normally be evaluated.
488 processes all but the command line arguments.
490 True if the difference between the file last modification time and the time
492 was started, rounded up to the next full minute, is
495 .It Ic -mnewer Ar file
498 .It Ic -mtime Ar n Ns Op Cm smhdw
499 If no units are specified, this primary evaluates to
500 true if the difference between the file last modification time and the time
502 was started, rounded up to the next full 24-hour period, is
506 If units are specified, this primary evaluates to
507 true if the difference between the file last modification time and the time
509 was started is exactly
514 primary description for information on supported time units.
515 .It Ic -name Ar pattern
516 True if the last component of the pathname being examined matches
518 Special shell pattern matching characters
524 may be used as part of
526 These characters may be matched explicitly by escaping them with a
529 .It Ic -newer Ar file
530 True if the current file has a more recent last modification time than
532 .It Ic -newer Ns Ar X Ns Ar Y Ar file
533 True if the current file has a more recent last access time
534 .Ar ( X Ns = Ns Cm a ) ,
536 .Ar ( X Ns = Ns Cm B ) ,
538 .Ar ( X Ns = Ns Cm c ) ,
540 .Ar ( X Ns = Ns Cm m )
541 than the last access time
542 .Ar ( Y Ns = Ns Cm a ) ,
544 .Ar ( Y Ns = Ns Cm B ) ,
546 .Ar ( Y Ns = Ns Cm c ) ,
548 .Ar ( Y Ns = Ns Cm m )
555 is instead interpreted as a direct date specification of the form
563 True if the file belongs to an unknown group.
565 True if the file belongs to an unknown user.
566 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
569 primary is identical to the
571 primary with the exception that
573 requests user affirmation for the execution of the
576 a message to the terminal and reading a response.
577 If the response is not affirmative
582 the command is not executed and the
586 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
589 primary is identical to the
591 primary with the same exception as described for the
594 .It Ic -path Ar pattern
595 True if the pathname being examined matches
597 Special shell pattern matching characters
603 may be used as part of
605 These characters may be matched explicitly by escaping them with a
610 are treated as normal characters and do not have to be
612 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
615 may be either symbolic (see
620 is symbolic, a starting value of zero is assumed and the
622 sets or clears permissions without regard to the process' file mode
626 is octal, only bits 07777
627 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
628 of the file's mode bits participate
632 is preceded by a dash
634 this primary evaluates to true
635 if at least all of the bits in the
637 are set in the file's mode bits.
640 is preceded by a plus
642 this primary evaluates to true
643 if any of the bits in the
645 are set in the file's mode bits.
646 Otherwise, this primary evaluates to true if
649 exactly match the file's mode bits.
650 Note, the first character of a symbolic mode may not be a dash
653 This primary always evaluates to true.
654 It prints the pathname of the current file to standard output.
656 .Ic -exec , -ls , -print0 ,
659 is specified, the given expression shall be effectively replaced by
660 .Cm \&( Ar "given expression" Cm \&) Ic -print .
662 This primary always evaluates to true.
663 It prints the pathname of the current file to standard output, followed by an
665 character (character code 0).
667 This primary always evaluates to true.
670 to not descend into the current file.
673 primary has no effect if the
675 option was specified.
676 .It Ic -regex Ar pattern
677 True if the whole path of the file matches
679 using regular expression.
680 To match a file named
682 you can use the regular expression
690 .It Ic -size Ar n Ns Op Cm ckMGTP
691 True if the file's size, rounded up, in 512-byte blocks is
697 then the primary is true if the
703 is followed by a scale indicator then the file's size is compared to
707 .Bl -tag -width indent -compact
709 kilobytes (1024 bytes)
711 megabytes (1024 kilobytes)
713 gigabytes (1024 megabytes)
715 terabytes (1024 gigabytes)
717 petabytes (1024 terabytes)
721 True if the file is of the specified type.
722 Possible file types are as follows:
724 .Bl -tag -width indent -compact
740 .It Ic -user Ar uname
741 True if the file belongs to the user
745 is numeric and there is no such user name, then
747 is treated as a user ID.
750 All primaries which take a numeric argument allow the number to be
751 preceded by a plus sign
755 A preceding plus sign means
757 a preceding minus sign means
762 The primaries may be combined using the following operators.
763 The operators are listed in order of decreasing precedence.
765 .Bl -tag -width "( expression )" -compact
766 .It Cm \&( Ar expression Cm \&)
767 This evaluates to true if the parenthesized expression evaluates to
770 .It Cm \&! Ar expression
771 .It Cm -false Ar expression
772 .It Cm -not Ar expression
776 It evaluates to true if the expression is false.
778 .It Ar expression Cm -and Ar expression
779 .It Ar expression expression
782 operator is the logical
785 As it is implied by the juxtaposition of two expressions it does not
786 have to be specified.
787 The expression evaluates to true if both expressions are true.
788 The second expression is not evaluated if the first expression is false.
790 .It Ar expression Cm -or Ar expression
793 operator is the logical
796 The expression evaluates to true if either the first or the second expression
798 The second expression is not evaluated if the first expression is true.
801 All operands and primaries must be separate arguments to
803 Primaries which themselves take arguments expect each argument
804 to be a separate argument to
808 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
811 environment variables affect the execution of the
813 utility as described in
816 The following examples are shown as given to the shell:
817 .Bl -tag -width indent
818 .It Li "find / \e! -name \*q*.c\*q -print"
819 Print out a list of all the files whose names do not end in
821 .It Li "find / -newer ttt -user wnj -print"
822 Print out a list of all the files owned by user
827 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
828 Print out a list of all the files which are not both newer than
832 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
833 Print out a list of all the files that are either owned by
835 or that are newer than
837 .It Li "find / -newerct '1 minute ago' -print"
838 Print out a list of all the files whose inode change time is more
839 recent than the current time minus one minute.
840 .It Li "find / -type f -exec echo {} \e;"
843 command to print out a list of all the files.
844 .It Li "find -L /usr/ports/packages -type l -delete"
845 Delete all broken symbolic links in
846 .Pa /usr/ports/packages .
847 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
848 Find files and directories that are at least seven levels deep
849 in the working directory
851 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
852 Is not equivalent to the previous example, since
854 is not evaluated below level seven.
859 primary is deprecated; the
861 option should be used instead.
864 section below for details.
884 utility syntax is a superset of the syntax specified by the
888 All the single character options except
893 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls , -regex ,
896 birthtime related primaries are extensions to
903 options were implemented using the primaries
904 .Ic -depth , -follow ,
907 These primaries always evaluated to true.
908 As they were really global variables that took effect before the traversal
909 began, some legal expressions could have unexpected results.
910 An example is the expression
911 .Ic -print Cm -o Ic -depth .
914 always evaluates to true, the standard order of evaluation
917 would never be evaluated.
918 This is not the case.
929 Historic implementations of the
933 primaries did not replace the string
935 in the utility name or the
936 utility arguments if it had preceding or following non-whitespace characters.
937 This version replaces it no matter where in the utility name or arguments
942 option was inspired by the equivalent
953 The special characters used by
955 are also special characters to many shell programs.
956 In particular, the characters
967 may have to be escaped from the shell.
969 As there is no delimiter separating options and file names or file
972 it is difficult to specify files named
976 These problems are handled by the
985 primary does not interact well with other options that cause the file system
986 tree traversal options to be changed.
992 primaries are actually global options (as documented above).
994 probably be replaced by options which look like options.