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