Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1990 The Regents of the University of California. |
2 | .\" 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 | .\" @(#)find.1 6.29 (Berkeley) 7/29/91 | |
36 | .\" | |
37 | .Dd July 29, 1991 | |
38 | .Dt FIND 1 | |
39 | .Os | |
40 | .Sh NAME | |
41 | .Nm find | |
42 | .Nd walk a file hierarchy | |
43 | .Sh SYNOPSIS | |
44 | .Nm find | |
45 | .Op Fl dsXx | |
46 | .Op Fl f Ar file | |
47 | .Op Ar file ... | |
48 | .Ar expression | |
49 | .Sh DESCRIPTION | |
50 | .Nm Find | |
51 | recursively descends the directory tree for each | |
52 | .Ar file | |
53 | listed, evaluating an | |
54 | .Ar expression | |
55 | (composed of the ``primaries'' and ``operands'' listed below) in terms | |
56 | of each file in the tree. | |
57 | .Pp | |
58 | If | |
59 | .Ar file | |
60 | is a symbolic link referencing an existing file, the directory tree | |
61 | referenced by the link is descended instead of the link itself. | |
62 | .Pp | |
63 | The options are as follows: | |
64 | .Pp | |
65 | .Bl -tag -width Ds | |
66 | .It Fl d | |
67 | The | |
68 | .Fl d | |
69 | option causes | |
70 | .Nm find | |
71 | to perform a depth\-first traversal, i.e. directories | |
72 | are visited in post\-order and all entries in a directory will be acted | |
73 | on before the directory itself. | |
74 | By default, | |
75 | .Nm find | |
76 | visits directories in pre\-order, i.e. before their contents. | |
77 | Note, the default is | |
78 | .Ar not | |
79 | a breadth\-first traversal. | |
80 | .It Fl f | |
81 | The | |
82 | .Fl f | |
83 | option specifies a file hierarchy for | |
84 | .Nm find | |
85 | to traverse. | |
86 | File hierarchies may also be specified as the operands immediately | |
87 | following the options. | |
88 | .It Fl s | |
89 | The | |
90 | .Fl s | |
91 | option causes the file information and file type (see | |
92 | .Xr stat 2 ) , | |
93 | returned for each symbolic link to be those of the file referenced by the | |
94 | link, not the link itself. | |
95 | If the referenced file does not exist, the file information and type will | |
96 | be for the link itself. | |
97 | .It Fl X | |
98 | The | |
99 | .Fl X | |
100 | option is a modification to permit | |
101 | .Nm | |
102 | to be safely used in conjunction with | |
103 | .Xr xargs 1 . | |
104 | If a file name contains any of the delimiting characters used by | |
105 | .Xr xargs , | |
106 | a diagnostic message is displayed on standard error, and the file | |
107 | is skipped. | |
108 | The delimiting characters include single (`` ' '') and double (`` " '') | |
109 | quotes, backslash (``\e''), space, tab and newline characters. | |
110 | .It Fl x | |
111 | The | |
112 | .Fl x | |
113 | option prevents | |
114 | .Nm find | |
115 | from descending into directories that have a device number different | |
116 | than that of the file from which the descent began. | |
117 | .El | |
118 | .Sh PRIMARIES | |
119 | .Bl -tag -width Ds | |
120 | .It Ic -atime Ar n | |
121 | True if the difference between the file last access time and the time | |
122 | .Nm find | |
123 | was started, rounded up to the next full 24\-hour period, is | |
124 | .Ar n | |
125 | 24\-hour periods. | |
126 | .It Ic -ctime Ar n | |
127 | True if the difference between the time of last change of file status | |
128 | information and the time | |
129 | .Nm find | |
130 | was started, rounded up to the next full 24\-hour period, is | |
131 | .Ar n | |
132 | 24\-hour periods. | |
133 | .It Ic -exec Ar utility Op argument ... ; | |
134 | True if the program named | |
135 | .Ar utility | |
136 | returns a zero value as its exit status. | |
137 | Optional arguments may be passed to the utility. | |
138 | The expression must be terminated by a semicolon (``;''). | |
139 | If the string ``{}'' appears anywhere in the utility name or the | |
140 | arguments it is replaced by the pathname of the current file. | |
141 | .Ar Utility | |
142 | will be executed from the directory from which | |
143 | .Nm find | |
144 | was executed. | |
145 | .It Ic -fstype Ar type | |
146 | True if the file is contained in a file system of type | |
147 | .Ar type . | |
148 | Currently supported types are ``local'', ``mfs'', ``nfs'', ``msdos'', ``isofs'', | |
05806b6f | 149 | ``fdesc'', ``kernfs'', ``rdonly'' and ``ufs''. |
15637ed4 RG |
150 | The types ``local'' and ``rdonly'' are not specific file system types. |
151 | The former matches any file system physically mounted on the system where | |
152 | the | |
153 | .Nm find | |
154 | is being executed and the latter matches any file system which is | |
155 | mounted read-only. | |
156 | .It Ic -group Ar gname | |
157 | True if the file belongs to the group | |
158 | .Ar gname . | |
159 | If | |
160 | .Ar gname | |
161 | is numeric and there is no such group name, then | |
162 | .Ar gname | |
163 | is treated as a group id. | |
164 | .It Ic -inum Ar n | |
165 | True if the file has inode number | |
166 | .Ar n . | |
167 | .It Ic -links Ar n | |
168 | True if the file has | |
169 | .Ar n | |
170 | links. | |
171 | .It Ic -ls | |
172 | This primary always evaluates to true. | |
173 | The following information for the current file is written to standard output: | |
174 | its inode number, size in 512\-byte blocks, file permissions, number of hard | |
175 | links, owner, group, size in bytes, last modification time, and pathname. | |
176 | If the file is a block or character special file, the major and minor numbers | |
177 | will be displayed instead of the size in bytes. | |
178 | If the file is a symbolic link, the pathname of the linked\-to file will be | |
179 | displayed preceded by ``\->''. | |
180 | The format is identical to that produced by ``ls \-dgils''. | |
181 | .It Ic -mtime Ar n | |
182 | True if the difference between the file last modification time and the time | |
183 | .Nm find | |
184 | was started, rounded up to the next full 24\-hour period, is | |
185 | .Ar n | |
186 | 24\-hour periods. | |
187 | .It Ic \&-ok Ar utility Ns Op argument ... ; | |
188 | The | |
189 | .Ic \&-ok | |
190 | primary is identical to the | |
191 | .Ic -exec | |
192 | primary with the exception that | |
193 | .Nm find | |
194 | requests user affirmation for the execution of the utility by printing | |
195 | a message to the terminal and reading a response. | |
196 | If the response is other than ``y'' the command is not executed and the | |
197 | value of the | |
198 | .Ar \&ok | |
199 | expression is false. | |
200 | .It Ic -name Ar pattern | |
201 | True if the last component of the pathname being examined matches | |
202 | .Ar pattern . | |
203 | Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') | |
204 | may be used as part of | |
205 | .Ar pattern . | |
206 | These characters may be matched explicitly by escaping them with a | |
207 | backslash (``\e''). | |
208 | .It Ic -newer Ar file | |
209 | True if the current file has a more recent last modification time than | |
210 | .Ar file . | |
211 | .It Ic -nouser | |
212 | True if the file belongs to an unknown user. | |
213 | .It Ic -nogroup | |
214 | True if the file belongs to an unknown group. | |
215 | .It Ic -path Ar pattern | |
216 | True if the pathname being examined matches | |
217 | .Ar pattern . | |
218 | Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') | |
219 | may be used as part of | |
220 | .Ar pattern . | |
221 | These characters may be matched explicitly by escaping them with a | |
222 | backslash (``\e''). | |
223 | Slashes (``/'') are treated as normal characters and do not have to be | |
224 | matched explicitly. | |
225 | .It Ic -perm Op Fl Ns Ar mode | |
226 | The | |
227 | .Ar mode | |
228 | may be either symbolic (see | |
229 | .Xr chmod 1 ) | |
230 | or an octal number. | |
231 | If the mode is symbolic, a starting value of zero is assumed and the | |
232 | mode sets or clears permissions without regard to the process' file mode | |
233 | creation mask. | |
234 | If the mode is octal, only bits 07777 | |
235 | .Pf ( Dv S_ISUID | |
236 | | | |
237 | .Dv S_ISGID | |
238 | | | |
239 | .Dv S_ISTXT | |
240 | | | |
241 | .Dv S_IRWXU | |
242 | | | |
243 | .Dv S_IRWXG | |
244 | | | |
245 | .Dv S_IRWXO ) | |
246 | of the file's mode bits participate | |
247 | in the comparison. | |
248 | If the mode is preceded by a dash (``\-''), this primary evaluates to true | |
249 | if at least all of the bits in the mode are set in the file's mode bits. | |
250 | If the mode is not preceded by a dash, this primary evaluates to true if | |
251 | the bits in the mode exactly match the file's mode bits. | |
252 | Note, the first character of a symbolic mode may not be a dash (``\-''). | |
253 | .It Ic -print | |
254 | This primary always evaluates to true. | |
255 | It prints the pathname of the current file to standard output. | |
256 | The expression is appended to the user specified expression if neither | |
257 | .Ic -exec , | |
258 | .Ic -ls | |
259 | or | |
260 | .Ic \&-ok | |
261 | is specified. | |
262 | .It Ic -prune | |
263 | This primary always evaluates to true. | |
264 | It causes | |
265 | .Nm find | |
266 | to not descend into the current file. | |
267 | Note, the | |
268 | .Ic -prune | |
269 | primary has no effect if the | |
270 | .Fl d | |
271 | option was specified. | |
272 | .It Ic -size Ar n Ns Op Cm c | |
273 | True if the file's size, rounded up, in 512\-byte blocks is | |
274 | .Ar n . | |
275 | If | |
276 | .Ar n | |
277 | is followed by a ``c'', then the primary is true if the | |
278 | file's size is | |
279 | .Ar n | |
280 | bytes. | |
281 | .It Ic -type Ar t | |
282 | True if the file is of the specified type. | |
283 | Possible file types are as follows: | |
284 | .Pp | |
285 | .Bl -tag -width flag -offset indent -compact | |
286 | .It Cm b | |
287 | block special | |
288 | .It Cm c | |
289 | character special | |
290 | .It Cm d | |
291 | directory | |
292 | .It Cm f | |
293 | regular file | |
294 | .It Cm l | |
295 | symbolic link | |
296 | .It Cm p | |
297 | FIFO | |
298 | .It Cm s | |
299 | socket | |
300 | .El | |
301 | .Pp | |
302 | .It Ic -user Ar uname | |
303 | True if the file belongs to the user | |
304 | .Ar uname . | |
305 | If | |
306 | .Ar uname | |
307 | is numeric and there is no such user name, then | |
308 | .Ar uname | |
309 | is treated as a user id. | |
310 | .El | |
311 | .Pp | |
312 | All primaries which take a numeric argument allow the number to be | |
313 | preceded by a plus sign (``+'') or a minus sign (``\-''). | |
314 | A preceding plus sign means ``more than n'', a preceding minus sign means | |
315 | ``less than n'' and neither means ``exactly n'' . | |
316 | .Sh OPERATORS | |
317 | The primaries may be combined using the following operators. | |
318 | The operators are listed in order of decreasing precedence. | |
319 | .Bl -tag -width (expression) | |
320 | .It Cm \&( Ns Ar expression Ns Cm \&) | |
321 | This evaluates to true if the parenthesized expression evaluates to | |
322 | true. | |
323 | .Pp | |
324 | .It Cm \&! Ns Ar expression | |
325 | This is the unary | |
326 | .Tn NOT | |
327 | operator. | |
328 | It evaluates to true if the expression is false. | |
329 | .Pp | |
330 | .It Ar expression Cm -and Ar expression | |
331 | .It Ar expression expression | |
332 | The | |
333 | .Cm -and | |
334 | operator is the logical | |
335 | .Tn AND | |
336 | operator. | |
337 | As it is implied by the juxtaposition of two expressions it does not | |
338 | have to be specified. | |
339 | The expression evaluates to true if both expressions are true. | |
340 | The second expression is not evaluated if the first expression is false. | |
341 | .Pp | |
342 | .It Ar expression Cm -or Ar expression | |
343 | The | |
344 | .Cm -or | |
345 | operator is the logical | |
346 | .Tn OR | |
347 | operator. | |
348 | The expression evaluates to true if either the first or the second expression | |
349 | is true. | |
350 | The second expression is not evaluated if the first expression is true. | |
351 | .El | |
352 | .Pp | |
353 | All operands and primaries must be separate arguments to | |
354 | .Nm find . | |
355 | Primaries which themselves take arguments expect each argument | |
356 | to be a separate argument to | |
357 | .Nm find . | |
358 | .Sh EXAMPLES | |
359 | .Pp | |
360 | The following examples are shown as given to the shell: | |
361 | .Bl -tag -width findx | |
362 | .It Li "find / \e! -name \*q*.c\*q -print" | |
363 | Print out a list of all the files whose names do not end in ``.c''. | |
364 | .It Li "find / -newer ttt -user wnj -print" | |
365 | Print out a list of all the files owned by user ``wnj'' that are newer | |
366 | than the file ``ttt''. | |
367 | .It Li "find / \e! \e( -newer ttt -user wnj \e) -print" | |
368 | Print out a list of all the files which are not both newer than ``ttt'' | |
369 | and owned by ``wnj''. | |
370 | .It Li "find / \e( -newer ttt -or -user wnj \e) -print" | |
371 | Print out a list of all the files that are either owned by ``wnj'' or | |
372 | that are newer than ``ttt''. | |
373 | .El | |
374 | .Sh SEE ALSO | |
375 | .Xr chmod 1 , | |
376 | .Xr sh 1 , | |
377 | .Xr test 1 , | |
378 | .Xr stat 2 , | |
379 | .Xr umask 2 , | |
380 | .Xr getpwent 3 , | |
381 | .Xr getgrent 3 , | |
382 | .Xr strmode 3 | |
383 | .Sh STANDARDS | |
384 | The | |
385 | .Nm find | |
386 | utility syntax is a superset of the syntax specified by the | |
387 | .St -p1003.2 | |
388 | standard. | |
389 | .Pp | |
390 | The | |
391 | .Fl s | |
392 | and | |
393 | .Fl X | |
394 | options and the | |
395 | .Ic -inum | |
396 | and | |
397 | .Ic -ls | |
398 | primaries are extensions to | |
399 | .St -p1003.2 . | |
400 | .Pp | |
401 | Historically, the | |
402 | .Fl d , | |
403 | .Fl s | |
404 | and | |
405 | .Fl x | |
406 | options were implemented using the primaries ``\-depth'', ``\-follow'', | |
407 | and ``\-xdev''. | |
408 | These primaries always evaluated to true. | |
409 | As they were really global variables that took effect before the traversal | |
410 | began, some legal expressions could have unexpected results. | |
411 | An example is the expression ``\-print \-o \-depth''. | |
412 | As \-print always evaluates to true, the standard order of evaluation | |
413 | implies that \-depth would never be evaluated. | |
414 | This is not the case. | |
415 | .Pp | |
416 | The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' | |
417 | was implemented as ``\-a''. | |
418 | .Pp | |
419 | Historic implementations of the | |
420 | .Ic exec | |
421 | and | |
422 | .Ic ok | |
423 | primaries did not replace the string ``{}'' in the utility name or the | |
424 | utility arguments if it had preceding or following non-whitespace characters. | |
425 | This version replaces it no matter where in the utility name or arguments | |
426 | it appears. | |
427 | .Sh BUGS | |
428 | The special characters used by | |
429 | .Nm find | |
430 | are also special characters to many shell programs. | |
431 | In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', | |
432 | ``!'', ``\e'' and ``;'' may have to be escaped from the shell. | |
433 | .Pp | |
434 | As there is no delimiter separating options and file names or file | |
435 | names and the | |
436 | .Ar expression , | |
437 | it is difficult to specify files named ``-xdev'' or ``!''. | |
438 | These problems are handled by the | |
439 | .Fl f | |
440 | option and the | |
441 | .Xr getopt 3 | |
442 | ``--'' construct. |