find - Find a file that meets specified criteria
Format
find path ... expression
Description
find searches a given file hierarchy that is specified by path, finding files that match the criteria that is given by expression. Each directory, file, and special file is passed through expression. If you use the -exec, -ok, or -cpio primary, expression runs a specified command on each file found. A nonexistent expression or an expression with commands to run automatically uses the -print primary to display the name of any file that matches the criteria of expression.
If the contents of a directory have changed since find begins traversing the directory tree, the results may omit new files or fail to open deleted or moved files.
find builds expression from a set of primaries and operators; juxtaposition of two primaries implies a logical AND operator.
Operators and primaries
- -a
- Used between primaries for a logical AND. You can omit this operator to get the same result because logical AND is assumed when no operator is used between two primaries.
- -o
- Used between primaries for a logical OR.
- !
- Precedes an expression in order to negate it.
- When you are using parentheses to group primaries and operators, you must escape the parentheses with the \ (backslash) character if the command is being executed in the shell environment.
- You must delimit all primaries, operators, numbers, arguments, and parentheses with white space.
Options
The find command supports the following primaries. If you use the ACL primaries, with the exception of -acl, performance might be affected.
- -aaudit auditmask
- The -aaudit primary is used to match the auditor audit bits. See -audit auditmask.
- -acl c
- Matches if the type of ACL is the same as the type given by the character
c. Possible values of the character are:
- a
- Access ACL (matches only if there are extended ACL entries)
- d
- Directory default ACL
- f
- File default ACL
- -acl_count number
- Matches if the numbers of extended ACL entries for any of the types of ACLs for the object is
number.
number 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.
- -acl_entry acl_text
- Matches if the ACL on the file contains an entry equivalent to
acl_text where acl_text is a single extended ACL
entry. This primary uses user and group names rather than UID and GID numbers to make the matches.
If aliases exist for a name, then it is possible a match might not occur. This behavior is different
than the -acl_user and -acl_group primaries, which match based
on UID and GID. Extended ACL entries have the following format:
where:[d[efault]: | f[default]:]u[ser]:uid:[+|^]perm [d[efault]: | f[default]:]g[roup]:gid:[+|^]perm
- d[efault]
- Extended ACL refers to directory default ACL.
- f[default]
- Extended ACL refers to file default ACL.
- u[ser]
- Extended ACL refers to a particular numeric user ID (UID) or username.
- g[roup]
- Extended ACL refers to a particular numeric group ID (GID) or group name.
- uid
- User name or numeric user ID (UID).
- gid
- Group name, or numeric group ID (GID).
- perm
- Permissions specified either in absolute form (string
rwx
with-
as a placeholder or octal form), or in relative format (by using the+
or^
modifiers).For relative permission settings, specifying+perm
means that you want the ACL entry to have that permission turned on. Specifying^perm
means that you want the ACL entry to have that permission off. For example, specifying the following will find files with an extended access ACL entry for user Billy in which the permissions are either-w-
orrw-:
user:Billy:+w^x
If the permission field of acl_text is omitted, then the ACL entries are searched to match only the ACL type, and user or group portions of the user-supplied entry.
If you want to find any of the base ACL entries (user, group, or other), you can use the
-perm
primary.
- -acl_group groupid
- Matches if the object has an extended group ACL entry for groupid.
groupid can also be a group ID number.
If your security product supports ACLs, the group base ACL entry can be matched using this primary. If a numeric group exists as a group in the group data base, the group ID number that is associated with that group is used.
- -acl_nogroup
- Matches if a group ACL entry (for any type of ACL) exists in which a group is not defined. The GID for at least one extended ACL entry for the file does not have a group name that is associated with it.
- -acl_nouser
- Matches if a user ACL entry (for any type of ACL) exists in which a user is not defined. The UID for at least one extended ACL entry for the file does not have a username that is associated with it.
- -acl_user userid
- Matches if the ACL of the object has an extended user ACL entry for
userid. userid can also be a user ID number.
If a numeric owner exists as a user name in the user database, the user ID number that is associated with that user name is used. If your security product supports ACLs, the user base ACL entry can be matched, using this primary.
- -atime number
- Matches if someone has accessed the file exactly number days ago.
number 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..
- -audit auditmask
- The -audit primary is used to match the user audit bits.
auditmask can be in octal or in symbolic form. The mask can be preceded by
a - character (as in the perm primary), but it
is ignored. Symbolic form is an operation=condition list, separated by commas:
where:[rwx]=[sf]
- =sf
- Success or failure on any of rwx.
- r=s
- Success on read.
- r=s, x=sf
- Success on read or exec, failure on exec.
- r, w=s
- Incorrect syntax.
- x
- Incorrect syntax.
Octal form is specified by using the chaudit bit constant definitions in the /usr/include/sys/stat.h header file. For example, in stat.h, the flag for failing read accesses is AUDTREADFAIL. It is defined to be 0x02000000, which has an octal value of 200000000. This octal value can be used as the auditmask to find failure on read.
- -cpio cpio-file
- Writes the file found to the target file cpio-file in
cpio format. This is equivalent to:
This primary matches if the command succeeds.find ... | cpio -o >cpio-file
- -ctime number
- Matches if someone changed the attributes of the file exactly number
days ago.
number 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.
- -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 that is exactly
{}
(two brace characters) with the current file name. It then executes the resulting command line, treating a return status of zero from this command as a successful match, nonzero as failure. You must delimit the ending semicolon with white space.If the replacement string contains the two characters"{}"
but not only those two characters, the string is used without substitution. For example, if you issue
for each file that is found, the find command will replace the-exec ls -al {} \;
{}
string with the found filename. If you issue
the substitution does not take place because the-exec ls -al {}.txt \;
"{}.txt"
argument string contains additional characters. The argument string can only be the two characters"{}"
.Restriction: The semicolon is a shell metacharacter. To use it in expression, you must escape it, either by enclosing it with single quotation marks or by preceding it with a backslash (\).
- -ext c
- Matches when the regular file has the extended attribute that is specified by character
c. See extattr - Set, reset, and display extended attributes for files for details on extended
attributes. The following list shows possible values of this character.
- a
- Program runs APF-authorized if linked
AC=1
. - l
- Program is loaded from the shared library region.
- p
- Program is considered program-controlled.
- s
- Program is allowed to run in a shared address space.
- -filetag c
- Matches if the file tag is the same as the one given by character c.
Possible values of the character are:
- b
- Matches if the file is tagged as binary (
txtflag = OFF
andccsid = 0xFFFF)
- n
- Matches if the file has
txtflag = OFF
. - t
- Matches if the file is tagged as text (
txtflag = ON
). - u
- Matches if the file is untagged (
ccsid = 0
).
- -filetag_codeset codeset
- Matches if the file is tagged with the given code set. codeset can be
a code set name that is known to the system or the numeric coded character set identifier (CCSID).
If a code set name exists, the numeric CCSID associated with that name is used. The command
iconv -l lists existing CCSIDs along with their corresponding code set names.
Note: Because code sets that are aliases of each other exist, tests might fail if the file inquiry operator returns an alias of the code set that you are testing.
- -follow
- Follows symbolic links. If present, this primary always matches.
- -group name
- Matches if the group owner is name. If name is not a valid group name, it is treated as a group ID.
- -inum number
- Matches if the file has inode number number.
number 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.
- -level number
- Matches if the file is less then or equal the level number number. number is a decimal number.
- -links number
- Matches if there are number links to the file.
number 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.
- -mtime number
- Matches if someone has modified the file exactly number days ago.
number 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.
- -name pattern
- Compares the current file name with pattern. If there is no match, the expression fails. The pattern uses the same syntax as file name generation (see sh). It matches as many trailing path name components as specified in pattern. Slashes in the pattern are matched explicitly.
- -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 with that of the file given. The match occurs if someone has modified the found file more recently than file.
- -nogroup
- Matches if no defined group owns the file.
- -none
- Indicates that some action was taken; thus find does not invoke the default -print action. If present, this primary always matches.
- -nouser
- Matches if no defined user owns the file.
- -okcommand;
- Is similar to -exec, but before find executes the
command, it displays the command to confirm that you want to go ahead. find
executes the command line only if your input matches the expression for
yes
(yes and no expressions are defined in LC_MESSAGES). If you type the expression forno
, the primary does not match. You must delimit the terminal semicolon with white space.The semicolon is a shell metacharacter. To use it in expression, you must put quotation marks around it.
- -perm[-] mask
- By default, matches if the permissions on file are identical to the ones given in
mask. You can 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 that 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 that begins with a minus sign (-).
If you use octal mode, find uses only the bottom 12 bits of 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.
- Displays the current file name, followed by a newline. This primary always matches.
- -print0
- Displays the current file name, followed by a null character.
- -prune
- Stops searching deeper into the tree at this point. If present, this primary always matches. -prune has no effect if -depth is also specified.
- -seclabel pattern
- Compares the file's security label with pattern. If there is no match, the expression fails. The pattern uses the same syntax as file name generation (see File name generation).
- -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.
number 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.
- -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 file (not supported for z/OS UNIX System Services)
- c
- Character special file
- d
- Directory
- f
- Regular file
- l
- Symbolic link
- n
- Network file
- p
- FIFO (named pipe)
- s
- Socket
- -user name
- Matches if the owner of the file is name. name can also be a user ID number.
- -xdev
- Does not cross device boundaries from the root of the tree search. If present, this primary always matches.
Examples
- To find all files with a suffix of
.c
that have the audit mode set to rwx (read, write, execute), issue:find / -name "*.c" -audit rwx=sf
The quotation marks are required around the "*.c" if you do not want the shell to expand this value to all files with a suffix of
.c
from within the current directory. - To find all files with a suffix of
.c
and audit mode bits set to 777 (rwx), issue:find / -name "*.c" -audit 777
- 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 that have the extension
.Z
and that have not been accessed in the last three days:find . -name "*.Z" -mtime +3
- To find all files that have a security label of OS390:
find . -seclabel OS390
- To find all files that have a security label starting with OS390:
find . -seclabel "OS390*"
- To find all files that have no security labels:
find . ! -seclabel "*"
- To find all files and directories starting at the current directory point, with an extended ACL
user entry for user Billy for any ACL (access, file default, or directory default), issue:
orfind . -acl_user Billy
find . -acl_entry user:Billy -o -acl_entry d:u:Billy -o -acl_entry f:u:Billy
- To find all files and directories (starting from the current directory) that have more than 10
extended ACL entries for any of the ACL types, issue:
find . -acl_count +10
- To find all files and directories that contain access ACLs that have an extended ACL entry for
user Averi, starting from the current user's home directory:
find ~ -acl_entry user:Averi
- To find all directories whose file default ACLs have a group entry for
Lakers, starting at the current point in the directory hierarchy:
find . -acl_entry fdefault:group:Lakers
- To find all files for user Marc (in other words, all the files that
Marc owns), starting from Marc's home directory:
find /u/marc -user marc
- To find all directories (starting from current directory) which have file default ACLs:
find . -acl f
- To find all directories whose file default or directory default ACLs have a group entry for
Lakers, starting at the current point in the directory hierarchy:
find . -acl_entry fdefault:group:Lakers -o -acl_entry default:group:Lakers
Localization
- LANG
- LC_ALL
- LC_COLLATE
- LC_CTYPE
- LC_MESSAGES
- LC_SYNTAX
- NLSPATH
Exit values
0
- Successful completion
1
- Failure due to any of the following reasons:
- Not enough memory.
- Incorrect character was specified after -type.
- Inability to get information about a file for -newer.
- Incorrect permissions for -perm.
- Inability to open a file for the -cpio option.
- Unknown user or group name.
- Unable to access the PATH variable.
- Cannot run a command that is specified for -exec or -ok.
- Syntax error.
- Stack overflow caused by an expression that is too complex.
2
- Failure due to one of the following:
- Incorrect command-line option.
- Not enough arguments on the command line.
- Missing option.
- Argument list that is not properly ended.
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 with another; however, find could not obtain a modification time for the specified file. Typically, the file does not exist or you do not have appropriate permissions to obtain this information.
Portability
POSIX.2, X/Open Portability Guide, UNIX systems.
Most UNIX systems do not have a default action of -print. Therefore, they do not need the -none option. The -a operator is not documented on many UNIX systems.
The following primaries are extensions of the POSIX standard: -aaudit, -acl, -acl_count, -acl_entry, -acl_group, -acl_nogroup-acl_nouser, -acl_user, -audit, -audit, -cpio, -follow, -level, -ncpio, -none
The aaudit and audit options are unique to the z/OS shell.
Related information
chaudit, chmod, cpio, sh