locate/locate.1

   1 .TH LOCATE 1 \" -*- nroff -*-
   2 .SH NAME
   3 locate \- list files in databases that match a pattern
   4 .SH SYNOPSIS
   5 .B locate
   6 [\-d path | \-\-database=path] [\-e | \-\-existing] [\-i | \-\-ignore-case]
   7 [\-0 | \-\-null] [\-c | \-\-count] [\-w | \-\-wholename] [\-b | \-\-basename]
   8 [\-l N | \-\-limit=N] [\-S | \-\-statistics] [\-\-version] [\-\-help] pattern...
   9 .SH DESCRIPTION
  10 This manual page
  11 documents the GNU version of
  12 .BR locate .
  13 For each given pattern,
  14 .B locate
  15 searches one or more databases of file names and displays the
  16 file names that contain the pattern.  Patterns can contain shell-style
  17 metacharacters: `*', `?', and `[]'.  The metacharacters do not treat
  18 `/' or `.'  specially.  Therefore, a pattern `foo*bar' can match a
  19 file name that contains `foo3/bar', and a pattern `*duck*' can match a
  20 file name that contains `lake/.ducky'.  Patterns that contain
  21 metacharacters should be quoted to protect them from expansion by the
  22 shell.
  23 .P
  24 If a pattern is a plain string \(em it contains no metacharacters \(em
  25 .B locate
  26 displays all file names in the database that contain that string
  27 anywhere.  If a pattern does contain metacharacters,
  28 .B locate
  29 only displays file names that match the pattern exactly.  As a result,
  30 patterns that contain metacharacters should usually begin with a `*',
  31 and will most often end with one as well.  The exceptions are patterns
  32 that are intended to explicitly match the beginning or end of a file
  33 name.
  34 .P
  35 The file name databases contain lists of files that were on the system
  36 when the databases were last updated.  The system administrator can
  37 choose the file name of the default database, the frequency with which
  38 the databases are updated, and the directories for which they contain
  39 entries; see \fBupdatedb\fP(1).
  40 .SH OPTIONS
  41 .TP
  42 .I "\-c, \-\-count"
  43 Instead of printing the matched filenames, just print the total
  44 number of matches we found.
  45 .TP
  46 .I "\-d \fIpath\fP, \-\-database=\fIpath\fP"
  47 Instead of searching the default file name database, search the file
  48 name databases in \fIpath\fP, which is a colon-separated list of
  49 database file names.  You can also use the environment variable
  50 .B LOCATE_PATH
  51 to set the list of database files to search.
  52 The option overrides the environment variable if both are used.  Empty
  53 elements in the path are taken to be synonyms for the file name of the
  54 default database.
  55 .IP
  56 The file name database format changed starting with GNU
  57 .B find
  58 and
  59 .B locate
  60 version 4.0 to allow machines with diffent byte orderings to share
  61 the databases.  This version of
  62 .B locate
  63 can automatically recognize and read databases produced for older
  64 versions of GNU
  65 .B locate
  66 or Unix versions of
  67 .B locate
  68 or
  69 .BR find .
  70 Support for the old locate database format will be discontinued in a
  71 future release.
  72 .TP
  73 .I "\-e, \-\-existing"
  74 Only print out such names that currently exist (instead of such names
  75 that existed when the database was created).
  76 Note that this may slow down the program a lot, if there are many matches
  77 in the database.  If you are using this option within a program,
  78 please note that it is possible for the file to be deleted after
  79 .B locate
  80 has checked that it exists, but before you use it.
  81 .TP
  82 .I "\-i, \-\-ignore-case"
  83 Ignore case distinctions in both the pattern and the file names.
  84 .TP
  85 .I "\-l N, \-\-limit=N"
  86 Limit the number of matches to N.  If a limit is set via this option,
  87 the number of results printed for the \-c option will never be larger
  88 than this number.
  89 .TP
  90 .I "\-0, \-\-null"
  91 Use ASCII NUL as a separator, instead of newline.
  92 .TP
  93 .I "\-w, \-\-wholename"
  94 Match against the whole name of the file as listed in the database.
  95 This is the default.
  96 .TP
  97 .I "\-b, \-\-basename"
  98 Results are considered to match if the pattern specified matches the
  99 final component of the name of a file as listed in the database.
 100 This final component is usually referred to as the `base name'.
 101 .TP
 102 .I "\-\-statistics"
 103 Print various statistics about each locate database and then exit
 104 without performing a search.  Any patterns given on the command line
 105 are ignored.  For compatibility with BSD, \-S is accepted as a synonym
 106 for \-\-statistics.
 107 .TP
 108 .I "\-\-help"
 109 Print a summary of the options to
 110 .B locate
 111 and exit.
 112 .TP
 113 .I "\-\-version"
 114 Print the version number of
 115 .B locate
 116 and exit.
 117 .SH ENVIRONMENT
 118 .TP
 119 .B LOCATE_PATH
 120 Colon-separated list of databases to search.  If the value has a
 121 leading or trailing colon, or has two colons in a row, you may get
 122 results that vary between different versions of
 123 .BR locate .
 124
 125 .SH "SEE ALSO"
 126 \fBfind\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1)
 127 \fBFinding Files\fP (on-line in Info, or printed)
 128 .SH "BUGS"
 129 .P
 130 The locate database correctly handles filenames containing newlines,
 131 but only if the system's sort command has a working
 132 .I \-z
 133 option.  If you suspect that
 134 .B locate
 135 may need to return filenames containing newlines, consider using its
 136 .I \-\-null
 137 option.
 138 .P
 139 The best way to report a bug is to use the form at
 140 http://savannah.gnu.org/bugs/?group=findutils.
 141 The reason for this is that you will then be able to track progress in
 142 fixing the problem.   Other comments about \fBlocate\fP(1) and about
 143 the findutils package in general can be sent to the
 144 .I bug-findutils
 145 mailing list.  To join the list, send email to
 146 .IR bug-findutils-request@gnu.org .