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

When using the find command, follow these rules:

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.

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

The find command supports the following primaries.

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 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:

[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 (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- 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 can 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 might 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 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 user name 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.

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

-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. To use it in expression, you must escape it, either by enclosing it in 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. 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 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. 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.

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

-mtime number

Matches if someone has modified the file exactly number days ago.

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

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

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:
```
 find  .  -acl_user Billy
```
or
```
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 containing 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

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

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