find -- find files within file tree

find walks down the given file hierarchy starting at directory, and finds files which match the criteria given by expression. Each directory, file, and special file is checked against expression. If you use the -exec, -ok, or -cpio primaries, expression has the side-effect of invoking a specified command on each file found. A non-existent expression or an expression with no side-effects automatically uses the -print primary to display the name of any file that matches the criteria of expression.

find builds expression from a set of primaries and operators. The juxtaposition of two primaries implies the logical AND operator. You can group primaries and operators using parentheses.

Note:: Parentheses, semi-colons and braces are shell metacharacters. You must quote them to use them in an expression.

You must delimit all primaries, operators, numbers, arguments, and parentheses with white space. Each number noted in the primary list is a decimal number, optionally preceded by a plus (+) or minus (-) sign. If a number is given without a sign, find tests for equality; a plus sign implies greater than or older than and a minus sign implies less than or newer than.

Operators

find accepts the following operators:

-a: is used between primaries for logical AND. This operator can be omitted with the same result since logical AND is assumed when no operator is used between two primaries.
-o: is used between primaries for logical OR.
!: negates expression which follows it.

Primaries

find accepts the following primaries:

-acl user-pattern [:[+-=]access-mask]

matches if the file has a name in its Access Control List which matches user-pattern and the optional access-mask information also matches. The user-pattern uses the same syntax as file name generation (see sh). For example,

find c:/ -acl '*Administrator'

finds files with an ACL for Administrator in any domain.

You can optionally specify an access mask which takes the same form as that used by the chacl command; that is, the different permissions are separated by spaces. The following symbols determine how the access-mask matches the ACL:

=     matches if only the specified permission bits are on.
-     matches if only the specified permission bits are off.
+     matches if at least the specified permission bits are on.

For example,

find c:/ -acl '*Administrator:+r w'

finds files with an ACL for Administrator in any domain which have read and write permissions.

-atime number

matches if someone accessed the file during the 24-hour period beginning number days ago.

-cpio cpio-file

writes the file found to the target file cpio-file in cpio format. This is equivalent to

find ... | cpio -o >cpio-file

This primary matches if the command succeeds.

-ctime number

matches if the file was creation during the 24-hour period beginning number days ago.

-depth

processes directories after their contents. If present, this primary always matches.

-exec command ;

takes all arguments between -exec and the semicolon as a command line, replacing any argument which is exactly {} (that is, the two brace characters) with the current path name. It then executes the resulting command line, treating a return status of zero from this command as a successful match, non-zero as failure. The terminal semicolon must be quoted or escaped and delimited with white spce.

-follow

follows symbolic links. If present, this primary always matches.

Note:: Symbolic links are only available on 8.1/2012R2/2016/2019/2022 systems with the NTFS file system.

-group name

matches if the group owner is name. If name is not a valid group name, it is treated as a group ID. On 8.1/2012R2/10/2016/2019/11/2022, if the security enhancements are enabled (see security) then 8.1/2012R2/10/2016/2019/11/2022 group names can be used. Using groupID numbers should not be used in this case. On 8.1/2012R2/10/2016/2019/11/2022, if the security enhancements are disabled, groupID 0 can be used to select all files.

-inum number

matches if the file has inode number number. This option is not useful on the extended FAT and NTFS file systems where files do not have inode numbers (See stat).

-level number

does not descend below number levels.

Note:: find only recognizes one -level primary on a command line (even when it appears on different sides of a logical operator). If you do specify -level multiple times, find only uses the last one.

-links number

matches if there are number links to the file. Files on the extended FAT file system have exactly one link.

-ls

displays the equivalent of ls -ld for the file.

Addtional ls options can be specified with the TK_FIND_LS_OPTIONS environment variables.

-mtime number

matches if someone modified the file during the 24-hour period beginning number days ago.

-name pattern

compares the current file name to pattern. If there is no match, expression fails. The pattern uses the same syntax as file name generation (see sh). It attempts to match as many trailing path name components as specified in pattern.

-ncpio cpio-file

writes the file found to the target file cpio-file in cpio -c format. This is equivalent to

find ... | cpio -oc >cpio-file

This primary matches if the command succeeds.

-newer file

compares the modification date of the found file to that of the file given. This matches if someone has modified the found file more recently than file.

-nogroup

matches if no group with a name in the group database (traditionally the file /etc/group) owns the file.

-none

indicates that some action has been taken; thus find does not invoke the default -print action. If present, this primary always matches.

-nouser

matches if no user with a name in the user database (traditionally the file /etc/passwd) owns the file.

-ok command ;

is similar to -exec, but before find executes the command, it displays the command to confirm that you want to go ahead. find only executes the command line if your input matches the expression for yes. If you type the expression for no, the primary does not match. The terminal semicolon must be quoted or escaped and delimited with white spce.

-perm [-]mask

by default, matches if the permissions on the file are identical to the ones given in mask. You may specify mask in octal or in symbolic mode (see chmod). If you use symbolic mode, find assumes that you begin with no bits set in mask, and the symbolic mode is a recipe for turning the bits you want on and off. A leading minus sign (-) is special. It means that a file matches if at least all the bits in mask are set. As a result, with symbolic mode, you cannot use a mask value which begins with a minus sign (-).

If you use octal mode, find only uses the bottom twelve bits of the mask. With an initial minus sign (-), find again matches only if at least all the limits in mask are set in the file permissions lists.

-print

displays the current file name. This primary always matches.

-prune

stops traversing deeper into the tree at this point. If present, this primary always matches. -prune has no effect if -depth is also specified.

-size number[c]

matches if the size of the file is number blocks long, where a block is 512 bytes. If you include the suffix c, the file size is number bytes.

-streams number

matches if there are number of alternative streams on the file. Files on file systems other than NTFS are likely to display only 1 stream.

-type c

matches if the type of the file is the same as the type given by the character c. Possible values of the character are:

b   block-special
c   char-special
d   directory
f   regular file
l   symbolic link
n   network file
p   FIFO (named pipe)
s   socket

On the extended FAT and NTFS file systems, only directories and regular files exist.

-user name

matches if the owner of the file is name. Name can also be a user ID number. On 8.1/2012R2/10/2016/2019/11/2022, if the security enhancements are enabled (see security) then 8.1/2012R2/10/2016/2019/11/2022 user names can be used. Using numeric userIDs should not be used in this case. On 8.1/2012R2/10/2016/2019/11/2022, if the security enhancements are disabled, userID 0 can be used to select all files.

-xdev

does not cross device boundaries from the root of the tree traversal. If present, this primary always matches.

EXAMPLES

To find all files with the extensions .c and .h, starting at the current point in the directory hierarchy:

find . -name "*.[ch]"

To find all files which have the extension .Z and which were last modified three days ago:

find . -name "*.Z" -mtime 3

To find all files which have the extension .c and which were modified more than three days ago and less than nine days ago:

find . -name "*.c" -a "(" -mtime +3 -a -mtime -9 ")"

To run ls -l on all files over 10 days old:

find . -mtime +10 -exec ls -l "{}" ";"

Here is an extreme example:

find . "(" -name "tmp.*" -o -name "*.tmp" ")"
			-perm =rx -exec rm "{}" ";"

This finds all read-only files (on Windows systems) which have tmp in either part of their names and deletes all such files. Various parts of this expression are quoted to protect them from interpretation by the shell.

In the mopdern world of vulnerability exploits, the bad guys are hiding their expoits in hard to find places. So let's look for files with one or more alternative streams (two or more streams including the unnamed stream) and use ls -l -streams to view the output.

find . -type f -streams +1 -exec ls -l -streams "{}" ";"

or using TK_FIND_LS_OPTIONS to display sizes in human readable form:

export TK_FIND_LS_OPTIONS=h
find . -type f -streams +1 -ls ";"

ENVIRONMENT VARIABLES

PATH

determines the location of the command specified with the -exec or -ok primaries.

TK_FIND_LS_OPTIONS

specifies additional ls options to be used by the -ls primary. When this variable is not set, the -ls primary displays the equivalent of ls -ld for each file found. When it is set, its value is appended to the option list. For example, if TK_FIND_LS_OPTIONS is set to cgi, the -ls primary displays the equivalent of ls -ldcgi for each file found.

Supported ls options that can be included in the TK_FIND_LS_OPTIONS value are -c, -g, -i, -k, -n, -o, -s, and -u. See the ls reference page for more information.

TK_NTLINKS_OFF

MKS Toolkit supports hard links under 8.1/2012R2/10/2016/2019/11/2022 on NTFS file systems. There is a slight loss of performance for this support. If you do not require hard link support, you should set and export the environment variable TK_NTLINKS_OFF to disable this support.

TK_NTSECURITYINFO_OFF

MKS Toolkit supports 8.1/2012R2/10/2016/2019/11/2022 security information on NTFS file systems. There is a slight loss of performance for this support. If you do not require any security information, you should set and export the environment variable TK_NTSECURITYINFO_OFF to disable this feature.

TK_UNIX_FILESYSTEM

When this variable is set, the Enhanced UNIX Compatibility Mode is on and the virtual file system is in use.

Because the virtual file system treats all mounted drives as part of the same file system, a command like:

find / -name example

traverses all mounted drives when the Enhanced UNIX Compatibility Mode is on. To exclude mounted drives, specify the -xdev primary.

find / -xdev -name example

For details on the Enhanced UNIX Compatibility Mode and the virtual file system, see the EUCM reference page.

FILES

/etc/group: for group names for the -group and -nogroup options.
/etc/passwd: for user names for the -user and -nouser options.

DIAGNOSTICS

Possible exit status values are:

0

Successful completion.

1

Failure due to any of the following:

— insufficient memory

— invalid character specified after -type

— cannot obtain information on a file for -newer

— invalid permissions for -perm

— cannot open a file for the -cpio option

— unknown user or group name

— cannot access the PATH variable

— cannot execute a command specified for -exec or -ok

— syntax error

— stack overflow caused by an expression that is too complex

2

Invalid command line option, not enough arguments on command line, missing argument, or argument list that isn't properly terminated.

Messages

bad number specification in "string": You specified an option that takes a numeric value (for example, -atime, -ctime), but did not specify a valid number after the option.
cannot stat file "name" for -newer: You used a -newer option to compare one file to another; however, find could not obtain a modification time for the specified file. Typically, this happens because the file does not exist or you do not have appropriate permissions to obtain this information.

PORTABILITY

POSIX.2. x/OPEN Portability Guide 4.0. All UNIX systems. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019. Windows 11. Windows Server 2022.

Obviously, many of the options are of dubious utility on the extended FAT NTFS file systems (on Windows systems); but we have tried to supply approximations.

Most UNIX systems do not have a default action of -print; hence, they do not need the -none option. The -a operator is undocumented on many UNIX systems. The -cpio, -follow, -inum, -level, -ncpio, and -none primaries are extensions to the POSIX standard.

NOTE

The find command provided with PTC MKS Toolkit should not be confused with the Windows find command.

AVAILABILITY

PTC MKS Toolkit for Power Users
PTC MKS Toolkit for System Administrators
PTC MKS Toolkit for Developers
PTC MKS Toolkit for Interoperability
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

find
find files within file tree

Command

SYNOPSIS

DESCRIPTION