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