Annotation of src/usr.bin/find/find.1, Revision 1.23
1.23 ! aaron 1: .\" $OpenBSD: find.1,v 1.22 1999/06/05 01:21:25 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 ,
1.23 ! aaron 488: .Xr whereis 1 ,
! 489: .Xr which 1 ,
1.1 deraadt 490: .Xr stat 2 ,
491: .Xr fts 3 ,
1.16 aaron 492: .Xr getgrent 3 ,
1.1 deraadt 493: .Xr getpwent 3 ,
494: .Xr strmode 3 ,
495: .Xr symlink 7
496: .Sh STANDARDS
497: The
1.22 aaron 498: .Nm
1.1 deraadt 499: utility syntax is a superset of the syntax specified by the
500: .St -p1003.2
501: standard.
502: .Pp
1.13 deraadt 503: The options and primaries
1.18 deraadt 504: .Ic -amin ,
505: .Ic -cmin ,
1.9 tholo 506: .Ic -empty ,
1.1 deraadt 507: .Ic -follow ,
508: .Ic -fstype ,
1.2 deraadt 509: .Ic -inum ,
1.1 deraadt 510: .Ic -links ,
1.9 tholo 511: .Ic -ls ,
1.18 deraadt 512: .Ic -mmin ,
1.9 tholo 513: .Ic -maxdepth ,
1.13 deraadt 514: .Ic -mindepth ,
515: .Ic -execdir ,
1.1 deraadt 516: and
517: .Ic -print0
1.13 deraadt 518: are extensions to
1.1 deraadt 519: .St -p1003.2 .
520: .Pp
521: Historically, the
522: .Fl d ,
1.14 deraadt 523: .Fl H
1.1 deraadt 524: and
525: .Fl x
1.14 deraadt 526: options were implemented using the primaries
527: .Ic -depth ,
528: .Ic -follow ,
529: and
530: .Ic -xdev .
1.1 deraadt 531: These primaries always evaluated to true.
532: As they were really global variables that took effect before the traversal
533: began, some legal expressions could have unexpected results.
1.22 aaron 534: An example is the expression
535: .Dq \-print \-o \-depth .
536: As
537: .Cm \-print
538: always evaluates to true, the standard order of evaluation
539: implies that
540: .Cm \-depth
541: would never be evaluated.
1.1 deraadt 542: This is not the case.
543: .Pp
1.22 aaron 544: The operator
545: .Cm -or
546: was implemented as
547: .Cm \-o ,
548: and the operator
549: .Cm -and
550: was implemented as
551: .Cm \-a .
1.1 deraadt 552: .Pp
553: Historic implementations of the
554: .Ic -exec
555: and
556: .Ic -ok
1.22 aaron 557: primaries did not replace the string
558: .Qq {}
559: in the utility name or the
1.1 deraadt 560: utility arguments if it had preceding or following non-whitespace characters.
561: This version replaces it no matter where in the utility name or arguments
562: it appears.
563: .Sh BUGS
564: The special characters used by
1.22 aaron 565: .Nm
1.1 deraadt 566: are also special characters to many shell programs.
1.22 aaron 567: In particular, the characters
568: .Ql * ,
569: .Ql [ ,
570: .Ql \&] ,
571: .Ql ? ,
572: .Ql ( ,
573: .Ql \&) ,
574: .Ql ! ,
575: .Ql \e ,
576: and
577: .Ql \&;
578: may have to be escaped from the shell.
1.1 deraadt 579: .Pp
580: As there is no delimiter separating options and file names or file
581: names and the
582: .Ar expression ,
1.22 aaron 583: it is difficult to specify files named
584: .Dq -xdev
585: or
586: .Dq ! .
1.1 deraadt 587: These problems are handled by the
588: .Fl f
589: option and the
590: .Xr getopt 3
1.22 aaron 591: .Dq \-\-
592: construct.
1.19 espie 593: .Pp
594: The
595: .Fl W
1.22 aaron 596: option is probably not the most elegant way to handle whiteouts. It may
1.19 espie 597: 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