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