Seth Woolley's Man Viewer

locate(1) - locate, locate - list files in databases that match a pattern - man 1 locate

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

LOCATE(1)                                                            LOCATE(1)



NAME
       locate - list files in(1,8) 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 ] [-P
       | -H | --nofollow] [-L | --follow]  [--version]  [-A  |  --all]  [-p  |
       --print] [--help] pattern...

DESCRIPTION
       This  manual  page documents the GNU version(1,3,5) of locate.  For each given
       pattern, locate searches one or more databases of file(1,n) names  and  dis-
       plays  the  file(1,n)  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(1,n) name that contains `foo3/bar', and a pattern `*duck*'  can
       match  a  file(1,n) 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(3,n) -- it contains no metacharacters --
       locate displays all file(1,n) names in(1,8) the database that contain that string(3,n)
       anywhere.   If  a pattern does contain metacharacters, locate only dis-
       plays file(1,n) 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(1,n) name.

       The  file(1,n) name databases contain lists of files that were on the system
       when the databases were last updated.   The  system  administrator  can
       choose  the file(1,n) 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(1,8) the
       output are escaped in(1,8) the same way as for the -print action of the find
       command.   If  the  output  is  not going to a terminal, file(1,n) names are
       printed exactly as-is.


OPTIONS
       -A, --all
              Print only names which match all non-option arguments, not those
              matching one or more non-option arguments.

       -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(1,n) name database, search the
              file(1,n) name databases in(1,8) path, which is a colon-separated list  of
              database  file(1,n) names.  You can also use the environment variable
              LOCATE_PATH to set(7,n,1 builtins) the list of database files  to  search.   The
              option  overrides  the  environment  variable  if(3,n) both are used.
              Empty elements in(1,8) the path are taken to be synonyms for the file(1,n)
              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 mes-
              sage is printed).

              The file(1,n) name database format changed starting with GNU find and
              locate  version(1,3,5) 4.0 to allow machines with different byte order-
              ings to share the databases.  This version(1,3,5) of locate  can  auto-
              matically  recognize  and read(2,n,1 builtins) databases produced for older ver-
              sions of GNU locate or Unix versions of locate or find.  Support
              for  the  old  locate  database format will be discontinued in(1,8) 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(3,n) there are many  matches
              in(1,8) the database.  If you are using this option within a program,
              please note that it is possible for the file(1,n) 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(3,n) there are many
              matches in(1,8) the database.

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

       -P, -H, --nofollow
              If testing for the  existence  of  files  (with  the  -e  or  -E
              options),  treat  broken symbolic links as if(3,n) they were existing
              files.  The -H form of this option is provided purely for  simi-
              larity with find; the use of -P is recommended over -H.

       -i, --ignore-case
              Ignore case distinctions in(1,8) both the pattern and the file(1,n) names.

       -l N, --limit=N
              Limit the number of matches to N.  If a limit is  set(7,n,1 builtins)  via  this
              option,  the  number  of  results printed for the -c option will
              never be larger than this number.

       -m, --mmap
              Accepted but does nothing, for compatibility with BSD locate.

       -0, --null
              Use ASCII NUL as a separator, instead of newline.

       -p, --print
              Print search results when they normally would  not,  because  of
              the presence of --statistics (-S) or --count (-c).

       -w, --wholename
              Match  against the whole name of the file(1,n) as listed in(1,8) the data-
              base.  This is the default.

       -b, --basename
              Results are considered to match if(3,n) the pattern specified matches
              the final component of the name of a file(1,n) as listed in(1,8) the data-
              base.  This final component is usually referred to as the  `base
              name'.

       -r, --regex
              The  pattern specified on the command line is understood to be a
              POSIX extended regular expression, as opposed to a glob(1,3,7,n) pattern.
              Filenames  whose  full paths match the specified regular expres-
              sion are printed (or, in(1,8) 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.   Newline is
              not considered to be special.

       -s, --stdio
              Accepted but does nothing, for compatibility with BSD locate.

       -S, --statistics
              Print various statistics about each  locate  database  and  then
              exit(3,n,1 builtins)  without  performing  a search, unless non-option arguments
              are given.  For compatibility with BSD, -S is accepted as a syn-
              onym for --statistics.

       --help Print a summary of the options to locate and exit.

       --version
              Print the version(1,3,5) number of locate and exit.

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


SEE ALSO
       find(1),  locatedb(5),  updatedb(1), xargs(1), glob(1,3,7,n)(3),egex(7), Finding
       Files (on-line in(1,8) Info, or printed)

BUGS
       The locate database correctly handles  filenames  containing  newlines,
       but  only if(3,n) the system's sort(1,3) command has a working -z option.  If you
       suspect that locate may need to return filenames  containing  newlines,
       consider using its --null option.

       The  best  way  to  report  a  bug  is to use the form at http://savan-
       nah.gnu.org/bugs/?group=findutils.  The reason for  this  is  that  you
       will then be able to track progress in(1,8) fixing the problem.   Other com-
       ments about locate(1) and about the findutils package in(1,8) general can be
       sent  to  the bug-findutils mailing list.  To join(1,n) the list, send(2,n) email
       to bug-findutils-request@gnu.org.



                                                                     LOCATE(1)

References for this manual (incoming links)