1 FIND(1)                          User Commands                         FIND(1)
   2 
   3 
   4 
   5 NAME
   6        find - find files
   7 
   8 SYNOPSIS
   9        /usr/bin/find [-E] [-H | -L] path... expression
  10 
  11 
  12        /usr/xpg4/bin/find [-H | -L] path... expression
  13 
  14 
  15 DESCRIPTION
  16        The find utility recursively descends the directory hierarchy for each
  17        path seeking files that match a Boolean expression written in the
  18        primaries specified below.
  19 
  20 
  21        find is able to descend to arbitrary depths in a file hierarchy and
  22        does not fail due to path length limitations (unless a path operand
  23        specified by the application exceeds PATH_MAX requirements).
  24 
  25 
  26        find detects infinite loops; that is, entering a previously visited
  27        directory that is an ancestor of the last file encountered.
  28 
  29 OPTIONS
  30        The following options are supported:
  31 
  32        -E
  33              Interpret regular expressions followed by -regex and -iregex
  34              primaries as extended regular expressions.
  35 
  36 
  37        -H
  38              Causes the file information and file type evaluated for each
  39              symbolic link encountered on the command line to be those of the
  40              file referenced by the link, and not the link itself. If the
  41              referenced file does not exist, the file information and type is
  42              for the link itself. File information for all symbolic links not
  43              on the command line is that of the link itself.
  44 
  45 
  46        -L
  47              Causes the file information and file type evaluated for each
  48              symbolic link to be those of the file referenced by the link, and
  49              not the link itself. See NOTES.
  50 
  51 
  52 
  53        Specifying more than one of the mutually-exclusive options -H and -L is
  54        not considered an error. The last option specified determines the
  55        behavior of the utility.
  56 
  57 OPERANDS
  58        The following operands are supported:
  59 
  60        path
  61                      A pathname of a starting point in the directory
  62                      hierarchy.
  63 
  64 
  65        expression
  66                      The first argument that starts with a -, or is a ! or a
  67                      (, and all subsequent arguments are interpreted as an
  68                      expression made up of the following primaries and
  69                      operators. In the descriptions, wherever n is used as a
  70                      primary argument, it is interpreted as a decimal integer
  71                      optionally preceded by a plus (+) or minus (-) sign, as
  72                      follows:
  73 
  74                      +n
  75                            more than n
  76 
  77 
  78                      n
  79                            exactly n
  80 
  81 
  82                      -n
  83                            less than n
  84 
  85 
  86 
  87    Expressions
  88        Valid expressions are:
  89 
  90        -acl
  91                         True if the file have additional ACLs defined.
  92 
  93 
  94        -amin n
  95                         File was last accessed n minutes ago.
  96 
  97 
  98        -atime n
  99                         True if the file was accessed n days ago. The access
 100                         time of directories in path is changed by find itself.
 101 
 102 
 103        -cmin n
 104                         File's status was last changed n minutes ago.
 105 
 106 
 107        -cpio device
 108                         Always true. Writes the current file on device in cpio
 109                         format (5120-byte records).
 110 
 111 
 112        -ctime n
 113                         True if the file's status was changed n days ago.
 114 
 115 
 116        -depth
 117                         Always true. Causes descent of the directory hierarchy
 118                         to be done so that all entries in a directory are
 119                         acted on before the directory itself. This can be
 120                         useful when find is used with cpio(1) to transfer
 121                         files that are contained in directories without write
 122                         permission.
 123 
 124 
 125        -exec command
 126                         True if the executed command returns a zero value as
 127                         exit status. The end of command must be punctuated by
 128                         an escaped semicolon (;). A command argument {} is
 129                         replaced by the current pathname. If the last argument
 130                         to -exec is {} and you specify + rather than the
 131                         semicolon (;), the command is invoked fewer times,
 132                         with {} replaced by groups of pathnames. If any
 133                         invocation of the command returns a non-zero value as
 134                         exit status, find returns a non-zero exit status.
 135 
 136 
 137        -follow
 138                         Always true and always evaluated no matter where it
 139                         appears in expression. The behavior is unspecified if
 140                         -follow is used when the find command is invoked with
 141                         either the -H or the -L option.  Causes symbolic links
 142                         to be followed. When following symbolic links, find
 143                         keeps track of the directories visited so that it can
 144                         detect infinite loops.  For example, such a loop would
 145                         occur if a symbolic link pointed to an ancestor.  This
 146                         expression should not be used with the find-type l
 147                         expression. See NOTES.
 148 
 149 
 150        -fstype type
 151                         True if the filesystem to which the file belongs is of
 152                         type type.
 153 
 154 
 155        -group gname
 156                         True if the file belongs to the group gname. If gname
 157                         is numeric and there's no such group name, it is taken
 158                         as a group ID.
 159 
 160 
 161        -groupacl gname
 162                         True if the file's ACL contains an entry for the group
 163                         gname.  If gname is numeric and there's no such group
 164                         name, it is taken as a group ID.
 165 
 166 
 167        -iname pattern
 168                         Like -name, but the match is case insensitive.
 169 
 170 
 171        -inum n
 172                         True if the file has inode number n.
 173 
 174 
 175        -ipath pattern
 176                         Like -path, but the match is case insensitive.
 177 
 178 
 179        -iregex pattern
 180                         Like -regex, but the match is case insensitive.
 181 
 182 
 183        -links n
 184                         True if the file has n links.
 185 
 186 
 187        -local
 188                         True if the file system type is not a remote file
 189                         system type as defined in the /etc/dfs/fstypes file.
 190                         nfs is used as the default remote filesystem type if
 191                         the /etc/dfs/fstypes file is not present. The -local
 192                         option descends the hierarchy of non-local
 193                         directories. See EXAMPLES for an example of how to
 194                         search for local files without descending.
 195 
 196 
 197        -ls
 198                         Always true. Prints current pathname together with its
 199                         associated statistics.  These include (respectively):
 200 
 201                             o      inode number
 202 
 203                             o      size in kilobytes (1024 bytes)
 204 
 205                             o      protection mode
 206 
 207                             o      number of hard links
 208 
 209                             o      user
 210 
 211                             o      group
 212 
 213                             o      size in bytes
 214 
 215                             o      modification time.
 216                         If the file is a special file, the size field instead
 217                         contains the major and minor device numbers.
 218 
 219                         If the file is a symbolic link, the pathname of the
 220                         linked-to file is printed preceded by `->'. The      format
 221                         is identical to that of ls -gilds (see ls(1B)).
 222 
 223                         Formatting is done internally, without executing the
 224                         ls program.
 225 
 226 
 227        -maxdepth n
 228                         Always true; descend at most n directory levels below
 229                         the command line arguments. If any -maxdepth primary
 230                         is specified, it applies to the entire expression even
 231                         if it would not normally be evaluated. -maxdepth 0
 232                         limits the whole search to the command line arguments.
 233 
 234 
 235        -mindepth n
 236                         Always true; do not apply any tests or actions at
 237                         levels less than n. If any -mindepth primary is
 238                         specified, it applies to the entire expression even if
 239                         it would not normally be evaluated.  -mindepth 1
 240                         processes all but the command line arguments.
 241 
 242 
 243        -mmin n
 244                         File's data was last modified n minutes ago.
 245 
 246 
 247        -mount
 248                         Always true. Restricts the search to the file system
 249                         containing the directory specified. Does not list
 250                         mount points to other file systems.
 251 
 252 
 253        -mtime n
 254                         True if the file's data was modified n days ago.
 255 
 256 
 257        -name pattern
 258                         True if pattern matches the basename of the current
 259                         file name. Normal shell file name generation
 260                         characters (see sh(1)) can be used. A backslash (\) is
 261                         used as an escape character within the pattern. The
 262                         pattern should be escaped or quoted when find is
 263                         invoked from the shell.
 264 
 265                         Unless the character '.' is explicitly specified in
 266                         the beginning of pattern, a current file name
 267                         beginning with '.' does not match pattern when using
 268                         /usr/bin/find. /usr/xpg4/bin/find does not make this
 269                         distinction; wildcard file name generation characters
 270                         can match file names beginning with '.'.
 271 
 272 
 273        -ncpio device
 274                         Always true. Writes the current file on device in cpio
 275                         -c format (5120 byte records).
 276 
 277 
 278        -newer file
 279                         True if the current file has been modified more
 280                         recently than the argument file.
 281 
 282 
 283        -nogroup
 284                         True if the file belongs to non-existing group.
 285 
 286 
 287        -nouser
 288                         True if the file belongs to non-existing user.
 289 
 290 
 291        -ok command
 292                         Like -exec, except that the generated command line is
 293                         printed with a question mark first, and is executed
 294                         only if the response is affirmative.
 295 
 296 
 297        -path
 298                         Like -name, but matches the entire file path and not
 299                         just basename.
 300 
 301 
 302        -perm [-]mode
 303                         The mode argument is used to represent file mode bits.
 304                         It is identical in format to the symbolic mode
 305                         operand, symbolic_mode_list, described in chmod(1),
 306                         and is interpreted as follows. To start, a template is
 307                         assumed with all file mode bits cleared. An op symbol
 308                         of:
 309 
 310                         +
 311                                 Set the appropriate mode bits in the template
 312 
 313 
 314                         -
 315                                 Clear the appropriate bits
 316 
 317 
 318                         =
 319                                 Set the appropriate mode bits, without regard
 320                                 to the contents of the file mode creation mask
 321                                 of the process
 322 
 323                         The op symbol of - cannot be the first character of
 324                         mode, to avoid ambiguity with the optional leading
 325                         hyphen. Since the initial mode is all bits off, there
 326                         are no symbolic modes that need to use - as the first
 327                         character.
 328 
 329                         If the hyphen is omitted, the primary evaluates as
 330                         true when the file permission bits exactly match the
 331                         value of the resulting template.
 332 
 333                         Otherwise, if mode is prefixed by a hyphen, the
 334                         primary evaluates as true if at least all the bits in
 335                         the resulting template are set in the file permission
 336                         bits.
 337 
 338 
 339        -perm [-]onum
 340                         True if the file permission flags exactly match the
 341                         octal number onum (see chmod(1)). If onum is prefixed
 342                         by a minus sign (-), only the bits that are set in
 343                         onum are compared with the file permission flags, and
 344                         the expression evaluates true if they match.
 345 
 346 
 347        -print
 348                         Always true. Causes the current pathname to be
 349                         printed.
 350 
 351 
 352        -print0
 353                         Always true. Causes the current pathname to be
 354                         printed, terminated by an ASCII NUL character
 355                         (character code 0) instead of a newline.
 356 
 357 
 358        -prune
 359                         Always yields true. Does not examine any directories
 360                         or files in the directory structure below the pattern
 361                         just matched. (See EXAMPLES). If -depth is specified,
 362                         -prune has no effect.
 363 
 364 
 365        -regex pattern
 366                         True if the full path of the file matches pattern
 367                         using regular expressions.
 368 
 369 
 370        -size n[c]
 371                         True if the file is n blocks long (512 bytes per
 372                         block). If n is followed by a c, the size is in bytes.
 373 
 374 
 375        -type c
 376                         True if the type of the file is c, where c is b, c, d,
 377                         D, f, l, p, or s for block special file, character
 378                         special file, directory, door, plain file, symbolic
 379                         link, fifo (named pipe), or socket, respectively.
 380 
 381 
 382        -user uname
 383                         True if the file belongs to the user uname. If uname
 384                         is numeric and there's no such user name, it is taken
 385                         as a user ID.
 386 
 387 
 388        -useracl uname
 389                         True if the file's ACL contains an entry for the user
 390                         uname.  If uname is numeric and there's no such user
 391                         name, it is taken as a user ID.
 392 
 393 
 394        -xdev
 395                         Same as the -mount primary.
 396 
 397 
 398        -xattr
 399                         True if the file has extended attributes.
 400 
 401 
 402    Complex Expressions
 403        The primaries can be combined using the following operators (in order
 404        of decreasing precedence):
 405 
 406        1)(expression)
 407 
 408            True if the parenthesized expression is true (parentheses are
 409            special to the shell and must be escaped).
 410 
 411 
 412        2)!expression
 413 
 414            The negation of a primary (! is the unary not operator).
 415 
 416 
 417        3) expression[-a] expression
 418 
 419            Concatenation of primaries (the and operation is implied by the
 420            juxtaposition of two primaries).
 421 
 422 
 423        4) expression-oexpression
 424 
 425            Alternation of primaries (-o is the or operator).
 426 
 427 
 428 
 429        When you use find in conjunction with cpio, if you use the -L option
 430        with cpio, you must use the -L option or the -follow primitive with
 431        find and vice versa. Otherwise the results are unspecified.
 432 
 433 
 434        If no expression is present, -print is used as the expression.
 435        Otherwise, if the specified expression does not contain any of the
 436        primaries -exec, -ok, -ls, or -print, the specified expression is
 437        effectively replaced by:
 438 
 439 
 440        (specified) -print
 441 
 442 
 443        The -user, -group, and -newer primaries each evaluate their respective
 444        arguments only once. Invocation of command specified by -exec or -ok
 445        does not affect subsequent primaries on the same file.
 446 
 447 USAGE
 448        See largefile(5) for the description of the behavior of find when
 449        encountering files greater than or equal to 2 Gbyte (2^31 bytes).
 450 
 451 EXAMPLES
 452        Example 1 Writing Out the Hierarchy Directory
 453 
 454 
 455        The following commands are equivalent:
 456 
 457 
 458          example% find .
 459          example% find . -print
 460 
 461 
 462 
 463 
 464        They both write out the entire directory hierarchy from the current
 465        directory.
 466 
 467 
 468        Example 2 Removing Files
 469 
 470 
 471        The following command removes all files in your home directory named
 472        a.out or *.o that have not been accessed for a week:
 473 
 474 
 475          example% find $HOME \( -name a.out -o -name '*.o' \) \
 476                 -atime +7 -exec rm {} \;
 477 
 478 
 479 
 480        Example 3 Printing All File Names But Skipping SCCS Directories
 481 
 482 
 483        The following command recursively print all file names in the current
 484        directory and below, but skipping SCCS directories:
 485 
 486 
 487          example% find . -name SCCS -prune -o -print
 488 
 489 
 490 
 491        Example 4 Printing all file names and the SCCS directory name
 492 
 493 
 494        Recursively print all file names in the current directory and below,
 495        skipping the contents of SCCS directories, but printing out the SCCS
 496        directory name:
 497 
 498 
 499          example% find . -print -name SCCS -prune
 500 
 501 
 502 
 503        Example 5 Testing for the Newer File
 504 
 505 
 506        The following command is basically equivalent to the -nt extension to
 507        test(1):
 508 
 509 
 510          example$ if [ -n "$(find
 511          file1 -prune -newer file2)" ]; then
 512 
 513          printf %s\\n "file1 is newer than file2"
 514 
 515 
 516 
 517        Example 6 Selecting a File Using 24-hour Mode
 518 
 519 
 520        The descriptions of -atime, -ctime, and -mtime use the terminology n
 521        ``24-hour periods''. For example, a file accessed at 23:59 is selected
 522        by:
 523 
 524 
 525          example% find . -atime -1 -print
 526 
 527 
 528 
 529 
 530        at 00:01 the next day (less than 24 hours later, not more than one day
 531        ago).  The midnight boundary between days has no effect on the 24-hour
 532        calculation.
 533 
 534 
 535        Example 7 Printing Files Matching a User's Permission Mode
 536 
 537 
 538        The following command recursively print all file names whose permission
 539        mode exactly matches read, write, and execute access for user, and read
 540        and execute access for group and other:
 541 
 542 
 543          example% find . -perm u=rwx,g=rx,o=rx
 544 
 545 
 546 
 547 
 548        The above could alternatively be specified as follows:
 549 
 550 
 551          example% find . -perm a=rwx,g-w,o-w
 552 
 553 
 554 
 555        Example 8 Printing Files with Write Access for other
 556 
 557 
 558        The following command recursively print all file names whose permission
 559        includes, but is not limited to, write access for other:
 560 
 561 
 562          example% find . -perm -o+w
 563 
 564 
 565 
 566        Example 9 Printing Local Files without Descending Non-local Directories
 567 
 568          example% find . ! -local -prune -o -print
 569 
 570 
 571 
 572        Example 10 Printing the Files in the Name Space Possessing Extended
 573        Attributes
 574 
 575          example% find . -xattr
 576 
 577 
 578 
 579 ENVIRONMENT VARIABLES
 580        See environ(5) for descriptions of the following environment variables
 581        that affect the execution of find: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
 582        LC_MESSAGES, and NLSPATH.
 583 
 584        PATH
 585                Determine the location of the utility_name for the -exec and
 586                -ok primaries.
 587 
 588 
 589 
 590        Affirmative responses are processed using the extended regular
 591        expression defined for the yesexpr keyword in the LC_MESSAGES category
 592        of the user's locale. The locale specified in the LC_COLLATE category
 593        defines the behavior of ranges, equivalence classes, and multi-
 594        character collating elements used in the expression defined for
 595        yesexpr. The locale specified in LC_CTYPE determines the locale for
 596        interpretation of sequences of bytes of text data a characters, the
 597        behavior of character classes used in the expression defined for the
 598        yesexpr. See locale(5).
 599 
 600 EXIT STATUS
 601        The following exit values are returned:
 602 
 603        0
 604              All path operands were traversed successfully.
 605 
 606 
 607        >0
 608              An error occurred.
 609 
 610 
 611 FILES
 612        /etc/passwd
 613                            Password file
 614 
 615 
 616        /etc/group
 617                            Group file
 618 
 619 
 620        /etc/dfs/fstypes
 621                            File that registers distributed file system
 622                            packages
 623 
 624 
 625 ATTRIBUTES
 626        See attributes(5) for descriptions of the following attributes:
 627 
 628 
 629 
 630 
 631        +--------------------+-------------------+
 632        |  ATTRIBUTE TYPE    |  ATTRIBUTE VALUE  |
 633        +--------------------+-------------------+
 634        |CSI                 | Enabled           |
 635        +--------------------+-------------------+
 636        |Interface Stability | Committed         |
 637        +--------------------+-------------------+
 638        |Standard            | See standards(5). |
 639        +--------------------+-------------------+
 640 
 641 SEE ALSO
 642        chmod(1), cpio(1), sh(1), test(1), ls(1B), acl(5), regex(5), stat(2),
 643        umask(2), attributes(5), environ(5), fsattr(5), largefile(5),
 644        locale(5), standards(5)
 645 
 646 WARNINGS
 647        The following options are obsolete and will not be supported in future
 648        releases:
 649 
 650        -cpio device
 651                         Always true. Writes the current file on device in cpio
 652                         format (5120-byte records).
 653 
 654 
 655        -ncpio device
 656                         Always true. Writes the current file on device in cpio
 657                         -c format (5120-byte records).
 658 
 659 
 660 NOTES
 661        When using find to determine files modified within a range of time, use
 662        the -mtime argument before the -print argument. Otherwise, find gives
 663        all files.
 664 
 665 
 666        Some files that might be under the Solaris root file system are
 667        actually mount points for virtual file systems, such as mntfs or
 668        namefs. When comparing against a ufs file system, such files are not
 669        selected if -mount or -xdev is specified in the find expression.
 670 
 671 
 672        Using the -L or -follow option is not recommended when descending a
 673        file-system hierarchy that is under the control of other users. In
 674        particular, when using -exec, symbolic links can lead the find command
 675        out of the hierarchy in which it started. Using -type is not sufficient
 676        to restrict the type of files on which the -exec command operates,
 677        because there is an inherent race condition between the type-check
 678        performed by the find command and the time the executed command
 679        operates on the file argument.
 680 
 681 
 682 
 683                                September 5, 2011                       FIND(1)