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