Annotation of src/usr.bin/find/find.1, Revision 1.24
1.24 ! millert 1: .\" $OpenBSD: find.1,v 1.23 1999/10/07 19:15:24 aaron 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.
16: .\" 3. All advertising materials mentioning features or use of this software
17: .\" must display the following acknowledgement:
18: .\" This product includes software developed by the University of
19: .\" California, Berkeley and its contributors.
20: .\" 4. Neither the name of the University nor the names of its contributors
21: .\" may be used to endorse or promote products derived from this software
22: .\" without specific prior written permission.
23: .\"
24: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
25: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34: .\" SUCH DAMAGE.
35: .\"
36: .\" from: @(#)find.1 8.1 (Berkeley) 6/6/93
37: .\"
1.24 ! millert 38: .Dd December 4, 1999
1.1 deraadt 39: .Dt FIND 1
40: .Os
41: .Sh NAME
42: .Nm find
43: .Nd walk a file hierarchy
44: .Sh SYNOPSIS
45: .Nm find
1.19 espie 46: .Op Fl HdhXxW
1.1 deraadt 47: .Op Fl f Ar file
48: .Op Ar file ...
49: .Ar expression
50: .Sh DESCRIPTION
1.22 aaron 51: .Nm
1.1 deraadt 52: recursively descends the directory tree for each
53: .Ar file
54: listed, evaluating an
55: .Ar expression
1.22 aaron 56: (composed of the
57: .Dq primaries
58: and
59: .Dq operands
60: listed below) in terms
1.12 millert 61: of each file in the tree.
1.1 deraadt 62: .Pp
63: The options are as follows:
64: .Bl -tag -width Ds
65: .It Fl H
1.16 aaron 66: Causes the file information and file type (see
1.22 aaron 67: .Xr stat 2 )
68: returned for each symbolic link encountered on the command line to be
1.1 deraadt 69: those of the file referenced by the link, not the link itself.
70: If the referenced file does not exist, the file information and type will
1.22 aaron 71: be for the link itself. File information of all symbolic links not on
1.1 deraadt 72: the command line is that of the link itself.
73: .It Fl d
1.16 aaron 74: Causes
1.22 aaron 75: .Nm
76: to perform a depth-first traversal, i.e., directories
77: are visited in post-order and all entries in a directory will be acted
1.1 deraadt 78: on before the directory itself.
79: By default,
1.22 aaron 80: .Nm
81: visits directories in pre-order, i.e., before their contents.
1.1 deraadt 82: Note, the default is
1.22 aaron 83: .Em not
84: a breadth-first traversal.
1.16 aaron 85: .It Fl f Ar file
86: Specifies a file hierarchy for
1.22 aaron 87: .Nm
1.1 deraadt 88: to traverse.
89: File hierarchies may also be specified as the operands immediately
90: following the options.
91: .It Fl h
1.16 aaron 92: Causes the file information and file type (see
1.22 aaron 93: .Xr stat 2 )
1.1 deraadt 94: returned for each symbolic link to be those of the file referenced by the
95: link, not the link itself.
96: If the referenced file does not exist, the file information and type will
97: be for the link itself.
98: .It Fl X
1.16 aaron 99: Permit
1.1 deraadt 100: .Nm
101: to be safely used in conjunction with
102: .Xr xargs 1 .
103: If a file name contains any of the delimiting characters used by
104: .Xr xargs ,
105: a diagnostic message is displayed on standard error, and the file
106: is skipped.
1.22 aaron 107: The delimiting characters include single
108: .Pq Ql '
109: and double
110: .Pq Ql \&"
111: quotes, backslash
112: .Pq Ql \e ,
113: space, tab, and newline
114: .Pq Sq \en
115: characters.
1.4 deraadt 116: As an alternative, the
117: .Fl print0
118: function may be used safely in conjunction with the
119: .Fl 0
120: argument to
1.16 aaron 121: .Xr xargs 1 .
1.1 deraadt 122: .It Fl x
1.16 aaron 123: Prevents
1.22 aaron 124: .Nm
1.1 deraadt 125: from descending into directories that have a device number different
126: than that of the file from which the descent began.
1.19 espie 127: .It Fl W
128: Let
129: .Nm
130: take whiteouts into account when scanning directories.
1.1 deraadt 131: .El
132: .Sh PRIMARIES
133: .Bl -tag -width Ds
1.22 aaron 134: .It Ic -amin Ar n
1.15 deraadt 135: True if the difference between the file last access time and the time
1.22 aaron 136: .Nm
1.20 aaron 137: was started, rounded up to the next full minute, is
1.15 deraadt 138: .Ar n
1.20 aaron 139: minutes.
1.24 ! millert 140: .It Ic -anewer Ar file
! 141: True if the current file has a more recent last access time than
! 142: .Ar file .
1.22 aaron 143: .It Ic -atime Ar n
1.1 deraadt 144: True if the difference between the file last access time and the time
1.22 aaron 145: .Nm
146: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 147: .Ar n
1.22 aaron 148: 24-hour periods.
149: .It Ic -cmin Ar n
1.15 deraadt 150: True if the difference between the time of last change of file status
151: information and the time
1.22 aaron 152: .Nm
1.20 aaron 153: was started, rounded up to the next full minute, is
1.15 deraadt 154: .Ar n
1.20 aaron 155: minutes.
1.24 ! millert 156: .It Ic -cnewer Ar file
! 157: True if the current file has a more recent last change time than
! 158: .Ar file .
1.22 aaron 159: .It Ic -ctime Ar n
1.1 deraadt 160: True if the difference between the time of last change of file status
161: information 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.8 tholo 166: .It Ic -empty
167: True if the current file or directory is empty.
1.22 aaron 168: .It Ic -exec Ar utility Op argument ... ;
1.1 deraadt 169: True if the program named
170: .Ar utility
171: returns a zero value as its exit status.
172: Optional arguments may be passed to the utility.
1.22 aaron 173: The expression must be terminated by a semicolon
174: .Pq Ql \&; .
175: If the string
176: .Qq {}
177: appears anywhere in the utility name or the
1.1 deraadt 178: arguments it is replaced by the pathname of the current file.
1.16 aaron 179: .Ar utility
1.1 deraadt 180: will be executed from the directory from which
1.22 aaron 181: .Nm
1.1 deraadt 182: was executed.
1.22 aaron 183: .It Ic -execdir Ar utility Op argument ... ;
184: Identical to the
1.10 millert 185: .Ic -exec
186: primary with the exception that
1.16 aaron 187: .Ar utility
1.10 millert 188: will be executed from the directory that holds
189: the current file. The filename substituted for
1.22 aaron 190: the string
191: .Qq {}
192: is not qualified.
1.2 deraadt 193: .It Ic -follow
194: Follow symbolic links.
1.22 aaron 195: .It Ic -fstype Ar type
1.1 deraadt 196: True if the file is contained in a file system of type
197: .Ar type .
1.22 aaron 198: Two special file system types are recognized:
199: .Dq local
200: and
201: .Dq rdonly .
1.1 deraadt 202: These do not describe actual file system types;
203: the former matches any file system physically mounted on the system where
1.22 aaron 204: .Nm
205: is being executed whereas the latter matches any file system which is
1.1 deraadt 206: mounted read-only.
1.22 aaron 207: .It Ic -group Ar gname
1.1 deraadt 208: True if the file belongs to the group
209: .Ar gname .
210: If
211: .Ar gname
212: is numeric and there is no such group name, then
213: .Ar gname
1.16 aaron 214: is treated as a group ID.
1.22 aaron 215: .It Ic -inum Ar n
1.1 deraadt 216: True if the file has inode number
217: .Ar n .
1.22 aaron 218: .It Ic -links Ar n
1.1 deraadt 219: True if the file has
220: .Ar n
221: links.
222: .It Ic -ls
223: This primary always evaluates to true.
224: The following information for the current file is written to standard output:
1.22 aaron 225: its inode number, size in 512-byte blocks, file permissions, number of hard
1.1 deraadt 226: links, owner, group, size in bytes, last modification time, and pathname.
227: If the file is a block or character special file, the major and minor numbers
228: will be displayed instead of the size in bytes.
1.22 aaron 229: If the file is a symbolic link, the pathname of the linked-to file will be
230: displayed preceded by
231: .Dq \-> .
232: The format is identical to that produced by
233: .Dq ls \-dgils .
1.6 tholo 234: .It Ic -maxdepth Ar n
1.7 tholo 235: True if the current search depth is less than or equal to what is specified in
236: .Ar n .
237: .It Ic -mindepth Ar n
238: True if the current search depth is at least what is specified in
1.6 tholo 239: .Ar n .
1.22 aaron 240: .It Ic -mmin Ar n
1.15 deraadt 241: True if the difference between the file last modification time and the time
1.22 aaron 242: .Nm
1.20 aaron 243: was started, rounded up to the next full minute, is
1.15 deraadt 244: .Ar n
1.20 aaron 245: minutes.
1.22 aaron 246: .It Ic -mtime Ar n
1.1 deraadt 247: True if the difference between the file last modification time and the time
1.22 aaron 248: .Nm
249: was started, rounded up to the next full 24-hour period, is
1.1 deraadt 250: .Ar n
1.22 aaron 251: 24-hour periods.
252: .It Ic -name Ar pattern
1.1 deraadt 253: True if the last component of the pathname being examined matches
254: .Ar pattern .
1.22 aaron 255: Special shell pattern matching characters
256: .Pf ( Ql [ ,
257: .Ql \&] ,
258: .Ql * ,
259: and
260: .Ql ? )
1.1 deraadt 261: may be used as part of
262: .Ar pattern .
263: These characters may be matched explicitly by escaping them with a
1.22 aaron 264: backslash
265: .Pq Ql \e .
266: .It Ic -newer Ar file
1.1 deraadt 267: True if the current file has a more recent last modification time than
268: .Ar file .
269: .It Ic -nouser
270: True if the file belongs to an unknown user.
271: .It Ic -nogroup
272: True if the file belongs to an unknown group.
1.22 aaron 273: .It Ic \&-ok Ar utility Op argument ... ;
274: Identical to the
275: .Ic -exec
276: primary with the exception that
277: .Nm
278: requests user affirmation for the execution of
279: .Ar utility
280: by printing
281: a message to the terminal and reading a response.
282: If the response is other than
283: .Sq y
284: the command is not executed and the
285: value of the
286: .Ic \&ok
287: expression is false.
288: .It Ic -path Ar pattern
1.1 deraadt 289: True if the pathname being examined matches
290: .Ar pattern .
1.22 aaron 291: Special shell pattern matching characters
292: .Pf ( Ql [ ,
293: .Ql \&] ,
294: .Ql * ,
295: and
296: .Ql ? )
1.1 deraadt 297: may be used as part of
298: .Ar pattern .
299: These characters may be matched explicitly by escaping them with a
1.22 aaron 300: backslash
301: .Pq Ql \e .
302: Slashes
303: .Pq Ql /
304: are treated as normal characters and do not have to be
1.1 deraadt 305: matched explicitly.
1.21 aaron 306: .It Xo
307: .Ic -perm
308: .Op Fl
309: .Ar mode
310: .Xc
1.1 deraadt 311: The
312: .Ar mode
313: may be either symbolic (see
314: .Xr chmod 1 )
315: or an octal number.
316: If the mode is symbolic, a starting value of zero is assumed and the
1.16 aaron 317: mode sets or clears permissions without regard to the process's file mode
1.1 deraadt 318: creation mask.
319: If the mode is octal, only bits 07777
320: .Pf ( Dv S_ISUID
321: |
322: .Dv S_ISGID
323: |
324: .Dv S_ISTXT
325: |
326: .Dv S_IRWXU
327: |
328: .Dv S_IRWXG
329: |
330: .Dv S_IRWXO )
331: of the file's mode bits participate
332: in the comparison.
1.22 aaron 333: If the mode is preceded by a dash
334: .Pq Sq \- ,
335: this primary evaluates to true
1.1 deraadt 336: if at least all of the bits in the mode are set in the file's mode bits.
1.22 aaron 337: If the mode is not preceded by a dash, this primary evaluates to
1.16 aaron 338: true if the bits in the mode exactly match the file's mode bits.
1.22 aaron 339: Note, the first character of a symbolic mode may not be a dash.
1.1 deraadt 340: .It Ic -print
341: This primary always evaluates to true.
342: It prints the pathname of the current file to standard output, followed
1.22 aaron 343: by a newline
344: .Pq Ql \en
345: character.
1.1 deraadt 346: If neither
347: .Ic -exec ,
348: .Ic -ls ,
349: .Ic -ok ,
350: nor
351: .Ic -print0
352: is specified, the given expression shall be effectively replaced by
1.22 aaron 353: .Cm \&( Ns Ar given\& expression Ns Cm \&)
1.1 deraadt 354: .Ic -print .
355: .It Ic -print0
356: This primary always evaluates to true.
357: It prints the pathname of the current file to standard output, followed
358: by a null character.
359: .It Ic -prune
360: This primary always evaluates to true.
361: It causes
1.22 aaron 362: .Nm
1.1 deraadt 363: to not descend into the current file.
364: Note, the
365: .Ic -prune
366: primary has no effect if the
367: .Fl d
368: option was specified.
1.22 aaron 369: .It Ic -size Ar n Ns Op Cm c
370: True if the file's size, rounded up, in 512-byte blocks is
1.1 deraadt 371: .Ar n .
372: If
373: .Ar n
1.22 aaron 374: is followed by a
375: .Sq c ,
376: then the primary is true if the
1.1 deraadt 377: file's size is
378: .Ar n
379: bytes.
1.22 aaron 380: .It Ic -type Ar t
1.1 deraadt 381: True if the file is of the specified type.
382: Possible file types are as follows:
383: .Pp
384: .Bl -tag -width flag -offset indent -compact
1.3 deraadt 385: .It Cm W
1.22 aaron 386: whiteout (currently, these won't even be visible without also specifying
1.19 espie 387: .Fl W )
1.1 deraadt 388: .It Cm b
389: block special
390: .It Cm c
391: character special
392: .It Cm d
393: directory
394: .It Cm f
395: regular file
396: .It Cm l
397: symbolic link
398: .It Cm p
399: FIFO
400: .It Cm s
401: socket
402: .El
403: .Pp
1.22 aaron 404: .It Ic -user Ar uname
1.1 deraadt 405: True if the file belongs to the user
406: .Ar uname .
407: If
408: .Ar uname
409: is numeric and there is no such user name, then
410: .Ar uname
1.16 aaron 411: is treated as a user ID.
1.1 deraadt 412: .El
413: .Pp
414: All primaries which take a numeric argument allow the number to be
1.22 aaron 415: preceded by a plus sign
416: .Pq Ql +
417: or a minus sign
418: .Pq Ql \- .
419: A preceding plus sign means
420: .Dq more than n ,
421: a preceding minus sign means
422: .Dq less than n ,
423: and neither means
424: .Dq exactly n .
1.1 deraadt 425: .Sh OPERATORS
426: The primaries may be combined using the following operators.
427: The operators are listed in order of decreasing precedence.
1.22 aaron 428: .Bl -tag -width (expression)
429: .It Cm \&( Ns Ar expression Ns Cm \&)
1.1 deraadt 430: This evaluates to true if the parenthesized expression evaluates to
431: true.
432: .Pp
1.22 aaron 433: .It Cm \&! Ns Ar expression
1.1 deraadt 434: This is the unary
435: .Tn NOT
436: operator.
437: It evaluates to true if the expression is false.
438: .Pp
1.22 aaron 439: .It Ar expression Cm -and Ar expression
440: .It Ar expression expression
1.1 deraadt 441: The
442: .Cm -and
443: operator is the logical
444: .Tn AND
445: operator.
446: As it is implied by the juxtaposition of two expressions it does not
447: have to be specified.
448: The expression evaluates to true if both expressions are true.
449: The second expression is not evaluated if the first expression is false.
450: .Pp
1.22 aaron 451: .It Ar expression Cm -or Ar expression
1.1 deraadt 452: The
453: .Cm -or
454: operator is the logical
455: .Tn OR
456: operator.
457: The expression evaluates to true if either the first or the second expression
458: is true.
459: The second expression is not evaluated if the first expression is true.
460: .El
461: .Pp
462: All operands and primaries must be separate arguments to
1.22 aaron 463: .Nm find .
1.1 deraadt 464: Primaries which themselves take arguments expect each argument
465: to be a separate argument to
1.22 aaron 466: .Nm find .
1.1 deraadt 467: .Sh EXAMPLES
468: The following examples are shown as given to the shell:
469: .Bl -tag -width findx
470: .It Li "find / \e! -name \*q*.c\*q -print"
1.22 aaron 471: Print out a list of all the files whose names do not end in
472: .Dq .c .
1.1 deraadt 473: .It Li "find / -newer ttt -user wnj -print"
1.22 aaron 474: Print out a list of all the files owned by user
475: .Dq wnj
476: that are newer
477: than the file
478: .Dq ttt .
1.1 deraadt 479: .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
1.22 aaron 480: Print out a list of all the files which are not both newer than
481: .Dq ttt
482: and owned by
483: .Dq wnj .
1.1 deraadt 484: .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
1.22 aaron 485: Print out a list of all the files that are either owned by
486: .Dq wnj
487: or
488: that are newer than
489: .Dq ttt .
1.1 deraadt 490: .El
491: .Sh SEE ALSO
492: .Xr chmod 1 ,
493: .Xr locate 1 ,
1.23 aaron 494: .Xr whereis 1 ,
495: .Xr which 1 ,
1.1 deraadt 496: .Xr stat 2 ,
497: .Xr fts 3 ,
1.16 aaron 498: .Xr getgrent 3 ,
1.1 deraadt 499: .Xr getpwent 3 ,
500: .Xr strmode 3 ,
501: .Xr symlink 7
502: .Sh STANDARDS
503: The
1.22 aaron 504: .Nm
1.1 deraadt 505: utility syntax is a superset of the syntax specified by the
506: .St -p1003.2
507: standard.
508: .Pp
1.13 deraadt 509: The options and primaries
1.18 deraadt 510: .Ic -amin ,
511: .Ic -cmin ,
1.9 tholo 512: .Ic -empty ,
1.1 deraadt 513: .Ic -follow ,
514: .Ic -fstype ,
1.2 deraadt 515: .Ic -inum ,
1.1 deraadt 516: .Ic -links ,
1.9 tholo 517: .Ic -ls ,
1.18 deraadt 518: .Ic -mmin ,
1.9 tholo 519: .Ic -maxdepth ,
1.13 deraadt 520: .Ic -mindepth ,
521: .Ic -execdir ,
1.1 deraadt 522: and
523: .Ic -print0
1.13 deraadt 524: are extensions to
1.1 deraadt 525: .St -p1003.2 .
526: .Pp
527: Historically, the
528: .Fl d ,
1.14 deraadt 529: .Fl H
1.1 deraadt 530: and
531: .Fl x
1.14 deraadt 532: options were implemented using the primaries
533: .Ic -depth ,
534: .Ic -follow ,
535: and
536: .Ic -xdev .
1.1 deraadt 537: These primaries always evaluated to true.
538: As they were really global variables that took effect before the traversal
539: began, some legal expressions could have unexpected results.
1.22 aaron 540: An example is the expression
541: .Dq \-print \-o \-depth .
542: As
543: .Cm \-print
544: always evaluates to true, the standard order of evaluation
545: implies that
546: .Cm \-depth
547: would never be evaluated.
1.1 deraadt 548: This is not the case.
549: .Pp
1.22 aaron 550: The operator
551: .Cm -or
552: was implemented as
553: .Cm \-o ,
554: and the operator
555: .Cm -and
556: was implemented as
557: .Cm \-a .
1.1 deraadt 558: .Pp
559: Historic implementations of the
560: .Ic -exec
561: and
562: .Ic -ok
1.22 aaron 563: primaries did not replace the string
564: .Qq {}
565: in the utility name or the
1.1 deraadt 566: utility arguments if it had preceding or following non-whitespace characters.
567: This version replaces it no matter where in the utility name or arguments
568: it appears.
569: .Sh BUGS
570: The special characters used by
1.22 aaron 571: .Nm
1.1 deraadt 572: are also special characters to many shell programs.
1.22 aaron 573: In particular, the characters
574: .Ql * ,
575: .Ql [ ,
576: .Ql \&] ,
577: .Ql ? ,
578: .Ql ( ,
579: .Ql \&) ,
580: .Ql ! ,
581: .Ql \e ,
582: and
583: .Ql \&;
584: may have to be escaped from the shell.
1.1 deraadt 585: .Pp
586: As there is no delimiter separating options and file names or file
587: names and the
588: .Ar expression ,
1.22 aaron 589: it is difficult to specify files named
590: .Dq -xdev
591: or
592: .Dq ! .
1.1 deraadt 593: These problems are handled by the
594: .Fl f
595: option and the
596: .Xr getopt 3
1.22 aaron 597: .Dq \-\-
598: construct.
1.19 espie 599: .Pp
600: The
601: .Fl W
1.22 aaron 602: option is probably not the most elegant way to handle whiteouts. It may
1.19 espie 603: be replaced by a more sophisticated algorithm eventually.
![[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