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