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
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.
79 option causes the file information and file type (see
81 returned for each symbolic link specified on the command line to be
82 those of the file referenced by the link, not the link itself.
83 If the referenced file does not exist, the file information and type will
84 be for the link itself.
85 File information of all symbolic links not on
86 the command line is that of the link itself.
90 option causes the file information and file type (see
92 returned for each symbolic link to be those of the file referenced by the
93 link, not the link itself.
94 If the referenced file does not exist, the file information and type will
95 be for the link itself.
99 option causes the file information and file type (see
101 returned for each symbolic link to be those of the link itself.
106 option is a modification to permit
108 to be safely used in conjunction with
110 If a file name contains any of the delimiting characters used by
112 a diagnostic message is displayed on standard error, and the file
114 The delimiting characters include single
120 space, tab and newline characters.
122 However, you may wish to consider the
124 primary in conjunction with
126 as an effective alternative.
132 to perform a depth\-first traversal, i.e., directories
133 are visited in post\-order and all entries in a directory will be acted
134 on before the directory itself.
137 visits directories in pre\-order, i.e., before their contents.
140 a breadth\-first traversal.
144 option specifies a file hierarchy for
147 File hierarchies may also be specified as the operands immediately
148 following the options.
154 to traverse the file hierarchies in lexicographical order,
155 i.e., alphabetical order within each directory.
160 may give different results.
166 from descending into directories that have a device number different
167 than that of the file from which the descent began.
170 .Bl -tag -width indent
172 True if the difference between the file last access time and the time
174 was started, rounded up to the next full minute, is
177 .It Ic -anewer Ar file
180 .It Ic -atime Ar n Ns Op Cm smhdw
181 If no units are specified, this primary evaluates to
182 true if the difference between the file last access time and the time
184 was started, rounded up to the next full 24\-hour period, is
188 If units are specified, this primary evaluates to
189 true if the difference between the file last access time and the time
191 was started is exactly
194 Possible time units are as follows:
196 .Bl -tag -width indent -compact
209 Any number of units may be combined in one
211 argument, for example,
212 .Dq Li "-atime -1h30m" .
213 Units are probably only useful when used in conjunction with the
219 True if the difference between the time of last change of file status
220 information and the time
222 was started, rounded up to the next full minute, is
225 .It Ic -cnewer Ar file
228 .It Ic -ctime Ar n Ns Op Cm smhdw
229 If no units are specified, this primary evaluates to
230 true if the difference between the time of last change of file status
231 information and the time
233 was started, rounded up to the next full 24\-hour period, is
237 If units are specified, this primary evaluates to
238 true if the difference between the time of last change of file status
239 information and the time
241 was started is exactly
246 primary description for information on supported time units.
248 Delete found files and/or directories.
251 from the current working directory as
253 recurses down the tree.
254 It will not attempt to delete a filename with a
256 character in its pathname relative to
258 for security reasons.
259 Depth\-first traversal processing is implied by this option.
270 to process files that are contained in directories with unusual permissions.
271 It ensures that you have write permission while you are placing files in a
272 directory, then sets the directory's permissions as the last thing.
274 True if the current file or directory is empty.
275 .It Ic -exec Ar utility Op Ar argument ... ;
276 True if the program named
278 returns a zero value as its exit status.
281 may be passed to the utility.
282 The expression must be terminated by a semicolon
286 appears anywhere in the utility name or the
287 arguments it is replaced by the pathname of the current file.
289 will be executed from the directory from which
295 are not subject to the further expansion of shell patterns
297 .It Ic -execdir Ar utility Op Ar argument ... ;
300 primary is identical to the
302 primary with the exception that
304 will be executed from the directory that holds
306 The filename substituted for
310 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
311 The flags are specified using symbolic names (see
321 are checked to be set, and flags in
323 are checked to be not set.
324 Note that this is different from
326 which only allows the user to specify mode bits that are set.
328 If flags are preceded by a dash
330 this primary evaluates to true
331 if at least all of the bits in
333 and none of the bits in
335 are set in the file's flags bits.
336 If flags are preceded by a plus
338 this primary evaluates to true
339 if any of the bits in
341 is set in the file's flags bits,
342 or any of the bits in
344 is not set in the file's flags bits.
346 this primary evaluates to true
349 exactly match the file's flags bits,
354 .It Ic -fstype Ar type
355 True if the file is contained in a file system of type
359 command can be used to find out the types of filesystems
360 that are available on the system:
364 In addition, there are two pseudo-types,
368 The former matches any file system physically mounted on the system where
371 is being executed and the latter matches any file system which is
373 .It Ic -group Ar gname
374 True if the file belongs to the group
378 is numeric and there is no such group name, then
380 is treated as a group ID.
381 .It Ic -iname Ar pattern
384 but the match is case insensitive.
386 True if the file has inode number
388 .It Ic -ipath Ar pattern
391 but the match is case insensitive.
392 .It Ic -iregex Ar pattern
395 but the match is case insensitive.
401 This primary always evaluates to true.
402 The following information for the current file is written to standard output:
403 its inode number, size in 512\-byte blocks, file permissions, number of hard
404 links, owner, group, size in bytes, last modification time, and pathname.
405 If the file is a block or character special file, the major and minor numbers
406 will be displayed instead of the size in bytes.
407 If the file is a symbolic link, the pathname of the linked\-to file will be
408 displayed preceded by
410 The format is identical to that produced by
414 .It Ic -maxdepth Ar n
415 True if the depth of the current file into the tree is less than or equal to
417 .It Ic -mindepth Ar n
418 True if the depth of the current file into the tree is greater than or equal to
421 True if the difference between the file last modification time and the time
423 was started, rounded up to the next full minute, is
426 .It Ic -mnewer Ar file
429 .It Ic -mtime Ar n Ns Op Cm smhdw
430 If no units are specified, this primary evaluates to
431 true if the difference between the file last modification time and the time
433 was started, rounded up to the next full 24\-hour period, is
437 If units are specified, this primary evaluates to
438 true if the difference between the file last modification time and the time
440 was started is exactly
445 primary description for information on supported time units.
446 .It Ic -name Ar pattern
447 True if the last component of the pathname being examined matches
449 Special shell pattern matching characters
455 may be used as part of
457 These characters may be matched explicitly by escaping them with a
460 .It Ic -newer Ar file
461 True if the current file has a more recent last modification time than
463 .It Ic -newer Ns Ar X Ns Ar Y Ar file
464 True if the current file has a more recent last access time
465 .Ar ( X Ns = Ns Cm a ) ,
467 .Ar ( X Ns = Ns Cm c ) ,
469 .Ar ( X Ns = Ns Cm m )
470 than the last access time
471 .Ar ( Y Ns = Ns Cm a ) ,
473 .Ar ( Y Ns = Ns Cm c ) ,
475 .Ar ( Y Ns = Ns Cm m )
482 is instead interpreted as a direct date specification of the form
490 True if the file belongs to an unknown group.
492 True if the file belongs to an unknown user.
493 .It Ic -ok Ar utility Op Ar argument ... ;
496 primary is identical to the
498 primary with the exception that
500 requests user affirmation for the execution of the
503 a message to the terminal and reading a response.
504 If the response is other than
506 the command is not executed and the
510 .It Ic -okdir Ar utility Op Ar argument ... ;
513 primary is identical to the
515 primary with the same exception as described for the
518 .It Ic -path Ar pattern
519 True if the pathname being examined matches
521 Special shell pattern matching characters
527 may be used as part of
529 These characters may be matched explicitly by escaping them with a
534 are treated as normal characters and do not have to be
536 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
539 may be either symbolic (see
544 is symbolic, a starting value of zero is assumed and the
546 sets or clears permissions without regard to the process' file mode
550 is octal, only bits 07777
551 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
552 of the file's mode bits participate
556 is preceded by a dash
558 this primary evaluates to true
559 if at least all of the bits in the
561 are set in the file's mode bits.
564 is preceded by a plus
566 this primary evaluates to true
567 if any of the bits in the
569 are set in the file's mode bits.
570 Otherwise, this primary evaluates to true if
573 exactly match the file's mode bits.
574 Note, the first character of a symbolic mode may not be a dash
577 This primary always evaluates to true.
578 It prints the pathname of the current file to standard output.
580 .Ic -exec , -ls , -print0 ,
583 is specified, the given expression shall be effectively replaced by
584 .Cm \&( Ar "given expression" Cm \&) Ic -print .
586 This primary always evaluates to true.
587 It prints the pathname of the current file to standard output, followed by an
589 character (character code 0).
591 This primary always evaluates to true.
594 to not descend into the current file.
597 primary has no effect if the
599 option was specified.
600 .It Ic -regex Ar pattern
601 True if the whole path of the file matches
603 using regular expression.
604 To match a file named
606 you can use the regular expression
614 .It Ic -size Ar n Ns Op Cm c
615 True if the file's size, rounded up, in 512\-byte blocks is
621 then the primary is true if the
626 True if the file is of the specified type.
627 Possible file types are as follows:
629 .Bl -tag -width indent -compact
645 .It Ic -user Ar uname
646 True if the file belongs to the user
650 is numeric and there is no such user name, then
652 is treated as a user ID.
655 All primaries which take a numeric argument allow the number to be
656 preceded by a plus sign
660 A preceding plus sign means
662 a preceding minus sign means
667 The primaries may be combined using the following operators.
668 The operators are listed in order of decreasing precedence.
670 .Bl -tag -width "( expression )" -compact
671 .It Cm \&( Ar expression Cm \&)
672 This evaluates to true if the parenthesized expression evaluates to
675 .It Cm \&! Ar expression
679 It evaluates to true if the expression is false.
681 .It Ar expression Cm -and Ar expression
682 .It Ar expression expression
685 operator is the logical
688 As it is implied by the juxtaposition of two expressions it does not
689 have to be specified.
690 The expression evaluates to true if both expressions are true.
691 The second expression is not evaluated if the first expression is false.
693 .It Ar expression Cm -or Ar expression
696 operator is the logical
699 The expression evaluates to true if either the first or the second expression
701 The second expression is not evaluated if the first expression is true.
704 All operands and primaries must be separate arguments to
706 Primaries which themselves take arguments expect each argument
707 to be a separate argument to
710 The following examples are shown as given to the shell:
711 .Bl -tag -width indent
712 .It Li "find / \e! -name \*q*.c\*q -print"
713 Print out a list of all the files whose names do not end in
715 .It Li "find / -newer ttt -user wnj -print"
716 Print out a list of all the files owned by user
721 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
722 Print out a list of all the files which are not both newer than
726 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
727 Print out a list of all the files that are either owned by
729 or that are newer than
731 .It Li "find . -newerct '1 minute ago' -print"
732 Print out a list of all the files whose inode change time is more
733 recent than the current time minus one minute.
753 utility syntax is a superset of the syntax specified by the
757 All the single character options as well as the
758 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
761 primaries are extensions to
768 options were implemented using the primaries
769 .Ic -depth , -follow ,
772 These primaries always evaluated to true.
773 As they were really global variables that took effect before the traversal
774 began, some legal expressions could have unexpected results.
775 An example is the expression
776 .Ic -print Cm -o Ic -depth .
779 always evaluates to true, the standard order of evaluation
782 would never be evaluated.
783 This is not the case.
794 Historic implementations of the
798 primaries did not replace the string
800 in the utility name or the
801 utility arguments if it had preceding or following non-whitespace characters.
802 This version replaces it no matter where in the utility name or arguments
807 option was implemented on the analogy of
812 The special characters used by
814 are also special characters to many shell programs.
815 In particular, the characters
826 may have to be escaped from the shell.
828 As there is no delimiter separating options and file names or file
831 it is difficult to specify files named
835 These problems are handled by the
844 primary does not interact well with other options that cause the filesystem
845 tree traversal options to be changed.