1 .\" $NetBSD: find.1,v 1.14 1998/05/27 13:15:30 msaitoh Exp $
3 .\" Copyright (c) 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" This code is derived from software contributed to Berkeley by
7 .\" the Institute of Electrical and Electronics Engineers, Inc.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. All advertising materials mentioning features or use of this software
18 .\" must display the following acknowledgement:
19 .\" This product includes software developed by the University of
20 .\" California, Berkeley and its contributors.
21 .\" 4. Neither the name of the University nor the names of its contributors
22 .\" may be used to endorse or promote products derived from this software
23 .\" without specific prior written permission.
25 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
37 .\" from: @(#)find.1 8.7 (Berkeley) 5/9/95
44 .Nd walk a file hierarchy
47 .Op Fl H | Fl L | Fl P
54 recursively descends the directory tree for each
58 (composed of the ``primaries'' and ``operands'' listed below) in terms
59 of each file in the tree.
61 The options are as follows:
67 option causes the file information and file type (see
69 returned for each symbolic link encountered on the command line to be
70 those of the file referenced by the link, not the link itself.
71 If the referenced file does not exist, the file information and type will
72 be for the link itself. File information of all symbolic links not on
73 the command line is that of the link itself.
77 option causes the file information and file type (see
79 returned for each symbolic link to be those of the file referenced by the
80 link, not the link itself.
81 If the referenced file does not exist, the file information and type will
82 be for the link itself.
86 option causes the file information and file type (see
88 returned for each symbolic link to be those of the link itself.
92 option is a modification to permit
94 to be safely used in conjunction with
96 If a file name contains any of the delimiting characters used by
98 a diagnostic message is displayed on standard error, and the file
100 The delimiting characters include single (`` ' '') and double (`` " '')
101 quotes, backslash (``\e''), space, tab and newline characters.
107 to perform a depth\-first traversal, i.e. directories
108 are visited in post\-order and all entries in a directory will be acted
109 on before the directory itself.
112 visits directories in pre\-order, i.e. before their contents.
115 a breadth\-first traversal.
119 option specifies a file hierarchy for
122 File hierarchies may also be specified as the operands immediately
123 following the options.
127 option causes the file information and file type (see
129 returned for each symbolic link to be those of the file referenced by the
130 link, not the link itself.
131 If the referenced file does not exist, the file information and type will
132 be for the link itself.
138 from descending into directories that have a device number different
139 than that of the file from which the descent began.
144 True if the difference between the file last access time and the time
146 was started, rounded up to the next full 24\-hour period, is
150 True if the difference between the time of last change of file status
151 information and the time
153 was started, rounded up to the next full 24\-hour period, is
156 .It Ic -exec Ar utility Op argument ... ;
157 True if the program named
159 returns a zero value as its exit status.
160 Optional arguments may be passed to the utility.
161 The expression must be terminated by a semicolon (``;'').
162 If the string ``{}'' appears anywhere in the utility name or the
163 arguments it is replaced by the pathname of the current file.
165 will be executed from the directory from which
169 Follow symbolic links.
170 .It Ic -fstype Ar type
171 True if the file is contained in a file system of type
175 command can be used to find out the types of filesystems
176 that are available on the system:
177 .Bd -literal -offset indent
180 In addition, there are two pseudo-types, ``local'' and ``rdonly''.
181 The former matches any file system physically mounted on the system where
184 is being executed, and the latter matches any file system which is
186 .It Ic -group Ar gname
187 True if the file belongs to the group
191 is numeric and there is no such group name, then
193 is treated as a group id.
195 True if the file has inode number
202 This primary always evaluates to true.
203 The following information for the current file is written to standard output:
204 its inode number, size in 512\-byte blocks, file permissions, number of hard
205 links, owner, group, size in bytes, last modification time, and pathname.
206 If the file is a block or character special file, the major and minor numbers
207 will be displayed instead of the size in bytes.
208 If the file is a symbolic link, the pathname of the linked\-to file will be
209 displayed preceded by ``\->''.
210 The format is identical to that produced by ``ls \-dgils''.
212 True if the difference between the file last modification time and the time
214 was started, rounded up to the next full 24\-hour period, is
217 .It Ic \&-ok Ar utility Op argument ... ;
220 primary is identical to the
222 primary with the exception that
224 requests user affirmation for the execution of the utility by printing
225 a message to the terminal and reading a response.
226 If the response is other than ``y'' the command is not executed and the
230 .It Ic -name Ar pattern
231 True if the last component of the pathname being examined matches
233 Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
234 may be used as part of
236 These characters may be matched explicitly by escaping them with a
238 .It Ic -newer Ar file
239 True if the current file has a more recent last modification time than
242 True if the file belongs to an unknown user.
244 True if the file belongs to an unknown group.
245 .It Ic -path Ar pattern
246 True if the pathname being examined matches
248 Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'')
249 may be used as part of
251 These characters may be matched explicitly by escaping them with a
253 Slashes (``/'') are treated as normal characters and do not have to be
255 .It Ic -perm Op Fl Ns Ar mode
258 may be either symbolic (see
261 If the mode is symbolic, a starting value of zero is assumed and the
262 mode sets or clears permissions without regard to the process' file mode
264 If the mode is octal, only bits 07777
276 of the file's mode bits participate
278 If the mode is preceded by a dash (``\-''), this primary evaluates to true
279 if at least all of the bits in the mode are set in the file's mode bits.
280 If the mode is not preceded by a dash, this primary evaluates to true if
281 the bits in the mode exactly match the file's mode bits.
282 Note, the first character of a symbolic mode may not be a dash (``\-'').
284 This primary always evaluates to true.
285 It prints the pathname of the current file to standard output, followed
286 by a newline character.
293 is specified, the given expression shall be effectively replaced by
294 .Cm \&( Ns Ar given\& expression Ns Cm \&)
297 This primary always evaluates to true.
298 It prints the pathname of the current file to standard output, followed
301 This primary always evaluates to true.
304 to not descend into the current file.
307 primary has no effect if the
309 option was specified.
310 .It Ic -size Ar n Ns Op Cm c
311 True if the file's size, rounded up, in 512\-byte blocks is
315 is followed by a ``c'', then the primary is true if the
320 True if the file is of the specified type.
321 Possible file types are as follows:
323 .Bl -tag -width flag -offset indent -compact
342 .It Ic -user Ar uname
343 True if the file belongs to the user
347 is numeric and there is no such user name, then
349 is treated as a user id.
352 All primaries which take a numeric argument allow the number to be
353 preceded by a plus sign (``+'') or a minus sign (``\-'').
354 A preceding plus sign means ``more than n'', a preceding minus sign means
355 ``less than n'' and neither means ``exactly n'' .
357 The primaries may be combined using the following operators.
358 The operators are listed in order of decreasing precedence.
359 .Bl -tag -width (expression)
360 .It Cm \&( Ns Ar expression Ns Cm \&)
361 This evaluates to true if the parenthesized expression evaluates to
364 .It Cm \&! Ns Ar expression
368 It evaluates to true if the expression is false.
370 .It Ar expression Cm -and Ar expression
371 .It Ar expression expression
374 operator is the logical
377 As it is implied by the juxtaposition of two expressions it does not
378 have to be specified.
379 The expression evaluates to true if both expressions are true.
380 The second expression is not evaluated if the first expression is false.
382 .It Ar expression Cm -or Ar expression
385 operator is the logical
388 The expression evaluates to true if either the first or the second expression
390 The second expression is not evaluated if the first expression is true.
393 All operands and primaries must be separate arguments to
395 Primaries which themselves take arguments expect each argument
396 to be a separate argument to
400 The following examples are shown as given to the shell:
401 .Bl -tag -width findx
402 .It Li "find / \e! -name \*q*.c\*q -print"
403 Print out a list of all the files whose names do not end in ``.c''.
404 .It Li "find / -newer ttt -user wnj -print"
405 Print out a list of all the files owned by user ``wnj'' that are newer
406 than the file ``ttt''.
407 .It Li "find / \e! \e( -newer ttt -user wnj \e) -print"
408 Print out a list of all the files which are not both newer than ``ttt''
409 and owned by ``wnj''.
410 .It Li "find / \e( -newer ttt -or -user wnj \e) -print"
411 Print out a list of all the files that are either owned by ``wnj'' or
412 that are newer than ``ttt''.
426 utility syntax is a superset of the syntax specified by the
438 primaries are extensions to
446 options were implemented using the primaries ``\-depth'', ``\-follow'',
448 These primaries always evaluated to true.
449 As they were really global variables that took effect before the traversal
450 began, some legal expressions could have unexpected results.
451 An example is the expression ``\-print \-o \-depth''.
452 As \-print always evaluates to true, the standard order of evaluation
453 implies that \-depth would never be evaluated.
454 This is not the case.
456 The operator ``-or'' was implemented as ``\-o'', and the operator ``-and''
457 was implemented as ``\-a''.
459 Historic implementations of the
463 primaries did not replace the string ``{}'' in the utility name or the
464 utility arguments if it had preceding or following non-whitespace characters.
465 This version replaces it no matter where in the utility name or arguments
468 The special characters used by
470 are also special characters to many shell programs.
471 In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'',
472 ``!'', ``\e'' and ``;'' may have to be escaped from the shell.
474 As there is no delimiter separating options and file names or file
477 it is difficult to specify files named ``-xdev'' or ``!''.
478 These problems are handled by the
projects / apple / shell_cmds.git / blob