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
36 .\" $FreeBSD: src/usr.bin/find/find.1,v 1.71 2005/01/11 10:32:51 ru Exp $
37 .\" $DragonFly: src/usr.bin/find/find.1,v 1.4 2007/04/20 08:04:20 swildner Exp $
44 .Nd walk a file hierarchy
47 .Op Fl H | Fl L | Fl P
55 utility recursively descends the directory tree for each
63 listed below) in terms
64 of each file in the tree.
66 The options are as follows:
67 .Bl -tag -width indent
69 Interpret regular expressions followed by
73 options as extended (modern) regular expressions rather than basic
74 regular expressions (BRE's).
77 manual page fully describes both formats.
79 Cause 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.
88 Cause the file information and file type (see
90 returned for each symbolic link to be those of the file referenced by the
91 link, not the link itself.
92 If the referenced file does not exist, the file information and type will
93 be for the link itself.
95 This option is equivalent to the deprecated
99 Cause the file information and file type (see
101 returned for each symbolic link to be those of the link itself.
106 to be safely used in conjunction with
108 If a file name contains any of the delimiting characters used by
110 a diagnostic message is displayed on standard error, and the file
112 The delimiting characters include single
118 space, tab and newline characters.
120 However, you may wish to consider the
122 primary in conjunction with
124 as an effective alternative.
128 to perform a depth-first traversal, i.e., directories
129 are visited in post-order and all entries in a directory will be acted
130 on before the directory itself.
133 visits directories in pre-order, i.e., before their contents.
136 a breadth-first traversal.
138 This option is equivalent to the
147 to process files that are contained in directories with unusual permissions.
148 It ensures that you have write permission while you are placing files in a
149 directory, then sets the directory's permissions as the last thing.
151 Specify a file hierarchy for
154 File hierarchies may also be specified as the operands immediately
155 following the options.
159 to traverse the file hierarchies in lexicographical order,
160 i.e., alphabetical order within each directory.
165 may give different results.
169 from descending into directories that have a device number different
170 than that of the file from which the descent began.
172 This option is equivalent to the deprecated
177 .Bl -tag -width indent
179 True if the difference between the file last access time and the time
181 was started, rounded up to the next full minute, is
184 .It Ic -anewer Ar file
187 .It Ic -atime Ar n Ns Op Cm smhdw
188 If no units are specified, this primary evaluates to
189 true if the difference between the file last access time and the time
191 was started, rounded up to the next full 24-hour period, is
195 If units are specified, this primary evaluates to
196 true if the difference between the file last access time and the time
198 was started is exactly
201 Possible time units are as follows:
203 .Bl -tag -width indent -compact
216 Any number of units may be combined in one
218 argument, for example,
219 .Dq Li "-atime -1h30m" .
220 Units are probably only useful when used in conjunction with the
226 True if the difference between the time of last change of file status
227 information and the time
229 was started, rounded up to the next full minute, is
232 .It Ic -cnewer Ar file
235 .It Ic -ctime Ar n Ns Op Cm smhdw
236 If no units are specified, this primary evaluates to
237 true if the difference between the time of last change of file status
238 information and the time
240 was started, rounded up to the next full 24-hour period, is
244 If units are specified, this primary evaluates to
245 true if the difference between the time of last change of file status
246 information and the time
248 was started is exactly
253 primary description for information on supported time units.
255 Delete found files and/or directories.
258 from the current working directory as
260 recurses down the tree.
261 It will not attempt to delete a filename with a
263 character in its pathname relative to
265 for security reasons.
266 Depth-first traversal processing is implied by this option.
273 True if the depth of the file relative to the starting point of the traversal
277 True if the current file or directory is empty.
278 .It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
279 True if the program named
281 returns a zero value as its exit status.
284 may be passed to the utility.
285 The expression must be terminated by a semicolon
289 from a shell you may need to quote the semicolon if the shell would
290 otherwise treat it as a control operator.
293 appears anywhere in the utility name or the
294 arguments it is replaced by the pathname of the current file.
296 will be executed from the directory from which
302 are not subject to the further expansion of shell patterns
304 .It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
309 is replaced with as many pathnames as possible for each invocation of
311 This behaviour is similar to that of
313 .It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
316 primary is identical to the
318 primary with the exception that
320 will be executed from the directory that holds
322 The filename substituted for
326 .It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
327 The flags are specified using symbolic names (see
337 are checked to be set, and flags in
339 are checked to be not set.
340 Note that this is different from
342 which only allows the user to specify mode bits that are set.
344 If flags are preceded by a dash
346 this primary evaluates to true
347 if at least all of the bits in
349 and none of the bits in
351 are set in the file's flags bits.
352 If flags are preceded by a plus
354 this primary evaluates to true
355 if any of the bits in
357 is set in the file's flags bits,
358 or any of the bits in
360 is not set in the file's flags bits.
362 this primary evaluates to true
365 exactly match the file's flags bits,
370 .It Ic -fstype Ar type
371 True if the file is contained in a file system of type
375 command can be used to find out the types of file systems
376 that are available on the system:
380 In addition, there are two pseudo-types,
384 The former matches any file system physically mounted on the system where
387 is being executed and the latter matches any file system which is
389 .It Ic -group Ar gname
390 True if the file belongs to the group
394 is numeric and there is no such group name, then
396 is treated as a group ID.
397 .It Ic -iname Ar pattern
400 but the match is case insensitive.
402 True if the file has inode number
404 .It Ic -ipath Ar pattern
407 but the match is case insensitive.
408 .It Ic -iregex Ar pattern
411 but the match is case insensitive.
417 This primary always evaluates to true.
418 The following information for the current file is written to standard output:
419 its inode number, size in 512-byte blocks, file permissions, number of hard
420 links, owner, group, size in bytes, last modification time, and pathname.
421 If the file is a block or character special file, the major and minor numbers
422 will be displayed instead of the size in bytes.
423 If the file is a symbolic link, the pathname of the linked-to file will be
424 displayed preceded by
426 The format is identical to that produced by
430 .It Ic -maxdepth Ar n
431 Always true; descend at most
433 directory levels below the command line arguments.
436 primary is specified, it applies to the entire expression even if it would
437 not normally be evaluated.
439 limits the whole search to the command line arguments.
440 .It Ic -mindepth Ar n
441 Always true; do not apply any tests or actions at levels less than
445 primary is specified, it applies to the entire expression even if it would
446 not normally be evaluated.
448 processes all but the command line arguments.
450 True if the difference between the file last modification time and the time
452 was started, rounded up to the next full minute, is
455 .It Ic -mnewer Ar file
458 .It Ic -mtime Ar n Ns Op Cm smhdw
459 If no units are specified, this primary evaluates to
460 true if the difference between the file last modification time and the time
462 was started, rounded up to the next full 24-hour period, is
466 If units are specified, this primary evaluates to
467 true if the difference between the file last modification time and the time
469 was started is exactly
474 primary description for information on supported time units.
475 .It Ic -name Ar pattern
476 True if the last component of the pathname being examined matches
478 Special shell pattern matching characters
484 may be used as part of
486 These characters may be matched explicitly by escaping them with a
489 .It Ic -newer Ar file
490 True if the current file has a more recent last modification time than
492 .It Ic -newer Ns Ar X Ns Ar Y Ar file
493 True if the current file has a more recent last access time
494 .Ar ( X Ns = Ns Cm a ) ,
496 .Ar ( X Ns = Ns Cm c ) ,
498 .Ar ( X Ns = Ns Cm m )
499 than the last access time
500 .Ar ( Y Ns = Ns Cm a ) ,
502 .Ar ( Y Ns = Ns Cm c ) ,
504 .Ar ( Y Ns = Ns Cm m )
511 is instead interpreted as a direct date specification of the form
519 True if the file belongs to an unknown group.
521 True if the file belongs to an unknown user.
522 .It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
525 primary is identical to the
527 primary with the exception that
529 requests user affirmation for the execution of the
532 a message to the terminal and reading a response.
533 If the response is other than
535 the command is not executed and the
539 .It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
542 primary is identical to the
544 primary with the same exception as described for the
547 .It Ic -path Ar pattern
548 True if the pathname being examined matches
550 Special shell pattern matching characters
556 may be used as part of
558 These characters may be matched explicitly by escaping them with a
563 are treated as normal characters and do not have to be
565 .It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
568 may be either symbolic (see
573 is symbolic, a starting value of zero is assumed and the
575 sets or clears permissions without regard to the process' file mode
579 is octal, only bits 07777
580 .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
581 of the file's mode bits participate
585 is preceded by a dash
587 this primary evaluates to true
588 if at least all of the bits in the
590 are set in the file's mode bits.
593 is preceded by a plus
595 this primary evaluates to true
596 if any of the bits in the
598 are set in the file's mode bits.
599 Otherwise, this primary evaluates to true if
602 exactly match the file's mode bits.
603 Note, the first character of a symbolic mode may not be a dash
606 This primary always evaluates to true.
607 It prints the pathname of the current file to standard output.
609 .Ic -exec , -ls , -print0 ,
612 is specified, the given expression shall be effectively replaced by
613 .Cm \&( Ar "given expression" Cm \&) Ic -print .
615 This primary always evaluates to true.
616 It prints the pathname of the current file to standard output, followed by an
618 character (character code 0).
620 This primary always evaluates to true.
623 to not descend into the current file.
626 primary has no effect if the
628 option was specified.
629 .It Ic -regex Ar pattern
630 True if the whole path of the file matches
632 using regular expression.
633 To match a file named
635 you can use the regular expression
643 .It Ic -size Ar n Ns Op Cm c
644 True if the file's size, rounded up, in 512-byte blocks is
650 then the primary is true if the
655 True if the file is of the specified type.
656 Possible file types are as follows:
658 .Bl -tag -width indent -compact
674 .It Ic -user Ar uname
675 True if the file belongs to the user
679 is numeric and there is no such user name, then
681 is treated as a user ID.
684 All primaries which take a numeric argument allow the number to be
685 preceded by a plus sign
689 A preceding plus sign means
691 a preceding minus sign means
696 The primaries may be combined using the following operators.
697 The operators are listed in order of decreasing precedence.
699 .Bl -tag -width "( expression )" -compact
700 .It Cm \&( Ar expression Cm \&)
701 This evaluates to true if the parenthesized expression evaluates to
704 .It Cm \&! Ar expression
705 .It Cm -false Ar expression
706 .It Cm -not Ar expression
710 It evaluates to true if the expression is false.
712 .It Ar expression Cm -and Ar expression
713 .It Ar expression expression
716 operator is the logical
719 As it is implied by the juxtaposition of two expressions it does not
720 have to be specified.
721 The expression evaluates to true if both expressions are true.
722 The second expression is not evaluated if the first expression is false.
724 .It Ar expression Cm -or Ar expression
727 operator is the logical
730 The expression evaluates to true if either the first or the second expression
732 The second expression is not evaluated if the first expression is true.
735 All operands and primaries must be separate arguments to
737 Primaries which themselves take arguments expect each argument
738 to be a separate argument to
741 The following examples are shown as given to the shell:
742 .Bl -tag -width indent
743 .It Li "find / \e! -name \*q*.c\*q"
744 Print out a list of all the files whose names do not end in
746 .It Li "find / -newer ttt -user wnj"
747 Print out a list of all the files owned by user
752 .It Li "find / \e! \e( -newer ttt -user wnj \e)"
753 Print out a list of all the files which are not both newer than
757 .It Li "find / \e( -newer ttt -or -user wnj \e)"
758 Print out a list of all the files that are either owned by
760 or that are newer than
762 .It Li "find / -newerct '1 minute ago'"
763 Print out a list of all the files whose inode change time is more
764 recent than the current time minus one minute.
765 .It Li "find / -type f -exec echo {} \e;"
768 command to print out a list of all the files.
769 .It Li "find /usr/src -name CVS -prune -o -depth +6"
770 Find files and directories that are at least seven levels deep
771 in the working directory
773 .It Li "find /usr/src -name CVS -prune -o -mindepth 7"
774 Is not equivalent to the previous example, since
776 is not evaluated below level seven.
781 primary is deprecated; the
783 option should be used instead.
786 section below for details.
805 utility syntax is a superset of the syntax specified by the
809 All the single character options except
814 .Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
817 primaries are extensions to
824 options were implemented using the primaries
825 .Ic -depth , -follow ,
828 These primaries always evaluated to true.
829 As they were really global variables that took effect before the traversal
830 began, some legal expressions could have unexpected results.
831 An example is the expression
832 .Ic -print Cm -o Ic -depth .
835 always evaluates to true, the standard order of evaluation
838 would never be evaluated.
839 This is not the case.
850 Historic implementations of the
854 primaries did not replace the string
856 in the utility name or the
857 utility arguments if it had preceding or following non-whitespace characters.
858 This version replaces it no matter where in the utility name or arguments
863 option was inspired by the equivalent
874 The special characters used by
876 are also special characters to many shell programs.
877 In particular, the characters
888 may have to be escaped from the shell.
890 As there is no delimiter separating options and file names or file
893 it is difficult to specify files named
897 These problems are handled by the
906 primary does not interact well with other options that cause the file system
907 tree traversal options to be changed.
913 primaries are actually global options (as documented above).
915 probably be replaced by options which look like options.
projects / dragonfly.git / blob