1.\" $NetBSD: find.1,v 1.39 2002/10/01 11:04:12 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. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" from: @(#)find.1 8.7 (Berkeley) 5/9/95 38.\" 39.Dd September 27, 2002 40.Dt FIND 1 41.Os 42.Sh NAME 43.Nm find 44.Nd walk a file hierarchy 45.Sh SYNOPSIS 46.Nm find 47.Op Fl H | Fl L | Fl P 48.Op Fl Xdhsx 49.Op Fl f Ar file 50.Op Ar file ... 51.Ar expression 52.Sh DESCRIPTION 53.Nm 54recursively descends the directory tree for each 55.Ar file 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.Pp 67.Bl -tag -width Ds 68.It Fl H 69The 70.Fl H 71option causes the file information and file type (see 72.Xr stat 2 ) , 73returned for each symbolic link encountered on the command line to be 74those of the file referenced by the link, not the link itself. 75If the referenced file does not exist, the file information and type will 76be for the link itself. 77File information of all symbolic links not on the command line is that 78of the link itself. 79.It Fl L 80The 81.Fl L 82option causes the file information and file type (see 83.Xr stat 2 ) 84returned for each symbolic link to be those of the file referenced by the 85link, not the link itself. 86If the referenced file does not exist, the file information and type will 87be for the link itself. 88.It Fl P 89The 90.Fl P 91option causes the file information and file type (see 92.Xr stat 2 ) 93returned for each symbolic link to be those of the link itself. 94.It Fl X 95The 96.Fl X 97option is a modification to permit 98.Nm 99to be safely used in conjunction with 100.Xr xargs 1 . 101If a file name contains any of the delimiting characters used by 102.Nm xargs , 103a diagnostic message is displayed on standard error, and the file 104is skipped. 105The delimiting characters include single 106.Pq Dq \&' 107and double 108.Pq Dq \&" 109quotes, backslash 110.Pq Dq \e , 111space, tab and newline characters. 112Alternatively, the 113.Ic -print0 114or 115.Ic -printx 116primaries can be used to format the output in a way that 117.Nm xargs 118can accept. 119.It Fl d 120The 121.Fl d 122option causes 123.Nm 124to perform a depth-first traversal, i.e., directories 125are visited in post-order and all entries in a directory will be acted 126on before the directory itself. 127By default, 128.Nm 129visits directories in pre-order, i.e., before their contents. 130Note, the default is 131.Ar not 132a breadth-first traversal. 133.It Fl f 134The 135.Fl f 136option specifies a file hierarchy for 137.Nm 138to traverse. 139File hierarchies may also be specified as the operands immediately 140following the options. 141.It Fl h 142The 143.Fl h 144option causes the file information and file type (see 145.Xr stat 2 ) , 146returned for each symbolic link to be those of the file referenced by the 147link, not the link itself. 148If the referenced file does not exist, the file information and type will 149be for the link itself. 150.It Fl s 151The 152.Fl s 153option causes the entries of each directory sorted in 154lexicographical order. 155Note that the sorting is done only inside of each directory; 156files in different directories are not sorted. 157Therefore, 158.Sq Li a/b 159appears before 160.Sq Li a.b , 161which is different from 162.Dq Li "find ... \&| sort" 163order. 164.It Fl x 165The 166.Fl x 167option restricts the search to the file system containing the 168directory specified. 169Does not list mount points to other file systems. 170.El 171.Sh PRIMARIES 172.Bl -tag -width Ds 173.It Ic -amin Ar n 174True if the difference between the file last access time and the time 175.Nm 176was started, rounded up to the next full minute, is 177.Ar n 178minutes. 179.It Ic -anewer Ar file 180True if the current file has a more recent last access time than 181.Ar file . 182.It Ic -atime 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 24-hour period, is 186.Ar n 18724-hour periods. 188.It Ic -cmin Ar n 189True if the difference between the time of last change of file status 190information and the time 191.Nm 192was started, rounded up to the next full minute, is 193.Ar n 194minutes. 195.It Ic -cnewer Ar file 196True if the current file has a more recent last change time than 197.Ar file . 198.It Ic -ctime Ar n 199True if the difference between the time of last change of file status 200information and the time 201.Nm 202was started, rounded up to the next full 24-hour period, is 203.Ar n 20424-hour periods. 205.It Ic -empty 206True if the current file or directory is empty. 207.It Ic -exec Ar utility Op argument ... ; 208True if the program named 209.Ar utility 210returns a zero value as its exit status. 211Optional arguments may be passed to the utility. 212The expression must be terminated by a semicolon 213.Pq Dq \&; . 214If the string 215.Dq {} 216appears anywhere in the utility name or the 217arguments it is replaced by the pathname of the current file. 218.Ar Utility 219will be executed from the directory from which 220.Nm 221was executed. 222.It Ic -execdir Ar utility Op argument ... ; 223The 224.Ic -execdir 225primary is identical to the 226.Ic -exec 227primary with the exception that 228.Ar Utility 229will be executed from the directory that holds 230the current file. 231The filename substituted for the string 232.Dq {} 233is not qualified. 234.It Xo 235.Ic -flags 236.Op Fl 237.Ns Ar flags 238.Xc 239If 240.Ar flags 241are preceded by a dash 242.Pq Dq - , 243this primary evaluates to true 244if at least all of the bits in 245.Ar flags 246are set in the file's flags bits. 247If 248.Ar flags 249are not preceded by a dash, this primary evaluates to true if 250the bits in 251.Ar flags 252exactly match the file's flags bits. 253If 254.Ar flags 255is 256.Dq none , 257files with no flags bits set are matched. 258(See 259.Xr chflags 1 260for more information about file flags.) 261.It Ic -follow 262Follow symbolic links. 263.It Ic -fstype Ar type 264True if the file is contained in a file system of type 265.Ar type . 266The 267.Xr sysctl 8 268command can be used to find out the types of filesystems 269that are available on the system: 270.Bd -literal -offset indent 271sysctl vfs 272.Pp 273.Ed 274In addition, there are two pseudo-types, 275.Dq local 276and 277.Dq rdonly . 278The former matches any file system physically mounted on the system where 279the 280.Nm 281is being executed, and the latter matches any file system which is 282mounted read-only. 283.It Ic -group Ar gname 284True if the file belongs to the group 285.Ar gname . 286If 287.Ar gname 288is numeric and there is no such group name, then 289.Ar gname 290is treated as a group id. 291.It Ic -inum Ar n 292True if the file has inode number 293.Ar n . 294.It Ic -iregex Ar regexp 295True if the path name of the current file matches the case-insensitive 296basic regular expression 297.Pq see Xr re_format 7 298.Ar regexp . 299This is a match on the whole path, not a search for the regular expression 300within the path. 301.It Ic -links Ar n 302True if the file has 303.Ar n 304links. 305.It Ic -ls 306This primary always evaluates to true. 307The following information for the current file is written to standard output: 308its inode number, size in 512-byte blocks, file permissions, number of hard 309links, owner, group, size in bytes, last modification time, and pathname. 310If the file is a block or character special file, the major and minor numbers 311will be displayed instead of the size in bytes. 312If the file is a symbolic link, the pathname of the linked-to file will be 313displayed preceded by 314.Dq -\*[Gt] . 315The format is identical to that produced by 316.Dq ls -dgils . 317.It Ic -maxdepth Ar n 318True if the current search depth is less than or equal to what is specified in 319.Ar n . 320.It Ic -mindepth Ar n 321True if the current search depth is at least what is specified in 322.Ar n . 323.It Ic -mmin Ar n 324True if the difference between the file last modification time and the time 325.Nm 326was started, rounded up to the next full minute, is 327.Ar n 328minutes. 329.It Ic -mtime Ar n 330True if the difference between the file last modification time and the time 331.Nm 332was started, rounded up to the next full 24-hour period, is 333.Ar n 33424-hour periods. 335.It Ic -ok Ar utility Op argument ... ; 336The 337.Ic -ok 338primary is identical to the 339.Ic -exec 340primary with the exception that 341.Nm 342requests user affirmation for the execution of the utility by printing 343a message to the terminal and reading a response. 344If the response is other than 345.Dq y 346the command is not executed and the 347value of the 348.Ar \&ok 349expression is false. 350.It Ic -name Ar pattern 351True if the last component of the pathname being examined matches 352.Ar pattern . 353Special shell pattern matching characters 354.Po 355.Dq \&[ , 356.Dq \&] , 357.Dq \&* , 358.Dq \&? 359.Pc 360may be used as part of 361.Ar pattern . 362These characters may be matched explicitly by escaping them with a 363backslash 364.Pq Dq \e . 365.It Ic -newer Ar file 366True if the current file has a more recent last modification time than 367.Ar file . 368.It Ic -nouser 369True if the file belongs to an unknown user. 370.It Ic -nogroup 371True if the file belongs to an unknown group. 372.It Ic -path Ar pattern 373True if the pathname being examined matches 374.Ar pattern . 375Special shell pattern matching characters 376.Po 377.Dq \&[ , 378.Dq \&] , 379.Dq \&* , 380and 381.Dq \&? 382.Pc 383may be used as part of 384.Ar pattern . 385These characters may be matched explicitly by escaping them with a 386backslash 387.Pq Dq \e . 388Slashes 389.Pq Dq / 390are treated as normal characters and do not have to be 391matched explicitly. 392.It Xo 393.Ic -perm 394.Op Fl 395.Ns Ar mode 396.Xc 397The 398.Ar mode 399may be either symbolic (see 400.Xr chmod 1 ) 401or an octal number. 402If the mode is symbolic, a starting value of zero is assumed and the 403mode sets or clears permissions without regard to the process' file mode 404creation mask. 405If the mode is octal, only bits 07777 406.Pf ( Dv S_ISUID 407| 408.Dv S_ISGID 409| 410.Dv S_ISTXT 411| 412.Dv S_IRWXU 413| 414.Dv S_IRWXG 415| 416.Dv S_IRWXO ) 417of the file's mode bits participate 418in the comparison. 419If the mode is preceded by a dash 420.Pq Dq - , 421this primary evaluates to true 422if at least all of the bits in the mode are set in the file's mode bits. 423If the mode is not preceded by a dash, this primary evaluates to true if 424the bits in the mode exactly match the file's mode bits. 425Note, the first character of a symbolic mode may not be a dash 426.Pq Dq - . 427.It Ic -print 428This primary always evaluates to true. 429It prints the pathname of the current file to standard output, followed 430by a newline character. 431If none of 432.Ic -exec , 433.Ic -ls , 434.Ic -ok , 435.Ic -print0 , 436nor 437.Ic -printx 438is specified, the given expression shall be effectively replaced by 439.Cm \&( Ns Ar given\& expression Ns Cm \&) 440.Ic -print . 441.It Ic -print0 442This primary always evaluates to true. 443It prints the pathname of the current file to standard output, followed 444by a null character. 445.It Ic -printx 446This primary always evaluates to true. 447It prints the pathname of the current file to standard output, 448with each space, tab, newline, backslash, and single or double 449quotation mark prefixed by a backslash, so the output of 450.Nm find 451can safely be used as input to 452.Nm xargs . 453.It Ic -prune 454This primary always evaluates to true. 455It causes 456.Nm 457to not descend into the current file. 458Note, the 459.Ic -prune 460primary has no effect if the 461.Fl d 462option was specified. 463.It Ic -regex Ar regexp 464True if the path name of the current file matches the case-sensitive 465basic regular expression 466.Pq see Xr re_format 7 467.Ar regexp . 468This is a match on the whole path, not a search for the regular expression 469within the path. 470.It Ic -size Ar n Ns Op Cm c 471True if the file's size, rounded up, in 512-byte blocks is 472.Ar n . 473If 474.Ar n 475is followed by a 476.Dq c , 477then the primary is true if the file's size is 478.Ar n 479bytes. 480.It Ic -type Ar t 481True if the file is of the specified type. 482Possible file types are as follows: 483.Pp 484.Bl -tag -width flag -offset indent -compact 485.It Cm W 486whiteout 487.It Cm b 488block special 489.It Cm c 490character special 491.It Cm d 492directory 493.It Cm f 494regular file 495.It Cm l 496symbolic link 497.It Cm p 498FIFO 499.It Cm s 500socket 501.El 502.Pp 503.It Ic -user Ar uname 504True if the file belongs to the user 505.Ar uname . 506If 507.Ar uname 508is numeric and there is no such user name, then 509.Ar uname 510is treated as a user id. 511.El 512.Pp 513All primaries which take a numeric argument allow the number to be 514preceded by a plus sign 515.Pq Dq + 516or a minus sign 517.Pq Dq \- . 518A preceding plus sign means 519.Dq more than n , 520a preceding minus sign means 521.Dq less than n , 522and neither means 523.Dq exactly n . 524.Sh OPERATORS 525The primaries may be combined using the following operators. 526The operators are listed in order of decreasing precedence. 527.Bl -tag -width (expression) 528.It Cm \&( Ns Ar expression Ns Cm \&) 529This evaluates to true if the parenthesized expression evaluates to 530true. 531.Pp 532.It Cm \&! Ns Ar expression 533This is the unary 534.Tn NOT 535operator. 536It evaluates to true if the expression is false. 537.Pp 538.It Ar expression Cm -and Ar expression 539.It Ar expression expression 540The 541.Cm -and 542operator is the logical 543.Tn AND 544operator. 545As it is implied by the juxtaposition of two expressions it does not 546have to be specified. 547The expression evaluates to true if both expressions are true. 548The second expression is not evaluated if the first expression is false. 549.Pp 550.It Ar expression Cm -or Ar expression 551The 552.Cm -or 553operator is the logical 554.Tn OR 555operator. 556The expression evaluates to true if either the first or the second expression 557is true. 558The second expression is not evaluated if the first expression is true. 559.El 560.Pp 561All operands and primaries must be separate arguments to 562.Nm "" . 563Primaries which themselves take arguments expect each argument 564to be a separate argument to 565.Nm "" . 566.Sh EXAMPLES 567The following examples are shown as given to the shell: 568.Bl -tag -width findx 569.It Li "find / \e! -name \*q*.c\*q -print" 570Print out a list of all the files whose names do not end in 571.Dq \&.c . 572.It Li "find / -newer ttt -user wnj -print" 573Print out a list of all the files owned by user 574.Dq wnj 575that are newer than the file 576.Dq ttt . 577.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 578Print out a list of all the files which are not both newer than 579.Dq ttt 580and owned by 581.Dq wnj . 582.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 583Print out a list of all the files that are either owned by 584.Dq wnj 585or that are newer than 586.Dq ttt . 587.El 588.Sh SEE ALSO 589.Xr chflags 1 , 590.Xr chmod 1 , 591.Xr locate 1 , 592.Xr stat 2 , 593.Xr fts 3 , 594.Xr getgrent 3 , 595.Xr getpwent 3 , 596.Xr strmode 3 , 597.Xr symlink 7 598.Sh STANDARDS 599The 600.Nm 601utility syntax is a superset of the syntax specified by the 602.St -p1003.2 603standard. 604.Pp 605The options and the 606.Ic -amin , 607.Ic -anewer , 608.Ic -cmin , 609.Ic -cnewer , 610.Ic -empty , 611.Ic -follow , 612.Ic -fstype , 613.Ic -inum , 614.Ic -iregex , 615.Ic -links , 616.Ic -ls , 617.Ic -maxdepth , 618.Ic -mindepth , 619.Ic -mmin , 620.Ic -path , 621.Ic -print0 622and 623.Ic -regex 624primaries are extensions to 625.St -p1003.2 . 626.Pp 627Historically, the 628.Fl d , 629.Fl h 630and 631.Fl x 632options were implemented using the primaries 633.Dq -depth , 634.Dq -follow , 635and 636.Dq -xdev . 637These primaries always evaluated to true. 638As they were really global variables that took effect before the traversal 639began, some legal expressions could have unexpected results. 640An example is the expression 641.Dq -print -o -depth . 642As -print always evaluates to true, the standard order of evaluation 643implies that -depth would never be evaluated. 644This is not the case. 645.Pp 646The operator 647.Dq -or 648was implemented as 649.Dq -o , 650and the operator 651.Dq -and 652was implemented as 653.Dq -a . 654.Pp 655Historic implementations of the 656.Ic -exec 657and 658.Ic -ok 659primaries did not replace the string 660.Dq {} 661in the utility name or the 662utility arguments if it had preceding or following non-whitespace characters. 663This version replaces it no matter where in the utility name or arguments 664it appears. 665.Sh HISTORY 666A much simpler 667.Nm find 668command appeared in First Edition AT\*[Am]T Unix. 669The syntax had become similar to the present version by 670the time of the Fifth Edition. 671.Sh BUGS 672The special characters used by 673.Nm 674are also special characters to many shell programs. 675In particular, the characters 676.Dq \&* , 677.Dq \&[ , 678.Dq \&] , 679.Dq \&? , 680.Dq \&( , 681.Dq \&) , 682.Dq \&! , 683.Dq \e 684and 685.Dq \&; 686may have to be escaped from the shell. 687.Pp 688As there is no delimiter separating options and file names or file 689names and the 690.Ar expression , 691it is difficult to specify files named 692.Dq -xdev 693or 694.Dq \&! . 695These problems are handled by the 696.Fl f 697option and the 698.Xr getopt 3 699.Dq -- 700construct. 701