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