xref: /freebsd/usr.bin/find/find.1 (revision 6780ab54325a71e7e70112b11657973edde8655e)
1.\"	The Regents of the University of California.  All rights reserved.
2.\"
3.\" This code is derived from software contributed to Berkeley by
4.\" the Institute of Electrical and Electronics Engineers, Inc.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
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.
21.\"
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
32.\" SUCH DAMAGE.
33.\"
34.\"	@(#)find.1	8.7 (Berkeley) 5/9/95
35.\" $FreeBSD$
36.\"
37.Dd May 3, 2001
38.Dt FIND 1
39.Os
40.Sh NAME
41.Nm find
42.Nd walk a file hierarchy
43.Sh SYNOPSIS
44.Nm
45.Op Fl H | Fl L | Fl P
46.Op Fl EXdsx
47.Op Fl f Ar pathname
48.Op Ar pathname ...
49.Ar expression
50.Sh DESCRIPTION
51The
52.Nm
53utility recursively descends the directory tree for each
54.Ar pathname
55listed, evaluating an
56.Ar expression
57(composed of the
58.Dq primaries
59and
60.Dq operands
61listed below) in terms
62of each file in the tree.
63.Pp
64The options are as follows:
65.Bl -tag -width indent
66.It Fl E
67Interpret regular expressions followed by
68.Ic -regex
69and
70.Ic -iregex
71options as extended (modern) regular expressions rather than basic
72regular expressions (BRE's).
73The
74.Xr re_format 7
75manual page fully describes both formats.
76.It Fl H
77Cause the file information and file type (see
78.Xr stat 2 )
79returned for each symbolic link specified on the command line to be
80those of the file referenced by the link, not the link itself.
81If the referenced file does not exist, the file information and type will
82be for the link itself.
83File information of all symbolic links not on
84the command line is that of the link itself.
85.It Fl L
86Cause the file information and file type (see
87.Xr stat 2 )
88returned for each symbolic link to be those of the file referenced by the
89link, not the link itself.
90If the referenced file does not exist, the file information and type will
91be for the link itself.
92.It Fl P
93Cause the file information and file type (see
94.Xr stat 2 )
95returned for each symbolic link to be those of the link itself.
96This is the default.
97.It Fl X
98Permit
99.Nm
100to be safely used in conjunction with
101.Xr xargs 1 .
102If a file name contains any of the delimiting characters used by
103.Xr xargs 1 ,
104a diagnostic message is displayed on standard error, and the file
105is skipped.
106The delimiting characters include single
107.Pq Dq Li " ' "
108and double
109.Pq Dq Li " \*q "
110quotes, backslash
111.Pq Dq Li \e ,
112space, tab and newline characters.
113.Pp
114However, you may wish to consider the
115.Fl print0
116primary in conjunction with
117.Dq Nm xargs Fl 0
118as an effective alternative.
119.It Fl d
120Cause
121.Nm
122to perform a depth\-first traversal, i.e., directories
123are visited in post\-order and all entries in a directory will be acted
124on before the directory itself.
125By default,
126.Nm
127visits directories in pre\-order, i.e., before their contents.
128Note, the default is
129.Em not
130a breadth\-first traversal.
131.It Fl f
132Specify a file hierarchy for
133.Nm
134to traverse.
135File hierarchies may also be specified as the operands immediately
136following the options.
137.It Fl s
138Cause
139.Nm
140to traverse the file hierarchies in lexicographical order,
141i.e., alphabetical order within each directory.
142Note:
143.Ql find -s
144and
145.Ql "find | sort"
146may give different results.
147.It Fl x
148Prevent
149.Nm
150from descending into directories that have a device number different
151than that of the file from which the descent began.
152.El
153.Sh PRIMARIES
154.Bl -tag -width indent
155.It Ic -amin Ar n
156True if the difference between the file last access time and the time
157.Nm
158was started, rounded up to the next full minute, is
159.Ar n
160minutes.
161.It Ic -anewer Ar file
162Same as
163.Ic -neweram .
164.It Ic -atime Ar n Ns Op Cm smhdw
165If no units are specified, this primary evaluates to
166true if the difference between the file last access time and the time
167.Nm
168was started, rounded up to the next full 24\-hour period, is
169.Ar n
17024\-hour periods.
171.Pp
172If units are specified, this primary evaluates to
173true if the difference between the file last access time and the time
174.Nm
175was started is exactly
176.Ar n
177units.
178Possible time units are as follows:
179.Pp
180.Bl -tag -width indent -compact
181.It Cm s
182second
183.It Cm m
184minute (60 seconds)
185.It Cm h
186hour (60 minutes)
187.It Cm d
188day (24 hours)
189.It Cm w
190week (7 days)
191.El
192.Pp
193Any number of units may be combined in one
194.Ic -atime
195argument, for example,
196.Dq Li "-atime -1h30m" .
197Units are probably only useful when used in conjunction with the
198.Cm +
199or
200.Cm -
201modifier.
202.It Ic -cmin Ar n
203True if the difference between the time of last change of file status
204information and the time
205.Nm
206was started, rounded up to the next full minute, is
207.Ar n
208minutes.
209.It Ic -cnewer Ar file
210Same as
211.Ic -newercm .
212.It Ic -ctime Ar n Ns Op Cm smhdw
213If no units are specified, this primary evaluates to
214true if the difference between the time of last change of file status
215information and the time
216.Nm
217was started, rounded up to the next full 24\-hour period, is
218.Ar n
21924\-hour periods.
220.Pp
221If units are specified, this primary evaluates to
222true if the difference between the time of last change of file status
223information and the time
224.Nm
225was started is exactly
226.Ar n
227units.
228Please refer to the
229.Ic -atime
230primary description for information on supported time units.
231.It Ic -delete
232Delete found files and/or directories.
233Always returns true.
234This executes
235from the current working directory as
236.Nm
237recurses down the tree.
238It will not attempt to delete a filename with a
239.Dq Pa /
240character in its pathname relative to
241.Dq Pa \&.
242for security reasons.
243Depth\-first traversal processing is implied by this option.
244.It Ic -depth
245Always true;
246same as the
247.Fl d
248option.
249.Ic -depth
250can be useful when
251.Nm
252is used with
253.Xr cpio 1
254to process files that are contained in directories with unusual permissions.
255It ensures that you have write permission while you are placing files in a
256directory, then sets the directory's permissions as the last thing.
257.It Ic -empty
258True if the current file or directory is empty.
259.It Ic -exec Ar utility Oo Ar argument ...  Oc Li \&;
260True if the program named
261.Ar utility
262returns a zero value as its exit status.
263Optional
264.Ar arguments
265may be passed to the utility.
266The expression must be terminated by a semicolon
267.Pq Dq Li \&; .
268If the string
269.Dq Li {}
270appears anywhere in the utility name or the
271arguments it is replaced by the pathname of the current file.
272.Ar Utility
273will be executed from the directory from which
274.Nm
275was executed.
276.Ar Utility
277and
278.Ar arguments
279are not subject to the further expansion of shell patterns
280and constructs.
281.It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
282Same as
283.Ic -exec ,
284except that
285.Dq Li {}
286is replaced with as many pathnames as possible for each invocation of
287.Ar utility .
288This behaviour is similar to that of
289.Xr xargs 1 .
290.It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
291The
292.Ic -execdir
293primary is identical to the
294.Ic -exec
295primary with the exception that
296.Ar utility
297will be executed from the directory that holds
298the current file.
299The filename substituted for
300the string
301.Dq Li {}
302is not qualified.
303.It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
304The flags are specified using symbolic names (see
305.Xr chflags 1 ) .
306Those with the
307.Qq Li no
308prefix (except
309.Qq Li nodump )
310are said to be
311.Ar notflags .
312Flags in
313.Ar flags
314are checked to be set, and flags in
315.Ar notflags
316are checked to be not set.
317Note that this is different from
318.Ic -perm ,
319which only allows the user to specify mode bits that are set.
320.Pp
321If flags are preceded by a dash
322.Pq Dq Li - ,
323this primary evaluates to true
324if at least all of the bits in
325.Ar flags
326and none of the bits in
327.Ar notflags
328are set in the file's flags bits.
329If flags are preceded by a plus
330.Pq Dq Li + ,
331this primary evaluates to true
332if any of the bits in
333.Ar flags
334is set in the file's flags bits,
335or any of the bits in
336.Ar notflags
337is not set in the file's flags bits.
338Otherwise,
339this primary evaluates to true
340if the bits in
341.Ar flags
342exactly match the file's flags bits,
343and none of the
344.Ar flags
345bits match those of
346.Ar notflags .
347.It Ic -fstype Ar type
348True if the file is contained in a file system of type
349.Ar type .
350The
351.Xr sysctl 8
352command can be used to find out the types of file systems
353that are available on the system:
354.Pp
355.Dl "sysctl vfs"
356.Pp
357In addition, there are two pseudo-types,
358.Dq Li local
359and
360.Dq Li rdonly .
361The former matches any file system physically mounted on the system where
362the
363.Nm
364is being executed and the latter matches any file system which is
365mounted read-only.
366.It Ic -group Ar gname
367True if the file belongs to the group
368.Ar gname .
369If
370.Ar gname
371is numeric and there is no such group name, then
372.Ar gname
373is treated as a group ID.
374.It Ic -iname Ar pattern
375Like
376.Ic -name ,
377but the match is case insensitive.
378.It Ic -inum Ar n
379True if the file has inode number
380.Ar n .
381.It Ic -ipath Ar pattern
382Like
383.Ic -path ,
384but the match is case insensitive.
385.It Ic -iregex Ar pattern
386Like
387.Ic -regex ,
388but the match is case insensitive.
389.It Ic -links Ar n
390True if the file has
391.Ar n
392links.
393.It Ic -ls
394This primary always evaluates to true.
395The following information for the current file is written to standard output:
396its inode number, size in 512\-byte blocks, file permissions, number of hard
397links, owner, group, size in bytes, last modification time, and pathname.
398If the file is a block or character special file, the major and minor numbers
399will be displayed instead of the size in bytes.
400If the file is a symbolic link, the pathname of the linked\-to file will be
401displayed preceded by
402.Dq Li -> .
403The format is identical to that produced by
404.Bk -words
405.Nm ls Fl dgils .
406.Ek
407.It Ic -maxdepth Ar n
408True if the depth of the current file into the tree is less than or equal to
409.Ar n .
410.It Ic -mindepth Ar n
411True if the depth of the current file into the tree is greater than or equal to
412.Ar n .
413.It Ic -mmin Ar n
414True if the difference between the file last modification time and the time
415.Nm
416was started, rounded up to the next full minute, is
417.Ar n
418minutes.
419.It Ic -mnewer Ar file
420Same as
421.Ic -newer .
422.It Ic -mtime Ar n Ns Op Cm smhdw
423If no units are specified, this primary evaluates to
424true if the difference between the file last modification time and the time
425.Nm
426was started, rounded up to the next full 24\-hour period, is
427.Ar n
42824\-hour periods.
429.Pp
430If units are specified, this primary evaluates to
431true if the difference between the file last modification time and the time
432.Nm
433was started is exactly
434.Ar n
435units.
436Please refer to the
437.Ic -atime
438primary description for information on supported time units.
439.It Ic -name Ar pattern
440True if the last component of the pathname being examined matches
441.Ar pattern .
442Special shell pattern matching characters
443.Dq ( Li \&[ ,
444.Dq Li \&] ,
445.Dq Li * ,
446and
447.Dq Li \&? )
448may be used as part of
449.Ar pattern .
450These characters may be matched explicitly by escaping them with a
451backslash
452.Pq Dq Li \e .
453.It Ic -newer Ar file
454True if the current file has a more recent last modification time than
455.Ar file .
456.It Ic -newer Ns Ar X Ns Ar Y Ar file
457True if the current file has a more recent last access time
458.Ar ( X Ns = Ns Cm a ) ,
459change time
460.Ar ( X Ns = Ns Cm c ) ,
461or modification time
462.Ar ( X Ns = Ns Cm m )
463than the last access time
464.Ar ( Y Ns = Ns Cm a ) ,
465change time
466.Ar ( Y Ns = Ns Cm c ) ,
467or modification time
468.Ar ( Y Ns = Ns Cm m )
469of
470.Ar file .
471In addition, if
472.Ar Y Ns = Ns Cm t ,
473then
474.Ar file
475is instead interpreted as a direct date specification of the form
476understood by
477.Xr cvs 1 .
478Note that
479.Ic -newermm
480is equivalent to
481.Ic -newer .
482.It Ic -nogroup
483True if the file belongs to an unknown group.
484.It Ic -nouser
485True if the file belongs to an unknown user.
486.It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
487The
488.Ic -ok
489primary is identical to the
490.Ic -exec
491primary with the exception that
492.Nm
493requests user affirmation for the execution of the
494.Ar utility
495by printing
496a message to the terminal and reading a response.
497If the response is other than
498.Dq Li y
499the command is not executed and the
500value of the
501.Ic -ok
502expression is false.
503.It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
504The
505.Ic -okdir
506primary is identical to the
507.Ic -execdir
508primary with the same exception as described for the
509.Ic -ok
510primary.
511.It Ic -path Ar pattern
512True if the pathname being examined matches
513.Ar pattern .
514Special shell pattern matching characters
515.Dq ( Li \&[ ,
516.Dq Li \&] ,
517.Dq Li * ,
518and
519.Dq Li \&? )
520may be used as part of
521.Ar pattern .
522These characters may be matched explicitly by escaping them with a
523backslash
524.Pq Dq Li \e .
525Slashes
526.Pq Dq Li /
527are treated as normal characters and do not have to be
528matched explicitly.
529.It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode
530The
531.Ar mode
532may be either symbolic (see
533.Xr chmod 1 )
534or an octal number.
535If the
536.Ar mode
537is symbolic, a starting value of zero is assumed and the
538.Ar mode
539sets or clears permissions without regard to the process' file mode
540creation mask.
541If the
542.Ar mode
543is octal, only bits 07777
544.Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
545of the file's mode bits participate
546in the comparison.
547If the
548.Ar mode
549is preceded by a dash
550.Pq Dq Li - ,
551this primary evaluates to true
552if at least all of the bits in the
553.Ar mode
554are set in the file's mode bits.
555If the
556.Ar mode
557is preceded by a plus
558.Pq Dq Li + ,
559this primary evaluates to true
560if any of the bits in the
561.Ar mode
562are set in the file's mode bits.
563Otherwise, this primary evaluates to true if
564the bits in the
565.Ar mode
566exactly match the file's mode bits.
567Note, the first character of a symbolic mode may not be a dash
568.Pq Dq Li - .
569.It Ic -print
570This primary always evaluates to true.
571It prints the pathname of the current file to standard output.
572If none of
573.Ic -exec , -ls , -print0 ,
574or
575.Ic -ok
576is specified, the given expression shall be effectively replaced by
577.Cm \&( Ar "given expression" Cm \&) Ic -print .
578.It Ic -print0
579This primary always evaluates to true.
580It prints the pathname of the current file to standard output, followed by an
581.Tn ASCII NUL
582character (character code 0).
583.It Ic -prune
584This primary always evaluates to true.
585It causes
586.Nm
587to not descend into the current file.
588Note, the
589.Ic -prune
590primary has no effect if the
591.Fl d
592option was specified.
593.It Ic -regex Ar pattern
594True if the whole path of the file matches
595.Ar pattern
596using regular expression.
597To match a file named
598.Dq Pa ./foo/xyzzy ,
599you can use the regular expression
600.Dq Li ".*/[xyz]*"
601or
602.Dq Li ".*/foo/.*" ,
603but not
604.Dq Li xyzzy
605or
606.Dq Li /foo/ .
607.It Ic -size Ar n Ns Op Cm c
608True if the file's size, rounded up, in 512\-byte blocks is
609.Ar n .
610If
611.Ar n
612is followed by a
613.Cm c ,
614then the primary is true if the
615file's size is
616.Ar n
617bytes (characters).
618.It Ic -type Ar t
619True if the file is of the specified type.
620Possible file types are as follows:
621.Pp
622.Bl -tag -width indent -compact
623.It Cm b
624block special
625.It Cm c
626character special
627.It Cm d
628directory
629.It Cm f
630regular file
631.It Cm l
632symbolic link
633.It Cm p
634FIFO
635.It Cm s
636socket
637.El
638.It Ic -user Ar uname
639True if the file belongs to the user
640.Ar uname .
641If
642.Ar uname
643is numeric and there is no such user name, then
644.Ar uname
645is treated as a user ID.
646.El
647.Pp
648All primaries which take a numeric argument allow the number to be
649preceded by a plus sign
650.Pq Dq Li +
651or a minus sign
652.Pq Dq Li - .
653A preceding plus sign means
654.Dq more than n ,
655a preceding minus sign means
656.Dq less than n
657and neither means
658.Dq exactly n .
659.Sh OPERATORS
660The primaries may be combined using the following operators.
661The operators are listed in order of decreasing precedence.
662.Pp
663.Bl -tag -width "( expression )" -compact
664.It Cm \&( Ar expression Cm \&)
665This evaluates to true if the parenthesized expression evaluates to
666true.
667.Pp
668.It Cm \&! Ar expression
669.It Cm -false Ar expression
670.It Cm -not Ar expression
671This is the unary
672.Tn NOT
673operator.
674It evaluates to true if the expression is false.
675.Pp
676.It Ar expression Cm -and Ar expression
677.It Ar expression expression
678The
679.Cm -and
680operator is the logical
681.Tn AND
682operator.
683As it is implied by the juxtaposition of two expressions it does not
684have to be specified.
685The expression evaluates to true if both expressions are true.
686The second expression is not evaluated if the first expression is false.
687.Pp
688.It Ar expression Cm -or Ar expression
689The
690.Cm -or
691operator is the logical
692.Tn OR
693operator.
694The expression evaluates to true if either the first or the second expression
695is true.
696The second expression is not evaluated if the first expression is true.
697.El
698.Pp
699All operands and primaries must be separate arguments to
700.Nm .
701Primaries which themselves take arguments expect each argument
702to be a separate argument to
703.Nm .
704.Sh EXAMPLES
705The following examples are shown as given to the shell:
706.Bl -tag -width indent
707.It Li "find / \e! -name \*q*.c\*q -print"
708Print out a list of all the files whose names do not end in
709.Pa .c .
710.It Li "find / -newer ttt -user wnj -print"
711Print out a list of all the files owned by user
712.Dq wnj
713that are newer
714than the file
715.Pa ttt .
716.It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
717Print out a list of all the files which are not both newer than
718.Pa ttt
719and owned by
720.Dq wnj .
721.It Li "find / \e( -newer ttt -or -user wnj \e) -print"
722Print out a list of all the files that are either owned by
723.Dq wnj
724or that are newer than
725.Pa ttt .
726.It Li "find . -newerct '1 minute ago' -print"
727Print out a list of all the files whose inode change time is more
728recent than the current time minus one minute.
729.El
730.Sh SEE ALSO
731.Xr chflags 1 ,
732.Xr chmod 1 ,
733.Xr cvs 1 ,
734.Xr locate 1 ,
735.Xr whereis 1 ,
736.Xr which 1 ,
737.Xr xargs 1 ,
738.Xr stat 2 ,
739.Xr fts 3 ,
740.Xr getgrent 3 ,
741.Xr getpwent 3 ,
742.Xr strmode 3 ,
743.Xr re_format 7 ,
744.Xr symlink 7
745.Sh STANDARDS
746The
747.Nm
748utility syntax is a superset of the syntax specified by the
749.St -p1003.2
750standard.
751.Pp
752All the single character options as well as the
753.Ic -iname , -inum , -iregex , -print0 , -delete , -ls ,
754and
755.Ic -regex
756primaries are extensions to
757.St -p1003.2 .
758.Pp
759Historically, the
760.Fl d , h
761and
762.Fl x
763options were implemented using the primaries
764.Ic -depth , -follow ,
765and
766.Ic -xdev .
767These primaries always evaluated to true.
768As they were really global variables that took effect before the traversal
769began, some legal expressions could have unexpected results.
770An example is the expression
771.Ic -print Cm -o Ic -depth .
772As
773.Ic -print
774always evaluates to true, the standard order of evaluation
775implies that
776.Ic -depth
777would never be evaluated.
778This is not the case.
779.Pp
780The operator
781.Cm -or
782was implemented as
783.Cm -o ,
784and the operator
785.Cm -and
786was implemented as
787.Cm -a .
788.Pp
789Historic implementations of the
790.Ic -exec
791and
792.Ic -ok
793primaries did not replace the string
794.Dq Li {}
795in the utility name or the
796utility arguments if it had preceding or following non-whitespace characters.
797This version replaces it no matter where in the utility name or arguments
798it appears.
799.Pp
800The
801.Fl E
802option was implemented on the analogy of
803.Xr grep 1
804and
805.Xr sed 1 .
806.Sh BUGS
807The special characters used by
808.Nm
809are also special characters to many shell programs.
810In particular, the characters
811.Dq Li * ,
812.Dq Li \&[ ,
813.Dq Li \&] ,
814.Dq Li \&? ,
815.Dq Li \&( ,
816.Dq Li \&) ,
817.Dq Li \&! ,
818.Dq Li \e
819and
820.Dq Li \&;
821may have to be escaped from the shell.
822.Pp
823As there is no delimiter separating options and file names or file
824names and the
825.Ar expression ,
826it is difficult to specify files named
827.Pa -xdev
828or
829.Pa \&! .
830These problems are handled by the
831.Fl f
832option and the
833.Xr getopt 3
834.Dq Fl Fl
835construct.
836.Pp
837The
838.Ic -delete
839primary does not interact well with other options that cause the file system
840tree traversal options to be changed.
841.Sh HISTORY
842A
843.Nm
844command appeared in
845.At v1 .
846