find — Find a file meeting specified criteria

Format

find path … expression

Description

find searches a given file hierarchy specified by path, finding files that match the criteria 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.

find builds expression from a set of primaries and operators; juxtaposition of two primaries implies a logical AND operator.

Operators and primaries

find supports the following operators:
–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.
Rules: When using the find command, follow these rules:
  • When grouping primaries and operators using parentheses, 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.

Each number 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".

Options

This section lists the primaries that find supports.

Tip: 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
If acl c is not defined, then find matches any of these ACLs when other ACL primaries are used.
-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 matches using user and group names rather than UID and GID numbers. 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:
[d[efault]: | f[default]:]u[ser]:uid:[+|^]perm
[d[efault]: | f[default]:]g[roup]:gid:[+|^]perm
where:
d[efault]
If specified, extended ACL refers to directory default ACL
f[default]
If specified, extended ACL refers to file default ACL
u[ser]
Extended ACL refers to a particular numeric user ID (UID) or user name
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 (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- or rw-:
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.

The first field of an ACL entry may specify the type of ACL (access, directory default, or file default) that will be processed. If the type is not specified, the operation applies only to the access ACL. If you are updating the ACL entries, you can specify the base ACL entries; however, specifying the base ACL entries may cause the file or directory's permission bits to change if what is specified is different than the current settings.
-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 name in the group data base, the group ID number 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 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 user name 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 data base, the user ID number 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:
[rwx]=[sf]
where:
=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:
find … | cpio -o >cpio-file
This primary matches if the command succeeds.
–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 {} (that is, the 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 terminal semicolon with white space.
Rule: The semicolon is a shell metacharacter. Start of changeTo use it in expression, you must escape it, either by enclosing it in single quotation marks or by preceding it with a backslash (\)End of change.
–ext c
Matches when the regular file has the extended attribute specified by character c. See extattr — Set, reset, and display extended attributes for files for details on extended attributes. Possible values of the character are:
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 and ccsid = 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 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. Note that 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
Does not descend below number levels.

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”.

–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. This matches 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 for “no”, the primary does not match. You must delimit the terminal semicolon with white space.

Rule: The semicolon is a shell metacharacter. To use it in expression, you must quote 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.

–print
Displays the current file name. This primary always matches.
–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" while 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

  1. 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.

  2. To find all files with a suffix of .c and audit mode bits set to 777 (rwx), issue:
    find / –name "*.c" –audit 777
  3. To find all files with the extensions .c and .h, starting at the current point in the directory hierarchy:
    find . –name "*.[ch]"
  4. 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
  5. To find all files that have a security label of OS390:
    find . -seclabel OS390
  6. To find all files that have a security label starting with OS390:
    find . -seclabel "OS390*"
  7. To find all files that have no security labels:
    find . ! -seclabel "*"
  8. 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:
     find  .  -acl_user Billy
    or
    find  .  -acl_entry user:Billy -o -acl_entry d:u:Billy -o -acl_entry f:u:Billy
  9. 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	
  10. To find all files and directories containing access ACLs which have an extended ACL entry for user Averi, starting from the current user's home directory:
    find ~ -acl_entry user:Averi
  11. 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 
  12. 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
  13. To find all directories (starting from current directory) which have file default ACLs:
    find . -acl f
  14. 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

find uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_COLLATE
  • LC_CTYPE
  • LC_MESSAGES
  • LC_SYNTAX
  • NLSPATH

See Localization for more information.

Exit values

0
Successful completion
1
Failure due to any of the following:
  • Not enough memory
  • Incorrect character 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 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

Possible error messages include:
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