1 .\" The Regents of the University of California. All rights reserved.
3 .\" This code is derived from software contributed to Berkeley by
4 .\" the Institute of Electrical and Electronics Engineers, Inc.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. All advertising materials mentioning features or use of this software
15 .\" must display the following acknowledgement:
16 .\" This product includes software developed by the University of
17 .\" California, Berkeley and its contributors.
18 .\" 4. Neither the name of the University nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" @(#)find.1 8.7 (Berkeley) 5/9/95
42 .Nd walk a file hierarchy
45 .Op Fl H | Fl L | Fl P
52 recursively descends the directory tree for each
60 listed below) in terms
61 of each file in the tree.
63 The options are as follows:
64 .Bl -tag -width indent
66 Interpret regular expressions followed by
70 options as extended (modern) regular expressions rather than basic
71 regular expressions (BRE's).
74 manual page fully describes both formats.
78 option causes 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.
89 option causes 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.
98 option causes the file information and file type (see
100 returned for each symbolic link to be those of the link itself.
105 option is a modification to permit
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.
131 to perform a depth\-first traversal, i.e., directories
132 are visited in post\-order and all entries in a directory will be acted
133 on before the directory itself.
136 visits directories in pre\-order, i.e., before their contents.
139 a breadth\-first traversal.
143 option specifies a file hierarchy for
146 File hierarchies may also be specified as the operands immediately
147 following the options.
153 to traverse the file hierarchies in lexicographical order,
154 i.e., alphabetical order within each directory.
159 may give different results.
165 from descending into directories that have a device number different
166 than that of the file from which the descent began.
169 .Bl -tag -width indent
171 True if the difference between the file last access time and the time
173 was started, rounded up to the next full minute, is
176 .It Ic -anewer Ar file
179 .It Ic -atime Ar n Ns Op Cm smhdw
180 If no units are specified, this primary evaluates to
181 true if the difference between the file last access time and the time
183 was started, rounded up to the next full 24\-hour period, is
187 If units are specified, this primary evaluates to
188 true if the difference between the file last access time and the time
190 was started is exactly
193 Possible time units are as follows:
195 .Bl -tag -width indent -compact
208 Any number of units may be combined in one
210 argument, for example,
211 .Dq Li "-atime -1h30m" .
212 Units are probably only useful when used in conjunction with the
218 True if the difference between the time of last change of file status
219 information and the time
221 was started, rounded up to the next full minute, is
224 .It Ic -cnewer Ar file
227 .It Ic -ctime Ar n Ns Op Cm smhdw
228 If no units are specified, this primary evaluates to
229 true if the difference between the time of last change of file status
230 information and the time
232 was started, rounded up to the next full 24\-hour period, is
236 If units are specified, this primary evaluates to
237 true if the difference between the time of last change of file status
238 information and the time
240 was started is exactly
245 primary description for information on supported time units.
247 Delete found files and/or directories.
250 from the current working directory as
252 recurses down the tree.
253 It will not attempt to delete a filename with a
255 character in its pathname relative to
257 for security reasons.
258 Depth\-first traversal processing is implied by this option.
269 to process files that are contained in directories with unusual permissions.
270 It ensures that you have write permission while you are placing files in a
271 directory, then sets the directory's permissions as the last thing.
273 True if the current file or directory is empty.
274 .It Ic -exec Ar utility Op Ar argument ... ;
275 True if the program named
277 returns a zero value as its exit status.
280 may be passed to the utility.
281 The expression must be terminated by a semicolon
285 appears anywhere in the utility name or the
286 arguments it is replaced by the pathname of the current file.
288 will be executed from the directory from which
294 are not subject to the further expansion of shell patterns
296 .It Ic -execdir Ar utility Op Ar argument ... ;
299 primary is identical to the
301 primary with the exception that
303 will be executed from the directory that holds
305 The filename substituted for
309 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
310 The flags are specified using symbolic names (see
320 are checked to be set, and flags in
322 are checked to be not set.
323 Note that this is different from
325 which only allows the user to specify mode bits that are set.
327 If flags are preceded by a dash
329 this primary evaluates to true
330 if at least all of the bits in
332 and none of the bits in
334 are set in the file's flags bits.
335 If flags are preceded by a plus
337 this primary evaluates to true
338 if any of the bits in
340 is set in the file's flags bits,
341 or any of the bits in
343 is not set in the file's flags bits.
345 this primary evaluates to true
348 exactly match the file's flags bits,
353 .It Ic -fstype Ar type
354 True if the file is contained in a file system of type
358 command can be used to find out the types of filesystems
359 that are available on the system:
363 In addition, there are two pseudo-types,
367 The former matches any file system physically mounted on the system where
370 is being executed and the latter matches any file system which is
372 .It Ic -group Ar gname
373 True if the file belongs to the group
377 is numeric and there is no such group name, then
379 is treated as a group ID.
380 .It Ic -iname Ar pattern
383 but the match is case insensitive.
385 True if the file has inode number
387 .It Ic -ipath Ar pattern
390 but the match is case insensitive.
391 .It Ic -iregex Ar pattern
394 but the match is case insensitive.
400 This primary always evaluates to true.
401 The following information for the current file is written to standard output:
402 its inode number, size in 512\-byte blocks, file permissions, number of hard
403 links, owner, group, size in bytes, last modification time, and pathname.
404 If the file is a block or character special file, the major and minor numbers
405 will be displayed instead of the size in bytes.
406 If the file is a symbolic link, the pathname of the linked\-to file will be
407 displayed preceded by
409 The format is identical to that produced by
413 .It Ic -maxdepth Ar n
414 True if the depth of the current file into the tree is less than or equal to
416 .It Ic -mindepth Ar n
417 True if the depth of the current file into the tree is greater than or equal to
420 True if the difference between the file last modification time and the time
422 was started, rounded up to the next full minute, is
425 .It Ic -mnewer Ar file
428 .It Ic -mtime Ar n Ns Op Cm smhdw
429 If no units are specified, this primary evaluates to
430 true if the difference between the file last modification time and the time
432 was started, rounded up to the next full 24\-hour period, is
436 If units are specified, this primary evaluates to
437 true if the difference between the file last modification time and the time
439 was started is exactly
444 primary description for information on supported time units.
445 .It Ic -name Ar pattern
446 True if the last component of the pathname being examined matches
448 Special shell pattern matching characters
454 may be used as part of
456 These characters may be matched explicitly by escaping them with a
459 .It Ic -newer Ar file
460 True if the current file has a more recent last modification time than
462 .It Ic -newer Ns Ar X Ns Ar Y Ar file
463 True if the current file has a more recent last access time
464 .Ar ( X Ns = Ns Cm a ) ,
466 .Ar ( X Ns = Ns Cm c ) ,
468 .Ar ( X Ns = Ns Cm m )
469 than the last access time
470 .Ar ( Y Ns = Ns Cm a ) ,
472 .Ar ( Y Ns = Ns Cm c ) ,
474 .Ar ( Y Ns = Ns Cm m )
481 is instead interpreted as a direct date specification of the form
489 True if the file belongs to an unknown group.
491 True if the file belongs to an unknown user.
492 .It Ic -ok Ar utility Op Ar argument ... ;
495 primary is identical to the
497 primary with the exception that
499 requests user affirmation for the execution of the
502 a message to the terminal and reading a response.
503 If the response is other than
505 the command is not executed and the
509 .It Ic -okdir Ar utility Op Ar argument ... ;
512 primary is identical to the
514 primary with the same exception as described for the
517 .It Ic -path Ar pattern
518 True if the pathname being examined matches
520 Special shell pattern matching characters
526 may be used as part of
528 These characters may be matched explicitly by escaping them with a
533 are treated as normal characters and do not have to be
535 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
538 may be either symbolic (see
543 is symbolic, a starting value of zero is assumed and the
545 sets or clears permissions without regard to the process' file mode
549 is octal, only bits 07777
550 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
551 of the file's mode bits participate
555 is preceded by a dash
557 this primary evaluates to true
558 if at least all of the bits in the
560 are set in the file's mode bits.
563 is preceded by a plus
565 this primary evaluates to true
566 if any of the bits in the
568 are set in the file's mode bits.
569 Otherwise, this primary evaluates to true if
572 exactly match the file's mode bits.
573 Note, the first character of a symbolic mode may not be a dash
576 This primary always evaluates to true.
577 It prints the pathname of the current file to standard output.
579 .Ic -exec , -ls , -print0 ,
582 is specified, the given expression shall be effectively replaced by
583 .Cm \&( Ar "given expression" Cm \&) Ic -print .
585 This primary always evaluates to true.
586 It prints the pathname of the current file to standard output, followed by an
588 character (character code 0).
590 This primary always evaluates to true.
593 to not descend into the current file.
596 primary has no effect if the
598 option was specified.
599 .It Ic -regex Ar pattern
600 True if the whole path of the file matches
602 using regular expression.
603 To match a file named
605 you can use the regular expression
613 .It Ic -size Ar n Ns Op Cm c
614 True if the file's size, rounded up, in 512\-byte blocks is
620 then the primary is true if the
625 True if the file is of the specified type.
626 Possible file types are as follows:
628 .Bl -tag -width indent -compact
644 .It Ic -user Ar uname
645 True if the file belongs to the user
649 is numeric and there is no such user name, then
651 is treated as a user ID.
654 All primaries which take a numeric argument allow the number to be
655 preceded by a plus sign
659 A preceding plus sign means
661 a preceding minus sign means
666 The primaries may be combined using the following operators.
667 The operators are listed in order of decreasing precedence.
669 .Bl -tag -width "( expression )" -compact
670 .It Cm \&( Ar expression Cm \&)
671 This evaluates to true if the parenthesized expression evaluates to
674 .It Cm \&! Ar expression
678 It evaluates to true if the expression is false.
680 .It Ar expression Cm -and Ar expression
681 .It Ar expression expression
684 operator is the logical
687 As it is implied by the juxtaposition of two expressions it does not
688 have to be specified.
689 The expression evaluates to true if both expressions are true.
690 The second expression is not evaluated if the first expression is false.
692 .It Ar expression Cm -or Ar expression
695 operator is the logical
698 The expression evaluates to true if either the first or the second expression
700 The second expression is not evaluated if the first expression is true.
703 All operands and primaries must be separate arguments to
705 Primaries which themselves take arguments expect each argument
706 to be a separate argument to
709 The following examples are shown as given to the shell:
710 .Bl -tag -width indent
711 .It Li "find / \e! -name \*q*.c\*q -print"
712 Print out a list of all the files whose names do not end in
714 .It Li "find / -newer ttt -user wnj -print"
715 Print out a list of all the files owned by user
720 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
721 Print out a list of all the files which are not both newer than
725 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
726 Print out a list of all the files that are either owned by
728 or that are newer than
730 .It Li "find . -newerct '1 minute ago' -print"
731 Print out a list of all the files whose inode change time is more
732 recent than the current time minus one minute.
752 utility syntax is a superset of the syntax specified by the
756 All the single character options as well as the
757 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
760 primaries are extensions to
767 options were implemented using the primaries
768 .Ic -depth , -follow ,
771 These primaries always evaluated to true.
772 As they were really global variables that took effect before the traversal
773 began, some legal expressions could have unexpected results.
774 An example is the expression
775 .Ic -print Cm -o Ic -depth .
778 always evaluates to true, the standard order of evaluation
781 would never be evaluated.
782 This is not the case.
793 Historic implementations of the
797 primaries did not replace the string
799 in the utility name or the
800 utility arguments if it had preceding or following non-whitespace characters.
801 This version replaces it no matter where in the utility name or arguments
806 option was implemented on the analogy of
811 The special characters used by
813 are also special characters to many shell programs.
814 In particular, the characters
825 may have to be escaped from the shell.
827 As there is no delimiter separating options and file names or file
830 it is difficult to specify files named
834 These problems are handled by the
843 primary does not interact well with other options that cause the filesystem
844 tree traversal options to be changed.