Annotation of src/usr.bin/find/find.1, Revision 1.101
1.101 ! naddy 1: .\" $OpenBSD: find.1,v 1.100 2021/03/07 15:25:15 jsg 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.101 ! naddy 34: .Dd $Mdocdate: March 7 2021 $
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
1.91 schwarze 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
1.94 tb 63: .Ic -delete ,
1.66 jmc 64: .Ic -exec ,
1.94 tb 65: .Ic -execdir ,
1.66 jmc 66: .Ic -ls ,
67: .Ic -ok ,
68: .Ic -print ,
69: or
70: .Ic -print0
1.67 jmc 71: are specified, the given expression is effectively replaced by
1.66 jmc 72: .Cm \&( Ar given expression Cm \&)
73: .Ic -print .
1.1 deraadt 74: .Pp
75: The options are as follows:
76: .Bl -tag -width Ds
77: .It Fl d
1.16 aaron 78: Causes
1.22 aaron 79: .Nm
1.45 jmc 80: to visit directories in post-order
81: i.e. all entries in a directory will be acted on before the directory itself.
1.1 deraadt 82: By default,
1.22 aaron 83: .Nm
1.45 jmc 84: visits directories in pre-order i.e. before their contents.
1.43 jaredy 85: .It Fl f Ar path
1.16 aaron 86: Specifies a file hierarchy for
1.22 aaron 87: .Nm
1.1 deraadt 88: to traverse.
1.52 otto 89: File hierarchies may be specified without the
90: .Fl f
91: option if they are given immediately after any other options.
1.35 millert 92: .It Fl H
93: Causes the file information and file type (see
94: .Xr stat 2 )
95: returned for each symbolic link encountered on the command line to be
96: those of the file referenced by the link, not the link itself.
97: If the referenced file does not exist, the file information and type will
98: be for the link itself.
99: File information of all symbolic links not on
100: the command line is that of the link itself.
1.1 deraadt 101: .It Fl h
1.35 millert 102: An alias for the
103: .Fl L
104: option.
1.37 david 105: This option exists for backwards compatibility.
1.35 millert 106: .It Fl L
1.16 aaron 107: Causes the file information and file type (see
1.22 aaron 108: .Xr stat 2 )
1.1 deraadt 109: returned for each symbolic link to be those of the file referenced by the
110: link, not the link itself.
111: If the referenced file does not exist, the file information and type will
112: be for the link itself.
113: .It Fl X
1.16 aaron 114: Permit
1.1 deraadt 115: .Nm
116: to be safely used in conjunction with
117: .Xr xargs 1 .
1.87 schwarze 118: If a file name contains any of the delimiting characters used by xargs,
1.1 deraadt 119: a diagnostic message is displayed on standard error, and the file
120: is skipped.
1.22 aaron 121: The delimiting characters include single
122: .Pq Ql '
123: and double
124: .Pq Ql \&"
125: quotes, backslash
126: .Pq Ql \e ,
127: space, tab, and newline
128: .Pq Sq \en
129: characters.
1.79 schwarze 130: Consider using
1.4 deraadt 131: .Fl print0
1.79 schwarze 132: instead.
1.1 deraadt 133: .It Fl x
1.16 aaron 134: Prevents
1.22 aaron 135: .Nm
1.1 deraadt 136: from descending into directories that have a device number different
137: than that of the file from which the descent began.
138: .El
1.76 schwarze 139: .Pp
140: It is not an error to specify more than one of
141: the mutually exclusive options
142: .Fl H
143: and
144: .Fl L .
145: Where more than one of these options is specified,
146: the last option given overrides the others.
1.1 deraadt 147: .Sh PRIMARIES
1.84 jmc 148: .Bl -tag -width Ds -compact
1.22 aaron 149: .It Ic -amin Ar n
1.15 deraadt 150: True if the difference between the file last access time and the time
1.22 aaron 151: .Nm
1.20 aaron 152: was started, rounded up to the next full minute, is
1.15 deraadt 153: .Ar n
1.20 aaron 154: minutes.
1.84 jmc 155: .Pp
1.24 millert 156: .It Ic -anewer Ar file
157: True if the current file has a more recent last access time than
1.25 aaron 158: .Ar file .
1.84 jmc 159: .Pp
1.22 aaron 160: .It Ic -atime Ar n
1.1 deraadt 161: True if the difference between the file last access time and the time
1.22 aaron 162: .Nm
163: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 164: .Ar n
1.22 aaron 165: 24-hour periods.
1.84 jmc 166: .Pp
1.22 aaron 167: .It Ic -cmin Ar n
1.15 deraadt 168: True if the difference between the time of last change of file status
169: information and the time
1.22 aaron 170: .Nm
1.20 aaron 171: was started, rounded up to the next full minute, is
1.15 deraadt 172: .Ar n
1.20 aaron 173: minutes.
1.84 jmc 174: .Pp
1.24 millert 175: .It Ic -cnewer Ar file
176: True if the current file has a more recent last change time than
1.25 aaron 177: .Ar file .
1.84 jmc 178: .Pp
1.22 aaron 179: .It Ic -ctime Ar n
1.1 deraadt 180: True if the difference between the time of last change of file status
181: information and the time
1.22 aaron 182: .Nm
183: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 184: .Ar n
1.22 aaron 185: 24-hour periods.
1.84 jmc 186: .Pp
1.92 tedu 187: .It Ic -delete
1.93 jmc 188: Delete found files and directories.
1.92 tedu 189: Always returns true.
190: This executes
191: from the current working directory as
192: .Nm
193: recurses down the tree.
194: It will not attempt to delete a filename with a
1.93 jmc 195: .Sq Pa /
1.92 tedu 196: character in its pathname relative to
1.93 jmc 197: .Sq Pa \&.
1.92 tedu 198: for security reasons.
199: Depth-first traversal processing is implied by this option.
200: The
201: .Ic -delete
202: primary will fail to delete a directory if it is not empty.
203: Following symlinks is incompatible with this option.
1.93 jmc 204: .Pp
1.56 jmc 205: .It Ic -depth
1.61 jmc 206: This primary always evaluates to true.
1.56 jmc 207: The same as specifying the
208: .Fl d
209: option.
1.84 jmc 210: .Pp
1.8 tholo 211: .It Ic -empty
212: True if the current file or directory is empty.
1.84 jmc 213: .Pp
1.89 jmc 214: .It Ic -exec Ar utility Oo Ar argument ... Oc \&;
215: .It Ic -exec Ar utility Oo Ar argument ... Oc {} +
1.83 pascal 216: Execute the specified
217: .Ar utility .
1.1 deraadt 218: Optional arguments may be passed to the utility.
1.22 aaron 219: The expression must be terminated by a semicolon
1.83 pascal 220: .Pq Ql \&;
221: or a plus sign
222: .Pq Ql \&+ .
223: .Pp
224: If terminated by a semicolon, the
225: .Ar utility
226: is executed once per path.
1.95 jmc 227: This form of the primary evaluates to true if
228: .Ar utility
229: exits with a zero exit status.
1.22 aaron 230: If the string
231: .Qq {}
232: appears anywhere in the utility name or the
1.101 ! naddy 233: arguments, it is replaced by the pathname of the current file.
1.83 pascal 234: .Pp
1.84 jmc 235: If terminated by a plus sign,
1.83 pascal 236: the pathnames for which the
237: primary is evaluated are aggregated into sets, and
1.16 aaron 238: .Ar utility
1.83 pascal 239: will be invoked once per set, similar to
240: .Xr xargs 1 .
1.95 jmc 241: This form of the primary always evaluates to true.
1.84 jmc 242: If any invocation exits with a non-zero exit status, then
1.83 pascal 243: .Nm
244: will eventually do so as well, but this does not cause
1.22 aaron 245: .Nm
1.83 pascal 246: to exit early.
247: The string
1.84 jmc 248: .Qq {}
1.83 pascal 249: must appear, and must appear last.
250: Each set is limited to no more than 5,000 pathnames,
251: and is also limited such that the invocation of
1.63 otto 252: .Ar utility
1.83 pascal 253: does not exceed
254: .Dv ARG_MAX .
1.84 jmc 255: .Pp
1.89 jmc 256: .It Ic -execdir Ar utility Oo Ar argument ... Oc \&;
1.85 sthen 257: Identical to the first form of the
1.10 millert 258: .Ic -exec
259: primary with the exception that
1.16 aaron 260: .Ar utility
1.10 millert 261: will be executed from the directory that holds
1.25 aaron 262: the current file.
263: The filename substituted for the string
1.22 aaron 264: .Qq {}
265: is not qualified.
1.84 jmc 266: .Pp
1.28 millert 267: .It Xo
268: .Ic -flags
1.65 jmc 269: .Oo - Oc Ns Ar flags
1.28 millert 270: .Xc
271: The
272: .Ar flags
273: are comma-separated symbolic file flags (see
274: .Xr chflags 1
275: for a list of valid flag names).
276: If the flags are preceded by a dash
1.54 jmc 277: .Pq Sq - ,
1.49 otto 278: this primary evaluates to true if at least all specified
279: .Ar flags
280: are set in the file's flags.
1.28 millert 281: If the flags are not preceded by a dash, this primary evaluates to true if the
282: flags specified exactly match those of the file.
1.84 jmc 283: .Pp
1.2 deraadt 284: .It Ic -follow
1.61 jmc 285: This primary always evaluates to true.
1.56 jmc 286: The same as specifying the
1.86 halex 287: .Fl L
1.56 jmc 288: option.
1.84 jmc 289: .Pp
1.22 aaron 290: .It Ic -fstype Ar type
1.1 deraadt 291: True if the file is contained in a file system of type
292: .Ar type .
1.22 aaron 293: Two special file system types are recognized:
294: .Dq local
295: and
296: .Dq rdonly .
1.1 deraadt 297: These do not describe actual file system types;
298: the former matches any file system physically mounted on the system where
1.22 aaron 299: .Nm
300: is being executed whereas the latter matches any file system which is
1.1 deraadt 301: mounted read-only.
1.84 jmc 302: .Pp
1.22 aaron 303: .It Ic -group Ar gname
1.1 deraadt 304: True if the file belongs to the group
1.25 aaron 305: .Ar gname .
1.1 deraadt 306: If
307: .Ar gname
308: is numeric and there is no such group name, then
309: .Ar gname
1.16 aaron 310: is treated as a group ID.
1.84 jmc 311: .Pp
1.27 deraadt 312: .It Ic -iname Ar pattern
1.77 schwarze 313: Identical to the
314: .Ic -name
315: primary except that the matching is done in a case insensitive manner.
1.84 jmc 316: .Pp
1.22 aaron 317: .It Ic -inum Ar n
1.1 deraadt 318: True if the file has inode number
1.25 aaron 319: .Ar n .
1.84 jmc 320: .Pp
1.22 aaron 321: .It Ic -links Ar n
1.1 deraadt 322: True if the file has
323: .Ar n
324: links.
1.84 jmc 325: .Pp
1.1 deraadt 326: .It Ic -ls
327: This primary always evaluates to true.
328: The following information for the current file is written to standard output:
1.22 aaron 329: its inode number, size in 512-byte blocks, file permissions, number of hard
1.1 deraadt 330: links, owner, group, size in bytes, last modification time, and pathname.
331: If the file is a block or character special file, the major and minor numbers
332: will be displayed instead of the size in bytes.
1.22 aaron 333: If the file is a symbolic link, the pathname of the linked-to file will be
334: displayed preceded by
1.89 jmc 335: .Dq -> .
1.22 aaron 336: The format is identical to that produced by
1.71 jmc 337: .Dq ls -dils .
1.84 jmc 338: .Pp
1.6 tholo 339: .It Ic -maxdepth Ar n
1.7 tholo 340: True if the current search depth is less than or equal to what is specified in
341: .Ar n .
1.84 jmc 342: .Pp
1.7 tholo 343: .It Ic -mindepth Ar n
344: True if the current search depth is at least what is specified in
1.6 tholo 345: .Ar n .
1.84 jmc 346: .Pp
1.22 aaron 347: .It Ic -mmin Ar n
1.15 deraadt 348: True if the difference between the file last modification time and the time
1.22 aaron 349: .Nm
1.20 aaron 350: was started, rounded up to the next full minute, is
1.15 deraadt 351: .Ar n
1.20 aaron 352: minutes.
1.84 jmc 353: .Pp
1.22 aaron 354: .It Ic -mtime Ar n
1.1 deraadt 355: True if the difference between the file last modification time and the time
1.22 aaron 356: .Nm
357: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 358: .Ar n
1.22 aaron 359: 24-hour periods.
1.84 jmc 360: .Pp
1.22 aaron 361: .It Ic -name Ar pattern
1.1 deraadt 362: True if the last component of the pathname being examined matches
1.77 schwarze 363: .Ar pattern ,
364: which may use any of the special characters documented in
365: .Xr glob 7 .
1.84 jmc 366: .Pp
1.22 aaron 367: .It Ic -newer Ar file
1.1 deraadt 368: True if the current file has a more recent last modification time than
1.25 aaron 369: .Ar file .
1.84 jmc 370: .Pp
1.44 jmc 371: .It Ic -nogroup
372: True if the file belongs to an unknown group.
1.84 jmc 373: .Pp
1.1 deraadt 374: .It Ic -nouser
375: True if the file belongs to an unknown user.
1.84 jmc 376: .Pp
1.89 jmc 377: .It Ic -ok Ar utility Oo Ar argument ... Oc \&;
1.22 aaron 378: Identical to the
379: .Ic -exec
380: primary with the exception that
381: .Nm
382: requests user affirmation for the execution of
383: .Ar utility
384: by printing
385: a message to the terminal and reading a response.
386: If the response is other than
1.101 ! naddy 387: .Sq y ,
1.22 aaron 388: the command is not executed and the
389: value of the
1.54 jmc 390: .Ic ok
1.22 aaron 391: expression is false.
1.84 jmc 392: .Pp
1.22 aaron 393: .It Ic -path Ar pattern
1.1 deraadt 394: True if the pathname being examined matches
1.77 schwarze 395: .Ar pattern ,
396: which may use any of the special characters documented in
397: .Xr glob 7 .
1.22 aaron 398: Slashes
399: .Pq Ql /
400: are treated as normal characters and do not have to be
1.1 deraadt 401: matched explicitly.
1.84 jmc 402: .Pp
1.21 aaron 403: .It Xo
404: .Ic -perm
1.65 jmc 405: .Oo - Oc Ns Ar mode
1.21 aaron 406: .Xc
1.1 deraadt 407: The
408: .Ar mode
409: may be either symbolic (see
1.25 aaron 410: .Xr chmod 1 )
1.1 deraadt 411: or an octal number.
412: If the mode is symbolic, a starting value of zero is assumed and the
1.16 aaron 413: mode sets or clears permissions without regard to the process's file mode
1.1 deraadt 414: creation mask.
415: If the mode is octal, only bits 07777
1.90 bentley 416: .Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO
1.1 deraadt 417: of the file's mode bits participate
418: in the comparison.
1.22 aaron 419: If the mode is preceded by a dash
1.54 jmc 420: .Pq Sq - ,
1.22 aaron 421: this primary evaluates to true
1.1 deraadt 422: if at least all of the bits in the mode are set in the file's mode bits.
1.22 aaron 423: If the mode is not preceded by a dash, this primary evaluates to
1.16 aaron 424: true if the bits in the mode exactly match the file's mode bits.
1.22 aaron 425: Note, the first character of a symbolic mode may not be a dash.
1.84 jmc 426: .Pp
1.1 deraadt 427: .It Ic -print
428: This primary always evaluates to true.
429: It prints the pathname of the current file to standard output, followed
1.22 aaron 430: by a newline
431: .Pq Ql \en
432: character.
1.84 jmc 433: .Pp
1.1 deraadt 434: .It Ic -print0
435: This primary always evaluates to true.
436: It prints the pathname of the current file to standard output, followed
1.79 schwarze 437: by a null character, suitable for use with the
438: .Fl 0
439: option to
440: .Xr xargs 1 .
1.84 jmc 441: .Pp
1.1 deraadt 442: .It Ic -prune
443: This primary always evaluates to true.
444: It causes
1.22 aaron 445: .Nm
1.1 deraadt 446: to not descend into the current file.
447: Note, the
448: .Ic -prune
449: primary has no effect if the
450: .Fl d
451: option was specified.
1.84 jmc 452: .Pp
1.22 aaron 453: .It Ic -size Ar n Ns Op Cm c
454: True if the file's size, rounded up, in 512-byte blocks is
1.25 aaron 455: .Ar n .
1.1 deraadt 456: If
457: .Ar n
1.22 aaron 458: is followed by a
459: .Sq c ,
460: then the primary is true if the
1.1 deraadt 461: file's size is
462: .Ar n
463: bytes.
1.84 jmc 464: .Pp
1.22 aaron 465: .It Ic -type Ar t
1.1 deraadt 466: True if the file is of the specified type.
467: Possible file types are as follows:
468: .Pp
469: .Bl -tag -width flag -offset indent -compact
470: .It Cm b
471: block special
472: .It Cm c
473: character special
474: .It Cm d
475: directory
476: .It Cm f
477: regular file
478: .It Cm l
479: symbolic link
480: .It Cm p
481: FIFO
482: .It Cm s
483: socket
484: .El
485: .Pp
1.22 aaron 486: .It Ic -user Ar uname
1.1 deraadt 487: True if the file belongs to the user
1.25 aaron 488: .Ar uname .
1.1 deraadt 489: If
490: .Ar uname
491: is numeric and there is no such user name, then
492: .Ar uname
1.16 aaron 493: is treated as a user ID.
1.84 jmc 494: .Pp
1.56 jmc 495: .It Ic -xdev
1.61 jmc 496: This primary always evaluates to true.
1.56 jmc 497: The same as specifying the
498: .Fl x
499: option.
1.1 deraadt 500: .El
501: .Pp
502: All primaries which take a numeric argument allow the number to be
1.22 aaron 503: preceded by a plus sign
504: .Pq Ql +
505: or a minus sign
1.54 jmc 506: .Pq Ql - .
1.22 aaron 507: A preceding plus sign means
508: .Dq more than n ,
509: a preceding minus sign means
510: .Dq less than n ,
511: and neither means
512: .Dq exactly n .
1.74 jmc 513: Exceptions are the primaries
514: .Ic mindepth
515: and
516: .Ic maxdepth .
1.1 deraadt 517: .Sh OPERATORS
518: The primaries may be combined using the following operators.
519: The operators are listed in order of decreasing precedence.
1.47 jmc 520: .Pp
521: .Bl -tag -width "(expression)" -compact
1.51 jmc 522: .It Cm \&( Ar expression Cm \&)
1.1 deraadt 523: This evaluates to true if the parenthesized expression evaluates to
524: true.
525: .Pp
1.51 jmc 526: .It Cm \&! Ar expression
1.96 tedu 527: .It Cm -not Ar expression
1.95 jmc 528: This is the unary NOT operator.
1.1 deraadt 529: It evaluates to true if the expression is false.
530: .Pp
1.89 jmc 531: .It Ar expression Cm -a Ar expression
1.22 aaron 532: .It Ar expression Cm -and Ar expression
533: .It Ar expression expression
1.89 jmc 534: The logical AND operator.
1.101 ! naddy 535: As it is implied by the juxtaposition of two expressions, it does not
1.1 deraadt 536: have to be specified.
537: The expression evaluates to true if both expressions are true.
538: The second expression is not evaluated if the first expression is false.
539: .Pp
1.89 jmc 540: .It Ar expression Cm -o Ar expression
1.22 aaron 541: .It Ar expression Cm -or Ar expression
1.89 jmc 542: The logical OR operator.
1.1 deraadt 543: The expression evaluates to true if either the first or the second expression
544: is true.
545: The second expression is not evaluated if the first expression is true.
546: .El
547: .Pp
1.53 otto 548: Operators, primaries, and arguments to primaries must be separate
549: arguments to
550: .Nm find ,
551: i.e. they should be separated by whitespace.
1.81 jmc 552: .Sh EXIT STATUS
553: The
554: .Nm
555: utility exits with a value of 0 on successful traversal of all path operands
1.89 jmc 556: or with a value >0 if an error occurred.
1.1 deraadt 557: .Sh EXAMPLES
1.62 jmc 558: Print out a list of all the files whose names end in
1.43 jaredy 559: .Dq \&.c :
560: .Pp
1.62 jmc 561: .Dl "$ find / -name '*.c'"
1.43 jaredy 562: .Pp
1.22 aaron 563: Print out a list of all the files which are not both newer than
564: .Dq ttt
565: and owned by
1.43 jaredy 566: .Dq wnj :
567: .Pp
1.99 jmc 568: .Dl "$ find / ! \e( -newer ttt -user wnj \e)"
1.43 jaredy 569: .Pp
570: Print out a list of all core files on local file systems:
571: .Pp
1.99 jmc 572: .Dl "$ find / ! -fstype local -prune -o -name '*.core'"
1.46 jmc 573: .Pp
574: Find all files in
575: .Pa /usr/src
576: ending in a dot and single digit, but skip directory
577: .Pa /usr/src/gnu :
578: .Pp
1.88 jmc 579: .Dl "$ find /usr/src -path /usr/src/gnu -prune -o -name \e*.[0-9]"
1.62 jmc 580: .Pp
1.79 schwarze 581: Find and remove all *.jpg and *.gif files under the current working
582: directory:
1.62 jmc 583: .Pp
1.97 kn 584: .Dl "$ find . \e( -name \e*.jpg -o -name \e*.gif \e) -exec rm {} +"
1.63 otto 585: or
1.97 kn 586: .Dl "$ find . \e( -name \e*.jpg -o -name \e*.gif \e) -delete"
1.1 deraadt 587: .Sh SEE ALSO
1.29 millert 588: .Xr chflags 1 ,
1.1 deraadt 589: .Xr chmod 1 ,
590: .Xr locate 1 ,
1.77 schwarze 591: .Xr ls 1 ,
1.23 aaron 592: .Xr whereis 1 ,
593: .Xr which 1 ,
1.41 millert 594: .Xr xargs 1 ,
1.1 deraadt 595: .Xr stat 2 ,
1.98 deraadt 596: .Xr fts_open 3 ,
1.77 schwarze 597: .Xr glob 7 ,
1.1 deraadt 598: .Xr symlink 7
599: .Sh STANDARDS
600: The
1.22 aaron 601: .Nm
1.68 jmc 602: utility is compliant with the
1.72 jmc 603: .St -p1003.1-2008
1.68 jmc 604: specification.
1.1 deraadt 605: .Pp
1.55 jmc 606: The options
1.88 jmc 607: .Op Fl dfhXx ,
608: primaries
1.18 deraadt 609: .Ic -amin ,
1.55 jmc 610: .Ic -anewer ,
1.18 deraadt 611: .Ic -cmin ,
1.55 jmc 612: .Ic -cnewer ,
1.92 tedu 613: .Ic -delete ,
1.9 tholo 614: .Ic -empty ,
1.55 jmc 615: .Ic -execdir ,
616: .Ic -flags ,
1.1 deraadt 617: .Ic -follow ,
618: .Ic -fstype ,
1.27 deraadt 619: .Ic -iname ,
1.2 deraadt 620: .Ic -inum ,
1.9 tholo 621: .Ic -ls ,
622: .Ic -maxdepth ,
1.13 deraadt 623: .Ic -mindepth ,
1.55 jmc 624: .Ic -mmin ,
1.1 deraadt 625: and
1.88 jmc 626: .Ic -print0 ,
627: and operators
1.96 tedu 628: .Fl and ,
629: .Fl not ,
1.88 jmc 630: and
1.96 tedu 631: .Fl or ,
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
1.100 jsg 668: A simple
1.30 aaron 669: .Nm
670: command appeared in
1.100 jsg 671: .At v1
672: and was removed in
673: .At v3 .
674: A new
675: .Nm
676: command was written for the Programmer's Workbench (PWB)
677: and appeared in
678: .At v5 .
679: It was rewritten for
680: .Bx 4.3 Reno .
1.50 jmc 681: .Sh CAVEATS
1.1 deraadt 682: The special characters used by
1.22 aaron 683: .Nm
1.1 deraadt 684: are also special characters to many shell programs.
1.22 aaron 685: In particular, the characters
686: .Ql * ,
1.78 schwarze 687: .Ql \&[ ,
1.22 aaron 688: .Ql \&] ,
1.40 jmc 689: .Ql \&? ,
1.78 schwarze 690: .Ql \&( ,
1.22 aaron 691: .Ql \&) ,
692: .Ql \e ,
693: and
694: .Ql \&;
695: may have to be escaped from the shell.
1.79 schwarze 696: .Pp
1.82 schwarze 697: As file names may contain whitespace and shell metacharacters,
698: passing the output of
1.79 schwarze 699: .Nm
700: to other programs requires some care:
701: .Pp
702: .Dl "$ find . -name \e*.jpg | xargs rm"
703: or
704: .Dl "$ rm `find . -name \e*.jpg`"
705: .Pp
706: would, given files
707: .Dq important\ .jpg
708: and
709: .Dq important ,
710: remove
711: .Dq important .
712: Use the
713: .Ic -print0
714: or
715: .Ic -exec
716: primaries instead.
1.1 deraadt 717: .Pp
718: As there is no delimiter separating options and file names or file
719: names and the
720: .Ar expression ,
1.22 aaron 721: it is difficult to specify files named
722: .Dq -xdev
723: or
1.65 jmc 724: .Sq \&! .
1.1 deraadt 725: These problems are handled by the
726: .Fl f
727: option and the
728: .Xr getopt 3
1.65 jmc 729: .Sq --
1.22 aaron 730: construct.