find command (searches for files in directories)
- Organization of this page
Format
find [-d] [-H] [-h] [-L] path-name [...] [search-pattern]
Description
This command specifies paths where you want to conduct a search and then follows the directory hierarchies searching for files. You can specify search conditions and how files that are found are to be handled.
Arguments
You specify options, path names where the search is to be conducted, and a search pattern. The path names where the search is to be conducted are specified as arguments to the find command.
Each option is specified as a one-letter option name preceded by a hyphen (-).
- -d
-
Specifies that files inside the deepest directory are searched for first, and processing proceeds from there up to the directory specified in path-name.
- -H
-
In UNIX, specifies that if a path name specified as an argument is a symbolic link, it is to be treated as if the link target were specified. If the link target does not exist, the symbolic link itself is processed. Symbolic links encountered during the search are not followed. If more than one of the -H, -h, and -L options is specified, the one specified last takes effect.
In Windows, the -H option is ignored.
- -h
-
In UNIX, specifies that anytime a symbolic link is encountered, it is to be followed and processing is to continue. If the link target does not exist, the symbolic link itself is processed. If more than one of the -H, -h, and -L options is specified, the one specified last takes effect.
In Windows, the -h option is ignored.
- -L
-
In UNIX, specifies that anytime a symbolic link is encountered, it is to be followed and processing is to continue. If the link target does not exist, the symbolic link itself is processed. If more than one of the -H, -h, and -L options is specified, the one specified last takes effect.
In Windows, the -L option is ignored.
- path-name
-
Specifies a path name.
- search-pattern
-
Specifies a search pattern (expression). A search pattern consists of primaries and operators.
-
Primaries
- -amin time-difference
-
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the number of minutes specified in time-difference is valid as the difference between the date and time of the last access to the file or directory and the date and time at which execution of the find command starts. A difference in date and time that is less than one minute is rounded up to the nearest minute.
The specified time-difference is interpreted as follows depending on whether no sign is specified or a numeric value with a + or - sign is specified:
-
When a sign is not specified: Specified time difference
-
+ is specified before a numeric value: Greater than the specified value
-
- is specified before a numeric value: Less than the specified value
The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
If time-difference is omitted, an error message (find: primary: requires additional arguments) is output.
In Windows, an error occurs if this primary is specified.
-
- -anewer path-name
-
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the date and time of the most recent access to the file or directory is more recent than the date and time of the most recent access to path-name.
In Windows, an error occurs if this primary is specified.
- -atime time-difference
-
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the number of days specified in time-difference is valid as the difference between the date and time of the last access to the file or directory and the date and time at which execution of the find command starts. A difference in date and time that is less than one day is rounded up to the nearest day.
The specified time-difference is interpreted as follows depending on whether no sign is specified or a numeric value with a + or - sign is specified:
-
When a sign is not specified: Specified time difference
-
+ is specified before a numeric value: Greater than the specified value
-
- is specified before a numeric value: Less than the specified value
The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
If time-difference is omitted, an error message (find: primary: requires additional arguments) is output.
In Windows, an error occurs if this primary is specified.
-
- -cmin time-difference
-
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the number of minutes specified in time-difference is valid as the difference between the last date and time the file information was changed (for example, the date and time the file was written to, or the date and time the owner, group, link count, or mode was changed) and the date and time at which execution of the find command starts. A difference in date and time that is less than one minute is rounded up to the nearest minute.
The specified time-difference is interpreted as follows depending on whether no sign is specified or a numeric value with a + or - sign is specified:
-
When a sign is not specified: Specified time difference
-
+ is specified before a numeric value: Greater than the specified value
-
- is specified before a numeric value: Less than the specified value
The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
If time-difference is omitted, an error message (find: primary: requires additional arguments) is output.
In Windows, an error occurs if this primary is specified.
-
- -cnewer path-name
-
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the last date and time the file information was changed (for example, the date and time the file was written to, or the date and time the owner, group, link count, or mode was changed) is more recent than the last time the file specified in path-name was changed.
In Windows, an error occurs if this primary is specified.
- -ctime time-difference
-
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the number of days specified in time-difference is valid as the difference between the last date and time the file information was changed (for example, the date and time the file was written to, or the date and time the owner, group, link count, or mode was changed) and the date and time at which execution of the find command starts. A difference in date and time that is less than one day is rounded up to the nearest day.
The specified time-difference is interpreted as follows depending on whether no sign is specified or a numeric value with a + or - sign is specified:
-
When a sign is not specified: Specified time difference
-
+ is specified before a numeric value: Greater than the specified value
-
- is specified before a numeric value: Less than the specified value
You can specify time-difference without a sign or with a leading + or - sign. When + is specified, the check determines whether the actual time is greater than the specified time difference value. When - is specified, the check determines whether the actual time is less than the specified time difference value. When no sign is specified, the check determines whether they are the same. The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
If time-difference is omitted, an error message (find: primary: requires additional arguments) is output.
In Windows, an error occurs if this primary is specified.
-
- -depth
-
Specifies that an evaluation is to be performed. The evaluation is true when the directories at the deepest level are searched first, and the files within a directory are processed before the directory itself. This evaluation is always true.
- -empty
-
Specifies that an evaluation is to be performed. The evaluation is true when the file or directory is empty.
- -exec command-line ;
-
Specifies a command line command for processing the files and directories being searched that is to be evaluated.
-
Depending on the shell in which the find command is executed, characters such as the asterisk (*) and semicolon (;) might be expanded by the shell, and so must be enclosed in double quotation marks (") or single quotation marks ('), or must be prefixed with the escape character (\).
-
The command-line specification must terminate with a semicolon (;).
-
The program specified in command-line is launched with the directory from which find was launched set as the current directory.
-
If you specify curly brackets ({ }) in command-line, they are replaced by the path name of the file or directory being searched. Their replacement is an absolute path name if you specified an absolute path name as the path for conducting the search or a relative path name if you specified a relative path name as the path for conducting the search.
-
The evaluation is true if the program specified in command-line terminates with a return code of 0.
-
- -follow
-
This evaluation is always true.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true if whenever a symbolic link is encountered it is to be followed and processing is to continue. If the link target does not exist, the symbolic link itself is processed.
- -group group-name
-
In Windows, this evaluation is always false.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the file belongs to the group whose name is specified. If you specify a number for the group name and no such group name exists, the specified value is interpreted as a group ID.
- -iname pattern
-
See the description of the -name option. This option functions identically except that it does not distinguish between uppercase and lowercase letters.
- -inum number
-
In Windows, this evaluation is always false.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the relationship between the inode number of the file and the specified value is valid.
-
You can specify number without a sign or with a leading + or - sign. When + is specified, the check determines whether the inode number is greater than the specified value. When - is specified, the check determines whether the inode number is less than the specified value. When no sign is specified, the check determines whether they are the same. The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
-
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
-
If number is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -links link-count
-
In Windows, this evaluation is always false.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the relationship between the link count for the file and the specified value is valid.
-
You can specify link-count without a sign or with a leading + or - sign. When + is specified, the check determines whether the link count for the file is greater than the specified value. When - is specified, the check determines whether the link count for the file is less than the specified value. When no sign is specified, the check determines whether they are the same. The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
-
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
-
If link-count is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -ls
-
In Windows, specifies that the file permissions, owner name, size (in bytes), most recent modification date and time, and path name are to be output to the standard output. This evaluation is always true.
In UNIX, specifies that the inode number, size (in units of 512 bytes), file permissions, hard links count, owner name, group, size (in bytes), most recent modification date and time, and path name are to be output to the standard output.
This evaluation is always true. If the file is a special file, the major and minor numbers are output instead of the size (in bytes). If the file is a symbolic link, -> is displayed followed by the path name of the link target.
- -maxdepth depth
-
Specifies an evaluation that is to be performed. The evaluation is true when the depth of the directory currently being searched is less than or equal to the specified value. The depth of a specified directory initially is 1.
-
The specified value must be in the range of 0 through 32767. If 0 is specified, the search target becomes the directory only (the files stored in the directory are not searched).
-
If you specify a value greater than the maximum specifiable value, an error message (find: specified-value: maxdepth value too large) is output.
-
If you specify a non-numeric value, an error message (find: specified-character-string: primary: value invalid) is output.
-
If depth is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -mindepth depth
-
Specifies an evaluation that is to be performed. The evaluation is true when the depth of the directory currently being searched is greater than or equal to the specified value.
-
The specified value must be in the range of 0 through 32767.
-
No error occurs is the specified value is greater than the maximum specifiable value.
-
If you specify a non-numeric value for depth, 0 is assumed.
-
If depth is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -mmin time-difference
-
Specifies an evaluation that is to be performed. The evaluation is true when the number of minutes specified in time-difference is valid as the difference between the last date and time the file or directory was modified and the time at which execution of the find command starts. A difference in date and time that is less than one minute is rounded up to the nearest minute.
-
You can specify time-difference without a sign or with a leading + or - sign. When + is specified, the check determines whether the actual time is greater than the specified time difference value. When - is specified, the check determines whether the actual time is less than the specified time difference value. When no sign is specified, the check determines whether they are the same. The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value 2147483647 is assumed.
-
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
-
If time-difference is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -mtime time-difference
-
Specifies an evaluation that is to be performed. The evaluation is true when the number of days specified in time-difference is valid as the difference between the time of the last modification of the file or directory and the time at which execution of the find command starts. A time difference that is less than one day is rounded up to the nearest day.
-
You can specify time-difference without a sign or with a leading + or - sign. When + is specified, the check determines whether the actual time is greater than the specified time difference value. When - is specified, the check determines whether the actual time is less than the specified time difference value. When no sign is specified, the check determines whether they are the same. The specified value must not exceed 2147483647 (0x7fffffff). If you specify a greater value, 2147483647 is assumed.
-
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
-
If time-difference is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -mount
-
This is always true. In UNIX, this argument specifies that a directory whose device number differs from that of the directory in which the search began is not to be searched.
- -name pattern
-
Specifies an evaluation that is to be performed. The evaluation is true when the name of the file or directory to be searched for matches the value specified in pattern.
The pattern is specified as a combination of characters and wildcards. You can use the escape character (\) to specify as part of the pattern value a character that would otherwise be a wildcard. If the escape character (\) is specified before a character that is not a wildcard characters, the \ is ignored.
The following table shows the characters that can be used as wildcards:
Wildcard
Meaning
?
Matches any single character.
*
Matches a character string of zero or more characters.
[ ]
Matches any single character in the character string enclosed in [ ]. If there is an ! or a ^ at the beginning of the character string enclosed in [ ], there is a match if none of the characters in [ ] is found. If two characters are separated by a hyphen (-), the match is of any character between those two characters (including the two characters themselves).
The following examples illustrate the use of the [ ] wildcard:
Example
Meaning
[!abc]
Matches any character other than a, b, or c.
[0-9]
Matches any character from 0 through 9.
[a-z]
Matches any lowercase letter.
[A-Z]
Matches any uppercase letter.
[0-9a-zA-Z]
Matches any alphanumeric character.
- -newer path-name
-
Specifies an evaluation that is to be performed. The evaluation is true when the current file or directory is newer than the time at which path-name was last modified.
- -nogroup
-
In Windows, this evaluation is always false.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the current file belongs to a non-existent group.
- -nouser
-
In Windows, this evaluation is always false.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the owner of the current file is a non-existent user.
- -ok command-line ;
-
Specifies a command line command for processing the files and directories being searched that is to be evaluated.
-
Depending on the shell in which the find command is executed, characters such as the asterisk (*) and semicolon (;) might be expanded by the shell, and so must be enclosed in double quotation marks (") or single quotation marks ('), or must be prefixed with the escape character (\).
-
The command-line specification must terminate with a semicolon (;).
-
The program specified in command-line is launched with the directory from which find was launched set as the current directory. Before the program is launched, a prompt is output asking for confirmation. If the response from the standard input is not y, the specified command does not execute and false is returned.
-
If you specify curly brackets ({ }) in command-line, they are replaced by the path name of the file or directory being searched. Their replacement is an absolute path name if you specified an absolute path name as the path for conducting the search or a relative path name if you specified a relative path name as the path for conducting the search.
-
The evaluation is true if the program specified in command-line terminates with a return code of 0.
-
- -path pattern
-
Specifies an evaluation that is to be performed. The evaluation is true when the name of the file or directory to be searched for matches the value specified in pattern.
-
The pattern is specified as a combination of characters and wildcards. You can use the escape character (\) to specify as part of the pattern value a character that would otherwise be a wildcard. If the escape character (\) is specified before a character that is not a wildcard characters, the \ is ignored.
-
For details about specifying pattern, see the description under -name pattern.
-
- -perm [-]permissions
-
In UNIX, specifies permissions as octal numbers or symbols. If this argument is specified in Windows, an error (find: -perm: unknown option) results.
If the specified permissions follow a hyphen (-), the evaluation is true when the specified permissions are set in the mode of the file or directory. If a hyphen (-) is not specified, the evaluation is true when the specified permissions match the file mode exactly.
When you specify a numeric value for permissions, an error occurs if you specify a non-octal number or you specify an octal value greater than 07777 (4095 decimal).
If you specify symbols for permissions, do so by setting, adding, and removing permissions, starting from the state in which nothing is specified (0 in numeric representation). The result from specifying one or more symbols is then used in the search.
A symbol consists of three parts. Specify one or more symbols, as explained below. If you specify more than one, separate them with the comma (,).
Order within the symbol
Permitted value
First
Specifies the items for which you want to set access permissions. You can specify more than one at the same time. The items below can be specified. If nothing is specified, a (all users) is assumed.
-
u: Owner
-
g: Group
-
o: Other
-
a: All users
Second
Specifies an operation on the mode. The following processing is performed on the items specified in the first part of a symbol:
-
=: Set (overwrite) access permissions
-
+: Add access permissions
-
-: Remove access permissions
The value to be set, added, or removed is specified in the third part of the symbol.
You can specify the second and third parts of a symbol following the third part. The third part of a symbol can be omitted.
Third
Specifies the applicable access permissions. You can specify more than one at the same time. The following values can be specified:
-
r: Read
-
w: Write
-
x: Execute
-
s: Set the user ID or group ID at run time
-
t: Sticky bit
-
u: Owner access permissions currently set in the mode
-
g: Group access permissions currently set in the mode
-
o: Other access permissions currently set in the mode
When this part is omitted and = is specified in the second part of the symbol, the items for which access permissions are set are cleared. When this part is omitted and + or - is specified in the second part of the symbol, no processing occurs.
Specifying s or t in this part will be ignored if only o is specified in the first part.
The following table shows examples of specifying symbols:
Value specified in -perm
Numeric equivalent
Description
u=x,g=w
120
Set u to x, and set g to w.
u=x,g=u
110
Set u to x, and set the same values for g and u.
u=x,=u
111
Set u to x, and then set a (the default value) to the same values as u.
u=x,u=w
200
Set u to x, and then set (overwrite) u to w.
u=x,u+w
300
Set u to x, and then add w to u.
ug=x
110
Set u and g to x.
u=rw
600
Set u to r and w.
u=r+x
500
Set u to r, and then add x.
u=r=w
200
Set u to r, and then set (overwrite) it to w.
=x,u=
011
Set a (the default value) to x, and clear the settings for u.
=
000
Clear a (the default value).
This argument cannot be specified in Windows; if it is specified, an error occurs (find: -perm: unknown option).
-
-
Specifies an evaluation that is to be performed. The evaluation is true when the path name of the file or directory being searched is output to the standard output followed by an end-of-line code. This evaluation is always true.
- -print0
-
Specifies an evaluation that is to be performed. The evaluation is true when the path name of the file or directory being searched is output to the standard output followed by NULL ('\0'). This evaluation is always true.
- -prune
-
Specifies an evaluation that is to be performed. The evaluation is true when directories encountered during the search are not to be followed. This evaluation is always true. This item is not valid when the -d option is specified.
- -size size[c]
-
Specifies an evaluation that is to be performed. The evaluation is true when the relationship between the file's size and the specified size value (in units of blocks, rounded up to an even increment of 512 bytes) is valid. When c is specified after size, the unit for evaluation is bytes.
The specified size is interpreted as follows depending on whether no sign is specified or a numeric value with a + or - sign is specified:
-
When a sign is not specified: Specified time difference
-
+ is specified before the numeric value: Greater than the specified value
-
- is specified before the numeric value: Less than the specified value
The specified value must not exceed 9223372036854775807 (0x7fffffffffffffff). If you specify a greater value, 9223372036854775807 is assumed.
If you specify a non-numeric value, an error message (find: primary: specified-character-string: illegal numeric value) is output.
If size is omitted, an error message (find: primary: requires additional arguments) is output.
-
- -type type
-
Specifies an evaluation that is to be performed. The evaluation is true when the type of the current file is the same as the specified type value. The types are listed below. If you specify a type other one than the following, an error message (find: -type: specified-value: unknown type) is output.
-
b: Block special file (cannot be specified in Windows)
-
c: Character special file (cannot be specified in Windows)
-
d: Directory
-
f: Regular file
-
l: Symbolic link (cannot be specified in Windows)
-
p: FIFO (cannot be specified in Windows)
-
s: Socket (cannot be specified in Windows)
-
- -user user-name
-
In Windows, specifies an evaluation that is to be performed. The evaluation is true when the file owner's user name is the same as the specified user-name value.
In UNIX, specifies an evaluation that is to be performed. The evaluation is true when the file owner's user name is the same as the specified user-name value. If you specify a numeric value for the user name and no such owner name exists, the specified value is interpreted as a user ID.
- -xdev
-
Specifies an evaluation that is to be performed. This evaluation is always true. It is true in UNIX when directories are never searched with a device number that differs from that of the directory where the search was started.
-
Operators
The primaries can be used with the operators listed below. The operators are shown in descending order of priority.
- (search-pattern)
-
True is when the search pattern in the parentheses satisfies the conditions.
- ! search-pattern
-
False is when the search pattern that follows the ! operator satisfies the conditions.
- search-pattern -and search-pattern | search-pattern -a search-pattern | search-pattern search-pattern
-
This is the logical AND of two search patterns connected by the -and or -a operator, or else two side-by-side search patterns. True is when both search patterns are true. If the first search pattern is false, the second search pattern is not evaluated.
- search-pattern -or search-pattern | search-pattern -o search-pattern
-
This is the logical OR of two search patterns connected by the -or or -o operator. True is when either search pattern is true.
-
Return codes
|
Return code |
Meaning |
|---|---|
|
0 |
Normal termination |
|
1 or greater |
Error termination |
Notes
-
Depending on the shell used to execute find, characters such as the semicolon and parentheses might need to be prefixed with the escape character (\) or enclosed in single quotation marks (') or double quotation marks (").
-
The output order of the files and directories being searched depends on the OS and the file system. If consistency across multiple platforms is desired, the output must be sorted.
-
In Windows, file descriptors are closed without being inherited by processes that were generated by the -exec primary or a similar means. For example, an error results if you attempt to perform input or output on a file descriptor opened by the parent process without reopening it. This does not apply to the standard input, standard output, and standard error output, which do not need to be reopened.
-
In Windows, if the program name specified in the -exec option contains no path, the program found according to the path search order of the target Windows API is executed.
Usage examples
-
Display file and directory names ending in .c.
$ find . -name '*.c' ./test/a.c ./test/b.c ./test/c.c ./test/abc.c $
-
Display files and directories that are older than file ttt, or whose owner is not root.
$ ls -l total 0 -rw-rw-r-- 1 user1 group1 0 Oct 7 10:12 a.c -rw-rw-r-- 1 root group1 0 Oct 7 10:12 abc.c -rw-rw-r-- 1 user1 group1 0 Oct 7 10:12 b.c -rw-rw-r-- 1 user1 group1 0 Oct 7 10:10 c.c -rw-rw-r-- 1 user1 group1 0 Oct 7 10:11 ttt $ find . \! \( -newer ttt -user root \) . ./ttt ./b.c ./a.c ./c.c $
-
Display file names under the current directory that end with a dot (.) followed by a single digit, skipping over the directory command1.
$ ls command1 command2 command1: a1.txt b1.txt command1 command1.1 command1.c command1.o extern.h obj command2: a2.txt b2.txt command2 command2.1 command2.c command2.o extern.h obj $ find . ! -path './command1/*' -name '*.[0-9]' ./command2/command2.1 $
-
Delete all .o files under the current directory.
$ ls command1 command2 command1: a1.txt b1.txt command1 command1.1 command1.c command1.o extern.h obj command2: a2.txt b2.txt command2 command2.1 command2.c command2.o extern.h obj $ find . -name '*.o' -exec rm {} \; $ ls command1 command2 command1: a1.txt b1.txt command1 command1.1 command1.c extern.h obj command2: a2.txt b2.txt command2 command2.1 command2.c extern.h obj $ -
Display an option error message.
This message might vary depending on the platform on which the command is executed. The following shows an example in Windows:
C:\TEMP>%ADSH_OSCMD_DIR%\find -w find: illegal option -- w usage: find [-dHhL] path ... [expression]