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