find.1 (12616B)
1 '\" t 2 .\" Sccsid @(#)find.1 1.44 (gritter) 8/14/05 3 .\" Parts taken from find(1), Unix 7th edition: 4 .\" Copyright(C) Caldera International Inc. 2001-2002. All rights reserved. 5 .\" 6 .\" Redistribution and use in source and binary forms, with or without 7 .\" modification, are permitted provided that the following conditions 8 .\" are met: 9 .\" Redistributions of source code and documentation must retain the 10 .\" above copyright notice, this list of conditions and the following 11 .\" disclaimer. 12 .\" Redistributions in binary form must reproduce the above copyright 13 .\" notice, this list of conditions and the following disclaimer in the 14 .\" documentation and/or other materials provided with the distribution. 15 .\" All advertising materials mentioning features or use of this software 16 .\" must display the following acknowledgement: 17 .\" This product includes software developed or owned by Caldera 18 .\" International, Inc. 19 .\" Neither the name of Caldera International, Inc. nor the names of 20 .\" other contributors may be used to endorse or promote products 21 .\" derived from this software without specific prior written permission. 22 .\" 23 .\" USE OF THE SOFTWARE PROVIDED FOR UNDER THIS LICENSE BY CALDERA 24 .\" INTERNATIONAL, INC. AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR 25 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 26 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 27 .\" ARE DISCLAIMED. IN NO EVENT SHALL CALDERA INTERNATIONAL, INC. BE 28 .\" LIABLE FOR ANY DIRECT, INDIRECT INCIDENTAL, SPECIAL, EXEMPLARY, OR 29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 31 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 32 .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 33 .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 34 .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 35 .\" 36 .TH FIND 1 "8/14/05" "Heirloom Toolchest" "User Commands" 37 .SH NAME 38 find \- find files 39 .SH SYNOPSIS 40 .B find 41 .I pathname-list expression 42 .SH DESCRIPTION 43 .I Find 44 recursively descends 45 the directory hierarchy for 46 each pathname in the 47 .I pathname-list 48 (i.\|e., one or more pathnames) 49 seeking files that match a boolean 50 .I expression 51 written in the primaries given below. 52 In the descriptions, the argument 53 .I n 54 is used as a decimal integer 55 where 56 .I +n 57 means more than 58 .I n, 59 .I \-n 60 means less than 61 .I n 62 and 63 .I n 64 means exactly 65 .IR n . 66 .TP 10n 67 .BR \-name " filename" 68 True if the 69 .I filename 70 argument matches the current file name. 71 Normal 72 Shell 73 argument syntax 74 as described in 75 .IR glob (7) 76 may be used if escaped (watch out for 77 `[', `?' and `*'). 78 The internationalization constructs 79 `[[:class:]]', `[[=e=]]', and `[[.cs.]]' 80 are understood with 81 .BR /usr/5bin/s42/find , 82 .BR /usr/5bin/posix/find , 83 and 84 .BR /usr/5bin/posix2001/find , 85 but not with 86 .BR /usr/5bin/find . 87 .TP 88 .BR \-perm " mode" 89 True if the file permission flags 90 exactly 91 match the 92 octal number 93 or symbolic 94 .I mode 95 (see 96 .IR chmod (1)). 97 If 98 .I mode 99 is prefixed by a minus sign, 100 the flags are compared: 101 .IR (flags&mode)==mode . 102 .TP 103 .BR \-type " c" 104 True if the type of the file 105 is 106 .I c, 107 where 108 .I c 109 is 110 .sp 111 .TS 112 lfB l. 113 b block special file; 114 c character special file; 115 d directory; 116 D Solaris door; 117 f plain file; 118 l symbolic link; 119 n HP-UX network special file; 120 p named pipe; 121 s socket. 122 .TE 123 .TP 124 .B \-follow 125 Always true; 126 causes find to follow symbolic links. 127 The `\fB\-type\fR l' condition never occurs in this case. 128 .TP 129 .BR \-links " n" 130 True if the file has 131 .I n 132 links. 133 .TP 134 .BR \-user " uname" 135 True if the file belongs to the user 136 .I uname 137 (login name or numeric user ID). 138 .TP 139 .BR \-group " gname" 140 True if the file belongs to group 141 .I gname 142 (group name or numeric group ID). 143 .TP 144 .BR \-size " n[" c ] 145 True if the file is 146 .I n 147 blocks long (512 bytes per block), 148 or, with 149 .BR c , 150 .I n 151 bytes long. 152 .TP 153 .BR \-inum " n" 154 True if the file has inode number 155 .I n. 156 .TP 157 .BR \-atime " n" 158 True if the file has been accessed in 159 .I n 160 days. 161 .TP 162 .BR \-mtime " n" 163 True if the file has been modified in 164 .I n 165 days. 166 .TP 167 .BR \-ctime " n" 168 True if the file inode has been changed in 169 .I n 170 days. 171 .TP 172 .BR \-exec " command ... " ; 173 True if the executed command returns 174 a zero value as exit status. 175 The end of the command must be punctuated by an (escaped) 176 semicolon. 177 A command argument `{}' is replaced by the 178 current pathname. 179 .TP 180 .BR \-exec " command ... " "{} +" 181 Always true. 182 The 183 .B {} 184 argument is replaced by a set of aggregated pathnames. 185 Each pathname is passed to the command as a single argument. 186 Every time a limit of arguments is reached 187 by the pathnames found so far, 188 the command is executed, 189 and aggregating starts using a new set 190 beginning with the next pathname. 191 If any invocation of command 192 returns a non-zero exit status, 193 find will return a non-zero exit status 194 when its processing is done. 195 .TP 196 .BR \-ok " command ... " ; 197 Like 198 .B \-exec 199 except that the generated command is written on 200 the standard output, then the standard input is read 201 and the command executed only upon response 202 .BR y . 203 .TP 204 .B \-print 205 Always true; 206 causes the current pathname to be printed. 207 If no expression is given, 208 .B \-print 209 is used per default 210 (as a change introduced by POSIX.2). 211 .TP 212 .BR \-newer " file" 213 True if 214 the current file has been modified more recently than the argument 215 .I file. 216 .TP 217 .BR \-anewer " file" 218 True if 219 the current file has been accessed more recently than the argument 220 .I file 221 was modified. 222 This primary is an extension. 223 .TP 224 .BR \-cnewer " file" 225 True if a status change 226 has occurred on the current file 227 more recently than the argument 228 .I file 229 was modified. 230 This primary is an extension. 231 .TP 232 .B \-depth 233 Always true; 234 causes the contents of each directory 235 to be examined before the directory itselves. 236 .TP 237 .BR \-fstype " type" 238 True if the current file 239 resides on a file system of the given type. 240 .TP 241 .B \-local 242 True if the file is on a local file system. 243 Are file system types except for 244 .I nfs 245 and 246 .I smbfs 247 are currently considered local. 248 .TP 249 .B \-mount 250 Always true; 251 restricts the search to directories 252 that have the same device id 253 as the currently examined path operand. 254 .TP 255 .B \-xdev 256 The same as 257 .BR \-mount . 258 This primary has been introduced by POSIX. 259 .TP 260 .B \-nouser 261 True if the file is owned by a user 262 that has no login name. 263 .TP 264 .B \-nogroup 265 True if the file is owned by a group 266 that lacks a group name. 267 .TP 268 .B \-prune 269 Always true. 270 Causes the search for the current path 271 to be stopped once the primary is evaluated. 272 When combined with 273 .BR \-depth , 274 .B \-prune 275 has no effect. 276 .TP 277 .BR \-cpio " device" 278 Always true. 279 Writes the file on the named device 280 in binary cpio format (5120-byte records). 281 Implies 282 .BR \-depth . 283 .TP 284 .BR \-ncpio " device" 285 Always true. 286 Writes the file on the named device 287 in SVR4 ASCII cpio format (5120-byte records). 288 Implies 289 .BR \-depth . 290 .PP 291 The primaries may be combined using the following operators 292 (in order of decreasing precedence): 293 .TP 4 294 1) 295 A parenthesized group of primaries and operators 296 (parentheses are special to the Shell and must be escaped). 297 .TP 4 298 2) 299 The negation of a primary 300 (`!' is the unary 301 .I not 302 operator). 303 .TP 4 304 3) 305 Concatenation of primaries 306 (the 307 .I and 308 operation 309 is implied by the juxtaposition of two primaries 310 or by an explicit 311 .B \-a 312 operator). 313 .TP 4 314 4) 315 Alternation of primaries 316 .RB "(`" \-o "' is the" 317 .I or 318 operator). 319 .PP 320 Options have been introduced by POSIX.1-2001 321 in addition to the expression operators. 322 They must preceed the 323 .I pathname-list 324 one the command line 325 and have no effect on boolean expression processing. 326 .TP 327 .B \-H 328 Follow symbolic links given on the command line, 329 but do not follow symbolic links encountered during directory traversal. 330 .TP 331 .B \-L 332 Follow all symbolic links found, 333 like the 334 .I \-follow 335 primary. 336 .PP 337 With the 338 .I \-follow 339 primary or the 340 .I \-L 341 option, hierarchy loops caused by symbolic links are detected, 342 but only 343 .B /usr/5bin/posix2001/find 344 prints an error message. 345 The offending link is not followed, 346 and operation continues with the next directory entry found. 347 .SH EXAMPLES 348 To remove all files named 349 `a.out' or `*.o' that have not been accessed for a week: 350 .IP "" .2i 351 find / \\( \-name a.out \-o \-name \'*.o\' \\) 352 \-atime +7 \-exec rm {} \\; 353 .PP 354 The rm command is executed once for each file. 355 The form 356 .IP "" .2i 357 find / \\( \-name a.out \-o \-name \'*.o\' \\) 358 \-atime +7 \-exec rm {} + 359 .PP 360 is faster since the rm command is executed with a set of pathnames. 361 .PP 362 To find all files below the directory `documents' 363 that contain the regular expression `string': 364 .IP "" .2i 365 find documents \-type f \-exec grep string {} + 366 .PP 367 To find all files in the directory `home', 368 not descending into its subdirectories: 369 .IP "" .2i 370 find home ! \-name home \-prune 371 .PP 372 To check whether the file `diary' 373 has been updated within the last two days; 374 the name of the file is printed if true, 375 and is not printed otherwise: 376 .IP "" .2i 377 find diary \-prune \-mtime \-2 378 .SH FILES 379 /etc/passwd 380 .br 381 /etc/group 382 .SH "ENVIRONMENT VARIABLES" 383 .TP 384 .BR LANG ", " LC_ALL 385 See 386 .IR locale (7). 387 .TP 388 .B LC_COLLATE 389 Affects the collation order for range expressions, 390 equivalence classes, and collation symbols in patterns with 391 .BR /usr/5bin/s42/find , 392 .BR /usr/5bin/posix/find , 393 and 394 .BR /usr/5bin/posix2001/find . 395 .TP 396 .B LC_CTYPE 397 Determines the mapping of bytes to characters 398 and character class expressions 399 in patterns. 400 .TP 401 .B SYSV3 402 Causes the text of some diagnostic messages to be changed; 403 causes 404 .I \-ncpio 405 to create traditional ASCII cpio format archives. 406 .SH "SEE ALSO" 407 chmod(1), 408 cpio(1), 409 pax(1), 410 sh(1), 411 xargs(1), 412 stat(2), 413 glob(7), 414 locale(7) 415 .SH NOTES 416 Undesired effects can result if file names printed by 417 .I find 418 contain newline characters, 419 as shown by the following command sequence: 420 .RS 421 .sp 422 .nf 423 $ mkdir \-p \'dummy 424 > /etc\' 425 $ touch \'dummy 426 > /etc/passwd\' 427 $ find . \-print 428 \&. 429 \&./dummy 430 .sp 431 \&./dummy 432 /etc 433 \&./dummy 434 /etc/passwd 435 $\ 436 .fi 437 .sp 438 .RE 439 Shell scripts or utilities unaware of this problem 440 will operate on 441 .I /etc/passwd 442 (or other arbitrary file names) 443 when reading such output; 444 a malicious user might create such files 445 to read or overwrite privileged information. 446 To circumvent this problem, 447 one of the following proposals should be taken 448 unless the file hierarchy traversed by the 449 .I find 450 command is definitively known not to contain such file names: 451 .IP \(en 2 452 If the output is read by the 453 .I xargs 454 utility to gain faster execution by aggregating command arguments as in 455 .in +2 456 .sp 457 find . \-print | xargs \fIcommand\fR 458 .sp 459 .in -2 460 a safe and equally fast substitute is the 461 .in +2 462 .sp 463 find . \-exec \fIcommand\fR {} + 464 .sp 465 .in -2 466 operand of 467 .IR find ; 468 it is not portably accepted by 469 .I find 470 implementations, though. 471 .IP \(en 2 472 A universal solution for submitting file names to the 473 .I xargs 474 utility is given in the 475 .I NOTES 476 section of 477 .IR xargs (1). 478 .IP \(en 2 479 The method employed by this script can be generalized as follows: 480 If the script or utility reading the output of 481 .I find 482 provides the necessary parsing capabilities, 483 special path prefixes can be given to the 484 .I find 485 command, such as 486 .in +2 487 .sp 488 find /.//. \-print 489 .sp 490 .in -2 491 for absolute path names or 492 .in +2 493 .sp 494 find .//. \-print 495 .sp 496 .in -2 497 for relative path names. 498 Since adjacent slash characters never appear 499 in relative file names found during directory traversal, 500 they can be taken as delimiters; 501 a line starts a new path name 502 only if the delimiter appears. 503 .IP \(en 2 504 The 505 .I \-name 506 operand can be used to exclude all path names 507 that contain newline characters, as in 508 .in +2 509 .sp 510 .nf 511 $ find . \-name \'* 512 > *\' \-prune \-o ! \-name \'* 513 > *\' \-print 514 .sp 515 .fi 516 .in -2 517 Note that certain other implementations of 518 .I find 519 require a leading period in the pattern 520 to match file names with a leading period; 521 it may be necessary to exclude such patterns as well. 522 .IP \(en 2 523 The 524 .I \-depth 525 operand cannot be combined with the 526 .I \-prune 527 operand used in the previous example. 528 When the directory name must be printed 529 after file names below that directory, 530 as with the 531 .IR cpio 532 command, 533 file names that leave the specified path hierarchy 534 should be filtered out: 535 .in +2 536 .sp 537 find . \-depth | egrep \'^\e./\' | cpio \-oc \-O /dev/rmt/c0s0 538 .sp 539 .in -2 540 (note the escaped regular expression meta-character). 541 .IP \(en 2 542 The 543 .I \-cpio 544 and 545 .I \-ncpio 546 operands will automatically exclude file names 547 that contain newline characters 548 with this 549 .I find 550 implementation. 551 .PP 552 The 553 .I \-print0 554 operand supported by some other implementations 555 is considered a very limited work-around 556 since it does not allow the output to be processed 557 by utilities unaware of NUL characters; 558 it has therefore not been included here.