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