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