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
54 utility recursively descends the directory tree for each
62 listed below) in terms
63 of each file in the tree.
65 The options are as follows:
66 .Bl -tag -width indent
68 Interpret regular expressions followed by
72 options as extended (modern) regular expressions rather than basic
73 regular expressions (BRE's).
76 manual page fully describes both formats.
78 Cause the file information and file type (see
80 returned for each symbolic link specified on the command line to be
81 those of the file referenced by the link, not the link itself.
82 If the referenced file does not exist, the file information and type will
83 be for the link itself.
84 File information of all symbolic links not on
85 the command line is that of the link itself.
87 Cause the file information and file type (see
89 returned for each symbolic link to be those of the file referenced by the
90 link, not the link itself.
91 If the referenced file does not exist, the file information and type will
92 be for the link itself.
94 This option is equivalent to the deprecated
98 Cause the file information and file type (see
100 returned for each symbolic link to be those of the link itself.
105 to be safely used in conjunction with
107 If a file name contains any of the delimiting characters used by
109 a diagnostic message is displayed on standard error, and the file
111 The delimiting characters include single
117 space, tab and newline characters.
119 However, you may wish to consider the
121 primary in conjunction with
123 as an effective alternative.
127 to perform a depth-first traversal, i.e., directories
128 are visited in post-order and all entries in a directory will be acted
129 on before the directory itself.
132 visits directories in pre-order, i.e., before their contents.
135 a breadth-first traversal.
137 This option is equivalent to the
146 to process files that are contained in directories with unusual permissions.
147 It ensures that you have write permission while you are placing files in a
148 directory, then sets the directory's permissions as the last thing.
150 Specify a file hierarchy for
153 File hierarchies may also be specified as the operands immediately
154 following the options.
158 to traverse the file hierarchies in lexicographical order,
159 i.e., alphabetical order within each directory.
164 may give different results.
168 from descending into directories that have a device number different
169 than that of the file from which the descent began.
171 This option is equivalent to the deprecated
176 .Bl -tag -width indent
178 True if the difference between the time of a file's inode creation
181 was started, rounded up to the next full minute, is
184 .It Ic -Bnewer Ar file
187 .It Ic -Btime Ar n Ns Op Cm smhdw
188 If no units are specified, this primary evaluates to
189 true if the difference between the time of a file's inode creation
192 was started, rounded up to the next full 24-hour period, is
196 If units are specified, this primary evaluates to
197 true if the difference between the time of last change of file status
198 information and the time
200 was started is exactly
205 primary description for information on supported time units.
207 May be used in conjunction with other options to locate
208 files with extended ACLs.
211 for more information.
213 True if the difference between the file last access time and the time
215 was started, rounded up to the next full minute, is
218 .It Ic -anewer Ar file
221 .It Ic -atime Ar n Ns Op Cm smhdw
222 If no units are specified, this primary evaluates to
223 true if the difference between the file last access time and the time
225 was started, rounded up to the next full 24-hour period, is
229 If units are specified, this primary evaluates to
230 true if the difference between the file last access time and the time
232 was started is exactly
235 Possible time units are as follows:
237 .Bl -tag -width indent -compact
250 Any number of units may be combined in one
252 argument, for example,
253 .Dq Li "-atime -1h30m" .
254 Units are probably only useful when used in conjunction with the
260 True if the difference between the time of last change of file status
261 information and the time
263 was started, rounded up to the next full minute, is
266 .It Ic -cnewer Ar file
269 .It Ic -ctime Ar n Ns Op Cm smhdw
270 If no units are specified, this primary evaluates to
271 true if the difference between the time of last change of file status
272 information and the time
274 was started, rounded up to the next full 24-hour period, is
278 If units are specified, this primary evaluates to
279 true if the difference between the time of last change of file status
280 information and the time
282 was started is exactly
287 primary description for information on supported time units.
289 Delete found files and/or directories.
292 from the current working directory as
294 recurses down the tree.
295 It will not attempt to delete a filename with a
297 character in its pathname relative to
299 for security reasons.
300 Depth-first traversal processing is implied by this option.
307 True if the depth of the file relative to the starting point of the traversal
311 True if the current file or directory is empty.
312 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
313 True if the program named
315 returns a zero value as its exit status.
318 may be passed to the utility.
319 The expression must be terminated by a semicolon
323 from a shell you may need to quote the semicolon if the shell would
324 otherwise treat it as a control operator.
327 appears anywhere in the utility name or the
328 arguments it is replaced by the pathname of the current file.
330 will be executed from the directory from which
336 are not subject to the further expansion of shell patterns
338 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
343 is replaced with as many pathnames as possible for each invocation of
345 This behaviour is similar to that of
347 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
350 primary is identical to the
352 primary with the exception that
354 will be executed from the directory that holds
356 The filename substituted for
360 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
361 The flags are specified using symbolic names (see
371 are checked to be set, and flags in
373 are checked to be not set.
374 Note that this is different from
376 which only allows the user to specify mode bits that are set.
378 If flags are preceded by a dash
380 this primary evaluates to true
381 if at least all of the bits in
383 and none of the bits in
385 are set in the file's flags bits.
386 If flags are preceded by a plus
388 this primary evaluates to true
389 if any of the bits in
391 is set in the file's flags bits,
392 or any of the bits in
394 is not set in the file's flags bits.
396 this primary evaluates to true
399 exactly match the file's flags bits,
404 .It Ic -fstype Ar type
405 True if the file is contained in a file system of type
409 command can be used to find out the types of file systems
410 that are available on the system:
414 In addition, there are two pseudo-types,
418 The former matches any file system physically mounted on the system where
421 is being executed and the latter matches any file system which is
423 .It Ic -group Ar gname
424 True if the file belongs to the group
428 is numeric and there is no such group name, then
430 is treated as a group ID.
431 .It Ic -iname Ar pattern
434 but the match is case insensitive.
436 True if the file has inode number
438 .It Ic -ipath Ar pattern
441 but the match is case insensitive.
442 .It Ic -iregex Ar pattern
445 but the match is case insensitive.
451 This primary always evaluates to true.
452 The following information for the current file is written to standard output:
453 its inode number, size in 512-byte blocks, file permissions, number of hard
454 links, owner, group, size in bytes, last modification time, and pathname.
455 If the file is a block or character special file, the major and minor numbers
456 will be displayed instead of the size in bytes.
457 If the file is a symbolic link, the pathname of the linked-to file will be
458 displayed preceded by
460 The format is identical to that produced by
464 .It Ic -maxdepth Ar n
465 Always true; descend at most
467 directory levels below the command line arguments.
470 primary is specified, it applies to the entire expression even if it would
471 not normally be evaluated.
473 limits the whole search to the command line arguments.
474 .It Ic -mindepth Ar n
475 Always true; do not apply any tests or actions at levels less than
479 primary is specified, it applies to the entire expression even if it would
480 not normally be evaluated.
482 processes all but the command line arguments.
484 True if the difference between the file last modification time and the time
486 was started, rounded up to the next full minute, is
489 .It Ic -mnewer Ar file
492 .It Ic -mtime Ar n Ns Op Cm smhdw
493 If no units are specified, this primary evaluates to
494 true if the difference between the file last modification time and the time
496 was started, rounded up to the next full 24-hour period, is
500 If units are specified, this primary evaluates to
501 true if the difference between the file last modification time and the time
503 was started is exactly
508 primary description for information on supported time units.
509 .It Ic -name Ar pattern
510 True if the last component of the pathname being examined matches
512 Special shell pattern matching characters
518 may be used as part of
520 These characters may be matched explicitly by escaping them with a
523 .It Ic -newer Ar file
524 True if the current file has a more recent last modification time than
526 .It Ic -newer Ns Ar X Ns Ar Y Ar file
527 True if the current file has a more recent last access time
528 .Ar ( X Ns = Ns Cm a ) ,
530 .Ar ( X Ns = Ns Cm B ) ,
532 .Ar ( X Ns = Ns Cm c ) ,
534 .Ar ( X Ns = Ns Cm m )
535 than the last access time
536 .Ar ( Y Ns = Ns Cm a ) ,
538 .Ar ( Y Ns = Ns Cm B ) ,
540 .Ar ( Y Ns = Ns Cm c ) ,
542 .Ar ( Y Ns = Ns Cm m )
549 is instead interpreted as a direct date specification of the form
557 True if the file belongs to an unknown group.
559 True if the file belongs to an unknown user.
560 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
563 primary is identical to the
565 primary with the exception that
567 requests user affirmation for the execution of the
570 a message to the terminal and reading a response.
571 If the response is not affirmative
576 the command is not executed and the
580 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
583 primary is identical to the
585 primary with the same exception as described for the
588 .It Ic -path Ar pattern
589 True if the pathname being examined matches
591 Special shell pattern matching characters
597 may be used as part of
599 These characters may be matched explicitly by escaping them with a
604 are treated as normal characters and do not have to be
606 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
609 may be either symbolic (see
614 is symbolic, a starting value of zero is assumed and the
616 sets or clears permissions without regard to the process' file mode
620 is octal, only bits 07777
621 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
622 of the file's mode bits participate
626 is preceded by a dash
628 this primary evaluates to true
629 if at least all of the bits in the
631 are set in the file's mode bits.
634 is preceded by a plus
636 this primary evaluates to true
637 if any of the bits in the
639 are set in the file's mode bits.
640 Otherwise, this primary evaluates to true if
643 exactly match the file's mode bits.
644 Note, the first character of a symbolic mode may not be a dash
647 This primary always evaluates to true.
648 It prints the pathname of the current file to standard output.
650 .Ic -exec , -ls , -print0 ,
653 is specified, the given expression shall be effectively replaced by
654 .Cm \&( Ar "given expression" Cm \&) Ic -print .
656 This primary always evaluates to true.
657 It prints the pathname of the current file to standard output, followed by an
659 character (character code 0).
661 This primary always evaluates to true.
664 to not descend into the current file.
667 primary has no effect if the
669 option was specified.
670 .It Ic -regex Ar pattern
671 True if the whole path of the file matches
673 using regular expression.
674 To match a file named
676 you can use the regular expression
684 .It Ic -size Ar n Ns Op Cm ckMGTP
685 True if the file's size, rounded up, in 512-byte blocks is
691 then the primary is true if the
697 is followed by a scale indicator then the file's size is compared to
701 .Bl -tag -width indent -compact
703 kilobytes (1024 bytes)
705 megabytes (1024 kilobytes)
707 gigabytes (1024 megabytes)
709 terabytes (1024 gigabytes)
711 petabytes (1024 terabytes)
715 True if the file is of the specified type.
716 Possible file types are as follows:
718 .Bl -tag -width indent -compact
734 .It Ic -user Ar uname
735 True if the file belongs to the user
739 is numeric and there is no such user name, then
741 is treated as a user ID.
744 All primaries which take a numeric argument allow the number to be
745 preceded by a plus sign
749 A preceding plus sign means
751 a preceding minus sign means
756 The primaries may be combined using the following operators.
757 The operators are listed in order of decreasing precedence.
759 .Bl -tag -width "( expression )" -compact
760 .It Cm \&( Ar expression Cm \&)
761 This evaluates to true if the parenthesized expression evaluates to
764 .It Cm \&! Ar expression
765 .It Cm -false Ar expression
766 .It Cm -not Ar expression
770 It evaluates to true if the expression is false.
772 .It Ar expression Cm -and Ar expression
773 .It Ar expression expression
776 operator is the logical
779 As it is implied by the juxtaposition of two expressions it does not
780 have to be specified.
781 The expression evaluates to true if both expressions are true.
782 The second expression is not evaluated if the first expression is false.
784 .It Ar expression Cm -or Ar expression
787 operator is the logical
790 The expression evaluates to true if either the first or the second expression
792 The second expression is not evaluated if the first expression is true.
795 All operands and primaries must be separate arguments to
797 Primaries which themselves take arguments expect each argument
798 to be a separate argument to
802 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
805 environment variables affect the execution of the
807 utility as described in
810 The following examples are shown as given to the shell:
811 .Bl -tag -width indent
812 .It Li "find / \e! -name \*q*.c\*q -print"
813 Print out a list of all the files whose names do not end in
815 .It Li "find / -newer ttt -user wnj -print"
816 Print out a list of all the files owned by user
821 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
822 Print out a list of all the files which are not both newer than
826 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
827 Print out a list of all the files that are either owned by
829 or that are newer than
831 .It Li "find / -newerct '1 minute ago' -print"
832 Print out a list of all the files whose inode change time is more
833 recent than the current time minus one minute.
834 .It Li "find / -type f -exec echo {} \e;"
837 command to print out a list of all the files.
838 .It Li "find -L /usr/ports/packages -type l -delete"
839 Delete all broken symbolic links in
840 .Pa /usr/ports/packages .
841 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
842 Find files and directories that are at least seven levels deep
843 in the working directory
845 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
846 Is not equivalent to the previous example, since
848 is not evaluated below level seven.
853 primary is deprecated; the
855 option should be used instead.
858 section below for details.
878 utility syntax is a superset of the syntax specified by the
882 All the single character options except
887 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls , -regex ,
890 birthtime related primaries are extensions to
897 options were implemented using the primaries
898 .Ic -depth , -follow ,
901 These primaries always evaluated to true.
902 As they were really global variables that took effect before the traversal
903 began, some legal expressions could have unexpected results.
904 An example is the expression
905 .Ic -print Cm -o Ic -depth .
908 always evaluates to true, the standard order of evaluation
911 would never be evaluated.
912 This is not the case.
923 Historic implementations of the
927 primaries did not replace the string
929 in the utility name or the
930 utility arguments if it had preceding or following non-whitespace characters.
931 This version replaces it no matter where in the utility name or arguments
936 option was inspired by the equivalent
947 The special characters used by
949 are also special characters to many shell programs.
950 In particular, the characters
961 may have to be escaped from the shell.
963 As there is no delimiter separating options and file names or file
966 it is difficult to specify files named
970 These problems are handled by the
979 primary does not interact well with other options that cause the file system
980 tree traversal options to be changed.
986 primaries are actually global options (as documented above).
988 probably be replaced by options which look like options.