# locate

## NAME



           locate - list files in databases that match a pattern
    


## SYNOPSIS



           **locate**[-d path | --database=path] [-e | -E | --[non-]existing]
           [-i | --ignore-case] [-0 | --null] [-c | --count] [-w |
           --wholename] [-b | --basename] [-l N | --limit=N] [-S |
           --statistics] [-r | --regex ] [--regextype R] [--max-database-age
           D] [-P | -H | --nofollow] [-L | --follow] [--version] [-A | --all]
           [-p | --print] [--help] pattern...
    


## DESCRIPTION



           This manual page documents the GNU version of **locate**.  For each
           given pattern, **locate** searches one or more databases of file names
           and displays the file names that contain the pattern.  Patterns
           can contain shell-style metacharacters: `*', `?', and `[]'.  The
           metacharacters do not treat `/' or `.'  specially.  Therefore, a
           pattern `foo*bar' can match a file name that contains `foo3/bar',
           and a pattern `*duck*' can match a file name that contains
           `lake/.ducky'.  Patterns that contain metacharacters should be
           quoted to protect them from expansion by the shell.
    
           If a pattern is a plain string — it contains no metacharacters —
           **locate** displays all file names in the database that contain that
           string anywhere.  If a pattern does contain 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 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; see updatedb(1).
    
           If **locate** 's output is going to a terminal, unusual characters in
           the output are escaped in the same way as for the -print action of
           the **find** command.  If the output is not going to a terminal, file
           names are printed exactly as-is.
    


## OPTIONS



           _-0, --null_
                  Use ASCII NUL as a separator, instead of newline.
    
           _-A, --all_
                  Print only names which match all non-option arguments, not
                  those matching one or more non-option arguments.
    
           _-b, --basename_
                  Results are considered to match if the pattern specified
                  matches the final component of the name of a file as listed
                  in the database.  This final component is usually referred
                  to as the `base name'.
    
           _-c, --count_
                  Instead of printing the matched filenames, just print the
                  total number of matches we found, unless --_print_ (-p) is
                  also present.
    
           _-d path, --database=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.  Empty elements in
                  the path are taken to be synonyms for the file name of the
                  default database.  A database can be supplied on stdin,
                  using `-' as an element of _path_. If more than one element
                  of _path_ is `-', later instances are ignored (and a warning
                  message is printed).
    
                  The file name database format changed starting with GNU
                  **find** and **locate** version 4.0 to allow machines with
                  different byte orderings to share the databases.  This
                  version of **locate** can automatically recognize and read
                  databases produced for older versions of GNU **locate** or Unix
                  versions of **locate** or **find**.  Support for the old locate
                  database format will be discontinued in a future release.
    
           _-e, --existing_
                  Only print out such names that currently exist (instead of
                  such names that existed when the database was created).
                  Note that this may slow down the program a lot, if there
                  are many matches in the database.  If you are using this
                  option within a program, please note that it is possible
                  for the file to be deleted after **locate** has checked that it
                  exists, but before you use it.
    
           _-E, --non-existing_
                  Only print out such names that currently do not exist
                  (instead of such names that existed when the database was
                  created).  Note that this may slow down the program a lot,
                  if there are many matches in the database.
    
           _--help_ Print a summary of the options to **locate** and exit.
    
           _-i, --ignore-case_
                  Ignore case distinctions in both the pattern and the file
                  names.
    
           _-l N, --limit=N_
                  Limit the number of matches to N.  If a limit is set via
                  this option, the number of results printed for the -c
                  option will never be larger than this number.
    
           _-L, --follow_
                  If testing for the existence of files (with the -e or -E
                  options), consider broken symbolic links to be non-
                  existing.   This is the default.
    
           _--max-database-age D_
                  Normally, **locate** will issue a warning message when it
                  searches a database which is more than 8 days old.  This
                  option changes that value to something other than 8.  The
                  effect of specifying a negative value is undefined.
    
           _-m, --mmap_
                  Accepted but does nothing, for compatibility with BSD
                  **locate**.
    
           _-P, -H, --nofollow_
                  If testing for the existence of files (with the -e or -E
                  options), treat broken symbolic links as if they were
                  existing files.  The -H form of this option is provided
                  purely for similarity with **find** ; the use of -P is
                  recommended over -H.
    
           _-p, --print_
                  Print search results when they normally would not, because
                  of the presence of --statistics (-S) or --count (-c).
    
           _-r, --regex_
                  The pattern specified on the command line is understood to
                  be a regular expression, as opposed to a glob pattern.  The
                  Regular expressions work in the same was as in **emacs** except
                  for the fact that "." will match a newline.  GNU **find** uses
                  the same regular expressions.  Filenames whose full paths
                  match the specified regular expression are printed (or, in
                  the case of the -c option, counted).  If you wish to anchor
                  your regular expression at the ends of the full path name,
                  then as is usual with regular expressions, you should use
                  the characters ^ and $ to signify this.
    
           _--regextype R_
                  Use regular expression dialect R.  Supported dialects
                  include `findutils-default', `posix-awk', `posix-basic',
                  `posix-egrep', `posix-extended', `posix-minimal-basic',
                  `awk', `ed', `egrep', `emacs', `gnu-awk', `grep' and `sed'.
                  See the Texinfo documentation for a detailed explanation of
                  these dialects.
    
           _-s, --stdio_
                  Accepted but does nothing, for compatibility with BSD
                  **locate**.
    
           _-S, --statistics_
                  Print various statistics about each locate database and
                  then exit without performing a search, unless non-option
                  arguments are given.  For compatibility with BSD, -S is
                  accepted as a synonym for --statistics.  However, the
                  output of **locate -S** is different for the GNU and BSD
                  implementations of **locate**.
    
           _--version_
                  Print the version number of **locate** and exit.
    
           _-w, --wholename_
                  Match against the whole name of the file as listed in the
                  database.  This is the default.
    


## ENVIRONMENT



           **LOCATE_PATH**
                  Colon-separated list of databases to search.  If the value
                  has a leading or trailing colon, or has two colons in a
                  row, you may get results that vary between different
                  versions of **locate**.
    


## BUGS



           The **locate** database correctly handles filenames containing
           newlines, but only if the system's sort command has a working _-z_
           option.  If you suspect that **locate** may need to return filenames
           containing newlines, consider using its _--null_ option.
    


* * *