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