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