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