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]
   7 [\-e | \-E | \-\-[non\-]existing]
   8 [\-i | \-\-ignore-case]
   9 [\-0 | \-\-null]
  10 [\-c | \-\-count]
  11 [\-w | \-\-wholename]
  12 [\-b | \-\-basename]
  13 [\-l N | \-\-limit=N]
  14 [\-S | \-\-statistics]
  15 [\-r | \-\-regex ]
  16 [\-\-max-database-age D]
  17 [\-P | \-H | \-\-nofollow]
  18 [\-L | \-\-follow]
  19 [\-\-version]
  20 [\-A | \-\-all]
  21 [\-p | \-\-print]
  22 [\-\-help]
  23 pattern...
  24 .SH DESCRIPTION
  25 This manual page
  26 documents the GNU version of
  27 .BR locate .
  28 For each given pattern,
  29 .B locate
  30 searches one or more databases of file names and displays the
  31 file names that contain the pattern.  Patterns can contain shell-style
  32 metacharacters: `*', `?', and `[]'.  The metacharacters do not treat
  33 `/' or `.'  specially.  Therefore, a pattern `foo*bar' can match a
  34 file name that contains `foo3/bar', and a pattern `*duck*' can match a
  35 file name that contains `lake/.ducky'.  Patterns that contain
  36 metacharacters should be quoted to protect them from expansion by the
  37 shell.
  38 .P
  39 If a pattern is a plain string \(em it contains no metacharacters \(em
  40 .B locate
  41 displays all file names in the database that contain that string
  42 anywhere.  If a pattern does contain metacharacters,
  43 .B locate
  44 only displays file names that match the pattern exactly.  As a result,
  45 patterns that contain metacharacters should usually begin with a `*',
  46 and will most often end with one as well.  The exceptions are patterns
  47 that are intended to explicitly match the beginning or end of a file
  48 name.
  49 .P
  50 The file name databases contain lists of files that were on the system
  51 when the databases were last updated.  The system administrator can
  52 choose the file name of the default database, the frequency with which
  53 the databases are updated, and the directories for which they contain
  54 entries; see \fBupdatedb\fP(1).
  55 .P
  56 If
  57 .BR locate 's
  58 output is going to a terminal, unusual characters in the output are
  59 escaped in the same way as for the \-print action of the
  60 .B find
  61 command.  If the output is not going to a terminal, file names are
  62 printed exactly as-is.
  63
  64 .SH OPTIONS
  65 .TP
  66 .I "\-0, \-\-null"
  67 Use ASCII NUL as a separator, instead of newline.
  68 .TP
  69 .I "\-A, \-\-all"
  70 Print only names which match all non-option arguments, not those matching
  71 one or more non-option arguments.
  72 .TP
  73 .I "\-b, \-\-basename"
  74 Results are considered to match if the pattern specified matches the
  75 final component of the name of a file as listed in the database.
  76 This final component is usually referred to as the `base name'.
  77 .TP
  78 .I "\-c, \-\-count"
  79 Instead of printing the matched filenames, just print the total
  80 number of matches we found, unless \-\-\fIprint\fP (\-p) is also present.
  81 .TP
  82 .I "\-d \fIpath\fP, \-\-database=\fIpath\fP"
  83 Instead of searching the default file name database, search the file
  84 name databases in \fIpath\fP, which is a colon-separated list of
  85 database file names.  You can also use the environment variable
  86 .B LOCATE_PATH
  87 to set the list of database files to search.
  88 The option overrides the environment variable if both are used.  Empty
  89 elements in the path are taken to be synonyms for the file name of the
  90 default database.
  91 A database can be supplied on stdin, using `\-' as an element
  92 of \fIpath\fP. If more than one element of \fIpath\fP is `\-',
  93 later instances are ignored (and a warning message is printed).
  94 .IP
  95 The file name database format changed starting with GNU
  96 .B find
  97 and
  98 .B locate
  99 version 4.0 to allow machines with different byte orderings to share
 100 the databases.  This version of
 101 .B locate
 102 can automatically recognize and read databases produced for older
 103 versions of GNU
 104 .B locate
 105 or Unix versions of
 106 .B locate
 107 or
 108 .BR find .
 109 Support for the old locate database format will be discontinued in a
 110 future release.
 111 .TP
 112 .I "\-e, \-\-existing"
 113 Only print out such names that currently exist (instead of such names
 114 that existed when the database was created).
 115 Note that this may slow down the program a lot, if there are many matches
 116 in the database.  If you are using this option within a program,
 117 please note that it is possible for the file to be deleted after
 118 .B locate
 119 has checked that it exists, but before you use it.
 120 .TP
 121 .I "\-E, \-\-non\-existing"
 122 Only print out such names that currently do not exist (instead of such names
 123 that existed when the database was created).
 124 Note that this may slow down the program a lot, if there are many matches
 125 in the database.
 126 .TP
 127 .I "\-\-help"
 128 Print a summary of the options to
 129 .B locate
 130 and exit.
 131 .TP
 132 .I "\-i, \-\-ignore-case"
 133 Ignore case distinctions in both the pattern and the file names.
 134 .TP
 135 .I "\-l N, \-\-limit=N"
 136 Limit the number of matches to N.  If a limit is set via this option,
 137 the number of results printed for the \-c option will never be larger
 138 than this number.
 139 .TP
 140 .I "\-L, \-\-follow"
 141 If testing for the existence of files (with the \-e or \-E options),
 142 consider broken symbolic links to be non-existing.   This is the default.
 143 .TP
 144 .I "\-\-max-database-age D"
 145 Normally,
 146 .B locate
 147 will issue a warning message when it searches a database which is more
 148 than 8 days old.  This option changes that value to something other
 149 than 8.  The effect of specifying a negative value is undefined.
 150 .TP
 151 .I "\-m, \-\-mmap"
 152 Accepted but does nothing, for compatibility with BSD
 153 .BR locate .
 154 .TP
 155 .I "\-P, \-H, \-\-nofollow"
 156 If testing for the existence of files (with the \-e or \-E options), treat
 157 broken symbolic links as if they were existing files.  The \-H
 158 form of this option is provided purely for similarity with
 159 .BR find ;
 160 the use of \-P is recommended over \-H.
 161 .TP
 162 .I "\-p, \-\-print"
 163 Print search results when they normally would not, because of the presence
 164 of \-\-statistics (\-S) or \-\-count (\-c).
 165 .TP
 166 .I "\-r, \-\-regex "
 167 The pattern specified on the command line is understood to be a
 168 regular expression, as opposed to a glob pattern.  The Regular
 169 expressions work in the same was as in
 170 .B emacs
 171 and
 172 .BR find ,
 173 except for the fact that "." will match a newline.
 174 Filenames whose full paths match the specified regular expression are
 175 printed (or, in the case of the \-c option, counted).  If you wish to
 176 anchor your regular expression at the ends of the full path name, then
 177 as is usual with regular expressions, you should use the characters ^
 178 and $ to signify this.
 179 .TP
 180 .I "\-s, \-\-stdio"
 181 Accepted but does nothing, for compatibility with BSD
 182 .BR locate .
 183 .TP
 184 .I "\-S, \-\-statistics"
 185 Print various statistics about each locate database and then exit
 186 without performing a search, unless non-option arguments are given.
 187 For compatibility with BSD, \-S is accepted as a synonym
 188 for \-\-statistics.  However, the output of
 189 .B locate \-S
 190 is different for the GNU and BSD implementations of
 191 .BR locate .
 192 .TP
 193 .I "\-\-version"
 194 Print the version number of
 195 .B locate
 196 and exit.
 197 .TP
 198 .I "\-w, \-\-wholename"
 199 Match against the whole name of the file as listed in the database.
 200 This is the default.
 201 .SH ENVIRONMENT
 202 .TP
 203 .B LOCATE_PATH
 204 Colon-separated list of databases to search.  If the value has a
 205 leading or trailing colon, or has two colons in a row, you may get
 206 results that vary between different versions of
 207 .BR locate .
 208
 209 .SH "SEE ALSO"
 210 \fBfind\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1),
 211 \fBglob\fP(3)
 212
 213 The full documentation for
 214 .B locate
 215 is maintained as a Texinfo manual.  If the
 216 .B info
 217 and
 218 .B locate
 219 programs are properly installed at your site, the command
 220 .B info locate
 221 should give you access to the complete manual.
 222
 223
 224 .SH "HISTORY"
 225 The
 226 .B locate
 227 program started life as the BSD fast find program, contributed to BSD
 228 by James A. Woods.  This was described by his paper
 229 .I Finding Files Fast
 230 which was published in Usenix
 231 .IR ;login: ,
 232 Vol 8, No 1, February/March, 1983, pp. 8-10.   When the
 233 .B find
 234 program began to assume a default
 235 .B -print
 236 action if no action was specified, this changed the interpretation of
 237 .B find
 238 .BR pattern .
 239 The BSD developers therefore moved the fast find functionality into
 240 .BR locate .
 241 The GNU implementation of
 242 .B locate
 243 appears to be derived from the same code.
 244 .P
 245 Significant changes to
 246 .B locate
 247 in reverse order:
 248 .TS
 249 tab(|);
 250 LL.
 251 4.3.7 | Byte-order independent support for old database format
 252 4.3.3 | locate \fI\-i\fR supports multi-byte characters correctly
 253       | Introduced \fI\-\-max_db_age\fR
 254 4.3.2 | Support for the slocate database format
 255 4.2.22| Introduced the \fI\-\-all\fR option
 256 4.2.15| Introduced the \fI\-\-regex\fR option
 257 4.2.14| Introduced options \fI\-L, \-P, \-H\fR
 258 4.2.12| Empty items in \fBLOCATE_PATH\fR now indicate the default database
 259 4.2.11| Introduced the \fI\-\-statistics\fR option
 260 4.2.4 | Introduced \fI\-\-count\fR and \fI\-\-limit\fR
 261 4.2.0 | Glob characters cause matching against the whole file name
 262 4.0   | Introduced the LOCATE02 database format
 263 3.7   | Locate can search multiple databases
 264 .TE
 265 .SH "BUGS"
 266 .P
 267 The locate database correctly handles filenames containing newlines,
 268 but only if the system's sort command has a working
 269 \-z
 270 option.  If you suspect that
 271 .B locate
 272 may need to return filenames containing newlines, consider using its
 273 .I \-\-null
 274 option.
 275 .P
 276 The best way to report a bug is to use the form at
 277 http://savannah.gnu.org/bugs/?group=findutils.
 278 The reason for this is that you will then be able to track progress in
 279 fixing the problem.   Other comments about \fBlocate\fP(1) and about
 280 the findutils package in general can be sent to the
 281 .I bug-findutils
 282 mailing list.  To join the list, send email to
 283 .IR bug-findutils-request@gnu.org .