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