Annotation of src/usr.bin/find/find.1, Revision 1.19
1.19 ! espie 1: .\" $OpenBSD: find.1,v 1.18 1999/02/24 10:25:45 deraadt 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
126: was started, rounded up to the next full minutes period, is
127: .Ar n
128: minutes periods.
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
139: was started, rounded up to the next full minutes period, is
140: .Ar n
141: minutes periods.
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
218: was started, rounded up to the next full minutes period, is
219: .Ar n
220: minutes periods.
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.
267: .It Ic -perm Op Fl Ns Ar mode
268: The
269: .Ar mode
270: may be either symbolic (see
271: .Xr chmod 1 )
272: or an octal number.
273: If the mode is symbolic, a starting value of zero is assumed and the
1.16 aaron 274: mode sets or clears permissions without regard to the process's file mode
1.1 deraadt 275: creation mask.
276: If the mode is octal, only bits 07777
277: .Pf ( Dv S_ISUID
278: |
279: .Dv S_ISGID
280: |
281: .Dv S_ISTXT
282: |
283: .Dv S_IRWXU
284: |
285: .Dv S_IRWXG
286: |
287: .Dv S_IRWXO )
288: of the file's mode bits participate
289: in the comparison.
290: If the mode is preceded by a dash (``\-''), this primary evaluates to true
291: if at least all of the bits in the mode are set in the file's mode bits.
1.16 aaron 292: If the mode is not preceded by a dash (``\-''), this primary evaluates to
293: true if the bits in the mode exactly match the file's mode bits.
1.1 deraadt 294: Note, the first character of a symbolic mode may not be a dash (``\-'').
295: .It Ic -print
296: This primary always evaluates to true.
297: It prints the pathname of the current file to standard output, followed
1.16 aaron 298: by a newline (``\en'') character.
1.1 deraadt 299: If neither
300: .Ic -exec ,
301: .Ic -ls ,
302: .Ic -ok ,
303: nor
304: .Ic -print0
305: is specified, the given expression shall be effectively replaced by
306: .Cm \&( Ns Ar given\& expression Ns Cm \&)
307: .Ic -print .
308: .It Ic -print0
309: This primary always evaluates to true.
310: It prints the pathname of the current file to standard output, followed
311: by a null character.
312: .It Ic -prune
313: This primary always evaluates to true.
314: It causes
315: .Nm find
316: to not descend into the current file.
317: Note, the
318: .Ic -prune
319: primary has no effect if the
320: .Fl d
321: option was specified.
322: .It Ic -size Ar n Ns Op Cm c
323: True if the file's size, rounded up, in 512\-byte blocks is
324: .Ar n .
325: If
326: .Ar n
327: is followed by a ``c'', then the primary is true if the
328: file's size is
329: .Ar n
330: bytes.
331: .It Ic -type Ar t
332: True if the file is of the specified type.
333: Possible file types are as follows:
334: .Pp
335: .Bl -tag -width flag -offset indent -compact
1.3 deraadt 336: .It Cm W
1.19 ! espie 337: whiteout (currently, these won't even be visible without also specifying
! 338: .Fl W )
1.1 deraadt 339: .It Cm b
340: block special
341: .It Cm c
342: character special
343: .It Cm d
344: directory
345: .It Cm f
346: regular file
347: .It Cm l
348: symbolic link
349: .It Cm p
350: FIFO
351: .It Cm s
352: socket
353: .El
354: .Pp
355: .It Ic -user Ar uname
356: True if the file belongs to the user
357: .Ar uname .
358: If
359: .Ar uname
360: is numeric and there is no such user name, then
361: .Ar uname
1.16 aaron 362: is treated as a user ID.
1.1 deraadt 363: .El
364: .Pp
365: All primaries which take a numeric argument allow the number to be
366: preceded by a plus sign (``+'') or a minus sign (``\-'').
367: A preceding plus sign means ``more than n'', a preceding minus sign means
1.16 aaron 368: ``less than n'', and neither means ``exactly n'' .
1.1 deraadt 369: .Sh OPERATORS
370: The primaries may be combined using the following operators.
371: The operators are listed in order of decreasing precedence.
372: .Bl -tag -width (expression)
373: .It Cm \&( Ns Ar expression Ns Cm \&)
374: This evaluates to true if the parenthesized expression evaluates to
375: true.
376: .Pp
377: .It Cm \&! Ns Ar expression
378: This is the unary
379: .Tn NOT
380: operator.
381: It evaluates to true if the expression is false.
382: .Pp
383: .It Ar expression Cm -and Ar expression
384: .It Ar expression expression
385: The
386: .Cm -and
387: operator is the logical
388: .Tn AND
389: operator.
390: As it is implied by the juxtaposition of two expressions it does not
391: have to be specified.
392: The expression evaluates to true if both expressions are true.
393: The second expression is not evaluated if the first expression is false.
394: .Pp
395: .It Ar expression Cm -or Ar expression
396: The
397: .Cm -or
398: operator is the logical
399: .Tn OR
400: operator.
401: The expression evaluates to true if either the first or the second expression
402: is true.
403: The second expression is not evaluated if the first expression is true.
404: .El
405: .Pp
406: All operands and primaries must be separate arguments to
407: .Nm find .
408: Primaries which themselves take arguments expect each argument
409: to be a separate argument to
410: .Nm find .
411: .Sh EXAMPLES
412: The following examples are shown as given to the shell:
413: .Bl -tag -width findx
414: .It Li "find / \e! -name \*q*.c\*q -print"
415: Print out a list of all the files whose names do not end in ``.c''.
416: .It Li "find / -newer ttt -user wnj -print"
417: Print out a list of all the files owned by user ``wnj'' that are newer
418: than the file ``ttt''.
419: .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
420: Print out a list of all the files which are not both newer than ``ttt''
421: and owned by ``wnj''.
422: .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
423: Print out a list of all the files that are either owned by ``wnj'' or
424: that are newer than ``ttt''.
425: .El
426: .Sh SEE ALSO
427: .Xr chmod 1 ,
428: .Xr locate 1 ,
429: .Xr stat 2 ,
430: .Xr fts 3 ,
1.16 aaron 431: .Xr getgrent 3 ,
1.1 deraadt 432: .Xr getpwent 3 ,
433: .Xr strmode 3 ,
434: .Xr symlink 7
435: .Sh STANDARDS
436: The
437: .Nm find
438: utility syntax is a superset of the syntax specified by the
439: .St -p1003.2
440: standard.
441: .Pp
1.13 deraadt 442: The options and primaries
1.18 deraadt 443: .Ic -amin ,
444: .Ic -cmin ,
1.9 tholo 445: .Ic -empty ,
1.1 deraadt 446: .Ic -follow ,
447: .Ic -fstype ,
1.2 deraadt 448: .Ic -inum ,
1.1 deraadt 449: .Ic -links ,
1.9 tholo 450: .Ic -ls ,
1.18 deraadt 451: .Ic -mmin ,
1.9 tholo 452: .Ic -maxdepth ,
1.13 deraadt 453: .Ic -mindepth ,
454: .Ic -execdir ,
1.1 deraadt 455: and
456: .Ic -print0
1.13 deraadt 457: are extensions to
1.1 deraadt 458: .St -p1003.2 .
459: .Pp
460: Historically, the
461: .Fl d ,
1.14 deraadt 462: .Fl H
1.1 deraadt 463: and
464: .Fl x
1.14 deraadt 465: options were implemented using the primaries
466: .Ic -depth ,
467: .Ic -follow ,
468: and
469: .Ic -xdev .
1.1 deraadt 470: These primaries always evaluated to true.
471: As they were really global variables that took effect before the traversal
472: began, some legal expressions could have unexpected results.
473: An example is the expression ``\-print \-o \-depth''.
474: As \-print always evaluates to true, the standard order of evaluation
475: implies that \-depth would never be evaluated.
476: This is not the case.
477: .Pp
478: The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''
479: was implemented as ``\-a''.
480: .Pp
481: Historic implementations of the
482: .Ic -exec
483: and
484: .Ic -ok
485: primaries did not replace the string ``{}'' in the utility name or the
486: utility arguments if it had preceding or following non-whitespace characters.
487: This version replaces it no matter where in the utility name or arguments
488: it appears.
489: .Sh BUGS
490: The special characters used by
491: .Nm find
492: are also special characters to many shell programs.
493: In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
494: ``!'', ``\e'' and ``;'' may have to be escaped from the shell.
495: .Pp
496: As there is no delimiter separating options and file names or file
497: names and the
498: .Ar expression ,
499: it is difficult to specify files named ``-xdev'' or ``!''.
500: These problems are handled by the
501: .Fl f
502: option and the
503: .Xr getopt 3
504: ``--'' construct.
1.19 ! espie 505: .Pp
! 506: The
! 507: .Fl W
! 508: option is probably not the most elegant way to handle whiteouts, it may
! 509: 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