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