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. 277