locate/locate.1

   1 .TH LOCATE 1 \" -*- nroff -*-
   2 .SH NAME
   3 locate \- list files in databases that match a pattern
   4 .SH SYNOPSIS
   5 .B locate
   6 [\-d path | \-\-database=path] [\-e | \-\-existing] [\-i | \-\-ignore-case]
   7 [\-0 | \-\-null] [\-c | \-\-count] [\-w | \-\-wholename] [\-b | \-\-basename]
   8 [\-l N | \-\-limit=N] [\-S | \-\-statistics] [\-\-version]
   9 [\-P | \-H | \-\-nofollow] [\-L | \-\-follow] [\-\-help] pattern...
  10 .SH DESCRIPTION
  11 This manual page
  12 documents the GNU version of
  13 .BR locate .
  14 For each given pattern,
  15 .B locate
  16 searches one or more databases of file names and displays the
  17 file names that contain the pattern.  Patterns can contain shell-style
  18 metacharacters: `*', `?', and `[]'.  The metacharacters do not treat
  19 `/' or `.'  specially.  Therefore, a pattern `foo*bar' can match a
  20 file name that contains `foo3/bar', and a pattern `*duck*' can match a
  21 file name that contains `lake/.ducky'.  Patterns that contain
  22 metacharacters should be quoted to protect them from expansion by the
  23 shell.
  24 .P
  25 If a pattern is a plain string \(em it contains no metacharacters \(em
  26 .B locate
  27 displays all file names in the database that contain that string
  28 anywhere.  If a pattern does contain metacharacters,
  29 .B locate
  30 only displays file names that match the pattern exactly.  As a result,
  31 patterns that contain metacharacters should usually begin with a `*',
  32 and will most often end with one as well.  The exceptions are patterns
  33 that are intended to explicitly match the beginning or end of a file
  34 name.
  35 .P
  36 The file name databases contain lists of files that were on the system
  37 when the databases were last updated.  The system administrator can
  38 choose the file name of the default database, the frequency with which
  39 the databases are updated, and the directories for which they contain
  40 entries; see \fBupdatedb\fP(1).
  41 .SH OPTIONS
  42 .TP
  43 .I "\-c, \-\-count"
  44 Instead of printing the matched filenames, just print the total
  45 number of matches we found.
  46 .TP
  47 .I "\-d \fIpath\fP, \-\-database=\fIpath\fP"
  48 Instead of searching the default file name database, search the file
  49 name databases in \fIpath\fP, which is a colon-separated list of
  50 database file names.  You can also use the environment variable
  51 .B LOCATE_PATH
  52 to set the list of database files to search.
  53 The option overrides the environment variable if both are used.  Empty
  54 elements in the path are taken to be synonyms for the file name of the
  55 default database.
  56 .IP
  57 The file name database format changed starting with GNU
  58 .B find
  59 and
  60 .B locate
  61 version 4.0 to allow machines with diffent byte orderings to share
  62 the databases.  This version of
  63 .B locate
  64 can automatically recognize and read databases produced for older
  65 versions of GNU
  66 .B locate
  67 or Unix versions of
  68 .B locate
  69 or
  70 .BR find .
  71 Support for the old locate database format will be discontinued in a
  72 future release.
  73 .TP
  74 .I "\-e, \-\-existing"
  75 Only print out such names that currently exist (instead of such names
  76 that existed when the database was created).
  77 Note that this may slow down the program a lot, if there are many matches
  78 in the database.  If you are using this option within a program,
  79 please note that it is possible for the file to be deleted after
  80 .B locate
  81 has checked that it exists, but before you use it.
  82 .TP
  83 .I "\-L, \-\-follow"
  84 If testing for the existence of files (with the \-e option), omit
  85 broken symbolic links.   This is the default.
  86 .TP
  87 .I "\-P, \-H, \-\-nofollow"
  88 If testing for the existence of files (with the \-e option), treat
  89 broken symbolic links count as if they were exiting files.  The \-H
  90 form of this option is provided purely for similarity with
  91 .BR find ;
  92 the use of \-P is recommended over \-H.
  93 .TP
  94 .I "\-i, \-\-ignore-case"
  95 Ignore case distinctions in both the pattern and the file names.
  96 .TP
  97 .I "\-l N, \-\-limit=N"
  98 Limit the number of matches to N.  If a limit is set via this option,
  99 the number of results printed for the \-c option will never be larger
 100 than this number.
 101 .TP
 102 .I "\-0, \-\-null"
 103 Use ASCII NUL as a separator, instead of newline.
 104 .TP
 105 .I "\-w, \-\-wholename"
 106 Match against the whole name of the file as listed in the database.
 107 This is the default.
 108 .TP
 109 .I "\-b, \-\-basename"
 110 Results are considered to match if the pattern specified matches the
 111 final component of the name of a file as listed in the database.
 112 This final component is usually referred to as the `base name'.
 113 .TP
 114 .I "\-S, \-\-statistics"
 115 Print various statistics about each locate database and then exit
 116 without performing a search.  Any patterns given on the command line
 117 are ignored.  For compatibility with BSD, \-S is accepted as a synonym
 118 for \-\-statistics.
 119 .TP
 120 .I "\-\-help"
 121 Print a summary of the options to
 122 .B locate
 123 and exit.
 124 .TP
 125 .I "\-\-version"
 126 Print the version number of
 127 .B locate
 128 and exit.
 129 .SH ENVIRONMENT
 130 .TP
 131 .B LOCATE_PATH
 132 Colon-separated list of databases to search.  If the value has a
 133 leading or trailing colon, or has two colons in a row, you may get
 134 results that vary between different versions of
 135 .BR locate .
 136
 137 .SH "SEE ALSO"
 138 \fBfind\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1)
 139 \fBFinding Files\fP (on-line in Info, or printed)
 140 .SH "BUGS"
 141 .P
 142 The locate database correctly handles filenames containing newlines,
 143 but only if the system's sort command has a working
 144 .I \-z
 145 option.  If you suspect that
 146 .B locate
 147 may need to return filenames containing newlines, consider using its
 148 .I \-\-null
 149 option.
 150 .P
 151 The best way to report a bug is to use the form at
 152 http://savannah.gnu.org/bugs/?group=findutils.
 153 The reason for this is that you will then be able to track progress in
 154 fixing the problem.   Other comments about \fBlocate\fP(1) and about
 155 the findutils package in general can be sent to the
 156 .I bug-findutils
 157 mailing list.  To join the list, send email to
 158 .IR bug-findutils-request@gnu.org .