/usr.bin/locate/locate/locate.1

  1.\" Copyright (c) 1995 Wolfram Schneider <wosch@FreeBSD.org>. Berlin.
  2.\" Copyright (c) 1990, 1993
  3.\"	The Regents of the University of California.  All rights reserved.
  4.\"
  5.\" Redistribution and use in source and binary forms, with or without
  6.\" modification, are permitted provided that the following conditions
  7.\" are met:
  8.\" 1. Redistributions of source code must retain the above copyright
  9.\"    notice, this list of conditions and the following disclaimer.
 10.\" 2. Redistributions in binary form must reproduce the above copyright
 11.\"    notice, this list of conditions and the following disclaimer in the
 12.\"    documentation and/or other materials provided with the distribution.
 13.\" 3. All advertising materials mentioning features or use of this software
 14.\"    must display the following acknowledgement:
 15.\"	This product includes software developed by the University of
 16.\"	California, Berkeley and its contributors.
 17.\" 4. Neither the name of the University nor the names of its contributors
 18.\"    may be used to endorse or promote products derived from this software
 19.\"    without specific prior written permission.
 20.\"
 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 24.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 31.\" SUCH DAMAGE.
 32.\"
 33.\"	@(#)locate.1	8.1 (Berkeley) 6/6/93
 34.\" $FreeBSD$
 35.\"
 36.Dd August 17, 2006
 37.Dt LOCATE 1
 38.Os
 39.Sh NAME
 40.Nm locate
 41.Nd find filenames quickly
 42.Sh SYNOPSIS
 43.Nm
 44.Op Fl 0Scims
 45.Op Fl l Ar limit
 46.Op Fl d Ar database
 47.Ar pattern ...
 48.Sh DESCRIPTION
 49The
 50.Nm
 51program searches a database for all pathnames which match the specified
 52.Ar pattern .
 53The database is recomputed periodically (usually weekly or daily),
 54and contains the pathnames
 55of all files which are publicly accessible.
 56.Pp
 57Shell globbing and quoting characters
 58.Dq ( * ,
 59.Dq \&? ,
 60.Dq \e ,
 61.Dq \&[
 62and
 63.Dq \&] )
 64may be used in
 65.Ar pattern ,
 66although they will have to be escaped from the shell.
 67Preceding any character with a backslash
 68.Pq Dq \e
 69eliminates any special
 70meaning which it may have.
 71The matching differs in that no characters must be matched explicitly,
 72including slashes
 73.Pq Dq / .
 74.Pp
 75As a special case, a pattern containing no globbing characters
 76.Pq Dq foo
 77is matched as though it were
 78.Dq *foo* .
 79.Pp
 80Historically, locate only stored characters between 32 and 127.
 81The
 82current implementation store any character except newline
 83.Pq Sq \en
 84and
 85.Dv NUL
 86.Pq Sq \e0 .
 87The 8-bit character support does not waste extra space for
 88plain ASCII file names.
 89Characters less than 32 or greater than 127
 90are stored in 2 bytes.
 91.Pp
 92The following options are available:
 93.Bl -tag -width 10n
 94.It Fl 0
 95Print pathnames separated by an
 96.Tn ASCII
 97.Dv NUL
 98character (character code 0) instead of default NL
 99(newline, character code 10).
100.It Fl S
101Print some statistics about the database and exit.
102.It Fl c
103Suppress normal output; instead print a count of matching file names.
104.It Fl d Ar database
105Search in
106.Ar database
107instead of the default file name database.
108Multiple
109.Fl d
110options are allowed.
111Each additional
112.Fl d
113option adds the specified database to the list
114of databases to be searched.
115.Pp
116The option
117.Ar database
118may be a colon-separated list of databases.
119A single colon is a reference
120to the default database.
121.Bd -literal
122$ locate -d $HOME/lib/mydb: foo
123.Ed
124.Pp
125will first search string
126.Dq foo
127in
128.Pa $HOME/lib/mydb
129and then in
130.Pa /var/db/locate.database .
131.Bd -literal
132$ locate -d $HOME/lib/mydb::/cdrom/locate.database foo
133.Ed
134.Pp
135will first search string
136.Dq foo
137in
138.Pa $HOME/lib/mydb
139and then in
140.Pa /var/db/locate.database
141and then in
142.Pa /cdrom/locate.database .
143.Pp
144.Dl "$ locate -d db1 -d db2 -d db3 pattern"
145.Pp
146is the same as
147.Pp
148.Dl "$ locate -d db1:db2:db3 pattern"
149.Pp
150or
151.Pp
152.Dl "$ locate -d db1:db2 -d db3 pattern"
153.Pp
154If
155.Fl
156is given as the database name, standard input will be read instead.
157For example, you can compress your database
158and use:
159.Bd -literal
160$ zcat database.gz | locate -d - pattern
161.Ed
162.Pp
163This might be useful on machines with a fast CPU and little RAM and slow
164I/O.
165Note: you can only use
166.Em one
167pattern for stdin.
168.It Fl i
169Ignore case distinctions in both the pattern and the database.
170.It Fl l Ar number
171Limit output to
172.Ar number
173of file names and exit.
174.It Fl m
175Use
176.Xr mmap 2
177instead of the
178.Xr stdio 3
179library.
180This is the default behavior
181and is faster in most cases.
182.It Fl s
183Use the
184.Xr stdio 3
185library instead of
186.Xr mmap 2 .
187.El
188.Sh ENVIRONMENT
189.Bl -tag -width LOCATE_PATH -compact
190.It Pa LOCATE_PATH
191path to the locate database if set and not empty, ignored if the
192.Fl d
193option was specified.
194.El
195.Sh FILES
196.Bl -tag -width /etc/periodic/weekly/310.locate -compact
197.It Pa /var/db/locate.database
198locate database
199.It Pa /usr/libexec/locate.updatedb
200Script to update the locate database
201.It Pa /etc/periodic/weekly/310.locate
202Script that starts the database rebuild
203.El
204.Sh SEE ALSO
205.Xr find 1 ,
206.Xr whereis 1 ,
207.Xr which 1 ,
208.Xr fnmatch 3 ,
209.Xr locate.updatedb 8
210.Rs
211.%A Woods, James A.
212.%D 1983
213.%T "Finding Files Fast"
214.%J ";login"
215.%V 8:1
216.%P pp. 8-10
217.Re
218.Sh HISTORY
219The
220.Nm
221command first appeared in
222.Bx 4.4 .
223Many new features were
224added in
225.Fx 2.2 .
226.Sh BUGS
227The
228.Nm
229program may fail to list some files that are present, or may
230list files that have been removed from the system.
231This is because
232locate only reports files that are present in the database, which is
233typically only regenerated once a week by the
234.Pa /etc/periodic/weekly/310.locate
235script.
236Use
237.Xr find 1
238to locate files that are of a more transitory nature.
239.Pp
240The
241.Nm
242database is typically built by user
243.Dq nobody
244and the
245.Xr locate.updatedb 8
246utility skips directories
247which are not readable for user
248.Dq nobody ,
249group
250.Dq nobody ,
251or
252world.
253For example, if your HOME directory is not world-readable,
254.Em none
255of your files are
256in the database.
257.Pp
258The
259.Nm
260database is not byte order independent.
261It is not possible
262to share the databases between machines with different byte order.
263The current
264.Nm
265implementation understands databases in host byte order or
266network byte order if both architectures use the same integer size.
267So on a
268.Fx Ns /i386
269machine
270(little endian), you can read
271a locate database which was built on SunOS/sparc machine
272(big endian, net).
273.Pp
274The
275.Nm
276utility does not recognize multibyte characters.