Annotation of src/usr.bin/find/find.1, Revision 1.3
1.1 deraadt 1: .\" Copyright (c) 1990, 1993
2: .\" The Regents of the University of California. All rights reserved.
3: .\"
4: .\" This code is derived from software contributed to Berkeley by
5: .\" the Institute of Electrical and Electronics Engineers, Inc.
6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
15: .\" 3. All advertising materials mentioning features or use of this software
16: .\" must display the following acknowledgement:
17: .\" This product includes software developed by the University of
18: .\" California, Berkeley and its contributors.
19: .\" 4. Neither the name of the University nor the names of its contributors
20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" from: @(#)find.1 8.1 (Berkeley) 6/6/93
1.3 ! deraadt 36: .\" $Id: find.1,v 1.2 1996/01/15 01:11:16 deraadt Exp $
1.1 deraadt 37: .\"
38: .Dd June 6, 1993
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.
116: .It Fl x
117: The
118: .Fl x
119: option prevents
120: .Nm find
121: from descending into directories that have a device number different
122: than that of the file from which the descent began.
123: .El
124: .Sh PRIMARIES
125: .Bl -tag -width Ds
126: .It Ic -atime Ar n
127: True if the difference between the file last access time and the time
128: .Nm find
129: was started, rounded up to the next full 24\-hour period, is
130: .Ar n
131: 24\-hour periods.
132: .It Ic -ctime Ar n
133: True if the difference between the time of last change of file status
134: information 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 -exec Ar utility Op argument ... ;
140: True if the program named
141: .Ar utility
142: returns a zero value as its exit status.
143: Optional arguments may be passed to the utility.
144: The expression must be terminated by a semicolon (``;'').
145: If the string ``{}'' appears anywhere in the utility name or the
146: arguments it is replaced by the pathname of the current file.
147: .Ar Utility
148: will be executed from the directory from which
149: .Nm find
150: was executed.
1.2 deraadt 151: .It Ic -follow
152: Follow symbolic links.
1.1 deraadt 153: .It Ic -fstype Ar type
154: True if the file is contained in a file system of type
155: .Ar type .
156: Two special file system types are recognized: ``local'' and ``rdonly''.
157: These do not describe actual file system types;
158: the former matches any file system physically mounted on the system where
159: the
160: .Nm find
161: is being executed, and the latter matches any file system which is
162: mounted read-only.
163: .It Ic -group Ar gname
164: True if the file belongs to the group
165: .Ar gname .
166: If
167: .Ar gname
168: is numeric and there is no such group name, then
169: .Ar gname
170: is treated as a group id.
171: .It Ic -inum Ar n
172: True if the file has inode number
173: .Ar n .
174: .It Ic -links Ar n
175: True if the file has
176: .Ar n
177: links.
178: .It Ic -ls
179: This primary always evaluates to true.
180: The following information for the current file is written to standard output:
181: its inode number, size in 512\-byte blocks, file permissions, number of hard
182: links, owner, group, size in bytes, last modification time, and pathname.
183: If the file is a block or character special file, the major and minor numbers
184: will be displayed instead of the size in bytes.
185: If the file is a symbolic link, the pathname of the linked\-to file will be
186: displayed preceded by ``\->''.
187: The format is identical to that produced by ``ls \-dgils''.
188: .It Ic -mtime Ar n
189: True if the difference between the file last modification time and the time
190: .Nm find
191: was started, rounded up to the next full 24\-hour period, is
192: .Ar n
193: 24\-hour periods.
194: .It Ic \&-ok Ar utility Ns Op argument ... ;
195: The
196: .Ic \&-ok
197: primary is identical to the
198: .Ic -exec
199: primary with the exception that
200: .Nm find
201: requests user affirmation for the execution of the utility by printing
202: a message to the terminal and reading a response.
203: If the response is other than ``y'' the command is not executed and the
204: value of the
205: .Ar \&ok
206: expression is false.
207: .It Ic -name Ar pattern
208: True if the last component of the pathname being examined matches
209: .Ar pattern .
210: Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
211: may be used as part of
212: .Ar pattern .
213: These characters may be matched explicitly by escaping them with a
214: backslash (``\e'').
215: .It Ic -newer Ar file
216: True if the current file has a more recent last modification time than
217: .Ar file .
218: .It Ic -nouser
219: True if the file belongs to an unknown user.
220: .It Ic -nogroup
221: True if the file belongs to an unknown group.
222: .It Ic -path Ar pattern
223: True if the pathname being examined matches
224: .Ar pattern .
225: Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
226: may be used as part of
227: .Ar pattern .
228: These characters may be matched explicitly by escaping them with a
229: backslash (``\e'').
230: Slashes (``/'') are treated as normal characters and do not have to be
231: matched explicitly.
232: .It Ic -perm Op Fl Ns Ar mode
233: The
234: .Ar mode
235: may be either symbolic (see
236: .Xr chmod 1 )
237: or an octal number.
238: If the mode is symbolic, a starting value of zero is assumed and the
239: mode sets or clears permissions without regard to the process' file mode
240: creation mask.
241: If the mode is octal, only bits 07777
242: .Pf ( Dv S_ISUID
243: |
244: .Dv S_ISGID
245: |
246: .Dv S_ISTXT
247: |
248: .Dv S_IRWXU
249: |
250: .Dv S_IRWXG
251: |
252: .Dv S_IRWXO )
253: of the file's mode bits participate
254: in the comparison.
255: If the mode is preceded by a dash (``\-''), this primary evaluates to true
256: if at least all of the bits in the mode are set in the file's mode bits.
257: If the mode is not preceded by a dash, this primary evaluates to true if
258: the bits in the mode exactly match the file's mode bits.
259: Note, the first character of a symbolic mode may not be a dash (``\-'').
260: .It Ic -print
261: This primary always evaluates to true.
262: It prints the pathname of the current file to standard output, followed
263: by a newline character.
264: If neither
265: .Ic -exec ,
266: .Ic -ls ,
267: .Ic -ok ,
268: nor
269: .Ic -print0
270: is specified, the given expression shall be effectively replaced by
271: .Cm \&( Ns Ar given\& expression Ns Cm \&)
272: .Ic -print .
273: .It Ic -print0
274: This primary always evaluates to true.
275: It prints the pathname of the current file to standard output, followed
276: by a null character.
277: .It Ic -prune
278: This primary always evaluates to true.
279: It causes
280: .Nm find
281: to not descend into the current file.
282: Note, the
283: .Ic -prune
284: primary has no effect if the
285: .Fl d
286: option was specified.
287: .It Ic -size Ar n Ns Op Cm c
288: True if the file's size, rounded up, in 512\-byte blocks is
289: .Ar n .
290: If
291: .Ar n
292: is followed by a ``c'', then the primary is true if the
293: file's size is
294: .Ar n
295: bytes.
296: .It Ic -type Ar t
297: True if the file is of the specified type.
298: Possible file types are as follows:
299: .Pp
300: .Bl -tag -width flag -offset indent -compact
1.3 ! deraadt 301: .It Cm W
! 302: whiteout
1.1 deraadt 303: .It Cm b
304: block special
305: .It Cm c
306: character special
307: .It Cm d
308: directory
309: .It Cm f
310: regular file
311: .It Cm l
312: symbolic link
313: .It Cm p
314: FIFO
315: .It Cm s
316: socket
317: .El
318: .Pp
319: .It Ic -user Ar uname
320: True if the file belongs to the user
321: .Ar uname .
322: If
323: .Ar uname
324: is numeric and there is no such user name, then
325: .Ar uname
326: is treated as a user id.
327: .El
328: .Pp
329: All primaries which take a numeric argument allow the number to be
330: preceded by a plus sign (``+'') or a minus sign (``\-'').
331: A preceding plus sign means ``more than n'', a preceding minus sign means
332: ``less than n'' and neither means ``exactly n'' .
333: .Sh OPERATORS
334: The primaries may be combined using the following operators.
335: The operators are listed in order of decreasing precedence.
336: .Bl -tag -width (expression)
337: .It Cm \&( Ns Ar expression Ns Cm \&)
338: This evaluates to true if the parenthesized expression evaluates to
339: true.
340: .Pp
341: .It Cm \&! Ns Ar expression
342: This is the unary
343: .Tn NOT
344: operator.
345: It evaluates to true if the expression is false.
346: .Pp
347: .It Ar expression Cm -and Ar expression
348: .It Ar expression expression
349: The
350: .Cm -and
351: operator is the logical
352: .Tn AND
353: operator.
354: As it is implied by the juxtaposition of two expressions it does not
355: have to be specified.
356: The expression evaluates to true if both expressions are true.
357: The second expression is not evaluated if the first expression is false.
358: .Pp
359: .It Ar expression Cm -or Ar expression
360: The
361: .Cm -or
362: operator is the logical
363: .Tn OR
364: operator.
365: The expression evaluates to true if either the first or the second expression
366: is true.
367: The second expression is not evaluated if the first expression is true.
368: .El
369: .Pp
370: All operands and primaries must be separate arguments to
371: .Nm find .
372: Primaries which themselves take arguments expect each argument
373: to be a separate argument to
374: .Nm find .
375: .Sh EXAMPLES
376: .Pp
377: The following examples are shown as given to the shell:
378: .Bl -tag -width findx
379: .It Li "find / \e! -name \*q*.c\*q -print"
380: Print out a list of all the files whose names do not end in ``.c''.
381: .It Li "find / -newer ttt -user wnj -print"
382: Print out a list of all the files owned by user ``wnj'' that are newer
383: than the file ``ttt''.
384: .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
385: Print out a list of all the files which are not both newer than ``ttt''
386: and owned by ``wnj''.
387: .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
388: Print out a list of all the files that are either owned by ``wnj'' or
389: that are newer than ``ttt''.
390: .El
391: .Sh SEE ALSO
392: .Xr chmod 1 ,
393: .Xr locate 1 ,
394: .Xr stat 2 ,
395: .Xr fts 3 ,
396: .Xr getpwent 3 ,
397: .Xr getgrent 3 ,
398: .Xr strmode 3 ,
399: .Xr symlink 7
400: .Sh STANDARDS
401: The
402: .Nm find
403: utility syntax is a superset of the syntax specified by the
404: .St -p1003.2
405: standard.
406: .Pp
407: The options and the
408: .Ic -follow ,
409: .Ic -fstype ,
1.2 deraadt 410: .Ic -inum ,
1.1 deraadt 411: .Ic -links ,
412: .Ic -ls
413: and
414: .Ic -print0
415: primaries are extensions to
416: .St -p1003.2 .
417: .Pp
418: Historically, the
419: .Fl d ,
420: .Fl s
421: and
422: .Fl x
423: options were implemented using the primaries ``\-depth'', ``\-follow'',
424: and ``\-xdev''.
425: These primaries always evaluated to true.
426: As they were really global variables that took effect before the traversal
427: began, some legal expressions could have unexpected results.
428: An example is the expression ``\-print \-o \-depth''.
429: As \-print always evaluates to true, the standard order of evaluation
430: implies that \-depth would never be evaluated.
431: This is not the case.
432: .Pp
433: The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''
434: was implemented as ``\-a''.
435: .Pp
436: Historic implementations of the
437: .Ic -exec
438: and
439: .Ic -ok
440: primaries did not replace the string ``{}'' in the utility name or the
441: utility arguments if it had preceding or following non-whitespace characters.
442: This version replaces it no matter where in the utility name or arguments
443: it appears.
444: .Sh BUGS
445: The special characters used by
446: .Nm find
447: are also special characters to many shell programs.
448: In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
449: ``!'', ``\e'' and ``;'' may have to be escaped from the shell.
450: .Pp
451: As there is no delimiter separating options and file names or file
452: names and the
453: .Ar expression ,
454: it is difficult to specify files named ``-xdev'' or ``!''.
455: These problems are handled by the
456: .Fl f
457: option and the
458: .Xr getopt 3
459: ``--'' 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