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: src/usr.bin/locate/locate/locate.1,v 1.16.2.5 2002/07/08 21:31:28 trhodes Exp $ 35.\" $DragonFly: src/usr.bin/locate/locate/locate.1,v 1.3 2004/03/11 12:28:58 hmp Exp $ 36.\" 37.Dd June 6, 1993 38.Dt LOCATE 1 39.Os 40.Sh NAME 41.Nm locate 42.Nd find filenames quickly 43.Sh SYNOPSIS 44.Nm 45.Op Fl Scims 46.Op Fl l Ar limit 47.Op Fl d Ar database 48.Ar pattern ... 49.Sh DESCRIPTION 50The 51.Nm 52program searches a database for all pathnames which match the specified 53.Ar pattern . 54The database is recomputed periodically (usually weekly or daily), 55and contains the pathnames 56of all files which are publicly accessible. 57.Pp 58Shell globbing and quoting characters 59.Dq ( * , 60.Dq \&? , 61.Dq \e , 62.Dq \&[ 63and 64.Dq \&] ) 65may be used in 66.Ar pattern , 67although they will have to be escaped from the shell. 68Preceding any character with a backslash 69.Pq Dq \e 70eliminates any special 71meaning which it may have. 72The matching differs in that no characters must be matched explicitly, 73including slashes 74.Pq Dq / . 75.Pp 76As a special case, a pattern containing no globbing characters 77.Pq Dq foo 78is matched as though it were 79.Dq *foo* . 80.Pp 81Historically, locate only stored characters between 32 and 127. The 82current implementation store any character except newline 83.Pq Sq \en 84and NUL 85.Pq Sq \e0 . 86The 8-bit character support doesn't waste extra space for 87plain ASCII file names. 88Characters less than 32 or greater than 127 89are stored in 2 bytes. 90.Pp 91The following options are available: 92.Bl -tag -width 10n 93.It Fl S 94Print some statistic about the database and exit. 95.It Fl c 96Suppress normal output; instead print a count of matching file names. 97.It Fl d Ar database 98Search in 99.Ar database 100instead the default file name database. 101Multiple 102.Fl d 103options are allowed. Each additional 104.Fl d 105option adds the specified database to the list 106of databases to be searched. 107.Pp 108The option 109.Ar database 110may be a colon-separated list of databases. 111A single colon is a reference 112to the default database. 113.Bd -literal 114$ locate -d $HOME/lib/mydb: foo 115.Ed 116.Pp 117will first search string 118.Dq foo 119in 120.Pa $HOME/lib/mydb 121and then in 122.Pa /var/db/locate.database . 123.Bd -literal 124$ locate -d $HOME/lib/mydb::/cdrom/locate.database foo 125.Ed 126.Pp 127will first search string 128.Dq foo 129in 130.Pa $HOME/lib/mydb 131and then in 132.Pa /var/db/locate.database 133and then in 134.Pa /cdrom/locate.database . 135.Bd -literal 136$ locate -d db1 -d db2 -d db3 pattern 137.Ed 138.Pp 139is the same as 140.Bd -literal 141$ locate -d db1:db2:db3 pattern 142.Ed 143.Pp 144or 145.Bd -literal 146.Dq $ locate -d db1:db2 -d db3 pattern . 147.Ed 148.Pp 149If 150.Ar - 151is given as the database name, standard input will be read instead. 152For example, you can compress your database 153and use: 154.Bd -literal 155$ zcat database.gz | locate -d - pattern 156.Ed 157.Pp 158This might be useful on machines with a fast CPU and little RAM and slow 159I/O. Note: you can only use 160.Ar one 161pattern for stdin. 162.It Fl i 163Ignore case distinctions in both the pattern and the database. 164.It Fl l Ar number 165Limit output to 166.Ar number 167of file names and exit. 168.It Fl m 169Use 170.Xr mmap 2 171instead of the 172.Xr stdio 3 173library. 174This is the default behavior 175and is faster in most cases. 176.It Fl s 177Use the 178.Xr stdio 3 179library instead of 180.Xr mmap 2 . 181.El 182.Sh FILES 183.Bl -tag -width /etc/periodic/weekly/310.locate -compact 184.It Pa /var/db/locate.database 185locate database 186.It Pa /usr/libexec/locate.updatedb 187Script to update the locate database 188.It Pa /etc/periodic/weekly/310.locate 189Script that starts the database rebuild 190.El 191.Sh ENVIRONMENT 192.Bl -tag -width LOCATE_PATH -compact 193.It Pa LOCATE_PATH 194path to the locate database if set and not empty, ignored if the 195.Fl d 196option was specified. 197.El 198.Sh SEE ALSO 199.Xr find 1 , 200.Xr whereis 1 , 201.Xr which 1 , 202.Xr fnmatch 3 , 203.Xr locate.updatedb 8 204.Rs 205.%A Woods, James A. 206.%D 1983 207.%T "Finding Files Fast" 208.%J ";login" 209.%V 8:1 210.%P pp. 8-10 211.Re 212.Sh BUGS 213The 214.Nm 215program may fail to list some files that are present, or may 216list files that have been removed from the system. This is because 217locate only reports files that are present in the database, which is 218typically only regenerated once a week by the 219.Pa /etc/periodic/weekly/310.locate 220script. Use 221.Xr find 1 222to locate files that are of a more transitory nature. 223.Pp 224The 225.Nm 226database was built by user 227.Dq nobody . 228.Xr find 1 229skips directories, 230which are not readable for user 231.Dq nobody , 232group 233.Dq nobody , 234or 235world. 236E.g. if your HOME directory is not world-readable, all your 237files are 238.Ar not 239in the database. 240.Pp 241The 242.Nm 243database is not byte order independent. 244It is not possible 245to share the databases between machines with different byte order. 246The current 247.Nm 248implementation understand databases in host byte order or 249network byte order if both architectures use the same integer size. 250So you can read on a 251.Dx Ns /i386 252machine 253(little endian) 254a locate database which was built on SunOS/sparc machine 255(big endian, net). 256.Sh HISTORY 257The 258.Nm 259command first appeared in 260.Bx 4.4 . 261Many new features were 262added in 263.Fx 2.2 . 264