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 May be used in conjunction with other options to locate
179 files with extended ACLs.
182 for more information.
184 True if the difference between the file last access time and the time
186 was started, rounded up to the next full minute, is
189 .It Ic -anewer Ar file
192 .It Ic -atime Ar n Ns Op Cm smhdw
193 If no units are specified, this primary evaluates to
194 true if the difference between the file last access time and the time
196 was started, rounded up to the next full 24-hour period, is
200 If units are specified, this primary evaluates to
201 true if the difference between the file last access time and the time
203 was started is exactly
206 Possible time units are as follows:
208 .Bl -tag -width indent -compact
221 Any number of units may be combined in one
223 argument, for example,
224 .Dq Li "-atime -1h30m" .
225 Units are probably only useful when used in conjunction with the
231 True if the difference between the time of last change of file status
232 information and the time
234 was started, rounded up to the next full minute, is
237 .It Ic -cnewer Ar file
240 .It Ic -ctime Ar n Ns Op Cm smhdw
241 If no units are specified, this primary evaluates to
242 true if the difference between the time of last change of file status
243 information and the time
245 was started, rounded up to the next full 24-hour period, is
249 If units are specified, this primary evaluates to
250 true if the difference between the time of last change of file status
251 information and the time
253 was started is exactly
258 primary description for information on supported time units.
260 Delete found files and/or directories.
263 from the current working directory as
265 recurses down the tree.
266 It will not attempt to delete a filename with a
268 character in its pathname relative to
270 for security reasons.
271 Depth-first traversal processing is implied by this option.
278 True if the depth of the file relative to the starting point of the traversal
282 True if the current file or directory is empty.
283 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
284 True if the program named
286 returns a zero value as its exit status.
289 may be passed to the utility.
290 The expression must be terminated by a semicolon
294 from a shell you may need to quote the semicolon if the shell would
295 otherwise treat it as a control operator.
298 appears anywhere in the utility name or the
299 arguments it is replaced by the pathname of the current file.
301 will be executed from the directory from which
307 are not subject to the further expansion of shell patterns
309 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
314 is replaced with as many pathnames as possible for each invocation of
316 This behaviour is similar to that of
318 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
321 primary is identical to the
323 primary with the exception that
325 will be executed from the directory that holds
327 The filename substituted for
331 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
332 The flags are specified using symbolic names (see
342 are checked to be set, and flags in
344 are checked to be not set.
345 Note that this is different from
347 which only allows the user to specify mode bits that are set.
349 If flags are preceded by a dash
351 this primary evaluates to true
352 if at least all of the bits in
354 and none of the bits in
356 are set in the file's flags bits.
357 If flags are preceded by a plus
359 this primary evaluates to true
360 if any of the bits in
362 is set in the file's flags bits,
363 or any of the bits in
365 is not set in the file's flags bits.
367 this primary evaluates to true
370 exactly match the file's flags bits,
375 .It Ic -fstype Ar type
376 True if the file is contained in a file system of type
380 command can be used to find out the types of file systems
381 that are available on the system:
385 In addition, there are two pseudo-types,
389 The former matches any file system physically mounted on the system where
392 is being executed and the latter matches any file system which is
394 .It Ic -group Ar gname
395 True if the file belongs to the group
399 is numeric and there is no such group name, then
401 is treated as a group ID.
402 .It Ic -iname Ar pattern
405 but the match is case insensitive.
407 True if the file has inode number
409 .It Ic -ipath Ar pattern
412 but the match is case insensitive.
413 .It Ic -iregex Ar pattern
416 but the match is case insensitive.
422 This primary always evaluates to true.
423 The following information for the current file is written to standard output:
424 its inode number, size in 512-byte blocks, file permissions, number of hard
425 links, owner, group, size in bytes, last modification time, and pathname.
426 If the file is a block or character special file, the major and minor numbers
427 will be displayed instead of the size in bytes.
428 If the file is a symbolic link, the pathname of the linked-to file will be
429 displayed preceded by
431 The format is identical to that produced by
435 .It Ic -maxdepth Ar n
436 Always true; descend at most
438 directory levels below the command line arguments.
441 primary is specified, it applies to the entire expression even if it would
442 not normally be evaluated.
444 limits the whole search to the command line arguments.
445 .It Ic -mindepth Ar n
446 Always true; do not apply any tests or actions at levels less than
450 primary is specified, it applies to the entire expression even if it would
451 not normally be evaluated.
453 processes all but the command line arguments.
455 True if the difference between the file last modification time and the time
457 was started, rounded up to the next full minute, is
460 .It Ic -mnewer Ar file
463 .It Ic -mtime Ar n Ns Op Cm smhdw
464 If no units are specified, this primary evaluates to
465 true if the difference between the file last modification time and the time
467 was started, rounded up to the next full 24-hour period, is
471 If units are specified, this primary evaluates to
472 true if the difference between the file last modification time and the time
474 was started is exactly
479 primary description for information on supported time units.
480 .It Ic -name Ar pattern
481 True if the last component of the pathname being examined matches
483 Special shell pattern matching characters
489 may be used as part of
491 These characters may be matched explicitly by escaping them with a
494 .It Ic -newer Ar file
495 True if the current file has a more recent last modification time than
497 .It Ic -newer Ns Ar X Ns Ar Y Ar file
498 True if the current file has a more recent last access time
499 .Ar ( X Ns = Ns Cm a ) ,
501 .Ar ( X Ns = Ns Cm c ) ,
503 .Ar ( X Ns = Ns Cm m )
504 than the last access time
505 .Ar ( Y Ns = Ns Cm a ) ,
507 .Ar ( Y Ns = Ns Cm c ) ,
509 .Ar ( Y Ns = Ns Cm m )
516 is instead interpreted as a direct date specification of the form
524 True if the file belongs to an unknown group.
526 True if the file belongs to an unknown user.
527 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
530 primary is identical to the
532 primary with the exception that
534 requests user affirmation for the execution of the
537 a message to the terminal and reading a response.
538 If the response is other than
540 the command is not executed and the
544 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
547 primary is identical to the
549 primary with the same exception as described for the
552 .It Ic -path Ar pattern
553 True if the pathname being examined matches
555 Special shell pattern matching characters
561 may be used as part of
563 These characters may be matched explicitly by escaping them with a
568 are treated as normal characters and do not have to be
570 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
573 may be either symbolic (see
578 is symbolic, a starting value of zero is assumed and the
580 sets or clears permissions without regard to the process' file mode
584 is octal, only bits 07777
585 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
586 of the file's mode bits participate
590 is preceded by a dash
592 this primary evaluates to true
593 if at least all of the bits in the
595 are set in the file's mode bits.
598 is preceded by a plus
600 this primary evaluates to true
601 if any of the bits in the
603 are set in the file's mode bits.
604 Otherwise, this primary evaluates to true if
607 exactly match the file's mode bits.
608 Note, the first character of a symbolic mode may not be a dash
611 This primary always evaluates to true.
612 It prints the pathname of the current file to standard output.
614 .Ic -exec , -ls , -print0 ,
617 is specified, the given expression shall be effectively replaced by
618 .Cm \&( Ar "given expression" Cm \&) Ic -print .
620 This primary always evaluates to true.
621 It prints the pathname of the current file to standard output, followed by an
623 character (character code 0).
625 This primary always evaluates to true.
628 to not descend into the current file.
631 primary has no effect if the
633 option was specified.
634 .It Ic -regex Ar pattern
635 True if the whole path of the file matches
637 using regular expression.
638 To match a file named
640 you can use the regular expression
648 .It Ic -size Ar n Ns Op Cm c
649 True if the file's size, rounded up, in 512-byte blocks is
655 then the primary is true if the
660 True if the file is of the specified type.
661 Possible file types are as follows:
663 .Bl -tag -width indent -compact
679 .It Ic -user Ar uname
680 True if the file belongs to the user
684 is numeric and there is no such user name, then
686 is treated as a user ID.
689 All primaries which take a numeric argument allow the number to be
690 preceded by a plus sign
694 A preceding plus sign means
696 a preceding minus sign means
701 The primaries may be combined using the following operators.
702 The operators are listed in order of decreasing precedence.
704 .Bl -tag -width "( expression )" -compact
705 .It Cm \&( Ar expression Cm \&)
706 This evaluates to true if the parenthesized expression evaluates to
709 .It Cm \&! Ar expression
710 .It Cm -false Ar expression
711 .It Cm -not Ar expression
715 It evaluates to true if the expression is false.
717 .It Ar expression Cm -and Ar expression
718 .It Ar expression expression
721 operator is the logical
724 As it is implied by the juxtaposition of two expressions it does not
725 have to be specified.
726 The expression evaluates to true if both expressions are true.
727 The second expression is not evaluated if the first expression is false.
729 .It Ar expression Cm -or Ar expression
732 operator is the logical
735 The expression evaluates to true if either the first or the second expression
737 The second expression is not evaluated if the first expression is true.
740 All operands and primaries must be separate arguments to
742 Primaries which themselves take arguments expect each argument
743 to be a separate argument to
746 The following examples are shown as given to the shell:
747 .Bl -tag -width indent
748 .It Li "find / \e! -name \*q*.c\*q -print"
749 Print out a list of all the files whose names do not end in
751 .It Li "find / -newer ttt -user wnj -print"
752 Print out a list of all the files owned by user
757 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
758 Print out a list of all the files which are not both newer than
762 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
763 Print out a list of all the files that are either owned by
765 or that are newer than
767 .It Li "find / -newerct '1 minute ago' -print"
768 Print out a list of all the files whose inode change time is more
769 recent than the current time minus one minute.
770 .It Li "find / -type f -exec echo {} \e;"
773 command to print out a list of all the files.
774 .It Li "find -L /usr/ports/packages -type l -delete"
775 Delete all broken symbolic links in
776 .Pa /usr/ports/packages .
777 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
778 Find files and directories that are at least seven levels deep
779 in the working directory
781 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
782 Is not equivalent to the previous example, since
784 is not evaluated below level seven.
789 primary is deprecated; the
791 option should be used instead.
794 section below for details.
814 utility syntax is a superset of the syntax specified by the
818 All the single character options except
823 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
826 primaries are extensions to
833 options were implemented using the primaries
834 .Ic -depth , -follow ,
837 These primaries always evaluated to true.
838 As they were really global variables that took effect before the traversal
839 began, some legal expressions could have unexpected results.
840 An example is the expression
841 .Ic -print Cm -o Ic -depth .
844 always evaluates to true, the standard order of evaluation
847 would never be evaluated.
848 This is not the case.
859 Historic implementations of the
863 primaries did not replace the string
865 in the utility name or the
866 utility arguments if it had preceding or following non-whitespace characters.
867 This version replaces it no matter where in the utility name or arguments
872 option was inspired by the equivalent
883 The special characters used by
885 are also special characters to many shell programs.
886 In particular, the characters
897 may have to be escaped from the shell.
899 As there is no delimiter separating options and file names or file
902 it is difficult to specify files named
906 These problems are handled by the
915 primary does not interact well with other options that cause the file system
916 tree traversal options to be changed.
922 primaries are actually global options (as documented above).
924 probably be replaced by options which look like options.
projects / FreeBSD / FreeBSD.git / blob