1.\" Copyright (c) 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the Institute of Electrical and Electronics Engineers, Inc. 6.\" 7.\" %sccs.include.redist.roff% 8.\" 9.\" @(#)find.1 8.3 (Berkeley) 01/23/94 10.\" 11.Dd 12.Dt FIND 1 13.Os 14.Sh NAME 15.Nm find 16.Nd walk a file hierarchy 17.Sh SYNOPSIS 18.Nm find 19.Op Fl HdhXx 20.Op Fl f Ar file 21.Op Ar file ... 22.Ar expression 23.Sh DESCRIPTION 24.Nm Find 25recursively descends the directory tree for each 26.Ar file 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.Bl -tag -width Ds 35.It Fl H 36The 37.Fl H 38option causes the file information and file type (see 39.Xr stat 2 ) , 40returned for each symbolic link encountered on the command line to be 41those of the file referenced by the link, not the link itself. 42If the referenced file does not exist, the file information and type will 43be for the link itself. File information of all symbolic links not on 44the command line is that of the link itself. 45.It Fl d 46The 47.Fl d 48option causes 49.Nm find 50to perform a depth\-first traversal, i.e. directories 51are visited in post\-order and all entries in a directory will be acted 52on before the directory itself. 53By default, 54.Nm find 55visits directories in pre\-order, i.e. before their contents. 56Note, the default is 57.Ar not 58a breadth\-first traversal. 59.It Fl f 60The 61.Fl f 62option specifies a file hierarchy for 63.Nm find 64to traverse. 65File hierarchies may also be specified as the operands immediately 66following the options. 67.It Fl h 68The 69.Fl h 70option causes the file information and file type (see 71.Xr stat 2 ) , 72returned for each symbolic link to be those of the file referenced by the 73link, not the link itself. 74If the referenced file does not exist, the file information and type will 75be for the link itself. 76.It Fl X 77The 78.Fl X 79option is a modification to permit 80.Nm 81to be safely used in conjunction with 82.Xr xargs 1 . 83If a file name contains any of the delimiting characters used by 84.Xr xargs , 85a diagnostic message is displayed on standard error, and the file 86is skipped. 87The delimiting characters include single (`` ' '') and double (`` " '') 88quotes, backslash (``\e''), space, tab and newline characters. 89.It 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.El 97.Sh PRIMARIES 98.Bl -tag -width Ds 99.It Ic -atime Ar n 100True if the difference between the file last access time and the time 101.Nm find 102was started, rounded up to the next full 24\-hour period, is 103.Ar n 10424\-hour periods. 105.It Ic -ctime Ar n 106True if the difference between the time of last change of file status 107information and the time 108.Nm find 109was started, rounded up to the next full 24\-hour period, is 110.Ar n 11124\-hour periods. 112.It Ic -exec Ar utility Op argument ... ; 113True if the program named 114.Ar utility 115returns a zero value as its exit status. 116Optional arguments may be passed to the utility. 117The expression must be terminated by a semicolon (``;''). 118If the string ``{}'' appears anywhere in the utility name or the 119arguments it is replaced by the pathname of the current file. 120.Ar Utility 121will be executed from the directory from which 122.Nm find 123was executed. 124.It Ic -fstype Ar type 125True if the file is contained in a file system of type 126.Ar type . 127Currently supported types are ``local'', ``mfs'', ``nfs'', ``msdos'', 128``rdonly'' and ``ufs''. 129The types ``local'' and ``rdonly'' are not specific file system types. 130The former matches any file system physically mounted on the system where 131the 132.Nm find 133is being executed and the latter matches any file system which is 134mounted read-only. 135.It Ic -group Ar gname 136True if the file belongs to the group 137.Ar gname . 138If 139.Ar gname 140is numeric and there is no such group name, then 141.Ar gname 142is treated as a group id. 143.It Ic -inum Ar n 144True if the file has inode number 145.Ar n . 146.It Ic -links Ar n 147True if the file has 148.Ar n 149links. 150.It Ic -ls 151This primary always evaluates to true. 152The following information for the current file is written to standard output: 153its inode number, size in 512\-byte blocks, file permissions, number of hard 154links, owner, group, size in bytes, last modification time, and pathname. 155If the file is a block or character special file, the major and minor numbers 156will be displayed instead of the size in bytes. 157If the file is a symbolic link, the pathname of the linked\-to file will be 158displayed preceded by ``\->''. 159The format is identical to that produced by ``ls \-dgils''. 160.It Ic -mtime Ar n 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.It Ic \&-ok Ar utility Ns Op argument ... ; 167The 168.Ic \&-ok 169primary is identical to the 170.Ic -exec 171primary with the exception that 172.Nm find 173requests user affirmation for the execution of the utility by printing 174a message to the terminal and reading a response. 175If the response is other than ``y'' the command is not executed and the 176value of the 177.Ar \&ok 178expression is false. 179.It Ic -name Ar pattern 180True if the last component of the pathname being examined matches 181.Ar pattern . 182Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 183may be used as part of 184.Ar pattern . 185These characters may be matched explicitly by escaping them with a 186backslash (``\e''). 187.It Ic -newer Ar file 188True if the current file has a more recent last modification time than 189.Ar file . 190.It Ic -nouser 191True if the file belongs to an unknown user. 192.It Ic -nogroup 193True if the file belongs to an unknown group. 194.It Ic -path Ar pattern 195True if the pathname being examined matches 196.Ar pattern . 197Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 198may be used as part of 199.Ar pattern . 200These characters may be matched explicitly by escaping them with a 201backslash (``\e''). 202Slashes (``/'') are treated as normal characters and do not have to be 203matched explicitly. 204.It Ic -perm Op Fl Ns Ar mode 205The 206.Ar mode 207may be either symbolic (see 208.Xr chmod 1 ) 209or an octal number. 210If the mode is symbolic, a starting value of zero is assumed and the 211mode sets or clears permissions without regard to the process' file mode 212creation mask. 213If the mode is octal, only bits 07777 214.Pf ( Dv S_ISUID 215| 216.Dv S_ISGID 217| 218.Dv S_ISTXT 219| 220.Dv S_IRWXU 221| 222.Dv S_IRWXG 223| 224.Dv S_IRWXO ) 225of the file's mode bits participate 226in the comparison. 227If the mode is preceded by a dash (``\-''), this primary evaluates to true 228if at least all of the bits in the mode are set in the file's mode bits. 229If the mode is not preceded by a dash, this primary evaluates to true if 230the bits in the mode exactly match the file's mode bits. 231Note, the first character of a symbolic mode may not be a dash (``\-''). 232.It Ic -print 233This primary always evaluates to true. 234It prints the pathname of the current file to standard output. 235The expression is appended to the user specified expression if neither 236.Ic -exec , 237.Ic -ls 238or 239.Ic \&-ok 240is specified. 241.It Ic -prune 242This primary always evaluates to true. 243It causes 244.Nm find 245to not descend into the current file. 246Note, the 247.Ic -prune 248primary has no effect if the 249.Fl d 250option was specified. 251.It Ic -size Ar n Ns Op Cm c 252True if the file's size, rounded up, in 512\-byte blocks is 253.Ar n . 254If 255.Ar n 256is followed by a ``c'', then the primary is true if the 257file's size is 258.Ar n 259bytes. 260.It Ic -type Ar t 261True if the file is of the specified type. 262Possible file types are as follows: 263.Pp 264.Bl -tag -width flag -offset indent -compact 265.It Cm b 266block special 267.It Cm c 268character special 269.It Cm d 270directory 271.It Cm f 272regular file 273.It Cm l 274symbolic link 275.It Cm p 276FIFO 277.It Cm s 278socket 279.El 280.Pp 281.It Ic -user Ar uname 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.El 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 n'', a preceding minus sign means 294``less than n'' and neither means ``exactly n'' . 295.Sh OPERATORS 296The primaries may be combined using the following operators. 297The operators are listed in order of decreasing precedence. 298.Bl -tag -width (expression) 299.It Cm \&( Ns Ar expression Ns Cm \&) 300This evaluates to true if the parenthesized expression evaluates to 301true. 302.Pp 303.It Cm \&! Ns Ar expression 304This is the unary 305.Tn NOT 306operator. 307It evaluates to true if the expression is false. 308.Pp 309.It Ar expression Cm -and Ar expression 310.It Ar expression expression 311The 312.Cm -and 313operator is the logical 314.Tn AND 315operator. 316As it is implied by the juxtaposition of two expressions it does not 317have to be specified. 318The expression evaluates to true if both expressions are true. 319The second expression is not evaluated if the first expression is false. 320.Pp 321.It Ar expression Cm -or Ar expression 322The 323.Cm -or 324operator is the logical 325.Tn OR 326operator. 327The expression evaluates to true if either the first or the second expression 328is true. 329The second expression is not evaluated if the first expression is true. 330.El 331.Pp 332All operands and primaries must be separate arguments to 333.Nm find . 334Primaries which themselves take arguments expect each argument 335to be a separate argument to 336.Nm find . 337.Sh EXAMPLES 338.Pp 339The following examples are shown as given to the shell: 340.Bl -tag -width findx 341.It Li "find / \e! -name \*q*.c\*q -print" 342Print out a list of all the files whose names do not end in ``.c''. 343.It Li "find / -newer ttt -user wnj -print" 344Print out a list of all the files owned by user ``wnj'' that are newer 345than the file ``ttt''. 346.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 347Print out a list of all the files which are not both newer than ``ttt'' 348and owned by ``wnj''. 349.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 350Print out a list of all the files that are either owned by ``wnj'' or 351that are newer than ``ttt''. 352.El 353.Sh SEE ALSO 354.Xr chmod 1 , 355.Xr locate 1 , 356.Xr stat 2 , 357.Xr fts 3 , 358.Xr getpwent 3 , 359.Xr getgrent 3 , 360.Xr strmode 3 , 361.Xr symlink 7 362.Sh STANDARDS 363The 364.Nm find 365utility syntax is a superset of the syntax specified by the 366.St -p1003.2 367standard. 368.Pp 369The 370.Fl s 371and 372.Fl X 373options and the 374.Ic -inum 375and 376.Ic -ls 377primaries are extensions to 378.St -p1003.2 . 379.Pp 380Historically, the 381.Fl d , 382.Fl h 383and 384.Fl x 385options were implemented using the primaries ``\-depth'', ``\-follow'', 386and ``\-xdev''. 387These primaries always evaluated to true. 388As they were really global variables that took effect before the traversal 389began, some legal expressions could have unexpected results. 390An example is the expression ``\-print \-o \-depth''. 391As \-print always evaluates to true, the standard order of evaluation 392implies that \-depth would never be evaluated. 393This is not the case. 394.Pp 395The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' 396was implemented as ``\-a''. 397.Pp 398Historic implementations of the 399.Ic exec 400and 401.Ic ok 402primaries did not replace the string ``{}'' in the utility name or the 403utility arguments if it had preceding or following non-whitespace characters. 404This version replaces it no matter where in the utility name or arguments 405it appears. 406.Sh BUGS 407The special characters used by 408.Nm find 409are also special characters to many shell programs. 410In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 411``!'', ``\e'' and ``;'' may have to be escaped from the shell. 412.Pp 413As there is no delimiter separating options and file names or file 414names and the 415.Ar expression , 416it is difficult to specify files named ``-xdev'' or ``!''. 417These problems are handled by the 418.Fl f 419option and the 420.Xr getopt 3 421``--'' construct. 422