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