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