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