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