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