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