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