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] [\-\-wholename] [\-\-basename]
   8 [\-l N | \-\-limit=N] [\-\-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.
  53 .IP
  54 The file name database format changed starting with GNU
  55 .B find
  56 and
  57 .B locate
  58 version 4.0 to allow machines with diffent byte orderings to share
  59 the databases.  This version of
  60 .B locate
  61 can automatically recognize and read databases produced for older
  62 versions of GNU
  63 .B locate
  64 or Unix versions of
  65 .B locate
  66 or
  67 .BR find .
  68 Support for the old locate database format will be discontinued in a
  69 future release.
  70 .TP
  71 .I "\-e, \-\-existing"
  72 Only print out such names that currently exist (instead of such names
  73 that existed when the database was created).
  74 Note that this may slow down the program a lot, if there are many matches
  75 in the database.  If you are using this option within a program,
  76 please note that it is possible for the file to be deleted after
  77 .B locate
  78 has checked that it exists, but before you use it.
  79 .TP
  80 .I "\-i, \-\-ignore-case"
  81 Ignore case distinctions in both the pattern and the file names.
  82 .TP
  83 .I "\-l N, \-\-limit=N"
  84 Limit the number of matches to N.  If a limit is set via this option,
  85 the number of results printed for the \-c option will never be larger
  86 than this number.
  87 .TP
  88 .I "\-0, \-\-null"
  89 Use ASCII NUL as a separator, instead of newline.
  90 .TP
  91 .I "\-\-wholename"
  92 Match against the whole name of the file as listed in the database.
  93 This is the default.
  94 .TP
  95 .I "\-\-basename"
  96 Results are considered to match if the pattern specified matches the
  97 final component of the name of a file as listed in the database.
  98 This final component is usually referred to as the `base name'.
  99 .TP
 100 .I "\-\-statistics"
 101 Print various statistics about each locate database and then exit
 102 without performing a search.  Any patterns given on the command line
 103 are ignored.  For compatibility with BSD, \-S is accepted as a synonym
 104 for \-\-statistics.
 105 .TP
 106 .I "\-\-help"
 107 Print a summary of the options to
 108 .B locate
 109 and exit.
 110 .TP
 111 .I "\-\-version"
 112 Print the version number of
 113 .B locate
 114 and exit.
 115 .SH ENVIRONMENT
 116 .TP
 117 .B LOCATE_PATH
 118 Colon-separated list of databases to search.  If the value has a
 119 leading or trailing colon, or has two colons in a row, you may get
 120 results that vary between different versions of
 121 .BR locate .
 122
 123 .SH "SEE ALSO"
 124 \fBfind\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1), \fBxargs\fP(1)
 125 \fBFinding Files\fP (on-line in Info, or printed)
 126 .SH "BUGS"
 127 .P
 128 The locate database correctly handles filenames containing newlines,
 129 but only if the system's sort command has a working
 130 .I \-z
 131 option.  If you suspect that
 132 .B locate
 133 may need to return filenames containing newlines, consider using its
 134 .I \-\-null
 135 option.
 136 .P
 137 The best way to report a bug is to use the form at
 138 http://savannah.gnu.org/bugs/?group=findutils.
 139 The reason for this is that you will then be able to track progress in
 140 fixing the problem.   Other comments about \fBlocate\fP(1) and about
 141 the findutils package in general can be sent to the
 142 .I bug-findutils
 143 mailing list.  To join the list, send email to
 144 .IR bug-findutils-request@gnu.org .