1 .TH LOCATE 1 \" -*- nroff -*-
3 locate \- list files in databases that match a pattern
6 [\-d path | \-\-database=path] [\-e | \-E | \-\-[non\-]existing] [\-i
7 | \-\-ignore-case] [\-0 | \-\-null] [\-c | \-\-count] [\-w | \-\-wholename]
8 |\-b | \-\-basename] [\-l N | \-\-limit=N] [\-S | \-\-statistics] [\-r
9 | \-\-regex ] [\-P | \-H | \-\-nofollow] [\-L | \-\-follow] [\-\-version]
10 [\-p | \-\-print] [\-\-help] pattern...
13 documents the GNU version of
15 For each given pattern,
17 searches one or more databases of file names and displays the
18 file names that contain the pattern. Patterns can contain shell-style
19 metacharacters: `*', `?', and `[]'. The metacharacters do not treat
20 `/' or `.' specially. Therefore, a pattern `foo*bar' can match a
21 file name that contains `foo3/bar', and a pattern `*duck*' can match a
22 file name that contains `lake/.ducky'. Patterns that contain
23 metacharacters should be quoted to protect them from expansion by the
26 If a pattern is a plain string \(em it contains no metacharacters \(em
28 displays all file names in the database that contain that string
29 anywhere. If a pattern does contain metacharacters,
31 only displays file names that match the pattern exactly. As a result,
32 patterns that contain metacharacters should usually begin with a `*',
33 and will most often end with one as well. The exceptions are patterns
34 that are intended to explicitly match the beginning or end of a file
37 The file name databases contain lists of files that were on the system
38 when the databases were last updated. The system administrator can
39 choose the file name of the default database, the frequency with which
40 the databases are updated, and the directories for which they contain
41 entries; see \fBupdatedb\fP(1).
45 output is going to a terminal, unusual characters in the output are
46 escaped in the same way as for the -print action of the
48 command. If the output is not going to a terminal, file names are
49 printed exactly as-is.
54 Instead of printing the matched filenames, just print the total
55 number of matches we found, unless \-\-\fIprint\fP (\-p) is also present.
57 .I "\-d \fIpath\fP, \-\-database=\fIpath\fP"
58 Instead of searching the default file name database, search the file
59 name databases in \fIpath\fP, which is a colon-separated list of
60 database file names. You can also use the environment variable
62 to set the list of database files to search.
63 The option overrides the environment variable if both are used. Empty
64 elements in the path are taken to be synonyms for the file name of the
66 A database can be supplied on stdin, using `\-' as an element
67 of \fIpath\fP. If more than one element of \fIpath\fP is `\-',
68 later instances are ignored (and a warning message is printed).
70 The file name database format changed starting with GNU
74 version 4.0 to allow machines with different byte orderings to share
75 the databases. This version of
77 can automatically recognize and read databases produced for older
84 Support for the old locate database format will be discontinued in a
87 .I "\-e, \-\-existing"
88 Only print out such names that currently exist (instead of such names
89 that existed when the database was created).
90 Note that this may slow down the program a lot, if there are many matches
91 in the database. If you are using this option within a program,
92 please note that it is possible for the file to be deleted after
94 has checked that it exists, but before you use it.
96 .I "\-E, \-\-non\-existing"
97 Only print out such names that currently do not exist (instead of such names
98 that existed when the database was created).
99 Note that this may slow down the program a lot, if there are many matches
103 If testing for the existence of files (with the \-e or \-E options),
104 consider broken symbolic links to be non-existing. This is the default.
106 .I "\-P, \-H, \-\-nofollow"
107 If testing for the existence of files (with the \-e or \-E options), treat
108 broken symbolic links as if they were existing files. The \-H
109 form of this option is provided purely for similarity with
111 the use of \-P is recommended over \-H.
113 .I "\-i, \-\-ignore-case"
114 Ignore case distinctions in both the pattern and the file names.
116 .I "\-l N, \-\-limit=N"
117 Limit the number of matches to N. If a limit is set via this option,
118 the number of results printed for the \-c option will never be larger
122 Accepted but does nothing, for compatibility with BSD
126 Use ASCII NUL as a separator, instead of newline.
129 Print search results when they normally would not, because of the presence
130 of \-\-statistics (\-S) or \-\-count (\-c).
132 .I "\-w, \-\-wholename"
133 Match against the whole name of the file as listed in the database.
136 .I "\-b, \-\-basename"
137 Results are considered to match if the pattern specified matches the
138 final component of the name of a file as listed in the database.
139 This final component is usually referred to as the `base name'.
142 The pattern specified on the command line is understood to be a POSIX
143 exteded regular expression, as opposed to a glob pattern. Filenames
144 whose full paths match the specified regular expression are printed
145 (or, in the case of the -c option, counted). If you wish to anchor
146 your regular expression at the ends of the full path name, then as is
147 usual with regular expressions, you should use the characters ^ and $
148 to signify this. Newline is not considered to be special.
151 Accepted but does nothing, for compatibility with BSD
154 .I "\-S, \-\-statistics"
155 Print various statistics about each locate database and then exit
156 without performing a search, unless non-option arguments are given.
157 For compatibility with BSD, \-S is accepted as a synonym
161 Print a summary of the options to
166 Print the version number of
172 Colon-separated list of databases to search. If the value has a
173 leading or trailing colon, or has two colons in a row, you may get
174 results that vary between different versions of
178 \fBfind\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1),
179 \fBglob\fP(3),\fregex\fP(7),
180 \fBFinding Files\fP (on-line in Info, or printed)
183 The locate database correctly handles filenames containing newlines,
184 but only if the system's sort command has a working
186 option. If you suspect that
188 may need to return filenames containing newlines, consider using its
192 The best way to report a bug is to use the form at
193 http://savannah.gnu.org/bugs/?group=findutils.
194 The reason for this is that you will then be able to track progress in
195 fixing the problem. Other comments about \fBlocate\fP(1) and about
196 the findutils package in general can be sent to the
198 mailing list. To join the list, send email to
199 .IR bug-findutils-request@gnu.org .