xref: /freebsd/usr.bin/find/find.1 (revision fd45b686f9d92f583366c75b22c04c7ee49709c0)
1.\" Copyright (c) 1990, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the Institute of Electrical and Electronics Engineers, Inc.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
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. 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.
18.\"
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
29.\" SUCH DAMAGE.
30.\"
31.Dd January 21, 2024
32.Dt FIND 1
33.Os
34.Sh NAME
35.Nm find
36.Nd walk a file hierarchy
37.Sh SYNOPSIS
38.Nm
39.Op Fl H | Fl L | Fl P
40.Op Fl EXdsx
41.Op Fl f Ar path
42.Ar path ...
43.Op Ar expression
44.Nm
45.Op Fl H | Fl L | Fl P
46.Op Fl EXdsx
47.Fl f Ar path
48.Op Ar path ...
49.Op Ar expression
50.Sh DESCRIPTION
51The
52.Nm
53utility recursively descends the directory tree for each
54.Ar path
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 following the
68.Ic -regex
69and
70.Ic -iregex
71primaries 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.
127.Pp
128This option is a BSD-specific equivalent of the
129.Ic -depth
130primary specified by
131.St -p1003.1-2001 .
132Refer to its description under
133.Sx PRIMARIES
134for more information.
135.It Fl f Ar path
136Add
137.Ar path
138to the list of paths that will be recursed into.
139This is useful when
140.Ar path
141begins with a character that would otherwise be interpreted as an
142.Ar expression ,
143namely
144.Dq Li "!" ,
145.Dq Li "("
146and
147.Dq Li - .
148.It Fl s
149Cause
150.Nm
151to traverse the file hierarchies in lexicographical order,
152i.e., alphabetical order within each directory.
153Note:
154.Ql find -s
155and
156.Ql "find | sort"
157may give different results.
158.Pp
159For example,
160.Ql find -s
161puts a directory
162.Ql Ar foo
163with all its contents before a directory
164.Ql Ar foo .
165but
166.Ql "find | sort"
167puts the directory name
168.Ql Ar foo .
169before any string like
170.Ql Ar foo/bar
171because
172.Ql .\&
173goes before
174.Ql /
175in ASCII.
176In locales other than
177.Ar C
178results may vary more due to collation differences.
179.It Fl x
180Prevent
181.Nm
182from descending into directories that have a device number different
183than that of the file from which the descent began.
184.Pp
185This option is equivalent to the deprecated
186.Ic -xdev
187primary.
188.El
189.Sh PRIMARIES
190All primaries which take a numeric argument allow the number to be
191preceded by a plus sign
192.Pq Dq Li +
193or a minus sign
194.Pq Dq Li - .
195A preceding plus sign means
196.Dq more than n ,
197a preceding minus sign means
198.Dq less than n
199and neither means
200.Dq exactly n .
201.Bl -tag -width indent
202.It Ic -Bmin Ar n
203True if the difference between the time of a file's inode creation
204and the time
205.Nm
206was started, rounded up to the next full minute, is
207.Ar n
208minutes.
209.It Ic -Bnewer Ar file
210Same as
211.Ic -newerBm .
212.It Ic -Btime Ar n Ns Op Cm smhdw
213If no units are specified, this primary evaluates to
214true if the difference between the time of a file's inode creation
215and 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 a file's inode creation
223and 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 -acl
232May be used in conjunction with other primaries to locate
233files with extended ACLs.
234See
235.Xr acl 3
236for more information.
237.It Ic -amin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
238True if the difference between the file last access time and the time
239.Nm
240was started, rounded up to the next full minute, is
241more than
242.Ar n
243.Pq + Ns Ar n ,
244less than
245.Ar n
246.Pq - Ns Ar n ,
247or exactly
248.Ar n
249minutes ago.
250.It Ic -anewer Ar file
251Same as
252.Ic -neweram .
253.It Ic -atime Ar n Ns Op Cm smhdw
254If no units are specified, this primary evaluates to
255true if the difference between the file last access time and the time
256.Nm
257was started, rounded up to the next full 24-hour period, is
258.Ar n
25924-hour periods.
260.Pp
261If units are specified, this primary evaluates to
262true if the difference between the file last access time and the time
263.Nm
264was started is exactly
265.Ar n
266units.
267Possible time units are as follows:
268.Pp
269.Bl -tag -width indent -compact
270.It Cm s
271second
272.It Cm m
273minute (60 seconds)
274.It Cm h
275hour (60 minutes)
276.It Cm d
277day (24 hours)
278.It Cm w
279week (7 days)
280.El
281.Pp
282Any number of units may be combined in one
283.Ic -atime
284argument, for example,
285.Dq Li "-atime -1h30m" .
286Units are probably only useful when used in conjunction with the
287.Cm +
288or
289.Cm -
290modifier.
291.It Ic -cmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
292True if the difference between the time of last change of file status
293information and the time
294.Nm
295was started, rounded up to the next full minute, is
296more than
297.Ar n
298.Pq + Ns Ar n ,
299less than
300.Ar n
301.Pq - Ns Ar n ,
302or exactly
303.Ar n
304minutes ago.
305.It Ic -cnewer Ar file
306Same as
307.Ic -newercm .
308.It Ic -ctime Ar n Ns Op Cm smhdw
309If no units are specified, this primary evaluates to
310true if the difference between the time of last change of file status
311information and the time
312.Nm
313was started, rounded up to the next full 24-hour period, is
314.Ar n
31524-hour periods.
316.Pp
317If units are specified, this primary evaluates to
318true if the difference between the time of last change of file status
319information and the time
320.Nm
321was started is exactly
322.Ar n
323units.
324Please refer to the
325.Ic -atime
326primary description for information on supported time units.
327.It Ic -d
328Non-portable, BSD-specific version of
329.Ic depth .
330GNU find implements this as a primary in mistaken emulation of
331.Fx
332.Nm .
333.It Ic -delete
334Delete found files and/or directories.
335Always returns true.
336This executes
337from the current working directory as
338.Nm
339recurses down the tree.
340It will not attempt to delete a filename with a
341.Dq Pa /
342character in its pathname relative to
343.Dq Pa \&.
344for security reasons.
345Depth-first traversal processing is implied by this option.
346The
347.Ic -delete
348primary will fail to delete a directory if it is not empty.
349Following symlinks is incompatible with this option.
350.Pp
351.Em WARNING :
352The
353.Ic -delete
354primary will immediately attempt to delete the current path when
355evaluated.
356Be mindful of its place in the expression; as a general rule, it
357should almost always come last.
358If in doubt, try running with
359.Ic -print
360in place of
361.Ic -delete
362first.
363See
364.Sx OPERATORS
365below for additional information on the order of evaluation.
366.It Ic -depth
367Always true;
368same as the non-portable
369.Fl d
370option.
371Cause
372.Nm
373to perform a depth-first traversal, i.e., directories
374are visited in post-order and all entries in a directory will be acted
375on before the directory itself.
376By default,
377.Nm
378visits directories in pre-order, i.e., before their contents.
379Note, the default is
380.Em not
381a breadth-first traversal.
382.Pp
383The
384.Ic -depth
385primary
386can be useful when
387.Nm
388is used with
389.Xr cpio 1
390to process files that are contained in directories with unusual permissions.
391It ensures that you have write permission while you are placing files in a
392directory, then sets the directory's permissions as the last thing.
393.It Ic -depth Ar n
394True if the depth of the file relative to the starting point of the traversal
395is
396.Ar n .
397.It Ic -empty
398True if the current file or directory is empty.
399.It Ic -exec Ar utility Oo Ar argument ... Oc Li \&;
400True if the program named
401.Ar utility
402returns a zero value as its exit status.
403Optional
404.Ar arguments
405may be passed to the utility.
406The expression must be terminated by a semicolon
407.Pq Dq Li \&; .
408If you invoke
409.Nm
410from a shell you may need to quote the semicolon if the shell would
411otherwise treat it as a control operator.
412If the string
413.Dq Li {}
414appears anywhere in the utility name or the
415arguments it is replaced by the pathname of the current file.
416.Ar Utility
417will be executed from the directory from which
418.Nm
419was executed.
420.Ar Utility
421and
422.Ar arguments
423are not subject to the further expansion of shell patterns
424and constructs.
425.It Ic -exec Ar utility Oo Ar argument ... Oc Li {} +
426Same as
427.Ic -exec ,
428except that
429.Dq Li {}
430is replaced with as many pathnames as possible for each invocation of
431.Ar utility .
432This behaviour is similar to that of
433.Xr xargs 1 .
434The primary always returns true;
435if at least one invocation of
436.Ar utility
437returns a non-zero exit status,
438.Nm
439will return a non-zero exit status.
440.It Ic -execdir Ar utility Oo Ar argument ... Oc Li \&;
441The
442.Ic -execdir
443primary is identical to the
444.Ic -exec
445primary with the exception that
446.Ar utility
447will be executed from the directory that holds
448the current file.
449The filename substituted for
450the string
451.Dq Li {}
452is not qualified.
453.It Ic -execdir Ar utility Oo Ar argument ... Oc Li {} +
454Same as
455.Ic -execdir ,
456except that
457.Dq Li {}
458is replaced with as many pathnames as possible for each invocation of
459.Ar utility .
460This behaviour is similar to that of
461.Xr xargs 1 .
462The primary always returns true;
463if at least one invocation of
464.Ar utility
465returns a non-zero exit status,
466.Nm
467will return a non-zero exit status.
468.It Ic -executable
469Matches files which are executable by the current user.
470This test makes use of the
471.Xr access 2
472system call, and so can be fooled by NFS servers which do UID mapping (or root-squashing).
473This is a GNU find extension.
474.It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags
475The flags are specified using symbolic names (see
476.Xr chflags 1 ) .
477Those with the
478.Qq Li no
479prefix (except
480.Qq Li nodump )
481are said to be
482.Ar notflags .
483Flags in
484.Ar flags
485are checked to be set, and flags in
486.Ar notflags
487are checked to be not set.
488Note that this is different from
489.Ic -perm ,
490which only allows the user to specify mode bits that are set.
491.Pp
492If flags are preceded by a dash
493.Pq Dq Li - ,
494this primary evaluates to true
495if at least all of the bits in
496.Ar flags
497and none of the bits in
498.Ar notflags
499are set in the file's flags bits.
500If flags are preceded by a plus
501.Pq Dq Li + ,
502this primary evaluates to true
503if any of the bits in
504.Ar flags
505is set in the file's flags bits,
506or any of the bits in
507.Ar notflags
508is not set in the file's flags bits.
509Otherwise,
510this primary evaluates to true
511if the bits in
512.Ar flags
513exactly match the file's flags bits,
514and none of the
515.Ar flags
516bits match those of
517.Ar notflags .
518.It Ic -fstype Ar type
519True if the file is contained in a file system of type
520.Ar type .
521The
522.Xr lsvfs 1
523command can be used to find out the types of file systems
524that are available on the system.
525In addition, there are two pseudo-types,
526.Dq Li local
527and
528.Dq Li rdonly .
529The former matches any file system physically mounted on the system where
530the
531.Nm
532is being executed and the latter matches any file system which is
533mounted read-only.
534.It Ic -gid Ar gname
535The same thing as
536.Ic -group Ar gname
537for compatibility with GNU find.
538GNU find imposes a restriction that
539.Ar gname
540is numeric, while
541.Nm
542does not.
543.It Ic -group Ar gname
544True if the file belongs to the group
545.Ar gname .
546If
547.Ar gname
548is numeric and there is no such group name, then
549.Ar gname
550is treated as a group ID.
551.It Ic -ignore_readdir_race
552Ignore errors because a file or a directory is deleted
553after reading the name from a directory.
554This option does not affect errors occurring on starting points.
555.It Ic -ilname Ar pattern
556Like
557.Ic -lname ,
558but the match is case insensitive.
559This is a GNU find extension.
560.It Ic -iname Ar pattern
561Like
562.Ic -name ,
563but the match is case insensitive.
564.It Ic -inum Ar n
565True if the file has inode number
566.Ar n .
567.It Ic -ipath Ar pattern
568Like
569.Ic -path ,
570but the match is case insensitive.
571.It Ic -iregex Ar pattern
572Like
573.Ic -regex ,
574but the match is case insensitive.
575.It Ic -iwholename Ar pattern
576The same thing as
577.Ic -ipath ,
578for GNU find compatibility.
579.It Ic -links Ar n
580True if the file has
581.Ar n
582links.
583.It Ic -lname Ar pattern
584Like
585.Ic -name ,
586but the contents of the symbolic link are matched instead of the file
587name.
588Note that this only matches broken symbolic links
589if symbolic links are being followed.
590This is a GNU find extension.
591.It Ic -ls
592This primary always evaluates to true.
593The following information for the current file is written to standard output:
594its inode number, size in 512-byte blocks, file permissions, number of hard
595links, owner, group, size in bytes, last modification time, and pathname.
596If the file is a block or character special file, the device number
597will be displayed instead of the size in bytes.
598If the file is a symbolic link, the pathname of the linked-to file will be
599displayed preceded by
600.Dq Li -> .
601The format is identical to that produced by
602.Bk -words
603.Dq Nm ls Fl dgils .
604.Ek
605.It Ic -maxdepth Ar n
606Always true; descend at most
607.Ar n
608directory levels below the command line arguments.
609If any
610.Ic -maxdepth
611primary is specified, it applies to the entire expression even if it would
612not normally be evaluated.
613.Dq Ic -maxdepth Li 0
614limits the whole search to the command line arguments.
615.It Ic -mindepth Ar n
616Always true; do not apply any tests or actions at levels less than
617.Ar n .
618If any
619.Ic -mindepth
620primary is specified, it applies to the entire expression even if it would
621not normally be evaluated.
622.Dq Ic -mindepth Li 1
623processes all but the command line arguments.
624.It Ic -mmin Oo Cm - Ns | Ns Cm + Oc Ns Ar n
625True if the difference between the file last modification time and the time
626.Nm
627was started, rounded up to the next full minute, is
628more than
629.Ar n
630.Pq + Ns Ar n ,
631less than
632.Ar n
633.Pq - Ns Ar n ,
634or exactly
635.Ar n
636minutes ago.
637.It Ic -mnewer Ar file
638Same as
639.Ic -newer .
640.It Ic -mount
641The same thing as
642.Ic -xdev ,
643for GNU find compatibility.
644.It Ic -mtime Ar n Ns Op Cm smhdw
645If no units are specified, this primary evaluates to
646true if the difference between the file last modification time and the time
647.Nm
648was started, rounded up to the next full 24-hour period, is
649.Ar n
65024-hour periods.
651.Pp
652If units are specified, this primary evaluates to
653true if the difference between the file last modification time and the time
654.Nm
655was started is exactly
656.Ar n
657units.
658Please refer to the
659.Ic -atime
660primary description for information on supported time units.
661.It Ic -name Ar pattern
662True if the last component of the pathname being examined matches
663.Ar pattern .
664Special shell pattern matching characters
665.Dq ( Li \&[ ,
666.Dq Li \&] ,
667.Dq Li * ,
668and
669.Dq Li \&? )
670may be used as part of
671.Ar pattern .
672These characters may be matched explicitly by escaping them with a
673backslash
674.Pq Dq Li \e .
675.It Ic -newer Ar file
676True if the current file has a more recent last modification time than
677.Ar file .
678.It Ic -newer Ns Ar X Ns Ar Y Ar file
679True if the current file has a more recent last access time
680.Pq Ar X Ns = Ns Cm a ,
681inode creation time
682.Pq Ar X Ns = Ns Cm B ,
683change time
684.Pq Ar X Ns = Ns Cm c ,
685or modification time
686.Pq Ar X Ns = Ns Cm m
687than the last access time
688.Pq Ar Y Ns = Ns Cm a ,
689inode creation time
690.Pq Ar Y Ns = Ns Cm B ,
691change time
692.Pq Ar Y Ns = Ns Cm c ,
693or modification time
694.Pq Ar Y Ns = Ns Cm m
695of
696.Ar file .
697In addition, if
698.Ar Y Ns = Ns Cm t ,
699then
700.Ar file
701is instead interpreted as a direct date specification of the form
702understood by ISO8601 or RFC822.
703Note that
704.Ic -newermm
705is equivalent to
706.Ic -newer .
707.It Ic -nogroup
708True if the file belongs to an unknown group.
709.It Ic -noignore_readdir_race
710Turn off the effect of
711.Ic -ignore_readdir_race .
712This is default behaviour.
713.It Ic -noleaf
714This option is for GNU find compatibility.
715In GNU find it disables an optimization not relevant to
716.Nm ,
717so it is ignored.
718.It Ic -nouser
719True if the file belongs to an unknown user.
720.It Ic -ok Ar utility Oo Ar argument ... Oc Li \&;
721The
722.Ic -ok
723primary is identical to the
724.Ic -exec
725primary with the exception that
726.Nm
727requests user affirmation for the execution of the
728.Ar utility
729by printing
730a message to the terminal and reading a response.
731If the response is not affirmative
732.Ql ( y
733in the
734.Dq Li POSIX
735locale),
736the command is not executed and the
737value of the
738.Ic -ok
739expression is false.
740.It Ic -okdir Ar utility Oo Ar argument ... Oc Li \&;
741The
742.Ic -okdir
743primary is identical to the
744.Ic -execdir
745primary with the same exception as described for the
746.Ic -ok
747primary.
748.It Ic -path Ar pattern
749True if the pathname being examined matches
750.Ar pattern .
751Special shell pattern matching characters
752.Dq ( Li \&[ ,
753.Dq Li \&] ,
754.Dq Li * ,
755and
756.Dq Li \&? )
757may be used as part of
758.Ar pattern .
759These characters may be matched explicitly by escaping them with a
760backslash
761.Pq Dq Li \e .
762Slashes
763.Pq Dq Li /
764are treated as normal characters and do not have to be
765matched explicitly.
766.It Ic -perm Oo Cm - Ns | Ns Cm + Ns | Ns Cm / Oc Ns Ar mode
767The
768.Ar mode
769may be either symbolic (see
770.Xr chmod 1 )
771or an octal number.
772If the
773.Ar mode
774is symbolic, a starting value of zero is assumed and the
775.Ar mode
776sets or clears permissions without regard to the process' file mode
777creation mask.
778If the
779.Ar mode
780is octal, only bits 07777
781.Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
782of the file's mode bits participate
783in the comparison.
784If the
785.Ar mode
786is preceded by a dash
787.Pq Dq Li - ,
788this primary evaluates to true
789if at least all of the bits in the
790.Ar mode
791are set in the file's mode bits.
792If the
793.Ar mode
794is preceded by a plus
795.Pq Dq Li +
796this primary evaluates to true
797if any of the bits in the
798.Ar mode
799are set in the file's mode bits.
800A slash
801.Pq Dq Li /
802is also accepted with the same meaning as plus for compatibility with GNU find.
803Otherwise, this primary evaluates to true if
804the bits in the
805.Ar mode
806exactly match the file's mode bits.
807Note, the first character of a symbolic mode may not be a dash
808.Pq Dq Li - .
809.It Ic -print
810This primary always evaluates to true.
811It prints the pathname of the current file to standard output.
812If none of
813.Ic -exec , -ls , -print0 ,
814or
815.Ic -ok
816is specified, the given expression shall be effectively replaced by
817.Cm \&( Ar "given expression" Cm \&) Ic -print .
818.It Ic -print0
819This primary always evaluates to true.
820It prints the pathname of the current file to standard output, followed by an
821ASCII
822.Dv NUL
823character (character code 0).
824.It Ic -prune
825This primary always evaluates to true.
826It causes
827.Nm
828to not descend into the current file.
829Note, the
830.Ic -prune
831primary has no effect if the
832.Fl d
833option was specified.
834.It Ic -quit
835Causes
836.Nm
837to terminate immediately.
838.It Ic -readable
839Matches files which are readable by the current user.
840This test makes use of the
841.Xr access 2
842system call, and so can be fooled by NFS servers which do UID mapping (or root-squashing).
843This is a GNU find extension.
844.It Ic -regex Ar pattern
845True if the whole path of the file matches
846.Ar pattern
847using regular expression.
848To match a file named
849.Dq Pa ./foo/xyzzy ,
850you can use the regular expression
851.Dq Li ".*/[xyz]*"
852or
853.Dq Li ".*/foo/.*" ,
854but not
855.Dq Li xyzzy
856or
857.Dq Li /foo/ .
858.It Ic -samefile Ar name
859True if the file is a hard link to
860.Ar name .
861If the command option
862.Ic -L
863is specified, it is also true if the file is a symbolic link and
864points to
865.Ar name .
866.It Ic -size Ar n Ns Op Cm ckMGTP
867True if the file's size, rounded up, in 512-byte blocks is
868.Ar n .
869If
870.Ar n
871is followed by a
872.Cm c ,
873then the primary is true if the
874file's size is
875.Ar n
876bytes (characters).
877Similarly if
878.Ar n
879is followed by a scale indicator then the file's size is compared to
880.Ar n
881scaled as:
882.Pp
883.Bl -tag -width indent -compact
884.It Cm k
885kilobytes (1024 bytes)
886.It Cm M
887megabytes (1024 kilobytes)
888.It Cm G
889gigabytes (1024 megabytes)
890.It Cm T
891terabytes (1024 gigabytes)
892.It Cm P
893petabytes (1024 terabytes)
894.El
895.It Ic -sparse
896True if the current file is sparse,
897i.e. has fewer blocks allocated than expected based on its size in bytes.
898This might also match files that have been compressed by the filesystem.
899.It Ic -type Ar t
900True if the file is of the specified type.
901Possible file types are as follows:
902.Pp
903.Bl -tag -width indent -compact
904.It Cm b
905block special
906.It Cm c
907character special
908.It Cm d
909directory
910.It Cm f
911regular file
912.It Cm l
913symbolic link
914.It Cm p
915FIFO
916.It Cm s
917socket
918.El
919.It Ic -uid Ar uname
920The same thing as
921.Ar -user Ar uname
922for compatibility with GNU find.
923GNU find imposes a restriction that
924.Ar uname
925is numeric, while
926.Nm
927does not.
928.It Ic -user Ar uname
929True if the file belongs to the user
930.Ar uname .
931If
932.Ar uname
933is numeric and there is no such user name, then
934.Ar uname
935is treated as a user ID.
936.It Ic -wholename Ar pattern
937The same thing as
938.Ic -path ,
939for GNU find compatibility.
940.It Ic -writable
941Matches files which are writable by the current user.
942This test makes use of the
943.Xr access 2
944system call, and so can be fooled by NFS servers which do UID mapping (or root-squashing).
945This is a GNU find extension.
946.El
947.Sh OPERATORS
948The primaries may be combined using the following operators.
949The operators are listed in order of decreasing precedence.
950.Pp
951.Bl -tag -width indent -compact
952.It Cm \&( Ar expression Cm \&)
953This evaluates to true if the parenthesized expression evaluates to
954true.
955.Pp
956.It Cm \&! Ar expression
957.It Cm -not Ar expression
958This is the unary
959.Tn NOT
960operator.
961It evaluates to true if the expression is false.
962.Pp
963.It Cm -false
964Always false.
965.It Cm -true
966Always true.
967.Pp
968.It Ar expression Cm -and Ar expression
969.It Ar expression expression
970The
971.Cm -and
972operator is the logical
973.Tn AND
974operator.
975As it is implied by the juxtaposition of two expressions it does not
976have to be specified.
977The expression evaluates to true if both expressions are true.
978The second expression is not evaluated if the first expression is false.
979.Pp
980.It Ar expression Cm -or Ar expression
981The
982.Cm -or
983operator is the logical
984.Tn OR
985operator.
986The expression evaluates to true if either the first or the second expression
987is true.
988The second expression is not evaluated if the first expression is true.
989.El
990.Pp
991All operands and primaries must be separate arguments to
992.Nm .
993Primaries which themselves take arguments expect each argument
994to be a separate argument to
995.Nm .
996.Sh ENVIRONMENT
997The
998.Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
999and
1000.Ev LC_TIME
1001environment variables affect the execution of the
1002.Nm
1003utility as described in
1004.Xr environ 7 .
1005.Sh EXAMPLES
1006The following examples are shown as given to the shell:
1007.Bl -tag -width indent
1008.It Li "find / \e! -name \*q*.c\*q -print"
1009Print out a list of all the files whose names do not end in
1010.Pa .c .
1011.It Li "find / -newer ttt -user wnj -print"
1012Print out a list of all the files owned by user
1013.Dq wnj
1014that are newer
1015than the file
1016.Pa ttt .
1017.It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
1018Print out a list of all the files which are not both newer than
1019.Pa ttt
1020and owned by
1021.Dq wnj .
1022.It Li "find / \e( -newer ttt -or -user wnj \e) -print"
1023Print out a list of all the files that are either owned by
1024.Dq wnj
1025or that are newer than
1026.Pa ttt .
1027.It Li "find / -newerct '1 minute ago' -print"
1028Print out a list of all the files whose inode change time is more
1029recent than the current time minus one minute.
1030.It Li "find / -type f -exec echo {} \e;"
1031Use the
1032.Xr echo 1
1033command to print out a list of all the files.
1034.It Li "find -L /usr/ports/packages -type l -exec rm -- {} +"
1035Delete all broken symbolic links in
1036.Pa /usr/ports/packages .
1037.It Li "find /usr/src -name CVS -prune -o -depth +6 -print"
1038Find files and directories that are at least seven levels deep
1039in the working directory
1040.Pa /usr/src .
1041.It Li "find /usr/src -name CVS -prune -o -mindepth 7 -print"
1042Is not equivalent to the previous example, since
1043.Ic -prune
1044is not evaluated below level seven.
1045.El
1046.Sh COMPATIBILITY
1047The
1048.Ic -follow
1049primary is deprecated; the
1050.Fl L
1051option should be used instead.
1052See the
1053.Sx STANDARDS
1054section below for details.
1055.Sh SEE ALSO
1056.Xr chflags 1 ,
1057.Xr chmod 1 ,
1058.Xr locate 1 ,
1059.Xr lsvfs 1 ,
1060.Xr whereis 1 ,
1061.Xr which 1 ,
1062.Xr xargs 1 ,
1063.Xr stat 2 ,
1064.Xr acl 3 ,
1065.Xr fts 3 ,
1066.Xr getgrent 3 ,
1067.Xr getpwent 3 ,
1068.Xr strmode 3 ,
1069.Xr ascii 7 ,
1070.Xr re_format 7 ,
1071.Xr symlink 7
1072.Sh STANDARDS
1073The
1074.Nm
1075utility syntax is a superset of the syntax specified by the
1076.St -p1003.1-2001
1077standard.
1078.Pp
1079All the single character options except
1080.Fl H
1081and
1082.Fl L
1083as well as
1084.Ic -amin , -anewer , -cmin , -cnewer , -delete , -empty , -fstype ,
1085.Ic -iname , -inum , -iregex , -ls , -maxdepth , -mindepth , -mmin ,
1086.Ic -not , -path , -print0 , -regex , -sparse
1087and all of the
1088.Fl B*
1089birthtime related primaries are extensions to
1090.St -p1003.1-2001 .
1091.Pp
1092Historically, the
1093.Fl d , L
1094and
1095.Fl x
1096options were implemented using the primaries
1097.Ic -depth , -follow ,
1098and
1099.Ic -xdev .
1100These primaries always evaluated to true.
1101As they were really global variables that took effect before the traversal
1102began, some legal expressions could have unexpected results.
1103An example is the expression
1104.Ic -print Cm -o Ic -depth .
1105As
1106.Ic -print
1107always evaluates to true, the standard order of evaluation
1108implies that
1109.Ic -depth
1110would never be evaluated.
1111This is not the case.
1112.Pp
1113The operator
1114.Cm -or
1115was implemented as
1116.Cm -o ,
1117and the operator
1118.Cm -and
1119was implemented as
1120.Cm -a .
1121.Pp
1122Historic implementations of the
1123.Ic -exec
1124and
1125.Ic -ok
1126primaries did not replace the string
1127.Dq Li {}
1128in the utility name or the
1129utility arguments if it had preceding or following non-whitespace characters.
1130This version replaces it no matter where in the utility name or arguments
1131it appears.
1132.Pp
1133The
1134.Fl E
1135option was inspired by the equivalent
1136.Xr grep 1
1137and
1138.Xr sed 1
1139options.
1140.Pp
1141The
1142.Ic -perm
1143primary accepts a leading slash
1144.Pq Dq Li /
1145as an alias for a leading plus
1146.Pq Dq Li +
1147for its argument as an extension of
1148.St -p1003.1-2001
1149to be compatible with GNU find.
1150.Sh HISTORY
1151A simple
1152.Nm
1153command appeared in
1154.At v1
1155and was removed in
1156.At v3 .
1157It was rewritten for
1158.At v5
1159and later be enhanced for the Programmer's Workbench (PWB).
1160These changes were later incorporated in
1161.At v7 .
1162.Sh BUGS
1163The special characters used by
1164.Nm
1165are also special characters to many shell programs.
1166In particular, the characters
1167.Dq Li * ,
1168.Dq Li \&[ ,
1169.Dq Li \&] ,
1170.Dq Li \&? ,
1171.Dq Li \&( ,
1172.Dq Li \&) ,
1173.Dq Li \&! ,
1174.Dq Li \e
1175and
1176.Dq Li \&;
1177may have to be escaped from the shell.
1178.Pp
1179As there is no delimiter separating options and file names or file
1180names and the
1181.Ar expression ,
1182it is difficult to specify files named
1183.Pa -xdev
1184or
1185.Pa \&! .
1186These problems are handled by the
1187.Fl f
1188option and the
1189.Xr getopt 3
1190.Dq Fl Fl
1191construct.
1192.Pp
1193The
1194.Ic -delete
1195primary does not interact well with other options that cause the file system
1196tree traversal options to be changed.
1197.Pp
1198The
1199.Ic -mindepth
1200and
1201.Ic -maxdepth
1202primaries are actually global options (as documented above).
1203They should
1204probably be replaced by options which look like options.
1205