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.28 (Berkeley) 07/24/91 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.Tp.Ws 162 Ic \&-ok Ar utility Ns Op argument ... ; 163The 164.Ic \&-ok 165primary is identical to the 166.Ic -exec 167primary with the exception that 168.Nm find 169requests user affirmation for the execution of the utility by printing 170a message to the terminal and reading a response. 171If the response is other than ``y'' the command is not executed and the 172value of the 173.Ar \&ok 174expression is false. 175.It Ic -name Ar pattern 176True if the last component of the pathname being examined matches 177.Ar pattern . 178Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 179may be used as part of 180.Ar pattern . 181These characters may be matched explicitly by escaping them with a 182backslash (``\e''). 183.It Ic -newer Ar file 184True if the current file has a more recent last modification time than 185.Ar file . 186.It Ic -nouser 187True if the file belongs to an unknown user. 188.It Ic -nogroup 189True if the file belongs to an unknown group. 190.It Ic -path Ar pattern 191True if the pathname being examined matches 192.Ar pattern . 193Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 194may be used as part of 195.Ar pattern . 196These characters may be matched explicitly by escaping them with a 197backslash (``\e''). 198Slashes (``/'') are treated as normal characters and do not have to be 199matched explicitly. 200.It Ic -perm Op Fl Ns Ar mode 201The 202.Ar mode 203may be either symbolic (see 204.Xr chmod 1 ) 205or an octal number. 206If the mode is symbolic, a starting value of zero is assumed and the 207mode sets or clears permissions without regard to the process' file mode 208creation mask. 209If the mode is octal, only bits 07777 210.Pf ( Dv S_ISUID 211| 212.Dv S_ISGID 213| 214.Dv S_ISTXT 215| 216.Dv S_IRWXU 217| 218.Dv S_IRWXG 219| 220.Dv S_IRWXO ) 221of the file's mode bits participate 222in the comparison. 223If the mode is preceded by a dash (``\-''), this primary evaluates to true 224if at least all of the bits in the mode are set in the file's mode bits. 225If the mode is not preceded by a dash, this primary evaluates to true if 226the bits in the mode exactly match the file's mode bits. 227Note, the first character of a symbolic mode may not be a dash (``\-''). 228.It Ic -print 229This primary always evaluates to true. 230It prints the pathname of the current file to standard output. 231The expression is appended to the user specified expression if neither 232.Ic -exec , 233.Ic -ls 234or 235.Ic \&-ok 236is specified. 237.It Ic -prune 238This primary always evaluates to true. 239It causes 240.Nm find 241to not descend into the current file. 242Note, the 243.Ic -prune 244primary has no effect if the 245.Fl d 246option was specified. 247.It Ic -size Ar n Ns Op Cm c 248True if the file's size, rounded up, in 512\-byte blocks is 249.Ar n . 250If 251.Ar n 252is followed by a ``c'', then the primary is true if the 253file's size is 254.Ar n 255bytes. 256.It Ic -type Ar t 257True if the file is of the specified type. 258Possible file types are as follows: 259.Pp 260.Bl -tag -width flag -offset indent -compact 261.It Cm b 262block special 263.It Cm c 264character special 265.It Cm d 266directory 267.It Cm f 268regular file 269.It Cm l 270symbolic link 271.It Cm p 272FIFO 273.It Cm s 274socket 275.El 276.Pp 277.It Ic -user Ar uname 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.El 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 n'', a preceding minus sign means 290``less than n'' and neither means ``exactly n'' . 291.Sh OPERATORS 292The primaries may be combined using the following operators. 293The operators are listed in order of decreasing precedence. 294.Bl -tag -width (expression) 295.It Cm \&( Ns Ar expression Ns Cm \&) 296This evaluates to true if the parenthesized expression evaluates to 297true. 298.Pp 299.It Cm \&! Ns Ar expression 300This is the unary 301.Tn NOT 302operator. 303It evaluates to true if the expression is false. 304.Pp 305.It Ar expression Cm -and Ar expression 306.It Ar expression expression 307The 308.Cm -and 309operator is the logical 310.Tn AND 311operator. 312As it is implied by the juxtaposition of two expressions it does not 313have to be specified. 314The expression evaluates to true if both expressions are true. 315The second expression is not evaluated if the first expression is false. 316.Pp 317.It Ar expression Cm -or Ar expression 318The 319.Cm -or 320operator is the logical 321.Tn OR 322operator. 323The expression evaluates to true if either the first or the second expression 324is true. 325The second expression is not evaluated if the first expression is true. 326.El 327.Pp 328All operands and primaries must be separate arguments to 329.Nm find . 330Primaries which themselves take arguments expect each argument 331to be a separate argument to 332.Nm find . 333.Sh EXAMPLES 334.Pp 335The following examples are shown as given to the shell: 336.Bl -tag -width findx 337.It Li "find / \e! -name \*q*.c\*q -print" 338Print out a list of all the files whose names do not end in ``.c''. 339.It Li "find / -newer ttt -user wnj -print" 340Print out a list of all the files owned by user ``wnj'' that are newer 341than the file ``ttt''. 342.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 343Print out a list of all the files which are not both newer than ``ttt'' 344and owned by ``wnj''. 345.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 346Print out a list of all the files that are either owned by ``wnj'' or 347that are newer than ``ttt''. 348.El 349.Sh SEE ALSO 350.Xr chmod 1 , 351.Xr sh 1 , 352.Xr test 1 , 353.Xr stat 2 , 354.Xr umask 2 , 355.Xr getpwent 3 , 356.Xr getgrent 3 , 357.Xr strmode 3 358.Sh STANDARDS 359The 360.Nm find 361utility syntax is a superset of the syntax specified by the 362.St -p1003.2 363standard. 364.Pp 365The 366.Fl s 367and 368.Fl X 369options and the 370.Ic -inum 371and 372.Ic -ls 373primaries are extensions to 374.St -p1003.2 . 375.Pp 376Historically, the 377.Fl d , 378.Fl s 379and 380.Fl x 381options were implemented using the primaries ``\-depth'', ``\-follow'', 382and ``\-xdev''. 383These primaries always evaluated to true. 384As they were really global variables that took effect before the traversal 385began, some legal expressions could have unexpected results. 386An example is the expression ``\-print \-o \-depth''. 387As \-print always evaluates to true, the standard order of evaluation 388implies that \-depth would never be evaluated. 389This is not the case. 390.Pp 391The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' 392was implemented as ``\-a''. 393.Pp 394Historic implementations of the 395.Ic exec 396and 397.Ic ok 398primaries did not replace the string ``{}'' in the utility name or the 399utility arguments if it had preceding or following non-whitespace characters. 400This version replaces it no matter where in the utility name or arguments 401it appears. 402.Sh BUGS 403The special characters used by 404.Nm find 405are also special characters to many shell programs. 406In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 407``!'', ``\e'' and ``;'' may have to be escaped from the shell. 408.Pp 409As there is no delimiter separating options and file names or file 410names and the 411.Ar expression , 412it is difficult to specify files named ``-xdev'' or ``!''. 413These problems are handled by the 414.Fl f 415option and the 416.Xr getopt 3 417``--'' construct. 418