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