Annotation of src/usr.bin/find/find.1, Revision 1.88
1.88 ! jmc 1: .\" $OpenBSD: find.1,v 1.87 2014/01/20 05:07:48 schwarze Exp $
1.1 deraadt 2: .\" Copyright (c) 1990, 1993
3: .\" The Regents of the University of California. All rights reserved.
4: .\"
5: .\" This code is derived from software contributed to Berkeley by
6: .\" the Institute of Electrical and Electronics Engineers, Inc.
7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
1.38 millert 16: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 17: .\" may be used to endorse or promote products derived from this software
18: .\" without specific prior written permission.
19: .\"
20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30: .\" SUCH DAMAGE.
31: .\"
32: .\" from: @(#)find.1 8.1 (Berkeley) 6/6/93
33: .\"
1.88 ! jmc 34: .Dd $Mdocdate: January 20 2014 $
1.1 deraadt 35: .Dt FIND 1
36: .Os
37: .Sh NAME
38: .Nm find
39: .Nd walk a file hierarchy
40: .Sh SYNOPSIS
41: .Nm find
1.48 millert 42: .Op Fl dHhLXx
1.43 jaredy 43: .Op Fl f Ar path
44: .Ar path ...\&
1.34 deraadt 45: .Op Ar expression
1.1 deraadt 46: .Sh DESCRIPTION
1.22 aaron 47: .Nm
1.1 deraadt 48: recursively descends the directory tree for each
1.43 jaredy 49: .Ar path
1.1 deraadt 50: listed, evaluating an
51: .Ar expression
1.22 aaron 52: (composed of the
53: .Dq primaries
54: and
1.52 otto 55: .Dq operators
1.22 aaron 56: listed below) in terms
1.12 millert 57: of each file in the tree.
1.34 deraadt 58: In the absence of an expression,
59: .Ic -print
60: is assumed.
1.66 jmc 61: If an expression is given,
62: but none of the primaries
63: .Ic -exec ,
64: .Ic -ls ,
65: .Ic -ok ,
66: .Ic -print ,
67: or
68: .Ic -print0
1.67 jmc 69: are specified, the given expression is effectively replaced by
1.66 jmc 70: .Cm \&( Ar given expression Cm \&)
71: .Ic -print .
1.1 deraadt 72: .Pp
73: The options are as follows:
74: .Bl -tag -width Ds
75: .It Fl d
1.16 aaron 76: Causes
1.22 aaron 77: .Nm
1.45 jmc 78: to visit directories in post-order
79: i.e. all entries in a directory will be acted on before the directory itself.
1.1 deraadt 80: By default,
1.22 aaron 81: .Nm
1.45 jmc 82: visits directories in pre-order i.e. before their contents.
1.43 jaredy 83: .It Fl f Ar path
1.16 aaron 84: Specifies a file hierarchy for
1.22 aaron 85: .Nm
1.1 deraadt 86: to traverse.
1.52 otto 87: File hierarchies may be specified without the
88: .Fl f
89: option if they are given immediately after any other options.
1.35 millert 90: .It Fl H
91: Causes the file information and file type (see
92: .Xr stat 2 )
93: returned for each symbolic link encountered on the command line to be
94: those of the file referenced by the link, not the link itself.
95: If the referenced file does not exist, the file information and type will
96: be for the link itself.
97: File information of all symbolic links not on
98: the command line is that of the link itself.
1.1 deraadt 99: .It Fl h
1.35 millert 100: An alias for the
101: .Fl L
102: option.
1.37 david 103: This option exists for backwards compatibility.
1.35 millert 104: .It Fl L
1.16 aaron 105: Causes the file information and file type (see
1.22 aaron 106: .Xr stat 2 )
1.1 deraadt 107: returned for each symbolic link to be those of the file referenced by the
108: link, not the link itself.
109: If the referenced file does not exist, the file information and type will
110: be for the link itself.
111: .It Fl X
1.16 aaron 112: Permit
1.1 deraadt 113: .Nm
114: to be safely used in conjunction with
115: .Xr xargs 1 .
1.87 schwarze 116: If a file name contains any of the delimiting characters used by xargs,
1.1 deraadt 117: a diagnostic message is displayed on standard error, and the file
118: is skipped.
1.22 aaron 119: The delimiting characters include single
120: .Pq Ql '
121: and double
122: .Pq Ql \&"
123: quotes, backslash
124: .Pq Ql \e ,
125: space, tab, and newline
126: .Pq Sq \en
127: characters.
1.79 schwarze 128: Consider using
1.4 deraadt 129: .Fl print0
1.79 schwarze 130: instead.
1.1 deraadt 131: .It Fl x
1.16 aaron 132: Prevents
1.22 aaron 133: .Nm
1.1 deraadt 134: from descending into directories that have a device number different
135: than that of the file from which the descent began.
136: .El
1.76 schwarze 137: .Pp
138: It is not an error to specify more than one of
139: the mutually exclusive options
140: .Fl H
141: and
142: .Fl L .
143: Where more than one of these options is specified,
144: the last option given overrides the others.
1.1 deraadt 145: .Sh PRIMARIES
1.84 jmc 146: .Bl -tag -width Ds -compact
1.22 aaron 147: .It Ic -amin Ar n
1.15 deraadt 148: True if the difference between the file last access time and the time
1.22 aaron 149: .Nm
1.20 aaron 150: was started, rounded up to the next full minute, is
1.15 deraadt 151: .Ar n
1.20 aaron 152: minutes.
1.84 jmc 153: .Pp
1.24 millert 154: .It Ic -anewer Ar file
155: True if the current file has a more recent last access time than
1.25 aaron 156: .Ar file .
1.84 jmc 157: .Pp
1.22 aaron 158: .It Ic -atime Ar n
1.1 deraadt 159: True if the difference between the file last access time and the time
1.22 aaron 160: .Nm
161: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 162: .Ar n
1.22 aaron 163: 24-hour periods.
1.84 jmc 164: .Pp
1.22 aaron 165: .It Ic -cmin Ar n
1.15 deraadt 166: True if the difference between the time of last change of file status
167: information and the time
1.22 aaron 168: .Nm
1.20 aaron 169: was started, rounded up to the next full minute, is
1.15 deraadt 170: .Ar n
1.20 aaron 171: minutes.
1.84 jmc 172: .Pp
1.24 millert 173: .It Ic -cnewer Ar file
174: True if the current file has a more recent last change time than
1.25 aaron 175: .Ar file .
1.84 jmc 176: .Pp
1.22 aaron 177: .It Ic -ctime Ar n
1.1 deraadt 178: True if the difference between the time of last change of file status
179: information and the time
1.22 aaron 180: .Nm
181: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 182: .Ar n
1.22 aaron 183: 24-hour periods.
1.84 jmc 184: .Pp
1.56 jmc 185: .It Ic -depth
1.61 jmc 186: This primary always evaluates to true.
1.56 jmc 187: The same as specifying the
188: .Fl d
189: option.
1.84 jmc 190: .Pp
1.8 tholo 191: .It Ic -empty
192: True if the current file or directory is empty.
1.84 jmc 193: .Pp
1.59 jmc 194: .It Xo
195: .Ic -exec Ar utility
196: .Op argument ...
197: .No ;
198: .Xc
1.83 pascal 199: .It Xo
200: .Ic -exec Ar utility
201: .Op argument ...
1.84 jmc 202: .No {} +
1.83 pascal 203: .Xc
204: Execute the specified
205: .Ar utility .
1.1 deraadt 206: Optional arguments may be passed to the utility.
1.22 aaron 207: The expression must be terminated by a semicolon
1.83 pascal 208: .Pq Ql \&;
209: or a plus sign
210: .Pq Ql \&+ .
211: .Pp
212: If terminated by a semicolon, the
213: .Ar utility
214: is executed once per path.
1.22 aaron 215: If the string
216: .Qq {}
217: appears anywhere in the utility name or the
1.1 deraadt 218: arguments it is replaced by the pathname of the current file.
1.83 pascal 219: .Pp
1.84 jmc 220: If terminated by a plus sign,
1.83 pascal 221: the pathnames for which the
222: primary is evaluated are aggregated into sets, and
1.16 aaron 223: .Ar utility
1.83 pascal 224: will be invoked once per set, similar to
225: .Xr xargs 1 .
1.84 jmc 226: If any invocation exits with a non-zero exit status, then
1.83 pascal 227: .Nm
228: will eventually do so as well, but this does not cause
1.22 aaron 229: .Nm
1.83 pascal 230: to exit early.
231: The string
1.84 jmc 232: .Qq {}
1.83 pascal 233: must appear, and must appear last.
234: Each set is limited to no more than 5,000 pathnames,
235: and is also limited such that the invocation of
1.63 otto 236: .Ar utility
1.83 pascal 237: does not exceed
238: .Dv ARG_MAX .
1.84 jmc 239: .Pp
1.59 jmc 240: .It Xo
241: .Ic -execdir Ar utility
242: .Op argument ...
243: .No ;
244: .Xc
1.85 sthen 245: Identical to the first form of the
1.10 millert 246: .Ic -exec
247: primary with the exception that
1.16 aaron 248: .Ar utility
1.10 millert 249: will be executed from the directory that holds
1.25 aaron 250: the current file.
251: The filename substituted for the string
1.22 aaron 252: .Qq {}
253: is not qualified.
1.84 jmc 254: .Pp
1.28 millert 255: .It Xo
256: .Ic -flags
1.65 jmc 257: .Oo - Oc Ns Ar flags
1.28 millert 258: .Xc
259: The
260: .Ar flags
261: are comma-separated symbolic file flags (see
262: .Xr chflags 1
263: for a list of valid flag names).
264: If the flags are preceded by a dash
1.54 jmc 265: .Pq Sq - ,
1.49 otto 266: this primary evaluates to true if at least all specified
267: .Ar flags
268: are set in the file's flags.
1.28 millert 269: If the flags are not preceded by a dash, this primary evaluates to true if the
270: flags specified exactly match those of the file.
1.84 jmc 271: .Pp
1.2 deraadt 272: .It Ic -follow
1.61 jmc 273: This primary always evaluates to true.
1.56 jmc 274: The same as specifying the
1.86 halex 275: .Fl L
1.56 jmc 276: option.
1.84 jmc 277: .Pp
1.22 aaron 278: .It Ic -fstype Ar type
1.1 deraadt 279: True if the file is contained in a file system of type
280: .Ar type .
1.22 aaron 281: Two special file system types are recognized:
282: .Dq local
283: and
284: .Dq rdonly .
1.1 deraadt 285: These do not describe actual file system types;
286: the former matches any file system physically mounted on the system where
1.22 aaron 287: .Nm
288: is being executed whereas the latter matches any file system which is
1.1 deraadt 289: mounted read-only.
1.84 jmc 290: .Pp
1.22 aaron 291: .It Ic -group Ar gname
1.1 deraadt 292: True if the file belongs to the group
1.25 aaron 293: .Ar gname .
1.1 deraadt 294: If
295: .Ar gname
296: is numeric and there is no such group name, then
297: .Ar gname
1.16 aaron 298: is treated as a group ID.
1.84 jmc 299: .Pp
1.27 deraadt 300: .It Ic -iname Ar pattern
1.77 schwarze 301: Identical to the
302: .Ic -name
303: primary except that the matching is done in a case insensitive manner.
1.84 jmc 304: .Pp
1.22 aaron 305: .It Ic -inum Ar n
1.1 deraadt 306: True if the file has inode number
1.25 aaron 307: .Ar n .
1.84 jmc 308: .Pp
1.22 aaron 309: .It Ic -links Ar n
1.1 deraadt 310: True if the file has
311: .Ar n
312: links.
1.84 jmc 313: .Pp
1.1 deraadt 314: .It Ic -ls
315: This primary always evaluates to true.
316: The following information for the current file is written to standard output:
1.22 aaron 317: its inode number, size in 512-byte blocks, file permissions, number of hard
1.1 deraadt 318: links, owner, group, size in bytes, last modification time, and pathname.
319: If the file is a block or character special file, the major and minor numbers
320: will be displayed instead of the size in bytes.
1.22 aaron 321: If the file is a symbolic link, the pathname of the linked-to file will be
322: displayed preceded by
1.54 jmc 323: .Dq -\*(Gt .
1.22 aaron 324: The format is identical to that produced by
1.71 jmc 325: .Dq ls -dils .
1.84 jmc 326: .Pp
1.6 tholo 327: .It Ic -maxdepth Ar n
1.7 tholo 328: True if the current search depth is less than or equal to what is specified in
329: .Ar n .
1.84 jmc 330: .Pp
1.7 tholo 331: .It Ic -mindepth Ar n
332: True if the current search depth is at least what is specified in
1.6 tholo 333: .Ar n .
1.84 jmc 334: .Pp
1.22 aaron 335: .It Ic -mmin Ar n
1.15 deraadt 336: True if the difference between the file last modification time and the time
1.22 aaron 337: .Nm
1.20 aaron 338: was started, rounded up to the next full minute, is
1.15 deraadt 339: .Ar n
1.20 aaron 340: minutes.
1.84 jmc 341: .Pp
1.22 aaron 342: .It Ic -mtime Ar n
1.1 deraadt 343: True if the difference between the file last modification time and the time
1.22 aaron 344: .Nm
345: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 346: .Ar n
1.22 aaron 347: 24-hour periods.
1.84 jmc 348: .Pp
1.22 aaron 349: .It Ic -name Ar pattern
1.1 deraadt 350: True if the last component of the pathname being examined matches
1.77 schwarze 351: .Ar pattern ,
352: which may use any of the special characters documented in
353: .Xr glob 7 .
1.84 jmc 354: .Pp
1.22 aaron 355: .It Ic -newer Ar file
1.1 deraadt 356: True if the current file has a more recent last modification time than
1.25 aaron 357: .Ar file .
1.84 jmc 358: .Pp
1.44 jmc 359: .It Ic -nogroup
360: True if the file belongs to an unknown group.
1.84 jmc 361: .Pp
1.1 deraadt 362: .It Ic -nouser
363: True if the file belongs to an unknown user.
1.84 jmc 364: .Pp
1.60 jmc 365: .It Xo
366: .Ic -ok Ar utility
367: .Op argument ...
368: .No ;
369: .Xc
1.22 aaron 370: Identical to the
371: .Ic -exec
372: primary with the exception that
373: .Nm
374: requests user affirmation for the execution of
375: .Ar utility
376: by printing
377: a message to the terminal and reading a response.
378: If the response is other than
379: .Sq y
380: the command is not executed and the
381: value of the
1.54 jmc 382: .Ic ok
1.22 aaron 383: expression is false.
1.84 jmc 384: .Pp
1.22 aaron 385: .It Ic -path Ar pattern
1.1 deraadt 386: True if the pathname being examined matches
1.77 schwarze 387: .Ar pattern ,
388: which may use any of the special characters documented in
389: .Xr glob 7 .
1.22 aaron 390: Slashes
391: .Pq Ql /
392: are treated as normal characters and do not have to be
1.1 deraadt 393: matched explicitly.
1.84 jmc 394: .Pp
1.21 aaron 395: .It Xo
396: .Ic -perm
1.65 jmc 397: .Oo - Oc Ns Ar mode
1.21 aaron 398: .Xc
1.1 deraadt 399: The
400: .Ar mode
401: may be either symbolic (see
1.25 aaron 402: .Xr chmod 1 )
1.1 deraadt 403: or an octal number.
404: If the mode is symbolic, a starting value of zero is assumed and the
1.16 aaron 405: mode sets or clears permissions without regard to the process's file mode
1.1 deraadt 406: creation mask.
407: If the mode is octal, only bits 07777
1.64 jmc 408: .Po
1.70 kili 409: .Dv S_ISUID \*(Ba S_ISGID \*(Ba S_ISTXT \*(Ba
1.64 jmc 410: .Dv S_IRWXU \*(Ba S_IRWXG \*(Ba S_IRWXO
411: .Pc
1.1 deraadt 412: of the file's mode bits participate
413: in the comparison.
1.22 aaron 414: If the mode is preceded by a dash
1.54 jmc 415: .Pq Sq - ,
1.22 aaron 416: this primary evaluates to true
1.1 deraadt 417: if at least all of the bits in the mode are set in the file's mode bits.
1.22 aaron 418: If the mode is not preceded by a dash, this primary evaluates to
1.16 aaron 419: true if the bits in the mode exactly match the file's mode bits.
1.22 aaron 420: Note, the first character of a symbolic mode may not be a dash.
1.84 jmc 421: .Pp
1.1 deraadt 422: .It Ic -print
423: This primary always evaluates to true.
424: It prints the pathname of the current file to standard output, followed
1.22 aaron 425: by a newline
426: .Pq Ql \en
427: character.
1.84 jmc 428: .Pp
1.1 deraadt 429: .It Ic -print0
430: This primary always evaluates to true.
431: It prints the pathname of the current file to standard output, followed
1.79 schwarze 432: by a null character, suitable for use with the
433: .Fl 0
434: option to
435: .Xr xargs 1 .
1.84 jmc 436: .Pp
1.1 deraadt 437: .It Ic -prune
438: This primary always evaluates to true.
439: It causes
1.22 aaron 440: .Nm
1.1 deraadt 441: to not descend into the current file.
442: Note, the
443: .Ic -prune
444: primary has no effect if the
445: .Fl d
446: option was specified.
1.84 jmc 447: .Pp
1.22 aaron 448: .It Ic -size Ar n Ns Op Cm c
449: True if the file's size, rounded up, in 512-byte blocks is
1.25 aaron 450: .Ar n .
1.1 deraadt 451: If
452: .Ar n
1.22 aaron 453: is followed by a
454: .Sq c ,
455: then the primary is true if the
1.1 deraadt 456: file's size is
457: .Ar n
458: bytes.
1.84 jmc 459: .Pp
1.22 aaron 460: .It Ic -type Ar t
1.1 deraadt 461: True if the file is of the specified type.
462: Possible file types are as follows:
463: .Pp
464: .Bl -tag -width flag -offset indent -compact
465: .It Cm b
466: block special
467: .It Cm c
468: character special
469: .It Cm d
470: directory
471: .It Cm f
472: regular file
473: .It Cm l
474: symbolic link
475: .It Cm p
476: FIFO
477: .It Cm s
478: socket
479: .El
480: .Pp
1.22 aaron 481: .It Ic -user Ar uname
1.1 deraadt 482: True if the file belongs to the user
1.25 aaron 483: .Ar uname .
1.1 deraadt 484: If
485: .Ar uname
486: is numeric and there is no such user name, then
487: .Ar uname
1.16 aaron 488: is treated as a user ID.
1.84 jmc 489: .Pp
1.56 jmc 490: .It Ic -xdev
1.61 jmc 491: This primary always evaluates to true.
1.56 jmc 492: The same as specifying the
493: .Fl x
494: option.
1.1 deraadt 495: .El
496: .Pp
497: All primaries which take a numeric argument allow the number to be
1.22 aaron 498: preceded by a plus sign
499: .Pq Ql +
500: or a minus sign
1.54 jmc 501: .Pq Ql - .
1.22 aaron 502: A preceding plus sign means
503: .Dq more than n ,
504: a preceding minus sign means
505: .Dq less than n ,
506: and neither means
507: .Dq exactly n .
1.74 jmc 508: Exceptions are the primaries
509: .Ic mindepth
510: and
511: .Ic maxdepth .
1.1 deraadt 512: .Sh OPERATORS
513: The primaries may be combined using the following operators.
514: The operators are listed in order of decreasing precedence.
1.47 jmc 515: .Pp
516: .Bl -tag -width "(expression)" -compact
1.51 jmc 517: .It Cm \&( Ar expression Cm \&)
1.1 deraadt 518: This evaluates to true if the parenthesized expression evaluates to
519: true.
520: .Pp
1.51 jmc 521: .It Cm \&! Ar expression
1.1 deraadt 522: This is the unary
523: .Tn NOT
524: operator.
525: It evaluates to true if the expression is false.
526: .Pp
1.22 aaron 527: .It Ar expression Cm -and Ar expression
528: .It Ar expression expression
1.1 deraadt 529: The
530: .Cm -and
531: operator is the logical
532: .Tn AND
533: operator.
534: As it is implied by the juxtaposition of two expressions it does not
535: have to be specified.
536: The expression evaluates to true if both expressions are true.
537: The second expression is not evaluated if the first expression is false.
538: .Pp
1.22 aaron 539: .It Ar expression Cm -or Ar expression
1.1 deraadt 540: The
541: .Cm -or
542: operator is the logical
543: .Tn OR
544: operator.
545: The expression evaluates to true if either the first or the second expression
546: is true.
547: The second expression is not evaluated if the first expression is true.
548: .El
549: .Pp
1.53 otto 550: Operators, primaries, and arguments to primaries must be separate
551: arguments to
552: .Nm find ,
553: i.e. they should be separated by whitespace.
1.81 jmc 554: .Sh EXIT STATUS
555: The
556: .Nm
557: utility exits with a value of 0 on successful traversal of all path operands
558: or with a value \*(Gt0 if an error occurred.
1.1 deraadt 559: .Sh EXAMPLES
1.62 jmc 560: Print out a list of all the files whose names end in
1.43 jaredy 561: .Dq \&.c :
562: .Pp
1.62 jmc 563: .Dl "$ find / -name '*.c'"
1.43 jaredy 564: .Pp
1.22 aaron 565: Print out a list of all the files which are not both newer than
566: .Dq ttt
567: and owned by
1.43 jaredy 568: .Dq wnj :
569: .Pp
1.62 jmc 570: .Dl "$ find / \e! \e( -newer ttt -user wnj \e)"
1.43 jaredy 571: .Pp
572: Print out a list of all core files on local file systems:
573: .Pp
1.88 ! jmc 574: .Dl "$ find / \e! -fstype local -prune -o -name '*.core'"
1.46 jmc 575: .Pp
576: Find all files in
577: .Pa /usr/src
578: ending in a dot and single digit, but skip directory
579: .Pa /usr/src/gnu :
580: .Pp
1.88 ! jmc 581: .Dl "$ find /usr/src -path /usr/src/gnu -prune -o -name \e*.[0-9]"
1.62 jmc 582: .Pp
1.79 schwarze 583: Find and remove all *.jpg and *.gif files under the current working
584: directory:
1.62 jmc 585: .Pp
1.88 ! jmc 586: .Dl "$ find . \e( -name \e*.jpg -o -name \e*.gif \e) -exec rm {} \e;"
1.63 otto 587: or
1.88 ! jmc 588: .Dl "$ find . \e( -name \e*.jpg -o -name \e*.gif \e) -print0 | xargs -0r rm"
1.1 deraadt 589: .Sh SEE ALSO
1.29 millert 590: .Xr chflags 1 ,
1.1 deraadt 591: .Xr chmod 1 ,
592: .Xr locate 1 ,
1.77 schwarze 593: .Xr ls 1 ,
1.23 aaron 594: .Xr whereis 1 ,
595: .Xr which 1 ,
1.41 millert 596: .Xr xargs 1 ,
1.1 deraadt 597: .Xr stat 2 ,
598: .Xr fts 3 ,
1.77 schwarze 599: .Xr glob 7 ,
1.1 deraadt 600: .Xr symlink 7
601: .Sh STANDARDS
602: The
1.22 aaron 603: .Nm
1.68 jmc 604: utility is compliant with the
1.72 jmc 605: .St -p1003.1-2008
1.68 jmc 606: specification.
1.1 deraadt 607: .Pp
1.55 jmc 608: The options
1.88 ! jmc 609: .Op Fl dfhXx ,
! 610: primaries
1.18 deraadt 611: .Ic -amin ,
1.55 jmc 612: .Ic -anewer ,
1.18 deraadt 613: .Ic -cmin ,
1.55 jmc 614: .Ic -cnewer ,
1.9 tholo 615: .Ic -empty ,
1.55 jmc 616: .Ic -execdir ,
617: .Ic -flags ,
1.1 deraadt 618: .Ic -follow ,
619: .Ic -fstype ,
1.27 deraadt 620: .Ic -iname ,
1.2 deraadt 621: .Ic -inum ,
1.9 tholo 622: .Ic -ls ,
623: .Ic -maxdepth ,
1.13 deraadt 624: .Ic -mindepth ,
1.55 jmc 625: .Ic -mmin ,
1.1 deraadt 626: and
1.88 ! jmc 627: .Ic -print0 ,
! 628: and operators
! 629: .Fl or
! 630: and
! 631: .Fl and ,
1.68 jmc 632: are extensions to that specification.
1.1 deraadt 633: .Pp
634: Historically, the
635: .Fl d ,
1.86 halex 636: .Fl L ,
1.1 deraadt 637: and
638: .Fl x
1.14 deraadt 639: options were implemented using the primaries
640: .Ic -depth ,
641: .Ic -follow ,
642: and
643: .Ic -xdev .
1.1 deraadt 644: These primaries always evaluated to true.
645: As they were really global variables that took effect before the traversal
646: began, some legal expressions could have unexpected results.
1.22 aaron 647: An example is the expression
1.54 jmc 648: .Dq -print -o -depth .
1.22 aaron 649: As
1.54 jmc 650: .Cm -print
1.22 aaron 651: always evaluates to true, the standard order of evaluation
652: implies that
1.54 jmc 653: .Cm -depth
1.22 aaron 654: would never be evaluated.
1.1 deraadt 655: This is not the case.
656: .Pp
657: Historic implementations of the
658: .Ic -exec
659: and
660: .Ic -ok
1.22 aaron 661: primaries did not replace the string
662: .Qq {}
663: in the utility name or the
1.1 deraadt 664: utility arguments if it had preceding or following non-whitespace characters.
665: This version replaces it no matter where in the utility name or arguments
666: it appears.
1.30 aaron 667: .Sh HISTORY
668: A
669: .Nm
670: command appeared in
671: .At v1 .
1.50 jmc 672: .Sh CAVEATS
1.1 deraadt 673: The special characters used by
1.22 aaron 674: .Nm
1.1 deraadt 675: are also special characters to many shell programs.
1.22 aaron 676: In particular, the characters
677: .Ql * ,
1.78 schwarze 678: .Ql \&[ ,
1.22 aaron 679: .Ql \&] ,
1.40 jmc 680: .Ql \&? ,
1.78 schwarze 681: .Ql \&( ,
1.22 aaron 682: .Ql \&) ,
1.40 jmc 683: .Ql \&! ,
1.22 aaron 684: .Ql \e ,
685: and
686: .Ql \&;
687: may have to be escaped from the shell.
1.79 schwarze 688: .Pp
1.82 schwarze 689: As file names may contain whitespace and shell metacharacters,
690: passing the output of
1.79 schwarze 691: .Nm
692: to other programs requires some care:
693: .Pp
694: .Dl "$ find . -name \e*.jpg | xargs rm"
695: or
696: .Dl "$ rm `find . -name \e*.jpg`"
697: .Pp
698: would, given files
699: .Dq important\ .jpg
700: and
701: .Dq important ,
702: remove
703: .Dq important .
704: Use the
705: .Ic -print0
706: or
707: .Ic -exec
708: primaries instead.
1.1 deraadt 709: .Pp
710: As there is no delimiter separating options and file names or file
711: names and the
712: .Ar expression ,
1.22 aaron 713: it is difficult to specify files named
714: .Dq -xdev
715: or
1.65 jmc 716: .Sq \&! .
1.1 deraadt 717: These problems are handled by the
718: .Fl f
719: option and the
720: .Xr getopt 3
1.65 jmc 721: .Sq --
1.22 aaron 722: construct.