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