usr.bin/locate/locate/locate.1

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