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 December 11, 2020 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 stores 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 ASCII 92.Dv NUL 93character (character code 0) instead of default NL 94(newline, character code 10). 95.It Fl S 96Print some statistics about the database and exit. 97.It Fl c 98Suppress normal output; instead print a count of matching file names. 99.It Fl d Ar database 100Search in 101.Ar database 102instead of the default file name database. 103Multiple 104.Fl d 105options are allowed. 106Each additional 107.Fl d 108option adds the specified database to the list 109of databases to be searched. 110.Pp 111The option 112.Ar database 113may be a colon-separated list of databases. 114A single colon is a reference 115to the default database. 116.Bd -literal 117$ locate -d $HOME/lib/mydb: foo 118.Ed 119.Pp 120will first search string 121.Dq foo 122in 123.Pa $HOME/lib/mydb 124and then in 125.Pa /var/db/locate.database . 126.Bd -literal 127$ locate -d $HOME/lib/mydb::/cdrom/locate.database foo 128.Ed 129.Pp 130will first search string 131.Dq foo 132in 133.Pa $HOME/lib/mydb 134and then in 135.Pa /var/db/locate.database 136and then in 137.Pa /cdrom/locate.database . 138.Pp 139.Dl "$ locate -d db1 -d db2 -d db3 pattern" 140.Pp 141is the same as 142.Pp 143.Dl "$ locate -d db1:db2:db3 pattern" 144.Pp 145or 146.Pp 147.Dl "$ locate -d db1:db2 -d db3 pattern" 148.Pp 149If 150.Fl 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. 160Note: you can only use 161.Em one 162pattern for stdin. 163.It Fl i 164Ignore case distinctions in both the pattern and the database. 165.It Fl l Ar number 166Limit output to 167.Ar number 168of file names and exit. 169.It Fl m 170Use 171.Xr mmap 2 172instead of the 173.Xr stdio 3 174library. 175This is the default behavior 176and is faster in most cases. 177.It Fl s 178Use the 179.Xr stdio 3 180library instead of 181.Xr mmap 2 . 182.El 183.Sh ENVIRONMENT 184.Bl -tag -width LOCATE_PATH -compact 185.It Pa LOCATE_PATH 186path to the locate database if set and not empty, ignored if the 187.Fl d 188option was specified. 189.El 190.Sh FILES 191.Bl -tag -width /etc/periodic/weekly/310.locate -compact 192.It Pa /var/db/locate.database 193locate database 194.It Pa /usr/libexec/locate.updatedb 195Script to update the locate database 196.It Pa /etc/periodic/weekly/310.locate 197Script that starts the database rebuild 198.El 199.Sh SEE ALSO 200.Xr find 1 , 201.Xr whereis 1 , 202.Xr which 1 , 203.Xr fnmatch 3 , 204.Xr locate.updatedb 8 205.Rs 206.%A Woods, James A. 207.%D 1983 208.%T "Finding Files Fast" 209.%J ";login" 210.%V 8:1 211.%P pp. 8-10 212.Re 213.Sh HISTORY 214The 215.Nm 216command first appeared in 217.Bx 4.4 . 218Many new features were 219added in 220.Fx 2.2 . 221.Sh BUGS 222The 223.Nm 224program may fail to list some files that are present, or may 225list files that have been removed from the system. 226This is because 227locate only reports files that are present in the database, which is 228typically only regenerated once a week by the 229.Pa /etc/periodic/weekly/310.locate 230script. 231Use 232.Xr find 1 233to locate files that are of a more transitory nature. 234.Pp 235The 236.Nm 237database is typically built by user 238.Dq nobody 239and the 240.Xr locate.updatedb 8 241utility skips directories 242which are not readable for user 243.Dq nobody , 244group 245.Dq nobody , 246or 247world. 248For example, if your HOME directory is not world-readable, 249.Em none 250of your files are 251in the database. 252.Pp 253The 254.Nm 255database is not byte order independent. 256It is not possible 257to share the databases between machines with different byte order. 258The current 259.Nm 260implementation understands databases in host byte order or 261network byte order if both architectures use the same integer size. 262So on a 263.Fx Ns /i386 264machine 265(little endian), you can read 266a locate database which was built on SunOS/sparc machine 267(big endian, net). 268.Pp 269The 270.Nm 271utility does not recognize multibyte characters. 272