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
35 .\" $FreeBSD: src/usr.bin/find/find.1,v 1.23.2.20 2003/02/25 20:31:18 trhodes Exp $
42 .Nd walk a file hierarchy
45 .Op Fl H | Fl L | Fl P
53 utility recursively descends the directory tree for each
61 listed below) in terms
62 of each file in the tree.
64 The options are as follows:
65 .Bl -tag -width indent
67 Interpret regular expressions followed by
71 options as extended (modern) regular expressions rather than basic
72 regular expressions (BRE's).
75 manual page fully describes both formats.
77 Cause the file information and file type (see
79 returned for each symbolic link specified on the command line to be
80 those of the file referenced by the link, not the link itself.
81 If the referenced file does not exist, the file information and type will
82 be for the link itself.
83 File information of all symbolic links not on
84 the command line is that of the link itself.
86 Cause the file information and file type (see
88 returned for each symbolic link to be those of the file referenced by the
89 link, not the link itself.
90 If the referenced file does not exist, the file information and type will
91 be for the link itself.
93 Cause the file information and file type (see
95 returned for each symbolic link to be those of the link itself.
100 to be safely used in conjunction with
102 If a file name contains any of the delimiting characters used by
104 a diagnostic message is displayed on standard error, and the file
106 The delimiting characters include single
112 space, tab and newline characters.
114 However, you may wish to consider the
116 primary in conjunction with
118 as an effective alternative.
122 to perform a depth\-first traversal, i.e., directories
123 are visited in post\-order and all entries in a directory will be acted
124 on before the directory itself.
127 visits directories in pre\-order, i.e., before their contents.
130 a breadth\-first traversal.
132 Specify a file hierarchy for
135 File hierarchies may also be specified as the operands immediately
136 following the options.
140 to traverse the file hierarchies in lexicographical order,
141 i.e., alphabetical order within each directory.
146 may give different results.
150 from descending into directories that have a device number different
151 than that of the file from which the descent began.
154 .Bl -tag -width indent
156 True if the difference between the file last access time and the time
158 was started, rounded up to the next full minute, is
161 .It Ic -anewer Ar file
164 .It Ic -atime Ar n Ns Op Cm smhdw
165 If no units are specified, this primary evaluates to
166 true if the difference between the file last access time and the time
168 was started, rounded up to the next full 24\-hour period, is
172 If units are specified, this primary evaluates to
173 true if the difference between the file last access time and the time
175 was started is exactly
178 Possible time units are as follows:
180 .Bl -tag -width indent -compact
193 Any number of units may be combined in one
195 argument, for example,
196 .Dq Li "-atime -1h30m" .
197 Units are probably only useful when used in conjunction with the
203 True if the difference between the time of last change of file status
204 information and the time
206 was started, rounded up to the next full minute, is
209 .It Ic -cnewer Ar file
212 .It Ic -ctime Ar n Ns Op Cm smhdw
213 If no units are specified, this primary evaluates to
214 true if the difference between the time of last change of file status
215 information and the time
217 was started, rounded up to the next full 24\-hour period, is
221 If units are specified, this primary evaluates to
222 true if the difference between the time of last change of file status
223 information and the time
225 was started is exactly
230 primary description for information on supported time units.
232 Delete found files and/or directories.
235 from the current working directory as
237 recurses down the tree.
238 It will not attempt to delete a filename with a
240 character in its pathname relative to
242 for security reasons.
243 Depth\-first traversal processing is implied by this option.
254 to process files that are contained in directories with unusual permissions.
255 It ensures that you have write permission while you are placing files in a
256 directory, then sets the directory's permissions as the last thing.
258 True if the current file or directory is empty.
259 .It Ic -exec Ar utility Op Ar argument ... ;
260 True if the program named
262 returns a zero value as its exit status.
265 may be passed to the utility.
266 The expression must be terminated by a semicolon
270 appears anywhere in the utility name or the
271 arguments it is replaced by the pathname of the current file.
273 will be executed from the directory from which
279 are not subject to the further expansion of shell patterns
281 .It Ic -execdir Ar utility Op Ar argument ... ;
284 primary is identical to the
286 primary with the exception that
288 will be executed from the directory that holds
290 The filename substituted for
294 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
295 The flags are specified using symbolic names (see
305 are checked to be set, and flags in
307 are checked to be not set.
308 Note that this is different from
310 which only allows the user to specify mode bits that are set.
312 If flags are preceded by a dash
314 this primary evaluates to true
315 if at least all of the bits in
317 and none of the bits in
319 are set in the file's flags bits.
320 If flags are preceded by a plus
322 this primary evaluates to true
323 if any of the bits in
325 is set in the file's flags bits,
326 or any of the bits in
328 is not set in the file's flags bits.
330 this primary evaluates to true
333 exactly match the file's flags bits,
338 .It Ic -fstype Ar type
339 True if the file is contained in a file system of type
343 command can be used to find out the types of file systems
344 that are available on the system:
348 In addition, there are two pseudo-types,
352 The former matches any file system physically mounted on the system where
355 is being executed and the latter matches any file system which is
357 .It Ic -group Ar gname
358 True if the file belongs to the group
362 is numeric and there is no such group name, then
364 is treated as a group ID.
365 .It Ic -iname Ar pattern
368 but the match is case insensitive.
370 True if the file has inode number
372 .It Ic -ipath Ar pattern
375 but the match is case insensitive.
376 .It Ic -iregex Ar pattern
379 but the match is case insensitive.
385 This primary always evaluates to true.
386 The following information for the current file is written to standard output:
387 its inode number, size in 512\-byte blocks, file permissions, number of hard
388 links, owner, group, size in bytes, last modification time, and pathname.
389 If the file is a block or character special file, the major and minor numbers
390 will be displayed instead of the size in bytes.
391 If the file is a symbolic link, the pathname of the linked\-to file will be
392 displayed preceded by
394 The format is identical to that produced by
398 .It Ic -maxdepth Ar n
399 True if the depth of the current file into the tree is less than or equal to
401 .It Ic -mindepth Ar n
402 True if the depth of the current file into the tree is greater than or equal to
405 True if the difference between the file last modification time and the time
407 was started, rounded up to the next full minute, is
410 .It Ic -mnewer Ar file
413 .It Ic -mtime Ar n Ns Op Cm smhdw
414 If no units are specified, this primary evaluates to
415 true if the difference between the file last modification time and the time
417 was started, rounded up to the next full 24\-hour period, is
421 If units are specified, this primary evaluates to
422 true if the difference between the file last modification time and the time
424 was started is exactly
429 primary description for information on supported time units.
430 .It Ic -name Ar pattern
431 True if the last component of the pathname being examined matches
433 Special shell pattern matching characters
439 may be used as part of
441 These characters may be matched explicitly by escaping them with a
444 .It Ic -newer Ar file
445 True if the current file has a more recent last modification time than
447 .It Ic -newer Ns Ar X Ns Ar Y Ar file
448 True if the current file has a more recent last access time
449 .Ar ( X Ns = Ns Cm a ) ,
451 .Ar ( X Ns = Ns Cm c ) ,
453 .Ar ( X Ns = Ns Cm m )
454 than the last access time
455 .Ar ( Y Ns = Ns Cm a ) ,
457 .Ar ( Y Ns = Ns Cm c ) ,
459 .Ar ( Y Ns = Ns Cm m )
466 is instead interpreted as a direct date specification of the form
474 True if the file belongs to an unknown group.
476 True if the file belongs to an unknown user.
477 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
480 primary is identical to the
482 primary with the exception that
484 requests user affirmation for the execution of the
487 a message to the terminal and reading a response.
488 If the response is other than
490 the command is not executed and the
494 .It Ic -okdir Ar utility Op Ar argument ... ;
497 primary is identical to the
499 primary with the same exception as described for the
502 .It Ic -path Ar pattern
503 True if the pathname being examined matches
505 Special shell pattern matching characters
511 may be used as part of
513 These characters may be matched explicitly by escaping them with a
518 are treated as normal characters and do not have to be
520 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
523 may be either symbolic (see
528 is symbolic, a starting value of zero is assumed and the
530 sets or clears permissions without regard to the process' file mode
534 is octal, only bits 07777
535 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
536 of the file's mode bits participate
540 is preceded by a dash
542 this primary evaluates to true
543 if at least all of the bits in the
545 are set in the file's mode bits.
548 is preceded by a plus
550 this primary evaluates to true
551 if any of the bits in the
553 are set in the file's mode bits.
554 Otherwise, this primary evaluates to true if
557 exactly match the file's mode bits.
558 Note, the first character of a symbolic mode may not be a dash
561 This primary always evaluates to true.
562 It prints the pathname of the current file to standard output.
564 .Ic -exec , -ls , -print0 ,
567 is specified, the given expression shall be effectively replaced by
568 .Cm \&( Ar "given expression" Cm \&) Ic -print .
570 This primary always evaluates to true.
571 It prints the pathname of the current file to standard output, followed by an
573 character (character code 0).
575 This primary always evaluates to true.
578 to not descend into the current file.
581 primary has no effect if the
583 option was specified.
584 .It Ic -regex Ar pattern
585 True if the whole path of the file matches
587 using regular expression.
588 To match a file named
590 you can use the regular expression
598 .It Ic -size Ar n Ns Op Cm c
599 True if the file's size, rounded up, in 512\-byte blocks is
605 then the primary is true if the
610 True if the file is of the specified type.
611 Possible file types are as follows:
613 .Bl -tag -width indent -compact
629 .It Ic -user Ar uname
630 True if the file belongs to the user
634 is numeric and there is no such user name, then
636 is treated as a user ID.
639 All primaries which take a numeric argument allow the number to be
640 preceded by a plus sign
644 A preceding plus sign means
646 a preceding minus sign means
651 The primaries may be combined using the following operators.
652 The operators are listed in order of decreasing precedence.
654 .Bl -tag -width "( expression )" -compact
655 .It Cm \&( Ar expression Cm \&)
656 This evaluates to true if the parenthesized expression evaluates to
659 .It Cm \&! Ar expression
660 .It Cm -false Ar expression
661 .It Cm -not Ar expression
665 It evaluates to true if the expression is false.
667 .It Ar expression Cm -and Ar expression
668 .It Ar expression expression
671 operator is the logical
674 As it is implied by the juxtaposition of two expressions it does not
675 have to be specified.
676 The expression evaluates to true if both expressions are true.
677 The second expression is not evaluated if the first expression is false.
679 .It Ar expression Cm -or Ar expression
682 operator is the logical
685 The expression evaluates to true if either the first or the second expression
687 The second expression is not evaluated if the first expression is true.
690 All operands and primaries must be separate arguments to
692 Primaries which themselves take arguments expect each argument
693 to be a separate argument to
696 The following examples are shown as given to the shell:
697 .Bl -tag -width indent
698 .It Li "find / \e! -name \*q*.c\*q -print"
699 Print out a list of all the files whose names do not end in
701 .It Li "find / -newer ttt -user wnj -print"
702 Print out a list of all the files owned by user
707 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
708 Print out a list of all the files which are not both newer than
712 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
713 Print out a list of all the files that are either owned by
715 or that are newer than
717 .It Li "find . -newerct '1 minute ago' -print"
718 Print out a list of all the files whose inode change time is more
719 recent than the current time minus one minute.
739 utility syntax is a superset of the syntax specified by the
743 All the single character options as well as the
744 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
747 primaries are extensions to
754 options were implemented using the primaries
755 .Ic -depth , -follow ,
758 These primaries always evaluated to true.
759 As they were really global variables that took effect before the traversal
760 began, some legal expressions could have unexpected results.
761 An example is the expression
762 .Ic -print Cm -o Ic -depth .
765 always evaluates to true, the standard order of evaluation
768 would never be evaluated.
769 This is not the case.
780 Historic implementations of the
784 primaries did not replace the string
786 in the utility name or the
787 utility arguments if it had preceding or following non-whitespace characters.
788 This version replaces it no matter where in the utility name or arguments
793 option was implemented on the analogy of
798 The special characters used by
800 are also special characters to many shell programs.
801 In particular, the characters
812 may have to be escaped from the shell.
814 As there is no delimiter separating options and file names or file
817 it is difficult to specify files named
821 These problems are handled by the
830 primary does not interact well with other options that cause the file system
831 tree traversal options to be changed.