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