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