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