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 332.Pq Dq - , 333this primary evaluates to true 334if at least all of the bits in the mode are set in the file's mode bits. 335If the mode is preceded by a plus 336.Pq Dq + , 337this primary evaluates to true 338if any of the bits in the mode are set in the file's mode bits. 339Otherwise, this primary evaluates to true if 340the bits in the mode exactly match the file's mode bits. 341Note, the first character of a symbolic mode may not be a dash (``\-''). 342.It Ic -flags Op Fl Ns Ar flags 343This primary evaluates to true if exactly those flags of the file are 344set which are also set using the specified 345.Ar flags 346(if these are not preceded by a dash (``\-''), 347or if they match the specified flags (if these are preceded by a dash). 348The 349.Ar flags 350are specified using symbolic names (see 351.Xr chflags 1 ). 352Note that this is different from 353.Ic -perm , 354which only allows you to specify flags which are set. 355.It Ic -print 356This primary always evaluates to true. 357It prints the pathname of the current file to standard output. 358If none of 359.Ic -exec , 360.Ic -ls , 361.Ic -print0 , 362or 363.Ic \&-ok 364is specified, the given expression shall be effectively replaced by 365.Cm \&( Ns Ar given\& expression Ns Cm \&) 366.Ic -print . 367.It Ic -print0 368This primary always evaluates to true. 369It prints the pathname of the current file to standard output, followed by an 370.Tn ASCII 371.Tn NUL 372character (character code 0). 373.It Ic -prune 374This primary always evaluates to true. 375It causes 376.Nm 377to not descend into the current file. 378Note, the 379.Ic -prune 380primary has no effect if the 381.Fl d 382option was specified. 383.It Ic -size Ar n Ns Op Cm c 384True if the file's size, rounded up, in 512\-byte blocks is 385.Ar n . 386If 387.Ar n 388is followed by a ``c'', then the primary is true if the 389file's size is 390.Ar n 391bytes. 392.It Ic -type Ar t 393True if the file is of the specified type. 394Possible file types are as follows: 395.Pp 396.Bl -tag -width flag -offset indent -compact 397.It Cm b 398block special 399.It Cm c 400character special 401.It Cm d 402directory 403.It Cm f 404regular file 405.It Cm l 406symbolic link 407.It Cm p 408FIFO 409.It Cm s 410socket 411.El 412.Pp 413.It Ic -user Ar uname 414True if the file belongs to the user 415.Ar uname . 416If 417.Ar uname 418is numeric and there is no such user name, then 419.Ar uname 420is treated as a user id. 421.El 422.Pp 423All primaries which take a numeric argument allow the number to be 424preceded by a plus sign 425.Pq Dq + 426or a minus sign 427.Pq Dq - . 428A preceding plus sign means ``more than n'', a preceding minus sign means 429``less than n'' and neither means ``exactly n'' . 430.Sh OPERATORS 431The primaries may be combined using the following operators. 432The operators are listed in order of decreasing precedence. 433.Bl -tag -width (expression) 434.It Cm \&( Ar expression Cm \&) 435This evaluates to true if the parenthesized expression evaluates to 436true. 437.Pp 438.It Cm \&! Ar expression 439This is the unary 440.Tn NOT 441operator. 442It evaluates to true if the expression is false. 443.Pp 444.It Ar expression Cm -and Ar expression 445.It Ar expression expression 446The 447.Cm -and 448operator is the logical 449.Tn AND 450operator. 451As it is implied by the juxtaposition of two expressions it does not 452have to be specified. 453The expression evaluates to true if both expressions are true. 454The second expression is not evaluated if the first expression is false. 455.Pp 456.It Ar expression Cm -or Ar expression 457The 458.Cm -or 459operator is the logical 460.Tn OR 461operator. 462The expression evaluates to true if either the first or the second expression 463is true. 464The second expression is not evaluated if the first expression is true. 465.El 466.Pp 467All operands and primaries must be separate arguments to 468.Nm . 469Primaries which themselves take arguments expect each argument 470to be a separate argument to 471.Nm . 472.Sh EXAMPLES 473.Pp 474The following examples are shown as given to the shell: 475.Bl -tag -width findx 476.It Li "find / \e! -name \*q*.c\*q -print" 477Print out a list of all the files whose names do not end in ``.c''. 478.It Li "find / -newer ttt -user wnj -print" 479Print out a list of all the files owned by user ``wnj'' that are newer 480than the file ``ttt''. 481.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 482Print out a list of all the files which are not both newer than ``ttt'' 483and owned by ``wnj''. 484.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 485Print out a list of all the files that are either owned by ``wnj'' or 486that are newer than ``ttt''. 487.El 488.Sh SEE ALSO 489.Xr chflags 1 , 490.Xr chmod 1 , 491.Xr locate 1 , 492.Xr whereis 1 , 493.Xr which 1 , 494.Xr stat 2 , 495.Xr fts 3 , 496.Xr getgrent 3 , 497.Xr getpwent 3 , 498.Xr strmode 3 , 499.Xr symlink 7 500.Sh STANDARDS 501The 502.Nm 503utility syntax is a superset of the syntax specified by the 504.St -p1003.2 505standard. 506.Pp 507All the single character options as well as the 508.Ic -inum , 509.Ic -print0 , 510.Ic -delete , 511and 512.Ic -ls 513primaries are extensions to 514.St -p1003.2 . 515.Pp 516Historically, the 517.Fl d , 518.Fl h 519and 520.Fl x 521options were implemented using the primaries ``\-depth'', ``\-follow'', 522and ``\-xdev''. 523These primaries always evaluated to true. 524As they were really global variables that took effect before the traversal 525began, some legal expressions could have unexpected results. 526An example is the expression ``\-print \-o \-depth''. 527As \-print always evaluates to true, the standard order of evaluation 528implies that \-depth would never be evaluated. 529This is not the case. 530.Pp 531The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' 532was implemented as ``\-a''. 533.Pp 534Historic implementations of the 535.Ic exec 536and 537.Ic ok 538primaries did not replace the string ``{}'' in the utility name or the 539utility arguments if it had preceding or following non-whitespace characters. 540This version replaces it no matter where in the utility name or arguments 541it appears. 542.Sh BUGS 543The special characters used by 544.Nm 545are also special characters to many shell programs. 546In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 547``!'', ``\e'' and ``;'' may have to be escaped from the shell. 548.Pp 549As there is no delimiter separating options and file names or file 550names and the 551.Ar expression , 552it is difficult to specify files named ``-xdev'' or ``!''. 553These problems are handled by the 554.Fl f 555option and the 556.Xr getopt 3 557``--'' construct. 558.Pp 559The 560.Ic -delete 561primary does not interact well with other options that cause the filesystem 562tree traversal options to be changed. 563.Sh HISTORY 564A 565.Nm 566command appeared in 567.At v1 . 568