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 .\" 4. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
31 .\" @(#)find.1 8.7 (Berkeley) 5/9/95
39 .Nd walk a file hierarchy
42 .Op Fl H | Fl L | Fl P
48 .Op Fl H | Fl L | Fl P
56 utility recursively descends the directory tree for each
64 listed below) in terms
65 of each file in the tree.
67 The options are as follows:
68 .Bl -tag -width indent
70 Interpret regular expressions followed by
74 primaries as extended (modern) regular expressions rather than basic
75 regular expressions (BRE's).
78 manual page fully describes both formats.
80 Cause the file information and file type (see
82 returned for each symbolic link specified on the command line to be
83 those of the file referenced by the link, not the link itself.
84 If the referenced file does not exist, the file information and type will
85 be for the link itself.
86 File information of all symbolic links not on
87 the command line is that of the link itself.
89 Cause 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.
96 This option is equivalent to the deprecated
100 Cause the file information and file type (see
102 returned for each symbolic link to be those of the link itself.
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.
129 to perform a depth-first traversal.
131 This option is a BSD-specific equivalent of the
135 Refer to its description under
137 for more information.
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.
154 This option is equivalent to the deprecated
159 All primaries which take a numeric argument allow the number to be
160 preceded by a plus sign
164 A preceding plus sign means
166 a preceding minus sign means
170 .Bl -tag -width indent
172 True if the difference between the time of a file's inode creation
175 was started, rounded up to the next full minute, is
178 .It Ic -Bnewer Ar file
181 .It Ic -Btime Ar n Ns Op Cm smhdw
182 If no units are specified, this primary evaluates to
183 true if the difference between the time of a file's inode creation
186 was started, rounded up to the next full 24-hour period, is
190 If units are specified, this primary evaluates to
191 true if the difference between the time of a file's inode creation
194 was started is exactly
199 primary description for information on supported time units.
201 May be used in conjunction with other primaries to locate
202 files with extended ACLs.
205 for more information.
207 True if the difference between the file last access time and the time
209 was started, rounded up to the next full minute, is
212 .It Ic -anewer Ar file
215 .It Ic -atime Ar n Ns Op Cm smhdw
216 If no units are specified, this primary evaluates to
217 true if the difference between the file last access time and the time
219 was started, rounded up to the next full 24-hour period, is
223 If units are specified, this primary evaluates to
224 true if the difference between the file last access time and the time
226 was started is exactly
229 Possible time units are as follows:
231 .Bl -tag -width indent -compact
244 Any number of units may be combined in one
246 argument, for example,
247 .Dq Li "-atime -1h30m" .
248 Units are probably only useful when used in conjunction with the
254 True if the difference between the time of last change of file status
255 information and the time
257 was started, rounded up to the next full minute, is
260 .It Ic -cnewer Ar file
263 .It Ic -ctime Ar n Ns Op Cm smhdw
264 If no units are specified, this primary evaluates to
265 true if the difference between the time of last change of file status
266 information and the time
268 was started, rounded up to the next full 24-hour period, is
272 If units are specified, this primary evaluates to
273 true if the difference between the time of last change of file status
274 information and the time
276 was started is exactly
281 primary description for information on supported time units.
283 Non-portable, BSD-specific version of
285 GNU find implements this as a primary in mistaken emulation of
289 Delete found files and/or directories.
292 from the current working directory as
294 recurses down the tree.
295 It will not attempt to delete a filename with a
297 character in its pathname relative to
299 for security reasons.
300 Depth-first traversal processing is implied by this option.
301 Following symlinks is incompatible with this option.
304 same as the non-portable
309 to perform a depth-first traversal, i.e., directories
310 are visited in post-order and all entries in a directory will be acted
311 on before the directory itself.
314 visits directories in pre-order, i.e., before their contents.
317 a breadth-first traversal.
326 to process files that are contained in directories with unusual permissions.
327 It ensures that you have write permission while you are placing files in a
328 directory, then sets the directory's permissions as the last thing.
330 True if the depth of the file relative to the starting point of the traversal
334 True if the current file or directory is empty.
335 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
336 True if the program named
338 returns a zero value as its exit status.
341 may be passed to the utility.
342 The expression must be terminated by a semicolon
346 from a shell you may need to quote the semicolon if the shell would
347 otherwise treat it as a control operator.
350 appears anywhere in the utility name or the
351 arguments it is replaced by the pathname of the current file.
353 will be executed from the directory from which
359 are not subject to the further expansion of shell patterns
361 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
366 is replaced with as many pathnames as possible for each invocation of
368 This behaviour is similar to that of
370 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
373 primary is identical to the
375 primary with the exception that
377 will be executed from the directory that holds
379 The filename substituted for
383 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
388 is replaced with as many pathnames as possible for each invocation of
390 This behaviour is similar to that of
392 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
393 The flags are specified using symbolic names (see
403 are checked to be set, and flags in
405 are checked to be not set.
406 Note that this is different from
408 which only allows the user to specify mode bits that are set.
410 If flags are preceded by a dash
412 this primary evaluates to true
413 if at least all of the bits in
415 and none of the bits in
417 are set in the file's flags bits.
418 If flags are preceded by a plus
420 this primary evaluates to true
421 if any of the bits in
423 is set in the file's flags bits,
424 or any of the bits in
426 is not set in the file's flags bits.
428 this primary evaluates to true
431 exactly match the file's flags bits,
436 .It Ic -fstype Ar type
437 True if the file is contained in a file system of type
441 command can be used to find out the types of file systems
442 that are available on the system.
443 In addition, there are two pseudo-types,
447 The former matches any file system physically mounted on the system where
450 is being executed and the latter matches any file system which is
455 for compatibility with GNU find.
456 GNU find imposes a restriction that
461 .It Ic -group Ar gname
462 True if the file belongs to the group
466 is numeric and there is no such group name, then
468 is treated as a group ID.
469 .It Ic -ignore_readdir_race
470 Ignore errors because a file or a directory is deleted
471 after reading the name from a directory.
472 This option does not affect errors occurring on starting points.
473 .It Ic -ilname Ar pattern
476 but the match is case insensitive.
477 This is a GNU find extension.
478 .It Ic -iname Ar pattern
481 but the match is case insensitive.
483 True if the file has inode number
485 .It Ic -ipath Ar pattern
488 but the match is case insensitive.
489 .It Ic -iregex Ar pattern
492 but the match is case insensitive.
493 .It Ic -iwholename Ar pattern
496 for GNU find compatibility.
501 .It Ic -lname Ar pattern
504 but the contents of the symbolic link are matched instead of the file
506 Note that this only matches broken symbolic links
507 if symbolic links are being followed.
508 This is a GNU find extension.
510 This primary always evaluates to true.
511 The following information for the current file is written to standard output:
512 its inode number, size in 512-byte blocks, file permissions, number of hard
513 links, owner, group, size in bytes, last modification time, and pathname.
514 If the file is a block or character special file, the major and minor numbers
515 will be displayed instead of the size in bytes.
516 If the file is a symbolic link, the pathname of the linked-to file will be
517 displayed preceded by
519 The format is identical to that produced by
523 .It Ic -maxdepth Ar n
524 Always true; descend at most
526 directory levels below the command line arguments.
529 primary is specified, it applies to the entire expression even if it would
530 not normally be evaluated.
531 .Dq Ic -maxdepth Li 0
532 limits the whole search to the command line arguments.
533 .It Ic -mindepth Ar n
534 Always true; do not apply any tests or actions at levels less than
538 primary is specified, it applies to the entire expression even if it would
539 not normally be evaluated.
540 .Dq Ic -mindepth Li 1
541 processes all but the command line arguments.
543 True if the difference between the file last modification time and the time
545 was started, rounded up to the next full minute, is
548 .It Ic -mnewer Ar file
554 for GNU find compatibility.
555 .It Ic -mtime Ar n Ns Op Cm smhdw
556 If no units are specified, this primary evaluates to
557 true if the difference between the file last modification time and the time
559 was started, rounded up to the next full 24-hour period, is
563 If units are specified, this primary evaluates to
564 true if the difference between the file last modification time and the time
566 was started is exactly
571 primary description for information on supported time units.
572 .It Ic -name Ar pattern
573 True if the last component of the pathname being examined matches
575 Special shell pattern matching characters
581 may be used as part of
583 These characters may be matched explicitly by escaping them with a
586 .It Ic -newer Ar file
587 True if the current file has a more recent last modification time than
589 .It Ic -newer Ns Ar X Ns Ar Y Ar file
590 True if the current file has a more recent last access time
591 .Pq Ar X Ns = Ns Cm a ,
593 .Pq Ar X Ns = Ns Cm B ,
595 .Pq Ar X Ns = Ns Cm c ,
597 .Pq Ar X Ns = Ns Cm m
598 than the last access time
599 .Pq Ar Y Ns = Ns Cm a ,
601 .Pq Ar Y Ns = Ns Cm B ,
603 .Pq Ar Y Ns = Ns Cm c ,
605 .Pq Ar Y Ns = Ns Cm m
612 is instead interpreted as a direct date specification of the form
620 True if the file belongs to an unknown group.
621 .It Ic -noignore_readdir_race
622 Turn off the effect of
623 .Ic -ignore_readdir_race .
624 This is default behaviour.
626 This option is for GNU find compatibility.
627 In GNU find it disables an optimization not relevant to
631 True if the file belongs to an unknown user.
632 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
635 primary is identical to the
637 primary with the exception that
639 requests user affirmation for the execution of the
642 a message to the terminal and reading a response.
643 If the response is not affirmative
648 the command is not executed and the
652 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
655 primary is identical to the
657 primary with the same exception as described for the
660 .It Ic -path Ar pattern
661 True if the pathname being examined matches
663 Special shell pattern matching characters
669 may be used as part of
671 These characters may be matched explicitly by escaping them with a
676 are treated as normal characters and do not have to be
678 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
681 may be either symbolic (see
686 is symbolic, a starting value of zero is assumed and the
688 sets or clears permissions without regard to the process' file mode
692 is octal, only bits 07777
693 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
694 of the file's mode bits participate
698 is preceded by a dash
700 this primary evaluates to true
701 if at least all of the bits in the
703 are set in the file's mode bits.
706 is preceded by a plus
708 this primary evaluates to true
709 if any of the bits in the
711 are set in the file's mode bits.
712 Otherwise, this primary evaluates to true if
715 exactly match the file's mode bits.
716 Note, the first character of a symbolic mode may not be a dash
719 This primary always evaluates to true.
720 It prints the pathname of the current file to standard output.
722 .Ic -exec , -ls , -print0 ,
725 is specified, the given expression shall be effectively replaced by
726 .Cm \&( Ar "given expression" Cm \&) Ic -print .
728 This primary always evaluates to true.
729 It prints the pathname of the current file to standard output, followed by an
732 character (character code 0).
734 This primary always evaluates to true.
737 to not descend into the current file.
740 primary has no effect if the
742 option was specified.
746 to immediately terminate.
747 .It Ic -regex Ar pattern
748 True if the whole path of the file matches
750 using regular expression.
751 To match a file named
753 you can use the regular expression
761 .It Ic -samefile Ar name
762 True if the file is a hard link to
764 If the command option
766 is specified, it is also true if the file is a symbolic link and
769 .It Ic -size Ar n Ns Op Cm ckMGTP
770 True if the file's size, rounded up, in 512-byte blocks is
776 then the primary is true if the
782 is followed by a scale indicator then the file's size is compared to
786 .Bl -tag -width indent -compact
788 kilobytes (1024 bytes)
790 megabytes (1024 kilobytes)
792 gigabytes (1024 megabytes)
794 terabytes (1024 gigabytes)
796 petabytes (1024 terabytes)
799 True if the file is of the specified type.
800 Possible file types are as follows:
802 .Bl -tag -width indent -compact
821 for compatibility with GNU find.
822 GNU find imposes a restriction that
827 .It Ic -user Ar uname
828 True if the file belongs to the user
832 is numeric and there is no such user name, then
834 is treated as a user ID.
835 .It Ic -wholename Ar pattern
838 for GNU find compatibility.
841 The primaries may be combined using the following operators.
842 The operators are listed in order of decreasing precedence.
844 .Bl -tag -width indent -compact
845 .It Cm \&( Ar expression Cm \&)
846 This evaluates to true if the parenthesized expression evaluates to
849 .It Cm \&! Ar expression
850 .It Cm -not Ar expression
854 It evaluates to true if the expression is false.
861 .It Ar expression Cm -and Ar expression
862 .It Ar expression expression
865 operator is the logical
868 As it is implied by the juxtaposition of two expressions it does not
869 have to be specified.
870 The expression evaluates to true if both expressions are true.
871 The second expression is not evaluated if the first expression is false.
873 .It Ar expression Cm -or Ar expression
876 operator is the logical
879 The expression evaluates to true if either the first or the second expression
881 The second expression is not evaluated if the first expression is true.
884 All operands and primaries must be separate arguments to
886 Primaries which themselves take arguments expect each argument
887 to be a separate argument to
891 .Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
894 environment variables affect the execution of the
896 utility as described in
899 The following examples are shown as given to the shell:
900 .Bl -tag -width indent
901 .It Li "find / \e! -name \*q*.c\*q -print"
902 Print out a list of all the files whose names do not end in
904 .It Li "find / -newer ttt -user wnj -print"
905 Print out a list of all the files owned by user
910 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
911 Print out a list of all the files which are not both newer than
915 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
916 Print out a list of all the files that are either owned by
918 or that are newer than
920 .It Li "find / -newerct '1 minute ago' -print"
921 Print out a list of all the files whose inode change time is more
922 recent than the current time minus one minute.
923 .It Li "find / -type f -exec echo {} \e;"
926 command to print out a list of all the files.
927 .It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
928 Delete all broken symbolic links in
929 .Pa /usr/ports/packages .
930 .It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
931 Find files and directories that are at least seven levels deep
932 in the working directory
934 .It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
935 Is not equivalent to the previous example, since
937 is not evaluated below level seven.
942 primary is deprecated; the
944 option should be used instead.
947 section below for details.
968 utility syntax is a superset of the syntax specified by the
972 All the single character options except
977 .Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
978 .Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
979 .Ic -path , -print0 , -regex
982 birthtime related primaries are extensions to
989 options were implemented using the primaries
990 .Ic -depth , -follow ,
993 These primaries always evaluated to true.
994 As they were really global variables that took effect before the traversal
995 began, some legal expressions could have unexpected results.
996 An example is the expression
997 .Ic -print Cm -o Ic -depth .
1000 always evaluates to true, the standard order of evaluation
1003 would never be evaluated.
1004 This is not the case.
1015 Historic implementations of the
1019 primaries did not replace the string
1021 in the utility name or the
1022 utility arguments if it had preceding or following non-whitespace characters.
1023 This version replaces it no matter where in the utility name or arguments
1028 option was inspired by the equivalent
1039 The special characters used by
1041 are also special characters to many shell programs.
1042 In particular, the characters
1053 may have to be escaped from the shell.
1055 As there is no delimiter separating options and file names or file
1058 it is difficult to specify files named
1062 These problems are handled by the
1071 primary does not interact well with other options that cause the file system
1072 tree traversal options to be changed.
1078 primaries are actually global options (as documented above).
1080 probably be replaced by options which look like options.
projects / FreeBSD / stable / 9.git / blob