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