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