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