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