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