1.\" $NetBSD: find.1,v 1.70 2010/09/09 11:42:13 wiz Exp $ 2.\" 3.\" Copyright (c) 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the Institute of Electrical and Electronics Engineers, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" from: @(#)find.1 8.7 (Berkeley) 5/9/95 34.\" 35.Dd November 6, 2009 36.Dt FIND 1 37.Os 38.Sh NAME 39.Nm find 40.Nd walk a file hierarchy 41.Sh SYNOPSIS 42.Nm 43.Op Fl H | Fl L | Fl P 44.Op Fl dEhsXx 45.Ar file 46.Op Ar file ... 47.Op Ar expression 48.Nm 49.Op Fl H | Fl L | Fl P 50.Op Fl dEhsXx 51.Fl f Ar file 52.Op Ar file ... 53.Op Ar expression 54.Sh DESCRIPTION 55.Nm 56recursively descends the directory tree for each 57.Ar file 58listed, evaluating an 59.Ar expression 60(composed of the 61.Dq primaries 62and 63.Dq operands 64listed below) in terms 65of each file in the tree. 66.Pp 67The options are as follows: 68.Pp 69.Bl -tag -width Ds 70.It Fl H 71The 72.Fl H 73option causes the file information and file type (see 74.Xr stat 2 ) , 75returned for each symbolic link encountered on the command line to be 76those of the file referenced by the link, not the link itself. 77If the referenced file does not exist, the file information and type will 78be for the link itself. 79File information of all symbolic links not on the command line is that 80of the link itself. 81.It Fl L 82The 83.Fl L 84option causes the file information and file type (see 85.Xr stat 2 ) 86returned for each symbolic link to be those of the file referenced by the 87link, not the link itself. 88If the referenced file does not exist, the file information and type will 89be for the link itself. 90.It Fl P 91The 92.Fl P 93option causes the file information and file type (see 94.Xr stat 2 ) 95returned for each symbolic link to be those of the link itself. 96.It Fl d 97The 98.Fl d 99option causes 100.Nm 101to perform a depth-first traversal, i.e., directories 102are visited in post-order and all entries in a directory will be acted 103on before the directory itself. 104By default, 105.Nm 106visits directories in pre-order, i.e., before their contents. 107Note, the default is 108.Ar not 109a breadth-first traversal. 110.It Fl E 111The 112.Fl E 113option causes 114.Ar regexp 115arguments to primaries to be interpreted as extended regular 116expressions (see 117.Xr re_format 7 ) . 118.It Fl f 119The 120.Fl f 121option specifies a file hierarchy for 122.Nm 123to traverse. 124File hierarchies may also be specified as the operands immediately 125following the options. 126.It Fl h 127The 128.Fl h 129option causes the file information and file type (see 130.Xr stat 2 ) , 131returned for each symbolic link to be those of the file referenced by the 132link, not the link itself. 133If the referenced file does not exist, the file information and type will 134be for the link itself. 135.It Fl s 136The 137.Fl s 138option causes the entries of each directory to be sorted in 139lexicographical order. 140Note that the sorting is done only inside of each directory; 141files in different directories are not sorted. 142Therefore, 143.Sq Li a/b 144appears before 145.Sq Li a.b , 146which is different from 147.Dq Li "find ... \&| sort" 148order. 149.It Fl X 150The 151.Fl X 152option is a modification to permit 153.Nm 154to be safely used in conjunction with 155.Xr xargs 1 . 156If a file name contains any of the delimiting characters used by 157.Nm xargs , 158a diagnostic message is displayed on standard error, and the file 159is skipped. 160The delimiting characters include single 161.Pq Dq \&' 162and double 163.Pq Dq \&" 164quotes, backslash 165.Pq Dq \e , 166space, tab and newline characters. 167Alternatively, the 168.Ic -print0 169or 170.Ic -printx 171primaries can be used to format the output in a way that 172.Nm xargs 173can accept. 174.It Fl x 175The 176.Fl x 177option restricts the search to the file system containing the 178directory specified. 179Does not list mount points to other file systems. 180.El 181.Sh PRIMARIES 182.Bl -tag -width Ds -compact 183.It Ic -amin Ar n 184True if the difference between the file last access time and the time 185.Nm 186was started, rounded up to the next full minute, is 187.Ar n 188minutes. 189.Pp 190.It Ic -anewer Ar file 191True if the current file has a more recent last access time than 192.Ar file . 193.Pp 194.It Ic -atime Ar n 195True if the difference between the file last access time and the time 196.Nm 197was started, rounded up to the next full 24-hour period, is 198.Ar n 19924-hour periods. 200.Pp 201.It Ic -cmin Ar n 202True if the difference between the time of last change of file status 203information and the time 204.Nm 205was started, rounded up to the next full minute, is 206.Ar n 207minutes. 208.Pp 209.It Ic -cnewer Ar file 210True if the current file has a more recent last change time than 211.Ar file . 212.Pp 213.It Ic -ctime Ar n 214True if the difference between the time of last change of file status 215information and the time 216.Nm 217was started, rounded up to the next full 24-hour period, is 218.Ar n 21924-hour periods. 220.Pp 221.It Ic -delete 222Delete found files, symbolic links and directories. 223Always returns True. 224This executes from the current working directory as 225.Nm 226recurses down the tree. 227To avoid deleting unexpected files, it will ignore any filenames that 228.Xr fts 3 229returns that contain a 230.Dq / 231.Xr ( fts 3 232should not return such pathnames). 233Depth-first traversal processing is implied by this option. 234This can also be invoked as 235.Ic -rm . 236.Pp 237.It Ic -empty 238True if the current file or directory is empty. 239.Pp 240.It Ic -exec Ar utility Oo argument ... Oc No ; 241.It Ic -exec Ar utility Oo argument ... Oc No {} + 242Execute the specified 243.Ar utility 244with the specified arguments. 245The list of arguments is terminated by 246.Dq Li \&; 247or 248.Dq Li \&+ . 249.Ar utility 250will be executed from the directory from which 251.Nm 252was executed. 253.Pp 254If terminated by a semicolon 255.Pq Dq \&; , 256the 257.Ar utility 258is invoked once per path. 259If the string 260.Dq {} 261appears anywhere in the utility name or the arguments, 262it is replaced by the pathname of the current file. 263.Pp 264If terminated by a plus sign 265.Pq Dq \&+ , 266the pathnames for which the 267primary is evaluated are aggregated into sets, and 268.Ar utility 269will be invoked once per set, similar to 270.Xr xargs 1 . 271If any invocation exits with non-zero exit status, then 272.Nm 273will eventually do so as well, but this does not cause 274.Nm 275to exit early. 276The string 277.Dq {} 278must appear, and must appear last. 279Each set is limited to no more than 5,000 pathnames, 280and is also limited such that the invocation of 281.Ar utility 282does not exceed 283.Dv ARG_MAX . 284.Pp 285.It Ic -execdir Ar utility Oo argument ... Oc No ; 286The 287.Ic -execdir 288primary is similar to the semicolon-terminated 289.Pq Dq \&; 290variant of the 291.Ic -exec 292primary, with the exception that 293.Ar utility 294will be executed from the directory that holds 295the current file. 296The filename substituted for the string 297.Dq {} 298is not qualified. 299Set aggregation 300.Pq Do \&+ Dc termination 301is not supported. 302.Pp 303.It Ic -exit Op Ar n 304This primary causes 305.Nm 306to stop traversing the file system and exit immediately if a 307previous condition was met. 308If no value is specified, the exit value will be 0, else 309.Ar n . 310Note that other primaries will be evaluated and acted upon before exiting. 311.Pp 312.It Ic -false 313This primary always evaluates to false. 314This can be used following a primary that caused the 315expression to be true to make the expression to be false. 316This can be useful after using a 317.Ic -fprint 318primary so it can continue to the next expression (using an 319.Cm -or 320operator, for example). 321.Pp 322.It Ic -flags Oo Fl Oc Ns Ar flags 323If 324.Ar flags 325are preceded by a dash 326.Pq Dq - , 327this primary evaluates to true 328if at least all of the bits in 329.Ar flags 330are set in the file's flags bits. 331If 332.Ar flags 333are not preceded by a dash, this primary evaluates to true if 334the bits in 335.Ar flags 336exactly match the file's flags bits. 337If 338.Ar flags 339is 340.Dq none , 341files with no flags bits set are matched. 342(See 343.Xr chflags 1 344for more information about file flags.) 345.Pp 346.It Ic -follow 347Follow symbolic links. 348.Pp 349.It Ic -fprint Ar filename 350This primary always evaluates to true. 351This creates 352.Ar filename 353or overwrites the file if it already exists. 354The file is created at startup. 355It writes the pathname of the current file to this file, followed 356by a newline character. 357The file will be empty if no files are matched. 358.Pp 359.It Ic -fstype Ar type 360True if the file is contained in a file system of type 361.Ar type . 362The 363.Xr sysctl 8 364command can be used to find out the types of file systems 365that are available on the system: 366.Bd -literal -offset indent 367sysctl vfs.generic.fstypes 368.Ed 369.Pp 370In addition, there are two pseudo-types, 371.Dq local 372and 373.Dq rdonly . 374The former matches any file system physically mounted on the system where 375the 376.Nm 377is being executed, and the latter matches any file system which is 378mounted read-only. 379.Pp 380.It Ic -group Ar gname 381True if the file belongs to the group 382.Ar gname . 383If 384.Ar gname 385is numeric and there is no such group name, then 386.Ar gname 387is treated as a group id. 388.Pp 389.It Ic -iname Ar pattern 390True if the last component of the pathname being examined 391matches 392.Ar pattern . 393Case insensitive. 394.Pp 395.It Ic -inum Ar n 396True if the file has inode number 397.Ar n . 398.Pp 399.It Ic -iregex Ar regexp 400True if the path name of the current file matches the case-insensitive 401basic regular expression 402.Pq see Xr re_format 7 403.Ar regexp . 404This is a match on the whole path, not a search for the regular expression 405within the path. 406.Pp 407.It Ic -links Ar n 408True if the file has 409.Ar n 410links. 411.Pp 412.It Ic -rm 413This is an alias for 414.Ic -delete . 415.Pp 416.It Ic -ls 417This primary always evaluates to true. 418The following information for the current file is written to standard output: 419its inode number, size in 512-byte blocks, file permissions, number of hard 420links, owner, group, size in bytes, last modification time, and pathname. 421If the file is a block or character special file, the major and minor numbers 422will be displayed instead of the size in bytes. 423If the file is a symbolic link, the pathname of the linked-to file will be 424displayed preceded by 425.Dq -\*[Gt] . 426The format is identical to that produced by 427.Dq ls -dgils . 428.Pp 429.It Ic -maxdepth Ar n 430True if the current search depth is less than or equal to what is specified in 431.Ar n . 432.Pp 433.It Ic -mindepth Ar n 434True if the current search depth is at least what is specified in 435.Ar n . 436.Pp 437.It Ic -mmin Ar n 438True if the difference between the file last modification time and the time 439.Nm 440was started, rounded up to the next full minute, is 441.Ar n 442minutes. 443.Pp 444.It Ic -mtime Ar n 445True if the difference between the file last modification time and the time 446.Nm 447was started, rounded up to the next full 24-hour period, is 448.Ar n 44924-hour periods. 450.Pp 451.It Ic -ok Ar utility Oo argument ... Oc No ; 452The 453.Ic -ok 454primary is similar to the semicolon-terminated 455.Pq Dq \&; 456variant of the 457.Ic -exec 458primary, with the exception that 459.Nm 460requests user affirmation for the execution of the utility by printing 461a message to the terminal and reading a response. 462If the response is other than 463.Dq y , 464the command is not executed and the 465.Ar -ok 466primary evaluates to false. 467Set aggregation 468.Pq Do \&+ Dc termination 469is not supported. 470.Pp 471.It Ic -name Ar pattern 472True if the last component of the pathname being examined matches 473.Ar pattern . 474Special shell pattern matching characters 475.Po 476.Dq \&[ , 477.Dq \&] , 478.Dq \&* , 479.Dq \&? 480.Pc 481may be used as part of 482.Ar pattern . 483These characters may be matched explicitly by escaping them with a 484backslash 485.Pq Dq \e . 486.Pp 487.It Ic -newer Ar file 488True if the current file has a more recent last modification time than 489.Ar file . 490.Pp 491.It Ic -nouser 492True if the file belongs to an unknown user. 493.Pp 494.It Ic -nogroup 495True if the file belongs to an unknown group. 496.Pp 497.It Ic -path Ar pattern 498True if the pathname being examined matches 499.Ar pattern . 500Special shell pattern matching characters 501.Po 502.Dq \&[ , 503.Dq \&] , 504.Dq \&* , 505and 506.Dq \&? 507.Pc 508may be used as part of 509.Ar pattern . 510These characters may be matched explicitly by escaping them with a 511backslash 512.Pq Dq \e . 513Slashes 514.Pq Dq / 515are treated as normal characters and do not have to be 516matched explicitly. 517.Pp 518.It Ic -perm Oo Fl Oc Ns Ar mode 519The 520.Ar mode 521may be either symbolic (see 522.Xr chmod 1 ) 523or an octal number. 524If the mode is symbolic, a starting value of zero is assumed and the 525mode sets or clears permissions without regard to the process' file mode 526creation mask. 527If the mode is octal, only bits 07777 528.Pf ( Dv S_ISUID 529| 530.Dv S_ISGID 531| 532.Dv S_ISTXT 533| 534.Dv S_IRWXU 535| 536.Dv S_IRWXG 537| 538.Dv S_IRWXO ) 539of the file's mode bits participate 540in the comparison. 541If the mode is preceded by a dash 542.Pq Dq - , 543this primary evaluates to true 544if at least all of the bits in the mode are set in the file's mode bits. 545If the mode is not preceded by a dash, this primary evaluates to true if 546the bits in the mode exactly match the file's mode bits. 547Note, the first character of a symbolic mode may not be a dash 548.Pq Dq - . 549.Pp 550.It Ic -print 551This primary always evaluates to true. 552It prints the pathname of the current file to standard output, followed 553by a newline character. 554If none of 555.Ic -exec , 556.Ic -exit , 557.Ic -fprint , 558.Ic -ls , 559.Ic -ok , 560.Ic -print0 , 561nor 562.Ic -printx 563is specified, the given expression shall be effectively replaced by 564.Cm \&( Ns Ar given\& expression Ns Cm \&) 565.Ic -print . 566.Pp 567.It Ic -print0 568This primary always evaluates to true. 569It prints the pathname of the current file to standard output, followed 570by a null character. 571.Pp 572.It Ic -printx 573This primary always evaluates to true. 574It prints the pathname of the current file to standard output, 575with each space, tab, newline, backslash, dollar sign, and single, 576double, or back quotation mark prefixed by a backslash, so the output of 577.Nm find 578can safely be used as input to 579.Nm xargs . 580.Pp 581.It Ic -prune 582This primary always evaluates to true. 583It causes 584.Nm 585to not descend into the current file. 586Note, the 587.Ic -prune 588primary has no effect if the 589.Fl d 590option was specified. 591.Pp 592.It Ic -regex Ar regexp 593True if the path name of the current file matches the case-sensitive 594basic regular expression 595.Pq see Xr re_format 7 596.Ar regexp . 597This is a match on the whole path, not a search for the regular expression 598within the path. 599.Pp 600.It Ic -size Ar n Ns Op Cm c 601True if the file's size, rounded up, in 512-byte blocks is 602.Ar n . 603If 604.Ar n 605is followed by a 606.Dq c , 607then the primary is true if the file's size is 608.Ar n 609bytes. 610.Pp 611.It Ic -type Ar t 612True if the file is of the specified type. 613Possible file types are as follows: 614.Pp 615.Bl -tag -width flag -offset indent -compact 616.It Cm b 617block special 618.It Cm c 619character special 620.It Cm d 621directory 622.It Cm f 623regular file 624.It Cm l 625symbolic link 626.It Cm p 627FIFO 628.It Cm s 629socket 630.It Cm W 631whiteout 632.It Cm w 633whiteout 634.El 635.Pp 636.It Ic -user Ar uname 637True if the file belongs to the user 638.Ar uname . 639If 640.Ar uname 641is numeric and there is no such user name, then 642.Ar uname 643is treated as a user id (and considered a numeric argument). 644.Pp 645.It Ic -xdev 646This primary always evaluates to true. 647It causes find not to descend past directories that have a different 648device ID (st_dev, see 649.Xr stat 2 650S5.6.2 [POSIX.1]). 651.El 652.Pp 653All primaries which take a numeric argument allow the number to be 654preceded by a plus sign 655.Pq Dq + 656or a minus sign 657.Pq Dq \- . 658A preceding plus sign means 659.Dq more than n , 660a preceding minus sign means 661.Dq less than n , 662and neither means 663.Dq exactly n . 664.Sh OPERATORS 665The primaries may be combined using the following operators. 666The operators are listed in order of decreasing precedence. 667.Bl -tag -width (expression) 668.It Cm \&( Ar expression Cm \&) 669This evaluates to true if the parenthesized expression evaluates to 670true. 671.Pp 672.It Cm \&! Ar expression 673This is the unary 674.Tn NOT 675operator. 676It evaluates to true if the expression is false. 677.Pp 678.It Ar expression Cm -and Ar expression 679.It Ar expression expression 680The 681.Cm -and 682operator is the logical 683.Tn AND 684operator. 685As it is implied by the juxtaposition of two expressions it does not 686have to be specified. 687The expression evaluates to true if both expressions are true. 688The second expression is not evaluated if the first expression is false. 689.Pp 690.It Ar expression Cm -or Ar expression 691The 692.Cm -or 693operator is the logical 694.Tn OR 695operator. 696The expression evaluates to true if either the first or the second expression 697is true. 698The second expression is not evaluated if the first expression is true. 699.El 700.Pp 701All operands and primaries must be separate arguments to 702.Nm . 703Primaries which themselves take arguments expect each argument 704to be a separate argument to 705.Nm . 706.Sh EXIT STATUS 707The 708.Nm 709utility normally exits 0 on success, and exits with 1 under certain 710internal error conditions. 711If any invocations of 712.Dq Ic -exec Ar ... No + 713primaries return non-zero exit-status, then 714.Nm 715will do so as well. 716.Sh EXAMPLES 717The following examples are shown as given to the shell: 718.Bl -tag -width findx 719.It Li "find / \e! -name \*q*.c\*q -print" 720Print out a list of all the files whose names do not end in 721.Dq \&.c . 722.It Li "find / -newer ttt -user wnj -print" 723Print out a list of all the files owned by user 724.Dq wnj 725that are newer than the file 726.Dq ttt . 727.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 728Print out a list of all the files which are not both newer than 729.Dq ttt 730and owned by 731.Dq wnj . 732.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 733Print out a list of all the files that are either owned by 734.Dq wnj 735or that are newer than 736.Dq ttt . 737.It Li "find / \e( -newer ttt -or -user wnj \e) -exit 1" 738Return immediately with a value of 1 if any files are found that are either 739owned by 740.Dq wnj 741or that are newer than 742.Dq ttt , 743but do not print them. 744.It Li "find / \e( -newer ttt -or -user wnj \e) -ls -exit 1" 745Same as above, but list the first file matching the criteria before exiting 746with a value of 1. 747.El 748.Sh SEE ALSO 749.Xr chflags 1 , 750.Xr chmod 1 , 751.Xr locate 1 , 752.Xr xargs 1 , 753.Xr stat 2 , 754.Xr fts 3 , 755.Xr getgrent 3 , 756.Xr getpwent 3 , 757.Xr strmode 3 , 758.Xr symlink 7 , 759.Xr sysctl 8 760.Sh STANDARDS 761The 762.Nm 763utility syntax is a superset of the syntax specified by the 764.St -p1003.2 765standard. 766.Pp 767The options and the 768.Ic -amin , 769.Ic -anewer , 770.Ic -cmin , 771.Ic -cnewer , 772.Ic -delete , 773.Ic -empty , 774.Ic -execdir , 775.Ic -follow , 776.Ic -fstype , 777.Ic -iname , 778.Ic -inum , 779.Ic -iregex , 780.Ic -links , 781.Ic -ls , 782.Ic -maxdepth , 783.Ic -mindepth , 784.Ic -mmin , 785.Ic -path , 786.Ic -print0 , 787.Ic -printx , 788.Ic -regex , 789and 790.Ic -rm 791primaries are extensions to 792.St -p1003.2 . 793.Pp 794Historically, the 795.Fl d , 796.Fl h , 797and 798.Fl x 799options were implemented using the primaries 800.Dq -depth , 801.Dq -follow , 802and 803.Dq -xdev . 804These primaries always evaluated to true. 805As they were really global variables that took effect before the traversal 806began, some legal expressions could have unexpected results. 807An example is the expression 808.Dq -print -o -depth . 809As -print always evaluates to true, the standard order of evaluation 810implies that -depth would never be evaluated. 811This is not the case. 812.Pp 813The operator 814.Dq -or 815was implemented as 816.Dq -o , 817and the operator 818.Dq -and 819was implemented as 820.Dq -a . 821.Pp 822Historic implementations of the 823.Ic -exec 824and 825.Ic -ok 826primaries did not replace the string 827.Dq {} 828in the utility name or the 829utility arguments if it had preceding or following non-whitespace characters. 830This version replaces it no matter where in the utility name or arguments 831it appears. 832.Pp 833Support for 834.Dq Ic -exec Ar ... No + 835is consistent with 836.Em IEEE PASC Interpretation 1003.2 #210 , 837though the feature originated in 838.Tn SVR4 . 839.Pp 840The 841.Ic -delete 842primary does not interact well with other options that cause the file system 843tree traversal options to be changed. 844.Sh HISTORY 845A much simpler 846.Nm find 847command appeared in First Edition AT\*[Am]T Unix. 848The syntax had become similar to the present version by 849the time of the Fifth Edition. 850.Sh BUGS 851The special characters used by 852.Nm 853are also special characters to many shell programs. 854In particular, the characters 855.Dq \&* , 856.Dq \&[ , 857.Dq \&] , 858.Dq \&? , 859.Dq \&( , 860.Dq \&) , 861.Dq \&! , 862.Dq \e , 863and 864.Dq \&; 865may have to be escaped from the shell. 866.Pp 867As there is no delimiter separating options and file names or file 868names and the 869.Ar expression , 870it is difficult to specify files named 871.Dq -xdev 872or 873.Dq \&! . 874These problems are handled by the 875.Fl f 876option and the 877.Xr getopt 3 878.Dq -- 879construct. 880