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.15 (Berkeley) 07/24/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.Ws 170.Op argument ... ; 171.Cx 172The 173.Ic \&ok 174primary is identical to the 175.Ic exec 176primary with the exception that 177.Nm find 178requests user affirmation for the execution of the utility by printing 179a message to the terminal and reading a response. 180If the response is other than ``y'' the command is not executed and the 181value of the 182.Ar \&ok 183expression is false. 184.Tp Cx Ic name 185.Cx \&\ \& 186.Ar pattern 187.Cx 188True if the last component of the pathname being examined matches 189.Ar pattern . 190Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 191may be used as part of 192.Ar pattern . 193These characters may be matched explicitly by escaping them with a 194backslash (``\e''). 195.Tp Cx Ic newer 196.Cx \&\ \& 197.Ar file 198.Cx 199True if the current file has a more recent last modification time than 200.Ar file . 201.Tp Ic nouser 202True if the file belongs to an unknown user. 203.Tp Ic nogroup 204True if the file belongs to an unknown group. 205.Tp Cx Ic perm 206.Cx \&\ \& 207.Op Fl 208.Ar mode 209.Cx 210The 211.Ar mode 212may be either symbolic (see 213.Xr chmod 1 ) 214or an octal number. 215If the mode is symbolic, a starting value of zero is assumed and the 216mode sets or clears permissions without regard to the process' file mode 217creation mask. 218If the mode is octal, only bits 07777 of the file's mode bits participate 219in the comparison. 220If the mode is preceded by a dash (``\-''), this primary evaluates to true 221if at least all of the bits in the mode are set in the file's mode bits. 222If the mode is not preceded by a dash, this primary evaluates to true if 223the bits in the mode exactly match the file's mode bits. 224Note, the first character of a symbolic mode may not be a dash (``\-''). 225.Tp Ic print 226This primary always evaluates to true. 227It prints the pathname of the current file to standard output. 228The expression is appended to the user specified expression if neither 229.Ic exec , 230.Ic ls , 231or 232.Ic \&ok 233is specified. 234.Tp Ic prune 235This primary always evaluates to true. 236It causes 237.Nm find 238to not descend into the current file. 239.Tp Cx Ic size 240.Cx \&\ \& 241.Ar n 242.Op Cm c 243.Cx 244True if the file's size, rounded up, in 512\-byte blocks is 245.Ar n . 246If 247.Ar n 248is followed by a ``c'', then the primary is true if the 249file's size is 250.Ar n 251bytes. 252.Tp Cx Ic type 253.Cx \&\ \& 254.Ar t 255.Cx 256True if the file is of the specified type. 257Possible file types are as follows: 258.Pp 259.Df I 260.Tw Ds 261.Tp Cm b 262block special 263.Tp Cm c 264character special 265.Tp Cm d 266directory 267.Tp Cm f 268regular file 269.Tp Cm l 270symbolic link 271.Tp Cm p 272FIFO 273.Tp Cm s 274socket 275.Tp 276.De 277.Pp 278.Tp Cx Ic user 279.Cx \&\ \& 280.Ar uname 281.Cx 282True if the file belongs to the user 283.Ar uname . 284If 285.Ar uname 286is numeric and there is no such user name, then 287.Ar uname 288is treated as a user id. 289.Tp 290.Pp 291All primaries which take a numeric argument allow the number to be 292preceded by a plus sign (``+'') or a minus sign (``\-''). 293A preceding plus sign means ``more than 294.Ar n ' ' , 295a preceding minus sign means ``less than 296.Ar n ' ' 297and neither means ``exactly 298.Ar n ' ' . 299.Sh OPERATORS 300The primaries may be combined using the following operators. 301The operators are listed in order of decreasing precedence. 302.Di L 303.Dp Cx Ic \&( 304.Ar expression 305.Cx \&) 306.Cx 307This evaluates to true if the parenthesized expression evaluates to 308true. 309.Pp 310.Dp Cx Ic \&! 311.Cx \&\ \& 312.Ar expression 313.Cx 314This is the unary NOT operator. 315It evaluates to true if the expression is false. 316.Pp 317.Dp Cx Ar expression 318.Cx \&\ \& 319.Ic and 320.Cx \&\ \& 321.Ar expression 322.Cx 323.Dp Cx Ar expression expression 324.Cx 325The 326.Ic and 327operator is the logical AND operator. 328As it is implied by the juxtaposition of two expressions it does not 329have to be specified. 330The expression evaluates to true if both expressions are true. 331The second expression is not evaluated if the first expression is false. 332.Pp 333.Dp Cx Ar expression 334.Cx \&\ \& 335.Ic or 336.Cx \&\ \& 337.Ar expression 338.Cx 339The 340.Ic or 341operator is the logical OR operator. 342The expression evaluates to true if either the first or the second expression 343is true. 344The second expression is not evaluated if the first expression is true. 345.Dp 346.Pp 347All operands and primaries must be separate arguments to 348.Nm find . 349Primaries which themselves take arguments expect each argument 350to be a separate argument to 351.Nm find . 352.Sh EXAMPLES 353.Pp 354The following examples are shown as given to the shell: 355.Tw findx 356.Tp Li find / \e! name "*.c" print 357Print out a list of all the files whose names do not end in ``.c''. 358.Tp Li find / newer ttt user wnj print 359Print out a list of all the files owned by user ``wnj'' that are newer 360than the file ``ttt''. 361.Tp Li find / \e! \e( newer ttt user wnj \e) print 362Print out a list of all the files which are not both newer than ``ttt'' 363and owned by ``wnj''. 364.Tp Li find / \e( newer ttt or user wnj \e) print 365Print out a list of all the files that are either owned by ``wnj'' or 366that are newer than ``ttt''. 367.Tp 368.Sh SEE ALSO 369.Xr chmod 1 , 370.Xr sh 1 , 371.Xr test 1 , 372.Xr stat 2 , 373.Xr umask 2 , 374.Xr getpwent 3 , 375.Xr getgrent 3 , 376.Xr strmode 3 377.Sh STANDARDS 378The 379.Nm find 380utility syntax is a replacement for the syntax specified by the POSIX 3811003.2 standard. 382The standard syntax is also supported; see the COMPATIBILITY section 383below for details. 384.Pp 385The 386.Fl s 387option as well as the primaries 388.Ic inum 389and 390.Ic ls 391are extensions to the POSIX standard. 392.Sh COMPATIBILITY 393The traditional, and standardized, syntax for 394.Nm find 395is as follows. 396All of the primaries are preceded by a dash (``\-''), i.e. the 397primary ``group'' is specified as ``\-group''. 398The 399.Fl d , 400.Fl s , 401and 402.Fl x 403options are implemented using the primaries ``\-depth'', ``\-follow'', 404and ``\-xdev''. 405These primaries always evaluate to true. 406The operator ``or'' is implemented as ``\-o'', and the operator 407``and'' is implemented as ``\-a''. 408The set of file trees to be traversed are specified as the first operands 409to 410.Nm find . 411The first operand beginning with a dash (``\-''), exclamation point (``!'') 412or left parenthesis (``('') is assumed to be the beginning of the expression 413and the end of the files to be traversed. 414.Pp 415The 416.Nm find 417syntax was changed for two reasons. 418The first is that the ``\-depth'', ``\-follow'' and ``\-xdev'' primaries 419are really global variables that take effect before the traversal begins. 420This causes some legal expressions to have unexpected results. 421An example is the expression ``\-print \-o \-depth''. 422As \-print always evaluates to true, the standard order of evaluation 423implies that \-depth would never be evaluated. 424This is not the case. 425.Pp 426The second reason is that traversing file trees with names beginning with 427a dash, exclamation point or left parenthesis was impossible. 428.Sh BUGS 429The special characters used by 430.Nm find 431are also special characters to many shell programs. 432In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 433``!'', ``\e'' and ``;'' may have to be escaped from the shell. 434