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 $
36 .\" $DragonFly: src/usr.bin/find/find.1,v 1.2 2003/06/17 04:29:26 dillon Exp $
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 Cause the file information and file type (see
96 returned for each symbolic link to be those of the link itself.
101 to be safely used in conjunction with
103 If a file name contains any of the delimiting characters used by
105 a diagnostic message is displayed on standard error, and the file
107 The delimiting characters include single
113 space, tab and newline characters.
115 However, you may wish to consider the
117 primary in conjunction with
119 as an effective alternative.
123 to perform a depth\-first traversal, i.e., directories
124 are visited in post\-order and all entries in a directory will be acted
125 on before the directory itself.
128 visits directories in pre\-order, i.e., before their contents.
131 a breadth\-first traversal.
133 Specify a file hierarchy for
136 File hierarchies may also be specified as the operands immediately
137 following the options.
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.
155 .Bl -tag -width indent
157 True if the difference between the file last access time and the time
159 was started, rounded up to the next full minute, is
162 .It Ic -anewer Ar file
165 .It Ic -atime Ar n Ns Op Cm smhdw
166 If no units are specified, this primary evaluates to
167 true if the difference between the file last access time and the time
169 was started, rounded up to the next full 24\-hour period, is
173 If units are specified, this primary evaluates to
174 true if the difference between the file last access time and the time
176 was started is exactly
179 Possible time units are as follows:
181 .Bl -tag -width indent -compact
194 Any number of units may be combined in one
196 argument, for example,
197 .Dq Li "-atime -1h30m" .
198 Units are probably only useful when used in conjunction with the
204 True if the difference between the time of last change of file status
205 information and the time
207 was started, rounded up to the next full minute, is
210 .It Ic -cnewer Ar file
213 .It Ic -ctime Ar n Ns Op Cm smhdw
214 If no units are specified, this primary evaluates to
215 true if the difference between the time of last change of file status
216 information and the time
218 was started, rounded up to the next full 24\-hour period, is
222 If units are specified, this primary evaluates to
223 true if the difference between the time of last change of file status
224 information and the time
226 was started is exactly
231 primary description for information on supported time units.
233 Delete found files and/or directories.
236 from the current working directory as
238 recurses down the tree.
239 It will not attempt to delete a filename with a
241 character in its pathname relative to
243 for security reasons.
244 Depth\-first traversal processing is implied by this option.
255 to process files that are contained in directories with unusual permissions.
256 It ensures that you have write permission while you are placing files in a
257 directory, then sets the directory's permissions as the last thing.
259 True if the current file or directory is empty.
260 .It Ic -exec Ar utility Op Ar argument ... ;
261 True if the program named
263 returns a zero value as its exit status.
266 may be passed to the utility.
267 The expression must be terminated by a semicolon
271 appears anywhere in the utility name or the
272 arguments it is replaced by the pathname of the current file.
274 will be executed from the directory from which
280 are not subject to the further expansion of shell patterns
282 .It Ic -execdir Ar utility Op Ar argument ... ;
285 primary is identical to the
287 primary with the exception that
289 will be executed from the directory that holds
291 The filename substituted for
295 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
296 The flags are specified using symbolic names (see
306 are checked to be set, and flags in
308 are checked to be not set.
309 Note that this is different from
311 which only allows the user to specify mode bits that are set.
313 If flags are preceded by a dash
315 this primary evaluates to true
316 if at least all of the bits in
318 and none of the bits in
320 are set in the file's flags bits.
321 If flags are preceded by a plus
323 this primary evaluates to true
324 if any of the bits in
326 is set in the file's flags bits,
327 or any of the bits in
329 is not set in the file's flags bits.
331 this primary evaluates to true
334 exactly match the file's flags bits,
339 .It Ic -fstype Ar type
340 True if the file is contained in a file system of type
344 command can be used to find out the types of file systems
345 that are available on the system:
349 In addition, there are two pseudo-types,
353 The former matches any file system physically mounted on the system where
356 is being executed and the latter matches any file system which is
358 .It Ic -group Ar gname
359 True if the file belongs to the group
363 is numeric and there is no such group name, then
365 is treated as a group ID.
366 .It Ic -iname Ar pattern
369 but the match is case insensitive.
371 True if the file has inode number
373 .It Ic -ipath Ar pattern
376 but the match is case insensitive.
377 .It Ic -iregex Ar pattern
380 but the match is case insensitive.
386 This primary always evaluates to true.
387 The following information for the current file is written to standard output:
388 its inode number, size in 512\-byte blocks, file permissions, number of hard
389 links, owner, group, size in bytes, last modification time, and pathname.
390 If the file is a block or character special file, the major and minor numbers
391 will be displayed instead of the size in bytes.
392 If the file is a symbolic link, the pathname of the linked\-to file will be
393 displayed preceded by
395 The format is identical to that produced by
399 .It Ic -maxdepth Ar n
400 True if the depth of the current file into the tree is less than or equal to
402 .It Ic -mindepth Ar n
403 True if the depth of the current file into the tree is greater than or equal to
406 True if the difference between the file last modification time and the time
408 was started, rounded up to the next full minute, is
411 .It Ic -mnewer Ar file
414 .It Ic -mtime Ar n Ns Op Cm smhdw
415 If no units are specified, this primary evaluates to
416 true if the difference between the file last modification time and the time
418 was started, rounded up to the next full 24\-hour period, is
422 If units are specified, this primary evaluates to
423 true if the difference between the file last modification time and the time
425 was started is exactly
430 primary description for information on supported time units.
431 .It Ic -name Ar pattern
432 True if the last component of the pathname being examined matches
434 Special shell pattern matching characters
440 may be used as part of
442 These characters may be matched explicitly by escaping them with a
445 .It Ic -newer Ar file
446 True if the current file has a more recent last modification time than
448 .It Ic -newer Ns Ar X Ns Ar Y Ar file
449 True if the current file has a more recent last access time
450 .Ar ( X Ns = Ns Cm a ) ,
452 .Ar ( X Ns = Ns Cm c ) ,
454 .Ar ( X Ns = Ns Cm m )
455 than the last access time
456 .Ar ( Y Ns = Ns Cm a ) ,
458 .Ar ( Y Ns = Ns Cm c ) ,
460 .Ar ( Y Ns = Ns Cm m )
467 is instead interpreted as a direct date specification of the form
475 True if the file belongs to an unknown group.
477 True if the file belongs to an unknown user.
478 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
481 primary is identical to the
483 primary with the exception that
485 requests user affirmation for the execution of the
488 a message to the terminal and reading a response.
489 If the response is other than
491 the command is not executed and the
495 .It Ic -okdir Ar utility Op Ar argument ... ;
498 primary is identical to the
500 primary with the same exception as described for the
503 .It Ic -path Ar pattern
504 True if the pathname being examined matches
506 Special shell pattern matching characters
512 may be used as part of
514 These characters may be matched explicitly by escaping them with a
519 are treated as normal characters and do not have to be
521 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
524 may be either symbolic (see
529 is symbolic, a starting value of zero is assumed and the
531 sets or clears permissions without regard to the process' file mode
535 is octal, only bits 07777
536 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
537 of the file's mode bits participate
541 is preceded by a dash
543 this primary evaluates to true
544 if at least all of the bits in the
546 are set in the file's mode bits.
549 is preceded by a plus
551 this primary evaluates to true
552 if any of the bits in the
554 are set in the file's mode bits.
555 Otherwise, this primary evaluates to true if
558 exactly match the file's mode bits.
559 Note, the first character of a symbolic mode may not be a dash
562 This primary always evaluates to true.
563 It prints the pathname of the current file to standard output.
565 .Ic -exec , -ls , -print0 ,
568 is specified, the given expression shall be effectively replaced by
569 .Cm \&( Ar "given expression" Cm \&) Ic -print .
571 This primary always evaluates to true.
572 It prints the pathname of the current file to standard output, followed by an
574 character (character code 0).
576 This primary always evaluates to true.
579 to not descend into the current file.
582 primary has no effect if the
584 option was specified.
585 .It Ic -regex Ar pattern
586 True if the whole path of the file matches
588 using regular expression.
589 To match a file named
591 you can use the regular expression
599 .It Ic -size Ar n Ns Op Cm c
600 True if the file's size, rounded up, in 512\-byte blocks is
606 then the primary is true if the
611 True if the file is of the specified type.
612 Possible file types are as follows:
614 .Bl -tag -width indent -compact
630 .It Ic -user Ar uname
631 True if the file belongs to the user
635 is numeric and there is no such user name, then
637 is treated as a user ID.
640 All primaries which take a numeric argument allow the number to be
641 preceded by a plus sign
645 A preceding plus sign means
647 a preceding minus sign means
652 The primaries may be combined using the following operators.
653 The operators are listed in order of decreasing precedence.
655 .Bl -tag -width "( expression )" -compact
656 .It Cm \&( Ar expression Cm \&)
657 This evaluates to true if the parenthesized expression evaluates to
660 .It Cm \&! Ar expression
661 .It Cm -false Ar expression
662 .It Cm -not Ar expression
666 It evaluates to true if the expression is false.
668 .It Ar expression Cm -and Ar expression
669 .It Ar expression expression
672 operator is the logical
675 As it is implied by the juxtaposition of two expressions it does not
676 have to be specified.
677 The expression evaluates to true if both expressions are true.
678 The second expression is not evaluated if the first expression is false.
680 .It Ar expression Cm -or Ar expression
683 operator is the logical
686 The expression evaluates to true if either the first or the second expression
688 The second expression is not evaluated if the first expression is true.
691 All operands and primaries must be separate arguments to
693 Primaries which themselves take arguments expect each argument
694 to be a separate argument to
697 The following examples are shown as given to the shell:
698 .Bl -tag -width indent
699 .It Li "find / \e! -name \*q*.c\*q -print"
700 Print out a list of all the files whose names do not end in
702 .It Li "find / -newer ttt -user wnj -print"
703 Print out a list of all the files owned by user
708 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
709 Print out a list of all the files which are not both newer than
713 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
714 Print out a list of all the files that are either owned by
716 or that are newer than
718 .It Li "find . -newerct '1 minute ago' -print"
719 Print out a list of all the files whose inode change time is more
720 recent than the current time minus one minute.
740 utility syntax is a superset of the syntax specified by the
744 All the single character options as well as the
745 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
748 primaries are extensions to
755 options were implemented using the primaries
756 .Ic -depth , -follow ,
759 These primaries always evaluated to true.
760 As they were really global variables that took effect before the traversal
761 began, some legal expressions could have unexpected results.
762 An example is the expression
763 .Ic -print Cm -o Ic -depth .
766 always evaluates to true, the standard order of evaluation
769 would never be evaluated.
770 This is not the case.
781 Historic implementations of the
785 primaries did not replace the string
787 in the utility name or the
788 utility arguments if it had preceding or following non-whitespace characters.
789 This version replaces it no matter where in the utility name or arguments
794 option was implemented on the analogy of
799 The special characters used by
801 are also special characters to many shell programs.
802 In particular, the characters
813 may have to be escaped from the shell.
815 As there is no delimiter separating options and file names or file
818 it is difficult to specify files named
822 These problems are handled by the
831 primary does not interact well with other options that cause the file system
832 tree traversal options to be changed.