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.18 (Berkeley) 03/09/91 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. 260Note, the 261.Ic prune 262primary has no effect if the 263.Op \-d 264option was specified. 265.Tp Cx Ic size 266.Cx \&\ \& 267.Ar n 268.Op Cm c 269.Cx 270True if the file's size, rounded up, in 512\-byte blocks is 271.Ar n . 272If 273.Ar n 274is followed by a ``c'', then the primary is true if the 275file's size is 276.Ar n 277bytes. 278.Tp Cx Ic type 279.Cx \&\ \& 280.Ar t 281.Cx 282True if the file is of the specified type. 283Possible file types are as follows: 284.Pp 285.Df I 286.Tw Ds 287.Tp Cm b 288block special 289.Tp Cm c 290character special 291.Tp Cm d 292directory 293.Tp Cm f 294regular file 295.Tp Cm l 296symbolic link 297.Tp Cm p 298FIFO 299.Tp Cm s 300socket 301.Tp 302.De 303.Pp 304.Tp Cx Ic user 305.Cx \&\ \& 306.Ar uname 307.Cx 308True if the file belongs to the user 309.Ar uname . 310If 311.Ar uname 312is numeric and there is no such user name, then 313.Ar uname 314is treated as a user id. 315.Tp 316.Pp 317All primaries which take a numeric argument allow the number to be 318preceded by a plus sign (``+'') or a minus sign (``\-''). 319A preceding plus sign means ``more than 320.Ar n ' ' , 321a preceding minus sign means ``less than 322.Ar n ' ' 323and neither means ``exactly 324.Ar n ' ' . 325.Sh OPERATORS 326The primaries may be combined using the following operators. 327The operators are listed in order of decreasing precedence. 328.Di L 329.Dp Cx Ic \&( 330.Ar expression 331.Cx \&) 332.Cx 333This evaluates to true if the parenthesized expression evaluates to 334true. 335.Pp 336.Dp Cx Ic \&! 337.Cx \&\ \& 338.Ar expression 339.Cx 340This is the unary NOT operator. 341It evaluates to true if the expression is false. 342.Pp 343.Dp Cx Ar expression 344.Cx \&\ \& 345.Ic and 346.Cx \&\ \& 347.Ar expression 348.Cx 349.Dp Cx Ar expression expression 350.Cx 351The 352.Ic and 353operator is the logical AND operator. 354As it is implied by the juxtaposition of two expressions it does not 355have to be specified. 356The expression evaluates to true if both expressions are true. 357The second expression is not evaluated if the first expression is false. 358.Pp 359.Dp Cx Ar expression 360.Cx \&\ \& 361.Ic or 362.Cx \&\ \& 363.Ar expression 364.Cx 365The 366.Ic or 367operator is the logical OR operator. 368The expression evaluates to true if either the first or the second expression 369is true. 370The second expression is not evaluated if the first expression is true. 371.Dp 372.Pp 373All operands and primaries must be separate arguments to 374.Nm find . 375Primaries which themselves take arguments expect each argument 376to be a separate argument to 377.Nm find . 378.Sh EXAMPLES 379.Pp 380The following examples are shown as given to the shell: 381.Tw findx 382.Tp Li find / \e! name "*.c" print 383Print out a list of all the files whose names do not end in ``.c''. 384.Tp Li find / newer ttt user wnj print 385Print out a list of all the files owned by user ``wnj'' that are newer 386than the file ``ttt''. 387.Tp Li find / \e! \e( newer ttt user wnj \e) print 388Print out a list of all the files which are not both newer than ``ttt'' 389and owned by ``wnj''. 390.Tp Li find / \e( newer ttt or user wnj \e) print 391Print out a list of all the files that are either owned by ``wnj'' or 392that are newer than ``ttt''. 393.Tp 394.Sh SEE ALSO 395.Xr chmod 1 , 396.Xr sh 1 , 397.Xr test 1 , 398.Xr stat 2 , 399.Xr umask 2 , 400.Xr getpwent 3 , 401.Xr getgrent 3 , 402.Xr strmode 3 403.Sh STANDARDS 404The 405.Nm find 406utility syntax is a replacement for the syntax specified by the POSIX 4071003.2 standard. 408The standard syntax is also supported; see the COMPATIBILITY section 409below for details. 410.Pp 411The 412.Fl s 413option as well as the primaries 414.Ic inum 415and 416.Ic ls 417are extensions to the POSIX standard. 418.Sh COMPATIBILITY 419The traditional, and standardized, syntax for 420.Nm find 421is as follows. 422All of the primaries are preceded by a dash (``\-''), i.e. the 423primary ``group'' is specified as ``\-group''. 424The 425.Fl d , 426.Fl s , 427and 428.Fl x 429options are implemented using the primaries ``\-depth'', ``\-follow'', 430and ``\-xdev''. 431These primaries always evaluate to true. 432The operator ``or'' is implemented as ``\-o'', and the operator 433``and'' is implemented as ``\-a''. 434The set of file trees to be traversed are specified as the first operands 435to 436.Nm find . 437The first operand beginning with a dash (``\-''), exclamation point (``!'') 438or left parenthesis (``('') is assumed to be the beginning of the expression 439and the end of the files to be traversed. 440.Pp 441The 442.Nm find 443syntax was changed for two reasons. 444The first is that the ``\-depth'', ``\-follow'' and ``\-xdev'' primaries 445are really global variables that take effect before the traversal begins. 446This causes some legal expressions to have unexpected results. 447An example is the expression ``\-print \-o \-depth''. 448As \-print always evaluates to true, the standard order of evaluation 449implies that \-depth would never be evaluated. 450This is not the case. 451.Pp 452The second reason is that traversing file trees with names beginning with 453a dash, exclamation point or left parenthesis was impossible. 454.Pp 455Historic implementations of the 456.Ic exec 457and 458.Ic ok 459primaries did not replace the string ``{}'' in the utility name or the 460utility arguments unless it appeared without any other characters. 461This version replaces it no matter where in the utility name or arguments 462it appears. 463.Sh BUGS 464The special characters used by 465.Nm find 466are also special characters to many shell programs. 467In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 468``!'', ``\e'' and ``;'' may have to be escaped from the shell. 469