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 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 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 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 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 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 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 151was started, rounded up to the next full minute, is 152.Ar n 153minutes. 154.It Ic -atime Ar n 155True if the difference between the file last access time and the time 156.Nm 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 164was started, rounded up to the next full minute, is 165.Ar n 166minutes. 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 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 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 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 -maxdepth Ar n 249True if the depth of the current file into the tree is less than or equal to 250.Ar n . 251.It Ic -mindepth Ar n 252True if the depth of the current file into the tree is greater than or equal to 253.Ar n . 254.It Ic -mmin Ar n 255True if the difference between the file last modification time and the time 256.Nm 257was started, rounded up to the next full minute, is 258.Ar n 259minutes. 260.It Ic -mtime Ar n 261True if the difference between the file last modification time and the time 262.Nm 263was started, rounded up to the next full 24\-hour period, is 264.Ar n 26524\-hour periods. 266.It Ic \&-ok Ar utility Op argument ... ; 267The 268.Ic \&-ok 269primary is identical to the 270.Ic -exec 271primary with the exception that 272.Nm 273requests user affirmation for the execution of the utility by printing 274a message to the terminal and reading a response. 275If the response is other than ``y'' the command is not executed and the 276value of the 277.Ar \&ok 278expression is false. 279.It Ic -name Ar pattern 280True if the last component of the pathname being examined matches 281.Ar pattern . 282Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 283may be used as part of 284.Ar pattern . 285These characters may be matched explicitly by escaping them with a 286backslash (``\e''). 287.It Ic -newer Ar file 288True if the current file has a more recent last modification time than 289.Ar file . 290.It Ic -nouser 291True if the file belongs to an unknown user. 292.It Ic -nogroup 293True if the file belongs to an unknown group. 294.It Ic -path Ar pattern 295True if the pathname being examined matches 296.Ar pattern . 297Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 298may be used as part of 299.Ar pattern . 300These characters may be matched explicitly by escaping them with a 301backslash (``\e''). 302Slashes (``/'') are treated as normal characters and do not have to be 303matched explicitly. 304.It Xo 305.Ic -perm 306.Op Fl 307.Ar mode 308.Xc 309The 310.Ar mode 311may be either symbolic (see 312.Xr chmod 1 ) 313or an octal number. 314If the mode is symbolic, a starting value of zero is assumed and the 315mode sets or clears permissions without regard to the process' file mode 316creation mask. 317If the mode is octal, only bits 07777 318.Pf ( Dv S_ISUID 319| 320.Dv S_ISGID 321| 322.Dv S_ISTXT 323| 324.Dv S_IRWXU 325| 326.Dv S_IRWXG 327| 328.Dv S_IRWXO ) 329of the file's mode bits participate 330in the comparison. 331If the mode is preceded by a dash (``\-''), this primary evaluates to true 332if at least all of the bits in the mode are set in the file's mode bits. 333If the mode is preceded by a plus (``\+''), this primary evaluates to true 334if any of the bits in the mode are set in the file's mode bits. 335Otherwise, this primary evaluates to true if 336the bits in the mode exactly match the file's mode bits. 337Note, the first character of a symbolic mode may not be a dash (``\-''). 338.It Ic -flags Op Fl Ns Ar flags 339This primary evaluates to true if exactly those flags of the file are 340set which are also set using the specified 341.Ar flags 342(if these are not preceded by a dash (``\-''), 343or if they match the specified flags (if these are preceded by a dash). 344The 345.Ar flags 346are specified using symbolic names (see 347.Xr chflags 1 ). 348Note that this is different from 349.Ic -perm , 350which only allows you to specify flags which are set. 351.It Ic -print 352This primary always evaluates to true. 353It prints the pathname of the current file to standard output. 354If none of 355.Ic -exec , 356.Ic -ls , 357.Ic -print0 , 358or 359.Ic \&-ok 360is specified, the given expression shall be effectively replaced by 361.Cm \&( Ns Ar given\& expression Ns Cm \&) 362.Ic -print . 363.It Ic -print0 364This primary always evaluates to true. 365It prints the pathname of the current file to standard output, followed by an 366.Tn ASCII 367.Tn NUL 368character (character code 0). 369.It Ic -prune 370This primary always evaluates to true. 371It causes 372.Nm 373to not descend into the current file. 374Note, the 375.Ic -prune 376primary has no effect if the 377.Fl d 378option was specified. 379.It Ic -size Ar n Ns Op Cm c 380True if the file's size, rounded up, in 512\-byte blocks is 381.Ar n . 382If 383.Ar n 384is followed by a ``c'', then the primary is true if the 385file's size is 386.Ar n 387bytes. 388.It Ic -type Ar t 389True if the file is of the specified type. 390Possible file types are as follows: 391.Pp 392.Bl -tag -width flag -offset indent -compact 393.It Cm b 394block special 395.It Cm c 396character special 397.It Cm d 398directory 399.It Cm f 400regular file 401.It Cm l 402symbolic link 403.It Cm p 404FIFO 405.It Cm s 406socket 407.El 408.Pp 409.It Ic -user Ar uname 410True if the file belongs to the user 411.Ar uname . 412If 413.Ar uname 414is numeric and there is no such user name, then 415.Ar uname 416is treated as a user id. 417.El 418.Pp 419All primaries which take a numeric argument allow the number to be 420preceded by a plus sign (``+'') or a minus sign (``\-''). 421A preceding plus sign means ``more than n'', a preceding minus sign means 422``less than n'' and neither means ``exactly n'' . 423.Sh OPERATORS 424The primaries may be combined using the following operators. 425The operators are listed in order of decreasing precedence. 426.Bl -tag -width (expression) 427.It Cm \&( Ar expression Cm \&) 428This evaluates to true if the parenthesized expression evaluates to 429true. 430.Pp 431.It Cm \&! Ar expression 432This is the unary 433.Tn NOT 434operator. 435It evaluates to true if the expression is false. 436.Pp 437.It Ar expression Cm -and Ar expression 438.It Ar expression expression 439The 440.Cm -and 441operator is the logical 442.Tn AND 443operator. 444As it is implied by the juxtaposition of two expressions it does not 445have to be specified. 446The expression evaluates to true if both expressions are true. 447The second expression is not evaluated if the first expression is false. 448.Pp 449.It Ar expression Cm -or Ar expression 450The 451.Cm -or 452operator is the logical 453.Tn OR 454operator. 455The expression evaluates to true if either the first or the second expression 456is true. 457The second expression is not evaluated if the first expression is true. 458.El 459.Pp 460All operands and primaries must be separate arguments to 461.Nm . 462Primaries which themselves take arguments expect each argument 463to be a separate argument to 464.Nm . 465.Sh EXAMPLES 466.Pp 467The following examples are shown as given to the shell: 468.Bl -tag -width findx 469.It Li "find / \e! -name \*q*.c\*q -print" 470Print out a list of all the files whose names do not end in ``.c''. 471.It Li "find / -newer ttt -user wnj -print" 472Print out a list of all the files owned by user ``wnj'' that are newer 473than the file ``ttt''. 474.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 475Print out a list of all the files which are not both newer than ``ttt'' 476and owned by ``wnj''. 477.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 478Print out a list of all the files that are either owned by ``wnj'' or 479that are newer than ``ttt''. 480.El 481.Sh SEE ALSO 482.Xr chflags 1 , 483.Xr chmod 1 , 484.Xr locate 1 , 485.Xr whereis 1 , 486.Xr which 1 , 487.Xr stat 2 , 488.Xr fts 3 , 489.Xr getgrent 3 , 490.Xr getpwent 3 , 491.Xr strmode 3 , 492.Xr symlink 7 493.Sh STANDARDS 494The 495.Nm 496utility syntax is a superset of the syntax specified by the 497.St -p1003.2 498standard. 499.Pp 500All the single character options as well as the 501.Ic -inum , 502.Ic -print0 , 503.Ic -delete , 504and 505.Ic -ls 506primaries are extensions to 507.St -p1003.2 . 508.Pp 509Historically, the 510.Fl d , 511.Fl h 512and 513.Fl x 514options were implemented using the primaries ``\-depth'', ``\-follow'', 515and ``\-xdev''. 516These primaries always evaluated to true. 517As they were really global variables that took effect before the traversal 518began, some legal expressions could have unexpected results. 519An example is the expression ``\-print \-o \-depth''. 520As \-print always evaluates to true, the standard order of evaluation 521implies that \-depth would never be evaluated. 522This is not the case. 523.Pp 524The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' 525was implemented as ``\-a''. 526.Pp 527Historic implementations of the 528.Ic exec 529and 530.Ic ok 531primaries did not replace the string ``{}'' in the utility name or the 532utility arguments if it had preceding or following non-whitespace characters. 533This version replaces it no matter where in the utility name or arguments 534it appears. 535.Sh BUGS 536The special characters used by 537.Nm 538are also special characters to many shell programs. 539In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 540``!'', ``\e'' and ``;'' may have to be escaped from the shell. 541.Pp 542As there is no delimiter separating options and file names or file 543names and the 544.Ar expression , 545it is difficult to specify files named ``-xdev'' or ``!''. 546These problems are handled by the 547.Fl f 548option and the 549.Xr getopt 3 550``--'' construct. 551.Pp 552The 553.Ic -delete 554primary does not interact well with other options that cause the filesystem 555tree traversal options to be changed. 556.Sh HISTORY 557A 558.Nm 559command appeared in 560.At v1 . 561