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