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 3, 2001 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 EXdsx 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 57.Dq primaries 58and 59.Dq operands 60listed below) in terms 61of each file in the tree. 62.Pp 63The options are as follows: 64.Bl -tag -width indent 65.It Fl E 66Interpret regular expressions followed by 67.Ic -regex 68and 69.Ic -iregex 70options as extended (modern) regular expressions rather than basic 71regular expressions (BRE's). 72The 73.Xr re_format 7 74manual page fully describes both formats. 75.It Fl H 76The 77.Fl H 78option causes the file information and file type (see 79.Xr stat 2 ) 80returned for each symbolic link specified on the command line to be 81those of the file referenced by the link, not the link itself. 82If the referenced file does not exist, the file information and type will 83be for the link itself. 84File information of all symbolic links not on 85the command line is that of the link itself. 86.It Fl L 87The 88.Fl L 89option causes the file information and file type (see 90.Xr stat 2 ) 91returned for each symbolic link to be those of the file referenced by the 92link, not the link itself. 93If the referenced file does not exist, the file information and type will 94be for the link itself. 95.It Fl P 96The 97.Fl P 98option causes the file information and file type (see 99.Xr stat 2 ) 100returned for each symbolic link to be those of the link itself. 101This is the default. 102.It Fl X 103The 104.Fl X 105option is a modification to permit 106.Nm 107to be safely used in conjunction with 108.Xr xargs 1 . 109If a file name contains any of the delimiting characters used by 110.Xr xargs 1 , 111a diagnostic message is displayed on standard error, and the file 112is skipped. 113The delimiting characters include single 114.Pq Dq Li " ' " 115and double 116.Pq Dq Li " \*q " 117quotes, backslash 118.Pq Dq Li \e , 119space, tab and newline characters. 120.It Fl d 121The 122.Fl d 123option causes 124.Nm 125to perform a depth\-first traversal, i.e., directories 126are visited in post\-order and all entries in a directory will be acted 127on before the directory itself. 128By default, 129.Nm 130visits directories in pre\-order, i.e., before their contents. 131Note, the default is 132.Em not 133a breadth\-first traversal. 134.It Fl f 135The 136.Fl f 137option specifies a file hierarchy for 138.Nm 139to traverse. 140File hierarchies may also be specified as the operands immediately 141following the options. 142.It Fl s 143The 144.Fl s 145option causes 146.Nm 147to traverse the file hierarchies in lexicographical order, 148i.e., alphabetical order within each directory. 149Note: 150.Ql find -s 151and 152.Ql "find | sort" 153may give different results. 154.It Fl x 155The 156.Fl x 157option prevents 158.Nm 159from descending into directories that have a device number different 160than that of the file from which the descent began. 161.El 162.Sh PRIMARIES 163.Bl -tag -width indent 164.It Ic -amin Ar n 165True if the difference between the file last access time and the time 166.Nm 167was started, rounded up to the next full minute, is 168.Ar n 169minutes. 170.It Ic -anewer Ar file 171Same as 172.Ic -neweram . 173.It Ic -atime Ar n Ns Op Cm smhdw 174If no units are specified, this primary evaluates to 175true if the difference between the file last access time and the time 176.Nm 177was started, rounded up to the next full 24\-hour period, is 178.Ar n 17924\-hour periods. 180.Pp 181If units are specified, this primary evaluates to 182true if the difference between the file last access time and the time 183.Nm 184was started is exactly 185.Ar n 186units. 187Possible time units are as follows: 188.Pp 189.Bl -tag -width indent -compact 190.It Cm s 191second 192.It Cm m 193minute (60 seconds) 194.It Cm h 195hour (60 minutes) 196.It Cm d 197day (24 hours) 198.It Cm w 199week (7 days) 200.El 201.Pp 202Any number of units may be combined in one 203.Ic -atime 204argument, for example, 205.Dq Li "-atime -1h30m" . 206Units are probably only useful when used in conjunction with the 207.Cm + 208or 209.Cm - 210modifier. 211.It Ic -cmin Ar n 212True if the difference between the time of last change of file status 213information and the time 214.Nm 215was started, rounded up to the next full minute, is 216.Ar n 217minutes. 218.It Ic -cnewer Ar file 219Same as 220.Ic -newercm . 221.It Ic -ctime Ar n Ns Op Cm smhdw 222If no units are specified, this primary evaluates to 223true if the difference between the time of last change of file status 224information and the time 225.Nm 226was started, rounded up to the next full 24\-hour period, is 227.Ar n 22824\-hour periods. 229.Pp 230If units are specified, this primary evaluates to 231true if the difference between the time of last change of file status 232information and the time 233.Nm 234was started is exactly 235.Ar n 236units. 237Please refer to the 238.Ic -atime 239primary description for information on supported time units. 240.It Ic -delete 241Delete found files and/or directories. 242Always returns true. 243This executes 244from the current working directory as 245.Nm 246recurses down the tree. 247It will not attempt to delete a filename with a 248.Dq Pa / 249character in its pathname relative to 250.Dq Pa \&. 251for security reasons. 252Depth\-first traversal processing is implied by this option. 253.It Ic -empty 254True if the current file or directory is empty. 255.It Ic -exec Ar utility Op Ar argument ... ; 256True if the program named 257.Ar utility 258returns a zero value as its exit status. 259Optional 260.Ar arguments 261may be passed to the utility. 262The expression must be terminated by a semicolon 263.Pq Dq Li \&; . 264If the string 265.Dq Li {} 266appears anywhere in the utility name or the 267arguments it is replaced by the pathname of the current file. 268.Ar Utility 269will be executed from the directory from which 270.Nm 271was executed. 272.Ar Utility 273and 274.Ar arguments 275are not subject to the further expansion of shell patterns 276and constructs. 277.It Ic -execdir Ar utility Op Ar argument ... ; 278The 279.Ic -execdir 280primary is identical to the 281.Ic -exec 282primary with the exception that 283.Ar utility 284will be executed from the directory that holds 285the current file. 286The filename substituted for 287the string 288.Dq Li {} 289is not qualified. 290.It Ic -flags Oo Cm - Ns | Ns Cm + Oc Ns Ar flags , Ns Ar notflags 291The flags are specified using symbolic names (see 292.Xr chflags 1 ) . 293Those with the 294.Qq Li no 295prefix (except 296.Qq Li nodump ) 297are said to be 298.Ar notflags . 299Flags in 300.Ar flags 301are checked to be set, and flags in 302.Ar notflags 303are checked to be not set. 304Note that this is different from 305.Ic -perm , 306which only allows the user to specify mode bits that are set. 307.Pp 308If flags are preceded by a dash 309.Pq Dq Li - , 310this primary evaluates to true 311if at least all of the bits in 312.Ar flags 313and none of the bits in 314.Ar notflags 315are set in the file's flags bits. 316If flags are preceded by a plus 317.Pq Dq Li + , 318this primary evaluates to true 319if any of the bits in 320.Ar flags 321is set in the file's flags bits, 322or any of the bits in 323.Ar notflags 324is not set in the file's flags bits. 325Otherwise, 326this primary evaluates to true 327if the bits in 328.Ar flags 329exactly match the file's flags bits, 330and none of the 331.Ar flags 332bits match those of 333.Ar notflags . 334.It Ic -fstype Ar type 335True if the file is contained in a file system of type 336.Ar type . 337The 338.Xr sysctl 8 339command can be used to find out the types of filesystems 340that are available on the system: 341.Pp 342.Dl "sysctl vfs" 343.Pp 344In addition, there are two pseudo-types, 345.Dq Li local 346and 347.Dq Li rdonly . 348The former matches any file system physically mounted on the system where 349the 350.Nm 351is being executed and the latter matches any file system which is 352mounted read-only. 353.It Ic -group Ar gname 354True if the file belongs to the group 355.Ar gname . 356If 357.Ar gname 358is numeric and there is no such group name, then 359.Ar gname 360is treated as a group ID. 361.It Ic -iname Ar pattern 362Like 363.Ic -name , 364but the match is case insensitive. 365.It Ic -inum Ar n 366True if the file has inode number 367.Ar n . 368.It Ic -ipath Ar pattern 369Like 370.Ic -path , 371but the match is case insensitive. 372.It Ic -iregex Ar pattern 373Like 374.Ic -regex , 375but the match is case insensitive. 376.It Ic -links Ar n 377True if the file has 378.Ar n 379links. 380.It Ic -ls 381This primary always evaluates to true. 382The following information for the current file is written to standard output: 383its inode number, size in 512\-byte blocks, file permissions, number of hard 384links, owner, group, size in bytes, last modification time, and pathname. 385If the file is a block or character special file, the major and minor numbers 386will be displayed instead of the size in bytes. 387If the file is a symbolic link, the pathname of the linked\-to file will be 388displayed preceded by 389.Dq Li -> . 390The format is identical to that produced by 391.Bk -words 392.Nm ls Fl dgils . 393.Ek 394.It Ic -maxdepth Ar n 395True if the depth of the current file into the tree is less than or equal to 396.Ar n . 397.It Ic -mindepth Ar n 398True if the depth of the current file into the tree is greater than or equal to 399.Ar n . 400.It Ic -mmin Ar n 401True if the difference between the file last modification time and the time 402.Nm 403was started, rounded up to the next full minute, is 404.Ar n 405minutes. 406.It Ic -mnewer Ar file 407Same as 408.Ic -newer . 409.It Ic -mtime Ar n Ns Op Cm smhdw 410If no units are specified, this primary evaluates to 411true if the difference between the file last modification time and the time 412.Nm 413was started, rounded up to the next full 24\-hour period, is 414.Ar n 41524\-hour periods. 416.Pp 417If units are specified, this primary evaluates to 418true if the difference between the file last modification time and the time 419.Nm 420was started is exactly 421.Ar n 422units. 423Please refer to the 424.Ic -atime 425primary description for information on supported time units. 426.It Ic -name Ar pattern 427True if the last component of the pathname being examined matches 428.Ar pattern . 429Special shell pattern matching characters 430.Dq ( Li \&[ , 431.Dq Li \&] , 432.Dq Li * , 433and 434.Dq Li \&? ) 435may be used as part of 436.Ar pattern . 437These characters may be matched explicitly by escaping them with a 438backslash 439.Pq Dq Li \e . 440.It Ic -newer Ar file 441True if the current file has a more recent last modification time than 442.Ar file . 443.It Ic -newer Ns Ar X Ns Ar Y Ar file 444True if the current file has a more recent last access time 445.Ar ( X Ns = Ns Cm a ) , 446change time 447.Ar ( X Ns = Ns Cm c ) , 448or modification time 449.Ar ( X Ns = Ns Cm m ) 450than the last access time 451.Ar ( Y Ns = Ns Cm a ) , 452change time 453.Ar ( Y Ns = Ns Cm c ) , 454or modification time 455.Ar ( Y Ns = Ns Cm m ) 456of 457.Ar file . 458In addition, if 459.Ar Y Ns = Ns Cm t , 460then 461.Ar file 462is instead interpreted as a direct date specification of the form 463understood by 464.Xr cvs 1 . 465Note that 466.Ic -newermm 467is equivalent to 468.Ic -newer . 469.It Ic -nogroup 470True if the file belongs to an unknown group. 471.It Ic -nouser 472True if the file belongs to an unknown user. 473.It Ic -ok Ar utility Op Ar argument ... ; 474The 475.Ic -ok 476primary is identical to the 477.Ic -exec 478primary with the exception that 479.Nm 480requests user affirmation for the execution of the 481.Ar utility 482by printing 483a message to the terminal and reading a response. 484If the response is other than 485.Dq Li y 486the command is not executed and the 487value of the 488.Ic -ok 489expression is false. 490.It Ic -okdir Ar utility Op Ar argument ... ; 491The 492.Ic -okdir 493primary is identical to the 494.Ic -execdir 495primary with the same exception as described for the 496.Ic -ok 497primary. 498.It Ic -path Ar pattern 499True if the pathname being examined matches 500.Ar pattern . 501Special shell pattern matching characters 502.Dq ( Li \&[ , 503.Dq Li \&] , 504.Dq Li * , 505and 506.Dq Li \&? ) 507may be used as part of 508.Ar pattern . 509These characters may be matched explicitly by escaping them with a 510backslash 511.Pq Dq Li \e . 512Slashes 513.Pq Dq Li / 514are treated as normal characters and do not have to be 515matched explicitly. 516.It Ic -perm Oo Cm - Ns | Ns Cm + Oc Ns Ar mode 517The 518.Ar mode 519may be either symbolic (see 520.Xr chmod 1 ) 521or an octal number. 522If the 523.Ar mode 524is symbolic, a starting value of zero is assumed and the 525.Ar mode 526sets or clears permissions without regard to the process' file mode 527creation mask. 528If the 529.Ar mode 530is octal, only bits 07777 531.Pq Dv S_ISUID | S_ISGID | S_ISTXT | S_IRWXU | S_IRWXG | S_IRWXO 532of the file's mode bits participate 533in the comparison. 534If the 535.Ar mode 536is preceded by a dash 537.Pq Dq Li - , 538this primary evaluates to true 539if at least all of the bits in the 540.Ar mode 541are set in the file's mode bits. 542If the 543.Ar mode 544is preceded by a plus 545.Pq Dq Li + , 546this primary evaluates to true 547if any of the bits in the 548.Ar mode 549are set in the file's mode bits. 550Otherwise, this primary evaluates to true if 551the bits in the 552.Ar mode 553exactly match the file's mode bits. 554Note, the first character of a symbolic mode may not be a dash 555.Pq Dq Li - . 556.It Ic -print 557This primary always evaluates to true. 558It prints the pathname of the current file to standard output. 559If none of 560.Ic -exec , -ls , -print0 , 561or 562.Ic -ok 563is specified, the given expression shall be effectively replaced by 564.Cm \&( Ar "given expression" Cm \&) Ic -print . 565.It Ic -print0 566This primary always evaluates to true. 567It prints the pathname of the current file to standard output, followed by an 568.Tn ASCII NUL 569character (character code 0). 570.It Ic -prune 571This primary always evaluates to true. 572It causes 573.Nm 574to not descend into the current file. 575Note, the 576.Ic -prune 577primary has no effect if the 578.Fl d 579option was specified. 580.It Ic -regex Ar pattern 581True if the whole path of the file matches 582.Ar pattern 583using regular expression. 584To match a file named 585.Dq Pa ./foo/xyzzy , 586you can use the regular expression 587.Dq Li ".*/[xyz]*" 588or 589.Dq Li ".*/foo/.*" , 590but not 591.Dq Li xyzzy 592or 593.Dq Li /foo/ . 594.It Ic -size Ar n Ns Op Cm c 595True if the file's size, rounded up, in 512\-byte blocks is 596.Ar n . 597If 598.Ar n 599is followed by a 600.Cm c , 601then the primary is true if the 602file's size is 603.Ar n 604bytes (characters). 605.It Ic -type Ar t 606True if the file is of the specified type. 607Possible file types are as follows: 608.Pp 609.Bl -tag -width indent -compact 610.It Cm b 611block special 612.It Cm c 613character special 614.It Cm d 615directory 616.It Cm f 617regular file 618.It Cm l 619symbolic link 620.It Cm p 621FIFO 622.It Cm s 623socket 624.El 625.It Ic -user Ar uname 626True if the file belongs to the user 627.Ar uname . 628If 629.Ar uname 630is numeric and there is no such user name, then 631.Ar uname 632is treated as a user ID. 633.El 634.Pp 635All primaries which take a numeric argument allow the number to be 636preceded by a plus sign 637.Pq Dq Li + 638or a minus sign 639.Pq Dq Li - . 640A preceding plus sign means 641.Dq more than n , 642a preceding minus sign means 643.Dq less than n 644and neither means 645.Dq exactly n . 646.Sh OPERATORS 647The primaries may be combined using the following operators. 648The operators are listed in order of decreasing precedence. 649.Pp 650.Bl -tag -width "( expression )" -compact 651.It Cm \&( Ar expression Cm \&) 652This evaluates to true if the parenthesized expression evaluates to 653true. 654.Pp 655.It Cm \&! Ar expression 656This is the unary 657.Tn NOT 658operator. 659It evaluates to true if the expression is false. 660.Pp 661.It Ar expression Cm -and Ar expression 662.It Ar expression expression 663The 664.Cm -and 665operator is the logical 666.Tn AND 667operator. 668As it is implied by the juxtaposition of two expressions it does not 669have to be specified. 670The expression evaluates to true if both expressions are true. 671The second expression is not evaluated if the first expression is false. 672.Pp 673.It Ar expression Cm -or Ar expression 674The 675.Cm -or 676operator is the logical 677.Tn OR 678operator. 679The expression evaluates to true if either the first or the second expression 680is true. 681The second expression is not evaluated if the first expression is true. 682.El 683.Pp 684All operands and primaries must be separate arguments to 685.Nm . 686Primaries which themselves take arguments expect each argument 687to be a separate argument to 688.Nm . 689.Sh EXAMPLES 690The following examples are shown as given to the shell: 691.Bl -tag -width indent 692.It Li "find / \e! -name \*q*.c\*q -print" 693Print out a list of all the files whose names do not end in 694.Pa .c . 695.It Li "find / -newer ttt -user wnj -print" 696Print out a list of all the files owned by user 697.Dq wnj 698that are newer 699than the file 700.Pa ttt . 701.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 702Print out a list of all the files which are not both newer than 703.Pa ttt 704and owned by 705.Dq wnj . 706.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 707Print out a list of all the files that are either owned by 708.Dq wnj 709or that are newer than 710.Pa ttt . 711.It Li "find . -newerct '1 minute ago' -print" 712Print out a list of all the files whose inode change time is more 713recent than the current time minus one minute. 714.El 715.Sh SEE ALSO 716.Xr chflags 1 , 717.Xr chmod 1 , 718.Xr cvs 1 , 719.Xr locate 1 , 720.Xr whereis 1 , 721.Xr which 1 , 722.Xr stat 2 , 723.Xr fts 3 , 724.Xr getgrent 3 , 725.Xr getpwent 3 , 726.Xr strmode 3 , 727.Xr re_format 7 , 728.Xr symlink 7 729.Sh STANDARDS 730The 731.Nm 732utility syntax is a superset of the syntax specified by the 733.St -p1003.2 734standard. 735.Pp 736All the single character options as well as the 737.Ic -iname , -inum , -iregex , -print0 , -delete , -ls , 738and 739.Ic -regex 740primaries are extensions to 741.St -p1003.2 . 742.Pp 743Historically, the 744.Fl d , h 745and 746.Fl x 747options were implemented using the primaries 748.Ic -depth , -follow , 749and 750.Ic -xdev . 751These primaries always evaluated to true. 752As they were really global variables that took effect before the traversal 753began, some legal expressions could have unexpected results. 754An example is the expression 755.Ic -print Cm -o Ic -depth . 756As 757.Ic -print 758always evaluates to true, the standard order of evaluation 759implies that 760.Ic -depth 761would never be evaluated. 762This is not the case. 763.Pp 764The operator 765.Cm -or 766was implemented as 767.Cm -o , 768and the operator 769.Cm -and 770was implemented as 771.Cm -a . 772.Pp 773Historic implementations of the 774.Ic -exec 775and 776.Ic -ok 777primaries did not replace the string 778.Dq Li {} 779in the utility name or the 780utility arguments if it had preceding or following non-whitespace characters. 781This version replaces it no matter where in the utility name or arguments 782it appears. 783.Pp 784The 785.Fl E 786option was implemented on the analogy of 787.Xr grep 1 788and 789.Xr sed 1 . 790.Sh BUGS 791The special characters used by 792.Nm 793are also special characters to many shell programs. 794In particular, the characters 795.Dq Li * , 796.Dq Li \&[ , 797.Dq Li \&] , 798.Dq Li \&? , 799.Dq Li \&( , 800.Dq Li \&) , 801.Dq Li \&! , 802.Dq Li \e 803and 804.Dq Li \&; 805may have to be escaped from the shell. 806.Pp 807As there is no delimiter separating options and file names or file 808names and the 809.Ar expression , 810it is difficult to specify files named 811.Pa -xdev 812or 813.Pa \&! . 814These problems are handled by the 815.Fl f 816option and the 817.Xr getopt 3 818.Dq Fl Fl 819construct. 820.Pp 821The 822.Ic -delete 823primary does not interact well with other options that cause the filesystem 824tree traversal options to be changed. 825.Sh HISTORY 826A 827.Nm 828command appeared in 829.At v1 . 830