Commit | Line | Data |
---|---|---|
6b479535 NW |
1 | .\" Copyright (c) 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
15637ed4 RG |
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 | .\" | |
6b479535 | 35 | .\" @(#)find.1 8.1 (Berkeley) 6/6/93 |
15637ed4 | 36 | .\" |
6b479535 | 37 | .Dd June 6, 1993 |
15637ed4 RG |
38 | .Dt FIND 1 |
39 | .Os | |
40 | .Sh NAME | |
41 | .Nm find | |
42 | .Nd walk a file hierarchy | |
43 | .Sh SYNOPSIS | |
44 | .Nm find | |
6b479535 | 45 | .Op Fl HdhXx |
15637ed4 RG |
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 | |
15637ed4 RG |
58 | The options are as follows: |
59 | .Pp | |
60 | .Bl -tag -width Ds | |
6b479535 NW |
61 | .It Fl H |
62 | The | |
63 | .Fl H | |
64 | option causes the file information and file type (see | |
65 | .Xr stat 2 ) , | |
66 | returned for each symbolic link encountered on the command line to be | |
67 | those of the file referenced by the link, not the link itself. | |
68 | If the referenced file does not exist, the file information and type will | |
69 | be for the link itself. File information of all symbolic links not on | |
70 | the command line is that of the link itself. | |
15637ed4 RG |
71 | .It Fl d |
72 | The | |
73 | .Fl d | |
74 | option causes | |
75 | .Nm find | |
76 | to perform a depth\-first traversal, i.e. directories | |
77 | are visited in post\-order and all entries in a directory will be acted | |
78 | on before the directory itself. | |
79 | By default, | |
80 | .Nm find | |
81 | visits directories in pre\-order, i.e. before their contents. | |
82 | Note, the default is | |
83 | .Ar not | |
84 | a breadth\-first traversal. | |
85 | .It Fl f | |
86 | The | |
87 | .Fl f | |
88 | option specifies a file hierarchy for | |
89 | .Nm find | |
90 | to traverse. | |
91 | File hierarchies may also be specified as the operands immediately | |
92 | following the options. | |
6b479535 | 93 | .It Fl h |
15637ed4 | 94 | The |
6b479535 | 95 | .Fl h |
15637ed4 RG |
96 | option causes the file information and file type (see |
97 | .Xr stat 2 ) , | |
98 | returned for each symbolic link to be those of the file referenced by the | |
99 | link, not the link itself. | |
100 | If the referenced file does not exist, the file information and type will | |
101 | be for the link itself. | |
102 | .It Fl X | |
103 | The | |
104 | .Fl X | |
105 | option is a modification to permit | |
106 | .Nm | |
107 | to be safely used in conjunction with | |
108 | .Xr xargs 1 . | |
109 | If a file name contains any of the delimiting characters used by | |
110 | .Xr xargs , | |
111 | a diagnostic message is displayed on standard error, and the file | |
112 | is skipped. | |
113 | The delimiting characters include single (`` ' '') and double (`` " '') | |
114 | quotes, backslash (``\e''), space, tab and newline characters. | |
115 | .It Fl x | |
116 | The | |
117 | .Fl x | |
118 | option prevents | |
119 | .Nm find | |
120 | from descending into directories that have a device number different | |
121 | than that of the file from which the descent began. | |
122 | .El | |
123 | .Sh PRIMARIES | |
124 | .Bl -tag -width Ds | |
125 | .It Ic -atime Ar n | |
126 | True if the difference between the file last access time and the time | |
127 | .Nm find | |
128 | was started, rounded up to the next full 24\-hour period, is | |
129 | .Ar n | |
130 | 24\-hour periods. | |
131 | .It Ic -ctime Ar n | |
132 | True if the difference between the time of last change of file status | |
133 | information 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 -exec Ar utility Op argument ... ; | |
139 | True if the program named | |
140 | .Ar utility | |
141 | returns a zero value as its exit status. | |
142 | Optional arguments may be passed to the utility. | |
143 | The expression must be terminated by a semicolon (``;''). | |
144 | If the string ``{}'' appears anywhere in the utility name or the | |
145 | arguments it is replaced by the pathname of the current file. | |
146 | .Ar Utility | |
147 | will be executed from the directory from which | |
148 | .Nm find | |
149 | was executed. | |
150 | .It Ic -fstype Ar type | |
151 | True if the file is contained in a file system of type | |
152 | .Ar type . | |
dc00eac9 | 153 | Currently supported types are ``isofs'', ``local'', ``mfs'', ``nfs'', ``pc'', |
4e97a0eb | 154 | ``rdonly'' and ``ufs''. |
15637ed4 RG |
155 | The types ``local'' and ``rdonly'' are not specific 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. | |
15637ed4 RG |
192 | .It Ic -name Ar pattern |
193 | True if the last component of the pathname being examined matches | |
194 | .Ar pattern . | |
195 | Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') | |
196 | may be used as part of | |
197 | .Ar pattern . | |
198 | These characters may be matched explicitly by escaping them with a | |
199 | backslash (``\e''). | |
200 | .It Ic -newer Ar file | |
201 | True if the current file has a more recent last modification time than | |
202 | .Ar file . | |
203 | .It Ic -nouser | |
204 | True if the file belongs to an unknown user. | |
205 | .It Ic -nogroup | |
206 | True if the file belongs to an unknown group. | |
a558e4ae GW |
207 | .It Ic \&-ok Ar utility Ns Op argument ... ; |
208 | The | |
209 | .Ic \&-ok | |
210 | primary is identical to the | |
211 | .Ic -exec | |
212 | primary with the exception that | |
213 | .Nm find | |
214 | requests user affirmation for the execution of the utility by printing | |
215 | a message to the terminal and reading a response. | |
216 | If the response is other than ``y'' the command is not executed and the | |
217 | value of the | |
218 | .Ar \&ok | |
219 | expression is false. | |
a558e4ae | 220 | .It Ic -path Ar pattern |
0b253bdd | 221 | True if the pathname being examined matches |
15637ed4 RG |
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. | |
a558e4ae | 261 | The expression is appended to the user specified expression if none of |
15637ed4 | 262 | .Ic -exec , |
a558e4ae GW |
263 | .Ic -ls , |
264 | .Ic -print0 , | |
265 | .Ic -printf | |
266 | and | |
15637ed4 | 267 | .Ic \&-ok |
a558e4ae GW |
268 | are specified. |
269 | .It Ic -print0 | |
270 | This primary prints the pathname of the current file to standard output, | |
271 | followed by a NUL (ASCII 0) character. No newline is output. It | |
272 | is intended for use when the files being reported may contain newlines or | |
273 | other special characters. | |
274 | .It Ic -printf | |
275 | This primary takes one argument, which is interpreted as a format string | |
276 | to be passed to | |
277 | .Xr printf 3 . | |
278 | It must contain exactly one | |
279 | .Dq Li \&%s | |
280 | format specifier, with or without modifier flags, which receives the | |
281 | full pathname of the current file. No C-style escape processing is | |
282 | performed. | |
15637ed4 RG |
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 | |
307 | .It Cm b | |
308 | block special | |
309 | .It Cm c | |
310 | character special | |
311 | .It Cm d | |
312 | directory | |
313 | .It Cm f | |
314 | regular file | |
315 | .It Cm l | |
316 | symbolic link | |
317 | .It Cm p | |
318 | FIFO | |
319 | .It Cm s | |
320 | socket | |
321 | .El | |
322 | .Pp | |
323 | .It Ic -user Ar uname | |
324 | True if the file belongs to the user | |
325 | .Ar uname . | |
326 | If | |
327 | .Ar uname | |
328 | is numeric and there is no such user name, then | |
329 | .Ar uname | |
330 | is treated as a user id. | |
331 | .El | |
332 | .Pp | |
333 | All primaries which take a numeric argument allow the number to be | |
334 | preceded by a plus sign (``+'') or a minus sign (``\-''). | |
335 | A preceding plus sign means ``more than n'', a preceding minus sign means | |
336 | ``less than n'' and neither means ``exactly n'' . | |
337 | .Sh OPERATORS | |
338 | The primaries may be combined using the following operators. | |
339 | The operators are listed in order of decreasing precedence. | |
340 | .Bl -tag -width (expression) | |
341 | .It Cm \&( Ns Ar expression Ns Cm \&) | |
342 | This evaluates to true if the parenthesized expression evaluates to | |
343 | true. | |
344 | .Pp | |
345 | .It Cm \&! Ns Ar expression | |
346 | This is the unary | |
347 | .Tn NOT | |
348 | operator. | |
349 | It evaluates to true if the expression is false. | |
350 | .Pp | |
351 | .It Ar expression Cm -and Ar expression | |
352 | .It Ar expression expression | |
353 | The | |
354 | .Cm -and | |
355 | operator is the logical | |
356 | .Tn AND | |
357 | operator. | |
358 | As it is implied by the juxtaposition of two expressions it does not | |
359 | have to be specified. | |
360 | The expression evaluates to true if both expressions are true. | |
361 | The second expression is not evaluated if the first expression is false. | |
362 | .Pp | |
363 | .It Ar expression Cm -or Ar expression | |
364 | The | |
365 | .Cm -or | |
366 | operator is the logical | |
367 | .Tn OR | |
368 | operator. | |
369 | The expression evaluates to true if either the first or the second expression | |
370 | is true. | |
371 | The second expression is not evaluated if the first expression is true. | |
372 | .El | |
373 | .Pp | |
374 | All operands and primaries must be separate arguments to | |
375 | .Nm find . | |
376 | Primaries which themselves take arguments expect each argument | |
377 | to be a separate argument to | |
378 | .Nm find . | |
379 | .Sh EXAMPLES | |
380 | .Pp | |
381 | The following examples are shown as given to the shell: | |
382 | .Bl -tag -width findx | |
383 | .It Li "find / \e! -name \*q*.c\*q -print" | |
384 | Print out a list of all the files whose names do not end in ``.c''. | |
385 | .It Li "find / -newer ttt -user wnj -print" | |
386 | Print out a list of all the files owned by user ``wnj'' that are newer | |
387 | than the file ``ttt''. | |
388 | .It Li "find / \e! \e( -newer ttt -user wnj \e) -print" | |
389 | Print out a list of all the files which are not both newer than ``ttt'' | |
390 | and owned by ``wnj''. | |
391 | .It Li "find / \e( -newer ttt -or -user wnj \e) -print" | |
392 | Print out a list of all the files that are either owned by ``wnj'' or | |
393 | that are newer than ``ttt''. | |
a558e4ae GW |
394 | .It Li "find / -name \e*~ -print0 | perl -n0e unlink" |
395 | Find all the | |
396 | .Xr emacs 1 | |
397 | backup files and delete them quickly using | |
398 | .Xr perl 1 . | |
15637ed4 RG |
399 | .El |
400 | .Sh SEE ALSO | |
401 | .Xr chmod 1 , | |
4e97a0eb | 402 | .Xr locate 1 , |
a558e4ae | 403 | .Xr xargs 1 , |
15637ed4 | 404 | .Xr stat 2 , |
6b479535 | 405 | .Xr fts 3 , |
15637ed4 RG |
406 | .Xr getpwent 3 , |
407 | .Xr getgrent 3 , | |
a558e4ae | 408 | .Xr printf 3 , |
6b479535 NW |
409 | .Xr strmode 3 , |
410 | .Xr symlink 7 | |
15637ed4 RG |
411 | .Sh STANDARDS |
412 | The | |
413 | .Nm find | |
414 | utility syntax is a superset of the syntax specified by the | |
415 | .St -p1003.2 | |
416 | standard. | |
417 | .Pp | |
418 | The | |
419 | .Fl s | |
420 | and | |
421 | .Fl X | |
422 | options and the | |
a558e4ae GW |
423 | .Ic -inum , |
424 | .Ic -ls , | |
425 | .Ic -print0 , | |
15637ed4 | 426 | and |
a558e4ae | 427 | .Ic -printf |
15637ed4 RG |
428 | primaries are extensions to |
429 | .St -p1003.2 . | |
430 | .Pp | |
431 | Historically, the | |
432 | .Fl d , | |
433 | .Fl s | |
434 | and | |
435 | .Fl x | |
436 | options were implemented using the primaries ``\-depth'', ``\-follow'', | |
437 | and ``\-xdev''. | |
438 | These primaries always evaluated to true. | |
439 | As they were really global variables that took effect before the traversal | |
440 | began, some legal expressions could have unexpected results. | |
441 | An example is the expression ``\-print \-o \-depth''. | |
442 | As \-print always evaluates to true, the standard order of evaluation | |
443 | implies that \-depth would never be evaluated. | |
444 | This is not the case. | |
445 | .Pp | |
446 | The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' | |
447 | was implemented as ``\-a''. | |
448 | .Pp | |
449 | Historic implementations of the | |
450 | .Ic exec | |
451 | and | |
452 | .Ic ok | |
453 | primaries did not replace the string ``{}'' in the utility name or the | |
454 | utility arguments if it had preceding or following non-whitespace characters. | |
455 | This version replaces it no matter where in the utility name or arguments | |
456 | it appears. | |
457 | .Sh BUGS | |
458 | The special characters used by | |
459 | .Nm find | |
460 | are also special characters to many shell programs. | |
461 | In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', | |
462 | ``!'', ``\e'' and ``;'' may have to be escaped from the shell. | |
463 | .Pp | |
464 | As there is no delimiter separating options and file names or file | |
465 | names and the | |
466 | .Ar expression , | |
467 | it is difficult to specify files named ``-xdev'' or ``!''. | |
468 | These problems are handled by the | |
469 | .Fl f | |
470 | option and the | |
471 | .Xr getopt 3 | |
472 | ``--'' construct. |