![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to find.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / usr.bin / find|
Return to find.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / usr.bin / find |
1.1 root 1: .\" Copyright (c) 1990 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)find.1 6.15 (Berkeley) 7/24/90
19: .\"
20: .Dd July 24, 1990
21: .Dt FIND 1
22: .Os BSD 4.4
23: .Sh NAME
24: .Nm find
25: .Nd walk a file hierarchy
26: .Sh SYNOPSIS
27: .Nm find
28: .Op Fl dsx
29: .Op Ar path
30: .Ar expression
31: .Nm find
32: .Op Fl dsx
33: .Op Fl f Ar path
34: .Ar expression
35: .Sh DESCRIPTION
36: .Nm Find
37: recursively descends the directory tree for each
38: .Ar path
39: listed, evaluating an
40: .Ar expression
41: (composed of the ``primaries'' and ``operands'' listed below) in terms
42: of each file in the tree.
43: .Pp
44: The options are as follows:
45: .Pp
46: .Tw Ds
47: .Tp Fl d
48: The
49: .Fl d
50: option causes find to perform a depth\-first traversal, i.e. directories
51: are visited in post\-order and all entries in a directory will be acted
52: on before the directory itself.
53: By default,
54: .Nm find
55: visits directories in pre\-order, i.e. before their contents.
56: Note, the default is
57: .Ar not
58: a breadth\-first traversal.
59: .Tp Fl f
60: The
61: .Fl f
62: option specifies a file hierarchy for
63: .Nm find
64: to traverse.
65: If no
66: .Fl f
67: option is specified, the first operand after the options is
68: expected to be the file hierarchy to be traversed.
69: .Tp Fl s
70: The
71: .Fl s
72: option causes the file information and file type (see
73: .Xr stat 2 ) ,
74: returned for each symbolic link to be those of the file referenced by the
75: link, not the link itself.
76: If the referenced file does not exist, the file information and type will
77: be for the link itself.
78: .Tp Fl x
79: The
80: .Fl x
81: option prevents
82: .Nm find
83: from descending into directories that have a device number different
84: than that of the file from which the descent began.
85: .Tp
86: .Sh PRIMARIES
87: .Tw Ds
88: .Tp Cx Ic atime
89: .Cx \&\ \&
90: .Ar n
91: .Cx
92: True if the difference between the file last access time and the time
93: .Nm find
94: was started, rounded up to the next full 24\-hour period, is
95: .Ar n
96: 24\-hour periods.
97: .Tp Cx Ic ctime
98: .Cx \&\ \&
99: .Ar n
100: .Cx
101: True if the difference between the time of last change of file status
102: information and the time
103: .Nm find
104: was started, rounded up to the next full 24\-hour period, is
105: .Ar n
106: 24\-hour periods.
107: .Tp Cx Ic exec
108: .Cx \&\ \&
109: .Ar utility
110: .Cx \&\ \&
111: .Op argument ... ;
112: .Cx
113: True if the program named
114: .Ar utility
115: returns a zero value as its exit status.
116: Optional arguments may be passed to the utility.
117: The expression must be terminated by a semicolon (``;'').
118: If the string ``{}'' appears anywhere in the utility name or the
119: arguments it is replaced by the pathname of the current file.
120: Utility will be executed in the directory from which
121: .Nm find
122: was executed.
123: .Tp Cx Ic fstype
124: .Cx \&\ \&
125: .Ar type
126: .Cx
127: True if the file is contained in a file system of type
128: .Ar type .
129: Currently supported types are ``local'', ``mfs'', ``nfs'', ``pc'' and
130: ``ufs''.
131: The type ``local'' is not a specific file system type, but matches
132: any file system physically mounted on the system where the
133: .Nm find
134: is being executed.
135: .Tp Cx Ic group
136: .Cx \&\ \&
137: .Ar gname
138: .Cx
139: True if the file belongs to the group
140: .Ar gname .
141: If
142: .Ar gname
143: is numeric and there is no such group name, then
144: .Ar gname
145: is treated as a group id.
146: .Tp Cx Ic inum
147: .Cx \&\ \&
148: .Ar n
149: .Cx
150: True if the file has inode number
151: .Ar n .
152: .Tp Cx Ic links
153: .Cx \&\ \&
154: .Ar n
155: .Cx
156: True if the file has
157: .Ar n
158: links.
159: .Tp Ic ls
160: This primary always evaluates to true.
161: The following information for the current file is written to standard output:
162: its inode number, size in 512\-byte blocks, file permissions, number of hard
163: links, owner, group, size in bytes, last modification time, and pathname.
164: If the file is a block or character special file, the major and minor numbers
165: will be displayed instead of the size in bytes.
166: If the file is a symbolic link, the pathname of the linked\-to file will be
167: displayed preceded by ``\->''.
168: The format is identical to that produced by ``ls \-dgils''.
169: .Tp Cx Ic mtime
170: .Cx \&\ \&
171: .Ar n
172: .Cx
173: True if the difference between the file last modification time and the time
174: .Nm find
175: was started, rounded up to the next full 24\-hour period, is
176: .Ar n
177: 24\-hour periods.
178: .Tp Cx Ic \&ok
179: .Cx \&\ \&
180: .Ar utility
181: .Ws
182: .Op argument ... ;
183: .Cx
184: The
185: .Ic \&ok
186: primary is identical to the
187: .Ic exec
188: primary with the exception that
189: .Nm find
190: requests user affirmation for the execution of the utility by printing
191: a message to the terminal and reading a response.
192: If the response is other than ``y'' the command is not executed and the
193: value of the
194: .Ar \&ok
195: expression is false.
196: .Tp Cx Ic name
197: .Cx \&\ \&
198: .Ar pattern
199: .Cx
200: True if the last component of the pathname being examined matches
201: .Ar pattern .
202: Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
203: may be used as part of
204: .Ar pattern .
205: These characters may be matched explicitly by escaping them with a
206: backslash (``\e'').
207: .Tp Cx Ic newer
208: .Cx \&\ \&
209: .Ar file
210: .Cx
211: True if the current file has a more recent last modification time than
212: .Ar file .
213: .Tp Ic nouser
214: True if the file belongs to an unknown user.
215: .Tp Ic nogroup
216: True if the file belongs to an unknown group.
217: .Tp Cx Ic perm
218: .Cx \&\ \&
219: .Op Fl
220: .Ar mode
221: .Cx
222: The
223: .Ar mode
224: may be either symbolic (see
225: .Xr chmod 1 )
226: or an octal number.
227: If the mode is symbolic, a starting value of zero is assumed and the
228: mode sets or clears permissions without regard to the process' file mode
229: creation mask.
230: If the mode is octal, only bits 07777 of the file's mode bits participate
231: in the comparison.
232: If the mode is preceded by a dash (``\-''), this primary evaluates to true
233: if at least all of the bits in the mode are set in the file's mode bits.
234: If the mode is not preceded by a dash, this primary evaluates to true if
235: the bits in the mode exactly match the file's mode bits.
236: Note, the first character of a symbolic mode may not be a dash (``\-'').
237: .Tp Ic print
238: This primary always evaluates to true.
239: It prints the pathname of the current file to standard output.
240: The expression is appended to the user specified expression if neither
241: .Ic exec ,
242: .Ic ls ,
243: or
244: .Ic \&ok
245: is specified.
246: .Tp Ic prune
247: This primary always evaluates to true.
248: It causes
249: .Nm find
250: to not descend into the current file.
251: .Tp Cx Ic size
252: .Cx \&\ \&
253: .Ar n
254: .Op Cm c
255: .Cx
256: True if the file's size, rounded up, in 512\-byte blocks is
257: .Ar n .
258: If
259: .Ar n
260: is followed by a ``c'', then the primary is true if the
261: file's size is
262: .Ar n
263: bytes.
264: .Tp Cx Ic type
265: .Cx \&\ \&
266: .Ar t
267: .Cx
268: True if the file is of the specified type.
269: Possible file types are as follows:
270: .Pp
271: .Df I
272: .Tw Ds
273: .Tp Cm b
274: block special
275: .Tp Cm c
276: character special
277: .Tp Cm d
278: directory
279: .Tp Cm f
280: regular file
281: .Tp Cm l
282: symbolic link
283: .Tp Cm p
284: FIFO
285: .Tp Cm s
286: socket
287: .Tp
288: .De
289: .Pp
290: .Tp Cx Ic user
291: .Cx \&\ \&
292: .Ar uname
293: .Cx
294: True if the file belongs to the user
295: .Ar uname .
296: If
297: .Ar uname
298: is numeric and there is no such user name, then
299: .Ar uname
300: is treated as a user id.
301: .Tp
302: .Pp
303: All primaries which take a numeric argument allow the number to be
304: preceded by a plus sign (``+'') or a minus sign (``\-'').
305: A preceding plus sign means ``more than
306: .Ar n ' ' ,
307: a preceding minus sign means ``less than
308: .Ar n ' '
309: and neither means ``exactly
310: .Ar n ' ' .
311: .Sh OPERATORS
312: The primaries may be combined using the following operators.
313: The operators are listed in order of decreasing precedence.
314: .Di L
315: .Dp Cx Ic \&(
316: .Ar expression
317: .Cx \&)
318: .Cx
319: This evaluates to true if the parenthesized expression evaluates to
320: true.
321: .Pp
322: .Dp Cx Ic \&!
323: .Cx \&\ \&
324: .Ar expression
325: .Cx
326: This is the unary NOT operator.
327: It evaluates to true if the expression is false.
328: .Pp
329: .Dp Cx Ar expression
330: .Cx \&\ \&
331: .Ic and
332: .Cx \&\ \&
333: .Ar expression
334: .Cx
335: .Dp Cx Ar expression expression
336: .Cx
337: The
338: .Ic and
339: operator is the logical AND operator.
340: As it is implied by the juxtaposition of two expressions it does not
341: have to be specified.
342: The expression evaluates to true if both expressions are true.
343: The second expression is not evaluated if the first expression is false.
344: .Pp
345: .Dp Cx Ar expression
346: .Cx \&\ \&
347: .Ic or
348: .Cx \&\ \&
349: .Ar expression
350: .Cx
351: The
352: .Ic or
353: operator is the logical OR operator.
354: The expression evaluates to true if either the first or the second expression
355: is true.
356: The second expression is not evaluated if the first expression is true.
357: .Dp
358: .Pp
359: All operands and primaries must be separate arguments to
360: .Nm find .
361: Primaries which themselves take arguments expect each argument
362: to be a separate argument to
363: .Nm find .
364: .Sh EXAMPLES
365: .Pp
366: The following examples are shown as given to the shell:
367: .Tw findx
368: .Tp Li find / \e! name "*.c" print
369: Print out a list of all the files whose names do not end in ``.c''.
370: .Tp Li find / newer ttt user wnj print
371: Print out a list of all the files owned by user ``wnj'' that are newer
372: than the file ``ttt''.
373: .Tp Li find / \e! \e( newer ttt user wnj \e) print
374: Print out a list of all the files which are not both newer than ``ttt''
375: and owned by ``wnj''.
376: .Tp Li find / \e( newer ttt or user wnj \e) print
377: Print out a list of all the files that are either owned by ``wnj'' or
378: that are newer than ``ttt''.
379: .Tp
380: .Sh SEE ALSO
381: .Xr chmod 1 ,
382: .Xr sh 1 ,
383: .Xr test 1 ,
384: .Xr stat 2 ,
385: .Xr umask 2 ,
386: .Xr getpwent 3 ,
387: .Xr getgrent 3 ,
388: .Xr strmode 3
389: .Sh STANDARDS
390: The
391: .Nm find
392: utility syntax is a replacement for the syntax specified by the POSIX
393: 1003.2 standard.
394: The standard syntax is also supported; see the COMPATIBILITY section
395: below for details.
396: .Pp
397: The
398: .Fl s
399: option as well as the primaries
400: .Ic inum
401: and
402: .Ic ls
403: are extensions to the POSIX standard.
404: .Sh COMPATIBILITY
405: The traditional, and standardized, syntax for
406: .Nm find
407: is as follows.
408: All of the primaries are preceded by a dash (``\-''), i.e. the
409: primary ``group'' is specified as ``\-group''.
410: The
411: .Fl d ,
412: .Fl s ,
413: and
414: .Fl x
415: options are implemented using the primaries ``\-depth'', ``\-follow'',
416: and ``\-xdev''.
417: These primaries always evaluate to true.
418: The operator ``or'' is implemented as ``\-o'', and the operator
419: ``and'' is implemented as ``\-a''.
420: The set of file trees to be traversed are specified as the first operands
421: to
422: .Nm find .
423: The first operand beginning with a dash (``\-''), exclamation point (``!'')
424: or left parenthesis (``('') is assumed to be the beginning of the expression
425: and the end of the files to be traversed.
426: .Pp
427: The
428: .Nm find
429: syntax was changed for two reasons.
430: The first is that the ``\-depth'', ``\-follow'' and ``\-xdev'' primaries
431: are really global variables that take effect before the traversal begins.
432: This causes some legal expressions to have unexpected results.
433: An example is the expression ``\-print \-o \-depth''.
434: As \-print always evaluates to true, the standard order of evaluation
435: implies that \-depth would never be evaluated.
436: This is not the case.
437: .Pp
438: The second reason is that traversing file trees with names beginning with
439: a dash, exclamation point or left parenthesis was impossible.
440: .Sh BUGS
441: The special characters used by
442: .Nm find
443: are also special characters to many shell programs.
444: In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
445: ``!'', ``\e'' and ``;'' may have to be escaped from the shell.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.