Finding Files - 2. Finding Files

Go to the first, previous, next, last section, table of contents.

# 2. Finding Files

By default, `find` prints to the standard output the names of the files that match the given criteria. See section 3. Actions, for how to get more information about the matching files.

## 2.1 Name

Here are ways to search for files whose name matches a certain pattern. See section 2.1.4 Shell Pattern Matching, for a description of the pattern arguments to these tests.

Each of these tests has a case-sensitive version and a case-insensitive version, whose name begins with ``i'`. In a case-insensitive comparison, the patterns ``fo*'` and ``F??'` match the file names ``Foo'`, ``FOO'`, ``foo'`, ``fOo'`, etc.

### 2.1.1 Base Name Patterns

Test: -name pattern
Test: -iname pattern
  True if the base of the file name (the path with the leading directories removed) matches shell pattern pattern. For ``-iname'`, the match is case-insensitive. To ignore a whole directory tree, use ``-prune'` (see section 2.9 Directories). As an example, to find Texinfo source files in ``/usr/local/doc'`:

      find /usr/local/doc -name '*.texi'

### 2.1.2 Full Name Patterns

Test: -path pattern
Test: -ipath pattern
  True if the entire file name, starting with the command line argument under which the file was found, matches shell pattern pattern. For ``-ipath'`, the match is case-insensitive. To ignore a whole directory tree, use ``-prune'` rather than checking every file in the tree (see section 2.9 Directories).

Test: -regex expr
Test: -iregex expr
  True if the entire file name matches regular expression expr. This is a match on the whole path, not a search. For example, to match a file named ``./fubar3'`, you can use the regular expression ``.*bar.'` or ``.*b.*3'`, but not ``b.*r3'`. See section `Syntax of Regular Expressions' in The GNU Emacs Manual, for a description of the syntax of regular expressions. For ``-iregex'`, the match is case-insensitive.

### 2.1.3 Fast Full Name Search

To search for files by name without having to actually scan the directories on the disk (which can be slow), you can use the `locate` program. For each shell pattern you give it, `locate` searches one or more databases of file names and displays the file names that contain the pattern. See section 2.1.4 Shell Pattern Matching, for details about shell patterns.

If a pattern is a plain string--it contains no metacharacters---`locate` displays all file names in the database that contain that string. If a pattern contains metacharacters, `locate` only displays file names that match the pattern exactly. As a result, patterns that contain metacharacters should usually begin with a ``*'`, and will most often end with one as well. The exceptions are patterns that are intended to explicitly match the beginning or end of a file name.

The command

    locate pattern

is almost equivalent to

    find directories -name pattern

where directories are the directories for which the file name databases contain information. The differences are that the `locate` information might be out of date, and that `locate` handles wildcards in the pattern slightly differently than `find` (see section 2.1.4 Shell Pattern Matching).

The file name databases contain lists of files that were on the system when the databases were last updated. The system administrator can choose the file name of the default database, the frequency with which the databases are updated, and the directories for which they contain entries.

Here is how to select which file name databases `locate` searches. The default is system-dependent.

`--database=path`
`-d path`
  Instead of searching the default file name database, search the file name databases in path, which is a colon-separated list of database file names. You can also use the environment variable `LOCATE_PATH` to set the list of database files to search. The option overrides the environment variable if both are used.

### 2.1.4 Shell Pattern Matching

`find` and `locate` can compare file names, or parts of file names, to shell patterns. A shell pattern is a string that may contain the following special characters, which are known as wildcards or metacharacters.

You must quote patterns that contain metacharacters to prevent the shell from expanding them itself. Double and single quotes both work; so does escaping with a backslash.

`*`
  Matches any zero or more characters.
`?`
  Matches any one character.
`[string]`
  Matches exactly one character that is a member of the string string. This is called a character class. As a shorthand, string may contain ranges, which consist of two characters with a dash between them. For example, the class ``[a-z0-9_]'` matches a lowercase letter, a number, or an underscore. You can negate a class by placing a ``!'` or ``^'` immediately after the opening bracket. Thus, ``[^A-Z@]'` matches any character except an uppercase letter or an at sign.
`\`
  Removes the special meaning of the character that follows it. This works even in character classes.

In the `find` tests that do shell pattern matching (``-name'`, ``-path'`, etc.), wildcards in the pattern do not match a ``.'` at the beginning of a file name. This is not the case for `locate`. Thus, ``find -name '*macs''` does not match a file named ``.emacs'`, but ``locate '*macs''` does.

Slash characters have no special significance in the shell pattern matching that `find` and `locate` do, unlike in the shell, in which wildcards do not match them. Therefore, a pattern ``foo*bar'` can match a file name ``foo3/bar'`, and a pattern ``./sr*sc'` can match a file name ``./src/misc'`.

## 2.2 Links

There are two ways that files can be linked together. Symbolic links are a special type of file whose contents are a portion of the name of another file. Hard links are multiple directory entries for one file; the file names all have the same index node (inode) number on the disk.

### 2.2.1 Symbolic Links

Test: -lname pattern
Test: -ilname pattern
  True if the file is a symbolic link whose contents match shell pattern pattern. For ``-ilname'`, the match is case-insensitive. See section 2.1.4 Shell Pattern Matching, for details about the pattern argument. So, to list any symbolic links to ``sysdep.c'` in the current directory and its subdirectories, you can do:

      find . -lname '*sysdep.c'

Option: -follow
  Dereference symbolic links. The following differences in behavior occur when this option is given:
  - `find` follows symbolic links to directories when searching directory trees.
  - ``-lname'` and ``-ilname'` always return false.
  - ``-type'` reports the types of the files that symbolic links point to.
  - Implies ``-noleaf'` (see section 2.9 Directories).

### 2.2.2 Hard Links

To find hard links, first get the inode number of the file whose links you want to find. You can learn a file's inode number and the number of links to it by running ``ls -i'` or ``find -ls'`. If the file has more than one link, you can search for the other links by passing that inode number to ``-inum'`. Add the ``-xdev'` option if you are starting the search at a directory that has other filesystems mounted on it, such as ``/usr'` on many systems. Doing this saves needless searching, since hard links to a file must be on the same filesystem. See section 2.10 Filesystems.

Test: -inum n
  File has inode number n.

You can also search for files that have a certain number of links, with ``-links'`. Directories normally have at least two hard links; their ``.'` entry is the second one. If they have subdirectories, each of those also has a hard link called ``..'` to its parent directory.

Test: -links n
  File has n hard links.

## 2.3 Time

Each file has three time stamps, which record the last time that certain operations were performed on the file:

1. access (read the file's contents)
2. change the status (modify the file or its attributes)
3. modify (change the file's contents)

You can search for files whose time stamps are within a certain age range, or compare them to other time stamps.

### 2.3.1 Age Ranges

These tests are mainly useful with ranges (``+n'` and ``-n'`).

Test: -atime n
Test: -ctime n
Test: -mtime n
  True if the file was last accessed (or its status changed, or it was modified) n*24 hours ago.

Test: -amin n
Test: -cmin n
Test: -mmin n
  True if the file was last accessed (or its status changed, or it was modified) n minutes ago. These tests provide finer granularity of measurement than ``-atime'` et al. For example, to list files in ``/u/bill'` that were last read from 2 to 6 hours ago:

      find /u/bill -amin +2 -amin -6

Option: -daystart
  Measure times from the beginning of today rather than from 24 hours ago. So, to list the regular files in your home directory that were modified yesterday, do

      find ~ -daystart -type f -mtime 1

### 2.3.2 Comparing Timestamps

As an alternative to comparing timestamps to the current time, you can compare them to another file's timestamp. That file's timestamp could be updated by another program when some event occurs. Or you could set it to a particular fixed date using the `touch` command. For example, to list files in ``/usr'` modified after February 1 of the current year:

    touch -t 02010000 /tmp/stamp$$
    find /usr -newer /tmp/stamp$$
    rm -f /tmp/stamp$$

Test: -anewer file
Test: -cnewer file
Test: -newer file
  True if the file was last accessed (or its status changed, or it was modified) more recently than file was modified. These tests are affected by ``-follow'` only if ``-follow'` comes before them on the command line. See section 2.2.1 Symbolic Links, for more information on ``-follow'`. As an example, to list any files modified since ``/bin/sh'` was last modified:

      find . -newer /bin/sh

Test: -used n
  True if the file was last accessed n days after its status was last changed. Useful for finding files that are not being used, and could perhaps be archived or removed to save disk space.

## 2.4 Size

Test: -size n[bckw]
  True if the file uses n units of space, rounding up. The units are 512-byte blocks by default, but they can be changed by adding a one-character suffix to n:
  `b`
    512-byte blocks
  `c`
    bytes
  `k`
    kilobytes (1024 bytes)
  `w`
    2-byte words

  The size does not count indirect blocks, but it does count blocks in sparse files that are not actually allocated.

Test: -empty
  True if the file is empty and is either a regular file or a directory. This might make it a good candidate for deletion. This test is useful with ``-depth'` (see section 2.9 Directories) and ``-exec rm -rf '{}' ';''` (see section 3.3.1 Single File).

## 2.5 Type

Test: -type c
  True if the file is of type c:
  `b`
    block (buffered) special
  `c`
    character (unbuffered) special
  `d`
    directory
  `p`
    named pipe (FIFO)
  `f`
    regular file
  `l`
    symbolic link
  `s`
    socket

Test: -xtype c
  The same as ``-type'` unless the file is a symbolic link. For symbolic links: if ``-follow'` has not been given, true if the file is a link to a file of type c; if ``-follow'` has been given, true if c is ``l'`. In other words, for symbolic links, ``-xtype'` checks the type of the file that ``-type'` does not check. See section 2.2.1 Symbolic Links, for more information on ``-follow'`.

## 2.6 Owner

Test: -user uname
Test: -group gname
  True if the file is owned by user uname (belongs to group gname). A numeric ID is allowed.

Test: -uid n
Test: -gid n
  True if the file's numeric user ID (group ID) is n. These tests support ranges (``+n'` and ``-n'`), unlike ``-user'` and ``-group'`.

Test: -nouser
Test: -nogroup
  True if no user corresponds to the file's numeric user ID (no group corresponds to the numeric group ID). These cases usually mean that the files belonged to users who have since been removed from the system. You probably should change the ownership of such files to an existing user or group, using the `chown` or `chgrp` program.

## 2.7 Permissions

See section 6. File Permissions, for information on how file permissions are structured and how to specify them.

Test: -perm mode
  True if the file's permissions are exactly mode (which can be numeric or symbolic). Symbolic modes use mode 0 as a point of departure. If mode starts with ``-'`, true if all of the permissions set in mode are set for the file; permissions not set in mode are ignored. If mode starts with ``+'`, true if any of the permissions set in mode are set for the file; permissions not set in mode are ignored.

## 2.8 Contents

To search for files based on their contents, you can use the `grep` program. For example, to find out which C source files in the current directory contain the string ``thing'`, you can do:

    grep -l thing *.[ch]

If you also want to search for the string in files in subdirectories, you can combine `grep` with `find` and `xargs`, like this:

    find . -name '*.[ch]' | xargs grep -l thing

The ``-l'` option causes `grep` to print only the names of files that contain the string, rather than the lines that contain it. The string argument (``thing'`) is actually a regular expression, so it can contain metacharacters. This method can be refined a little by using the ``-r'` option to make `xargs` not run `grep` if `find` produces no output, and using the `find` action ``-print0'` and the `xargs` option ``-0'` to avoid misinterpreting files whose names contain spaces:

    find . -name '*.[ch]' -print0 | xargs -r -0 grep -l thing

For a fuller treatment of finding files whose contents match a pattern, see the manual page for `grep`.

## 2.9 Directories

Here is how to control which directories `find` searches, and how it searches them. These two options allow you to process a horizontal slice of a directory tree.

Option: -maxdepth levels
  Descend at most levels (a non-negative integer) levels of directories below the command line arguments. ``-maxdepth 0'` means only apply the tests and actions to the command line arguments.

Option: -mindepth levels
  Do not apply any tests or actions at levels less than levels (a non-negative integer). ``-mindepth 1'` means process all files except the command line arguments.

Option: -depth
  Process each directory's contents before the directory itself. Doing this is a good idea when producing lists of files to archive with `cpio` or `tar`. If a directory does not have write permission for its owner, its contents can still be restored from the archive since the directory's permissions are restored after its contents.

Action: -prune
  If ``-depth'` is not given, true; do not descend the current directory. If ``-depth'` is given, false; no effect. ``-prune'` only affects tests and actions that come after it in the expression, not those that come before.

  For example, to skip the directory ``src/emacs'` and all files and directories under it, and print the names of the other files found:

      find . -path './src/emacs' -prune -o -print

Option: -noleaf
  Do not optimize by assuming that directories contain 2 fewer subdirectories than their hard link count. This option is needed when searching filesystems that do not follow the Unix directory-link convention, such as CD-ROM or MS-DOS filesystems or AFS volume mount points. Each directory on a normal Unix filesystem has at least 2 hard links: its name and its ``.'` entry. Additionally, its subdirectories (if any) each have a ``..'` entry linked to that directory. When `find` is examining a directory, after it has statted 2 fewer subdirectories than the directory's link count, it knows that the rest of the entries in the directory are non-directories (leaf files in the directory tree). If only the files' names need to be examined, there is no need to stat them; this gives a significant increase in search speed.

## 2.10 Filesystems

A filesystem is a section of a disk, either on the local host or mounted from a remote host over a network. Searching network filesystems can be slow, so it is common to make `find` avoid them.

There are two ways to avoid searching certain filesystems. One way is to tell `find` to only search one filesystem:

Option: -xdev
Option: -mount
  Don't descend directories on other filesystems. These options are synonyms.

The other way is to check the type of filesystem each file is on, and not descend directories that are on undesirable filesystem types:

Test: -fstype type
  True if the file is on a filesystem of type type. The valid filesystem types vary among different versions of Unix; an incomplete list of filesystem types that are accepted on some version of Unix or another is:

      ufs 4.2 4.3 nfs tmp mfs S51K S52K

  You can use ``-printf'` with the ``%F'` directive to see the types of your filesystems. See section 3.2 Print File Information. ``-fstype'` is usually used with ``-prune'` to avoid searching remote filesystems (see section 2.9 Directories).

## 2.11 Combining Primaries With Operators

Operators build a complex expression from tests and actions. The operators are, in order of decreasing precedence:

`( expr )`
  Force precedence. True if expr is true.
`! expr`
`-not expr`
  True if expr is false.
`expr1 expr2`
`expr1 -a expr2`
`expr1 -and expr2`
  And; expr2 is not evaluated if expr1 is false.
`expr1 -o expr2`
`expr1 -or expr2`
  Or; expr2 is not evaluated if expr1 is true.
`expr1 , expr2`
  List; both expr1 and expr2 are always evaluated. True if expr2 is true. The value of expr1 is discarded. This operator lets you do multiple independent operations on one traversal, without depending on whether other operations succeeded.

`find` searches the directory tree rooted at each file name by evaluating the expression from left to right, according to the rules of precedence, until the outcome is known (the left hand side is false for ``-and'`, true for ``-or'`), at which point `find` moves on to the next file name.

There are two other tests that can be useful in complex expressions:

Test: -true
  Always true.

Test: -false
  Always false.

Go to the first, previous, next, last section, table of contents.