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, and without any special treatment of
 300                         leading periods.
 301 
 302 
 303        -perm [-]mode
 304                         The mode argument is used to represent file mode bits.
 305                         It is identical in format to the symbolic mode
 306                         operand, symbolic_mode_list, described in chmod(1),
 307                         and is interpreted as follows. To start, a template is
 308                         assumed with all file mode bits cleared. An op symbol
 309                         of:
 310 
 311                         +
 312                                 Set the appropriate mode bits in the template
 313 
 314 
 315                         -
 316                                 Clear the appropriate bits
 317 
 318 
 319                         =
 320                                 Set the appropriate mode bits, without regard
 321                                 to the contents of the file mode creation mask
 322                                 of the process
 323 
 324                         The op symbol of - cannot be the first character of
 325                         mode, to avoid ambiguity with the optional leading
 326                         hyphen. Since the initial mode is all bits off, there
 327                         are no symbolic modes that need to use - as the first
 328                         character.
 329 
 330                         If the hyphen is omitted, the primary evaluates as
 331                         true when the file permission bits exactly match the
 332                         value of the resulting template.
 333 
 334                         Otherwise, if mode is prefixed by a hyphen, the
 335                         primary evaluates as true if at least all the bits in
 336                         the resulting template are set in the file permission
 337                         bits.
 338 
 339 
 340        -perm [-]onum
 341                         True if the file permission flags exactly match the
 342                         octal number onum (see chmod(1)). If onum is prefixed
 343                         by a minus sign (-), only the bits that are set in
 344                         onum are compared with the file permission flags, and
 345                         the expression evaluates true if they match.
 346 
 347 
 348        -print
 349                         Always true. Causes the current pathname to be
 350                         printed.
 351 
 352 
 353        -print0
 354                         Always true. Causes the current pathname to be
 355                         printed, terminated by an ASCII NUL character
 356                         (character code 0) instead of a newline.
 357 
 358 
 359        -prune
 360                         Always yields true. Does not examine any directories
 361                         or files in the directory structure below the pattern
 362                         just matched. (See EXAMPLES). If -depth is specified,
 363                         -prune has no effect.
 364 
 365 
 366        -regex pattern
 367                         True if the full path of the file matches pattern
 368                         using regular expressions.
 369 
 370 
 371        -size n[c]
 372                         True if the file is n blocks long (512 bytes per
 373                         block). If n is followed by a c, the size is in bytes.
 374 
 375 
 376        -type c
 377                         True if the type of the file is c, where c is b, c, d,
 378                         D, f, l, p, or s for block special file, character
 379                         special file, directory, door, plain file, symbolic
 380                         link, fifo (named pipe), or socket, respectively.
 381 
 382 
 383        -user uname
 384                         True if the file belongs to the user uname. If uname
 385                         is numeric and there's no such user name, it is taken
 386                         as a user ID.
 387 
 388 
 389        -useracl uname
 390                         True if the file's ACL contains an entry for the user
 391                         uname.  If uname is numeric and there's no such user
 392                         name, it is taken as a user ID.
 393 
 394 
 395        -xdev
 396                         Same as the -mount primary.
 397 
 398 
 399        -xattr
 400                         True if the file has extended attributes.
 401 
 402 
 403    Complex Expressions
 404        The primaries can be combined using the following operators (in order
 405        of decreasing precedence):
 406 
 407        1)(expression)
 408 
 409            True if the parenthesized expression is true (parentheses are
 410            special to the shell and must be escaped).
 411 
 412 
 413        2)!expression
 414 
 415            The negation of a primary (! is the unary not operator).
 416 
 417 
 418        3) expression[-a] expression
 419 
 420            Concatenation of primaries (the and operation is implied by the
 421            juxtaposition of two primaries).
 422 
 423 
 424        4) expression-oexpression
 425 
 426            Alternation of primaries (-o is the or operator).
 427 
 428 
 429 
 430        When you use find in conjunction with cpio, if you use the -L option
 431        with cpio, you must use the -L option or the -follow primitive with
 432        find and vice versa. Otherwise the results are unspecified.
 433 
 434 
 435        If no expression is present, -print is used as the expression.
 436        Otherwise, if the specified expression does not contain any of the
 437        primaries -exec, -ok, -ls, or -print, the specified expression is
 438        effectively replaced by:
 439 
 440 
 441        (specified) -print
 442 
 443 
 444        The -user, -group, and -newer primaries each evaluate their respective
 445        arguments only once. Invocation of command specified by -exec or -ok
 446        does not affect subsequent primaries on the same file.
 447 
 448 USAGE
 449        See largefile(5) for the description of the behavior of find when
 450        encountering files greater than or equal to 2 Gbyte (2^31 bytes).
 451 
 452 EXAMPLES
 453        Example 1 Writing Out the Hierarchy Directory
 454 
 455 
 456        The following commands are equivalent:
 457 
 458 
 459          example% find .
 460          example% find . -print
 461 
 462 
 463 
 464 
 465        They both write out the entire directory hierarchy from the current
 466        directory.
 467 
 468 
 469        Example 2 Removing Files
 470 
 471 
 472        The following command removes all files in your home directory named
 473        a.out or *.o that have not been accessed for a week:
 474 
 475 
 476          example% find $HOME \( -name a.out -o -name '*.o' \) \
 477                 -atime +7 -exec rm {} \;
 478 
 479 
 480 
 481        Example 3 Printing All File Names But Skipping SCCS Directories
 482 
 483 
 484        The following command recursively print all file names in the current
 485        directory and below, but skipping SCCS directories:
 486 
 487 
 488          example% find . -name SCCS -prune -o -print
 489 
 490 
 491 
 492        Example 4 Printing all file names and the SCCS directory name
 493 
 494 
 495        Recursively print all file names in the current directory and below,
 496        skipping the contents of SCCS directories, but printing out the SCCS
 497        directory name:
 498 
 499 
 500          example% find . -print -name SCCS -prune
 501 
 502 
 503 
 504        Example 5 Testing for the Newer File
 505 
 506 
 507        The following command is basically equivalent to the -nt extension to
 508        test(1):
 509 
 510 
 511          example$ if [ -n "$(find
 512          file1 -prune -newer file2)" ]; then
 513 
 514          printf %s\\n "file1 is newer than file2"
 515 
 516 
 517 
 518        Example 6 Selecting a File Using 24-hour Mode
 519 
 520 
 521        The descriptions of -atime, -ctime, and -mtime use the terminology n
 522        ``24-hour periods''. For example, a file accessed at 23:59 is selected
 523        by:
 524 
 525 
 526          example% find . -atime -1 -print
 527 
 528 
 529 
 530 
 531        at 00:01 the next day (less than 24 hours later, not more than one day
 532        ago).  The midnight boundary between days has no effect on the 24-hour
 533        calculation.
 534 
 535 
 536        Example 7 Printing Files Matching a User's Permission Mode
 537 
 538 
 539        The following command recursively print all file names whose permission
 540        mode exactly matches read, write, and execute access for user, and read
 541        and execute access for group and other:
 542 
 543 
 544          example% find . -perm u=rwx,g=rx,o=rx
 545 
 546 
 547 
 548 
 549        The above could alternatively be specified as follows:
 550 
 551 
 552          example% find . -perm a=rwx,g-w,o-w
 553 
 554 
 555 
 556        Example 8 Printing Files with Write Access for other
 557 
 558 
 559        The following command recursively print all file names whose permission
 560        includes, but is not limited to, write access for other:
 561 
 562 
 563          example% find . -perm -o+w
 564 
 565 
 566 
 567        Example 9 Printing Local Files without Descending Non-local Directories
 568 
 569          example% find . ! -local -prune -o -print
 570 
 571 
 572 
 573        Example 10 Printing the Files in the Name Space Possessing Extended
 574        Attributes
 575 
 576          example% find . -xattr
 577 
 578 
 579 
 580 ENVIRONMENT VARIABLES
 581        See environ(5) for descriptions of the following environment variables
 582        that affect the execution of find: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
 583        LC_MESSAGES, and NLSPATH.
 584 
 585        PATH
 586                Determine the location of the utility_name for the -exec and
 587                -ok primaries.
 588 
 589 
 590 
 591        Affirmative responses are processed using the extended regular
 592        expression defined for the yesexpr keyword in the LC_MESSAGES category
 593        of the user's locale. The locale specified in the LC_COLLATE category
 594        defines the behavior of ranges, equivalence classes, and multi-
 595        character collating elements used in the expression defined for
 596        yesexpr. The locale specified in LC_CTYPE determines the locale for
 597        interpretation of sequences of bytes of text data a characters, the
 598        behavior of character classes used in the expression defined for the
 599        yesexpr. See locale(5).
 600 
 601 EXIT STATUS
 602        The following exit values are returned:
 603 
 604        0
 605              All path operands were traversed successfully.
 606 
 607 
 608        >0
 609              An error occurred.
 610 
 611 
 612 FILES
 613        /etc/passwd
 614                            Password file
 615 
 616 
 617        /etc/group
 618                            Group file
 619 
 620 
 621        /etc/dfs/fstypes
 622                            File that registers distributed file system
 623                            packages
 624 
 625 
 626 ATTRIBUTES
 627        See attributes(5) for descriptions of the following attributes:
 628 
 629 
 630 
 631 
 632        +--------------------+-------------------+
 633        |  ATTRIBUTE TYPE    |  ATTRIBUTE VALUE  |
 634        +--------------------+-------------------+
 635        |CSI                 | Enabled           |
 636        +--------------------+-------------------+
 637        |Interface Stability | Committed         |
 638        +--------------------+-------------------+
 639        |Standard            | See standards(5). |
 640        +--------------------+-------------------+
 641 
 642 SEE ALSO
 643        chmod(1), cpio(1), sh(1), test(1), ls(1B), acl(5), regex(5), stat(2),
 644        umask(2), attributes(5), environ(5), fsattr(5), largefile(5),
 645        locale(5), standards(5)
 646 
 647 WARNINGS
 648        The following options are obsolete and will not be supported in future
 649        releases:
 650 
 651        -cpio device
 652                         Always true. Writes the current file on device in cpio
 653                         format (5120-byte records).
 654 
 655 
 656        -ncpio device
 657                         Always true. Writes the current file on device in cpio
 658                         -c format (5120-byte records).
 659 
 660 
 661 NOTES
 662        When using find to determine files modified within a range of time, use
 663        the -mtime argument before the -print argument. Otherwise, find gives
 664        all files.
 665 
 666 
 667        Some files that might be under the Solaris root file system are
 668        actually mount points for virtual file systems, such as mntfs or
 669        namefs. When comparing against a ufs file system, such files are not
 670        selected if -mount or -xdev is specified in the find expression.
 671 
 672 
 673        Using the -L or -follow option is not recommended when descending a
 674        file-system hierarchy that is under the control of other users. In
 675        particular, when using -exec, symbolic links can lead the find command
 676        out of the hierarchy in which it started. Using -type is not sufficient
 677        to restrict the type of files on which the -exec command operates,
 678        because there is an inherent race condition between the type-check
 679        performed by the find command and the time the executed command
 680        operates on the file argument.
 681 
 682 
 683 
 684                                February 20, 2020                       FIND(1)