1.\" $NetBSD: find.1,v 1.33 2002/02/08 01:36:22 ross 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 December 2, 2001 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 ``primaries'' and ``operands'' listed below) in terms 59of each file in the tree. 60.Pp 61The options are as follows: 62.Pp 63.Bl -tag -width Ds 64.It Fl H 65The 66.Fl H 67option causes the file information and file type (see 68.Xr stat 2 ) , 69returned for each symbolic link encountered on the command line to be 70those of the file referenced by the link, not the link itself. 71If the referenced file does not exist, the file information and type will 72be for the link itself. File information of all symbolic links not on 73the command line is that of the link itself. 74.It Fl L 75The 76.Fl L 77option causes the file information and file type (see 78.Xr stat 2 ) 79returned for each symbolic link to be those of the file referenced by the 80link, not the link itself. 81If the referenced file does not exist, the file information and type will 82be for the link itself. 83.It Fl P 84The 85.Fl P 86option causes the file information and file type (see 87.Xr stat 2 ) 88returned for each symbolic link to be those of the link itself. 89.It Fl X 90The 91.Fl X 92option is a modification to permit 93.Nm 94to be safely used in conjunction with 95.Xr xargs 1 . 96If a file name contains any of the delimiting characters used by 97.Nm xargs , 98a diagnostic message is displayed on standard error, and the file 99is skipped. 100The delimiting characters include single (`` ' '') and double (`` " '') 101quotes, backslash (``\e''), space, tab and newline characters. 102Alternatively, the 103.Ic -print0 104or 105.Ic -printx 106primaries can be used to format the output in a way that 107.Nm xargs 108can accept. 109.It Fl d 110The 111.Fl d 112option causes 113.Nm 114to perform a depth\-first traversal, i.e. directories 115are visited in post\-order and all entries in a directory will be acted 116on before the directory itself. 117By default, 118.Nm 119visits directories in pre\-order, i.e. before their contents. 120Note, the default is 121.Ar not 122a breadth\-first traversal. 123.It Fl f 124The 125.Fl f 126option specifies a file hierarchy for 127.Nm 128to traverse. 129File hierarchies may also be specified as the operands immediately 130following the options. 131.It Fl h 132The 133.Fl h 134option causes the file information and file type (see 135.Xr stat 2 ) , 136returned for each symbolic link to be those of the file referenced by the 137link, not the link itself. 138If the referenced file does not exist, the file information and type will 139be for the link itself. 140.It Fl s 141The 142.Fl s 143option causes the entries of each directory sorted in 144lexicographical order. 145Note that the sorting is done only inside of each directory; 146files in different directories are not sorted. 147Therefore, 148.Sq Li a/b 149appears before 150.Sq Li a.b , 151which is different from 152.Dq Li "find ... \&| sort" 153order. 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 Ds 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 171True if the current file has a more recent last access time than 172.Ar file . 173.It Ic -atime 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 24\-hour period, is 177.Ar n 17824\-hour periods. 179.It Ic -cmin Ar n 180True if the difference between the time of last change of file status 181information and the time 182.Nm 183was started, rounded up to the next full minute, is 184.Ar n 185minutes. 186.It Ic -cnewer Ar file 187True if the current file has a more recent last change time than 188.Ar file . 189.It Ic -ctime Ar n 190True if the difference between the time of last change of file status 191information and the time 192.Nm 193was started, rounded up to the next full 24\-hour period, is 194.Ar n 19524\-hour periods. 196.It Ic -exec Ar utility Op argument ... ; 197True if the program named 198.Ar utility 199returns a zero value as its exit status. 200Optional arguments may be passed to the utility. 201The expression must be terminated by a semicolon (``;''). 202If the string ``{}'' appears anywhere in the utility name or the 203arguments it is replaced by the pathname of the current file. 204.Ar Utility 205will be executed from the directory from which 206.Nm 207was executed. 208.It Xo 209.Ic -flags 210.Op Fl 211.Ns Ar flags 212.Xc 213If 214.Ar flags 215are preceded by a dash (``\-''), this primary evaluates to true 216if at least all of the bits in 217.Ar flags 218are set in the file's flags bits. 219If 220.Ar flags 221are not preceded by a dash, this primary evaluates to true if 222the bits in 223.Ar flags 224exactly match the file's flags bits. 225If 226.Ar flags 227is 228.Dq none , 229files with no flags bits set are matched. 230(See 231.Xr chflags 1 232for more information about file flags.) 233.It Ic -follow 234Follow symbolic links. 235.It Ic -fstype Ar type 236True if the file is contained in a file system of type 237.Ar type . 238The 239.Xr sysctl 8 240command can be used to find out the types of filesystems 241that are available on the system: 242.Bd -literal -offset indent 243sysctl vfs 244.Ed 245In addition, there are two pseudo-types, ``local'' and ``rdonly''. 246The former matches any file system physically mounted on the system where 247the 248.Nm 249is being executed, and the latter matches any file system which is 250mounted read-only. 251.It Ic -group Ar gname 252True if the file belongs to the group 253.Ar gname . 254If 255.Ar gname 256is numeric and there is no such group name, then 257.Ar gname 258is treated as a group id. 259.It Ic -inum Ar n 260True if the file has inode number 261.Ar n . 262.It Ic -iregex Ar regexp 263True if the path name of the current file matches the case-insensitive 264basic regular expression 265.Pq see Xr re_format 7 266.Ar regexp . 267This is a match on the whole path, not a search for the regular expression 268within the path. 269.It Ic -links Ar n 270True if the file has 271.Ar n 272links. 273.It Ic -ls 274This primary always evaluates to true. 275The following information for the current file is written to standard output: 276its inode number, size in 512\-byte blocks, file permissions, number of hard 277links, owner, group, size in bytes, last modification time, and pathname. 278If the file is a block or character special file, the major and minor numbers 279will be displayed instead of the size in bytes. 280If the file is a symbolic link, the pathname of the linked\-to file will be 281displayed preceded by ``\-\*[Gt]''. 282The format is identical to that produced by ``ls \-dgils''. 283.It Ic -mmin Ar n 284True if the difference between the file last modification time and the time 285.Nm 286was started, rounded up to the next full minute, is 287.Ar n 288minutes. 289.It Ic -mtime Ar n 290True if the difference between the file last modification time and the time 291.Nm 292was started, rounded up to the next full 24\-hour period, is 293.Ar n 29424\-hour periods. 295.It Ic \&-ok Ar utility Op argument ... ; 296The 297.Ic \&-ok 298primary is identical to the 299.Ic -exec 300primary with the exception that 301.Nm 302requests user affirmation for the execution of the utility by printing 303a message to the terminal and reading a response. 304If the response is other than ``y'' the command is not executed and the 305value of the 306.Ar \&ok 307expression is false. 308.It Ic -name Ar pattern 309True if the last component of the pathname being examined matches 310.Ar pattern . 311Special shell pattern matching characters 312.Po 313.Dq \&[ , 314.Dq \&] , 315.Dq \&* , 316.Dq \&? 317.Pc 318may be used as part of 319.Ar pattern . 320These characters may be matched explicitly by escaping them with a 321backslash (``\e''). 322.It Ic -newer Ar file 323True if the current file has a more recent last modification time than 324.Ar file . 325.It Ic -nouser 326True if the file belongs to an unknown user. 327.It Ic -nogroup 328True if the file belongs to an unknown group. 329.It Ic -path Ar pattern 330True if the pathname being examined matches 331.Ar pattern . 332Special shell pattern matching characters (``['', ``]'', ``*'', and ``?'') 333may be used as part of 334.Ar pattern . 335These characters may be matched explicitly by escaping them with a 336backslash (``\e''). 337Slashes (``/'') are treated as normal characters and do not have to be 338matched explicitly. 339.It Xo 340.Ic -perm 341.Op Fl 342.Ns Ar mode 343.Xc 344The 345.Ar mode 346may be either symbolic (see 347.Xr chmod 1 ) 348or an octal number. 349If the mode is symbolic, a starting value of zero is assumed and the 350mode sets or clears permissions without regard to the process' file mode 351creation mask. 352If the mode is octal, only bits 07777 353.Pf ( Dv S_ISUID 354| 355.Dv S_ISGID 356| 357.Dv S_ISTXT 358| 359.Dv S_IRWXU 360| 361.Dv S_IRWXG 362| 363.Dv S_IRWXO ) 364of the file's mode bits participate 365in the comparison. 366If the mode is preceded by a dash (``\-''), this primary evaluates to true 367if at least all of the bits in the mode are set in the file's mode bits. 368If the mode is not preceded by a dash, this primary evaluates to true if 369the bits in the mode exactly match the file's mode bits. 370Note, the first character of a symbolic mode may not be a dash (``\-''). 371.It Ic -print 372This primary always evaluates to true. 373It prints the pathname of the current file to standard output, followed 374by a newline character. 375If none of 376.Ic -exec , 377.Ic -ls , 378.Ic -ok , 379.Ic -print0 , 380nor 381.Ic -printx 382is specified, the given expression shall be effectively replaced by 383.Cm \&( Ns Ar given\& expression Ns Cm \&) 384.Ic -print . 385.It Ic -print0 386This primary always evaluates to true. 387It prints the pathname of the current file to standard output, followed 388by a null character. 389.It Ic -printx 390This primary always evaluates to true. 391It prints the pathname of the current file to standard output, 392with each space, tab, newline, backslash, and single or double 393quotation mark prefixed by a backslash, so the output of 394.Nm find 395can safely be used as input to 396.Nm xargs . 397.It Ic -prune 398This primary always evaluates to true. 399It causes 400.Nm 401to not descend into the current file. 402Note, the 403.Ic -prune 404primary has no effect if the 405.Fl d 406option was specified. 407.It Ic -regex Ar regexp 408True if the path name of the current file matches the case-sensitive 409basic regular expression 410.Pq see Xr re_format 7 411.Ar regexp . 412This is a match on the whole path, not a search for the regular expression 413within the path. 414.It Ic -size Ar n Ns Op Cm c 415True if the file's size, rounded up, in 512\-byte blocks is 416.Ar n . 417If 418.Ar n 419is followed by a ``c'', then the primary is true if the 420file's size is 421.Ar n 422bytes. 423.It Ic -type Ar t 424True if the file is of the specified type. 425Possible file types are as follows: 426.Pp 427.Bl -tag -width flag -offset indent -compact 428.It Cm W 429whiteout 430.It Cm b 431block special 432.It Cm c 433character special 434.It Cm d 435directory 436.It Cm f 437regular file 438.It Cm l 439symbolic link 440.It Cm p 441FIFO 442.It Cm s 443socket 444.El 445.Pp 446.It Ic -user Ar uname 447True if the file belongs to the user 448.Ar uname . 449If 450.Ar uname 451is numeric and there is no such user name, then 452.Ar uname 453is treated as a user id. 454.El 455.Pp 456All primaries which take a numeric argument allow the number to be 457preceded by a plus sign (``+'') or a minus sign (``\-''). 458A preceding plus sign means ``more than n'', a preceding minus sign means 459``less than n'' and neither means ``exactly n'' . 460.Sh OPERATORS 461The primaries may be combined using the following operators. 462The operators are listed in order of decreasing precedence. 463.Bl -tag -width (expression) 464.It Cm \&( Ns Ar expression Ns Cm \&) 465This evaluates to true if the parenthesized expression evaluates to 466true. 467.Pp 468.It Cm \&! Ns Ar expression 469This is the unary 470.Tn NOT 471operator. 472It evaluates to true if the expression is false. 473.Pp 474.It Ar expression Cm -and Ar expression 475.It Ar expression expression 476The 477.Cm -and 478operator is the logical 479.Tn AND 480operator. 481As it is implied by the juxtaposition of two expressions it does not 482have to be specified. 483The expression evaluates to true if both expressions are true. 484The second expression is not evaluated if the first expression is false. 485.Pp 486.It Ar expression Cm -or Ar expression 487The 488.Cm -or 489operator is the logical 490.Tn OR 491operator. 492The expression evaluates to true if either the first or the second expression 493is true. 494The second expression is not evaluated if the first expression is true. 495.El 496.Pp 497All operands and primaries must be separate arguments to 498.Nm "" . 499Primaries which themselves take arguments expect each argument 500to be a separate argument to 501.Nm "" . 502.Sh EXAMPLES 503The following examples are shown as given to the shell: 504.Bl -tag -width findx 505.It Li "find / \e! -name \*q*.c\*q -print" 506Print out a list of all the files whose names do not end in ``.c''. 507.It Li "find / -newer ttt -user wnj -print" 508Print out a list of all the files owned by user ``wnj'' that are newer 509than the file ``ttt''. 510.It Li "find / \e! \e( -newer ttt -user wnj \e) -print" 511Print out a list of all the files which are not both newer than ``ttt'' 512and owned by ``wnj''. 513.It Li "find / \e( -newer ttt -or -user wnj \e) -print" 514Print out a list of all the files that are either owned by ``wnj'' or 515that are newer than ``ttt''. 516.El 517.Sh SEE ALSO 518.Xr chflags 1 , 519.Xr chmod 1 , 520.Xr locate 1 , 521.Xr stat 2 , 522.Xr fts 3 , 523.Xr getgrent 3 , 524.Xr getpwent 3 , 525.Xr strmode 3 , 526.Xr symlink 7 527.Sh STANDARDS 528The 529.Nm 530utility syntax is a superset of the syntax specified by the 531.St -p1003.2 532standard. 533.Pp 534The options and the 535.Ic -amin , 536.Ic -anewer , 537.Ic -cmin , 538.Ic -cnewer , 539.Ic -follow , 540.Ic -fstype , 541.Ic -inum , 542.Ic -iregex , 543.Ic -links , 544.Ic -ls , 545.Ic -mmin , 546.Ic -print0 547and 548.Ic -regex 549primaries are extensions to 550.St -p1003.2 . 551.Pp 552Historically, the 553.Fl d , 554.Fl h 555and 556.Fl x 557options were implemented using the primaries ``\-depth'', ``\-follow'', 558and ``\-xdev''. 559These primaries always evaluated to true. 560As they were really global variables that took effect before the traversal 561began, some legal expressions could have unexpected results. 562An example is the expression ``\-print \-o \-depth''. 563As \-print always evaluates to true, the standard order of evaluation 564implies that \-depth would never be evaluated. 565This is not the case. 566.Pp 567The operator ``-or'' was implemented as ``\-o'', and the operator ``-and'' 568was implemented as ``\-a''. 569.Pp 570Historic implementations of the 571.Ic -exec 572and 573.Ic -ok 574primaries did not replace the string ``{}'' in the utility name or the 575utility arguments if it had preceding or following non-whitespace characters. 576This version replaces it no matter where in the utility name or arguments 577it appears. 578.Sh HISTORY 579A much simpler 580.Nm find 581command appeared in First Edition AT\*[Am]T Unix. 582The syntax had become similar to the present version by 583the time of the Fifth Edition. 584.Sh BUGS 585The special characters used by 586.Nm 587are also special characters to many shell programs. 588In particular, the characters ``*'', ``['', ``]'', ``?'', ``('', ``)'', 589``!'', ``\e'' and ``;'' may have to be escaped from the shell. 590.Pp 591As there is no delimiter separating options and file names or file 592names and the 593.Ar expression , 594it is difficult to specify files named ``-xdev'' or ``!''. 595These problems are handled by the 596.Fl f 597option and the 598.Xr getopt 3 599``--'' construct. 600