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