| 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 | .\" @(#)find.1 8.1 (Berkeley) 6/6/93 |
| 36 | .\" |
| 37 | .Dd June 6, 1993 |
| 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 HdhXx |
| 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 | The options are as follows: |
| 59 | .Pp |
| 60 | .Bl -tag -width Ds |
| 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. |
| 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. |
| 93 | .It Fl h |
| 94 | The |
| 95 | .Fl h |
| 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 . |
| 153 | Currently supported types are ``isofs'', ``local'', ``mfs'', ``nfs'', ``pc'', |
| 154 | ``rdonly'' and ``ufs''. |
| 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. |
| 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. |
| 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. |
| 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. |
| 261 | The expression is appended to the user specified expression if none of |
| 262 | .Ic -exec , |
| 263 | .Ic -ls , |
| 264 | .Ic -print0 , |
| 265 | .Ic -printf |
| 266 | and |
| 267 | .Ic \&-ok |
| 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. |
| 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''. |
| 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 . |
| 399 | .El |
| 400 | .Sh SEE ALSO |
| 401 | .Xr chmod 1 , |
| 402 | .Xr locate 1 , |
| 403 | .Xr xargs 1 , |
| 404 | .Xr stat 2 , |
| 405 | .Xr fts 3 , |
| 406 | .Xr getpwent 3 , |
| 407 | .Xr getgrent 3 , |
| 408 | .Xr printf 3 , |
| 409 | .Xr strmode 3 , |
| 410 | .Xr symlink 7 |
| 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 |
| 423 | .Ic -inum , |
| 424 | .Ic -ls , |
| 425 | .Ic -print0 , |
| 426 | and |
| 427 | .Ic -printf |
| 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. |