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