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