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