| 1 |
.TH LOCATEDB 5 \" -*- nroff -*- |
| 2 |
.SH NAME |
| 3 |
locatedb \- front-compressed file name database |
| 4 |
. |
| 5 |
.SH DESCRIPTION |
| 6 |
This manual page documents the format of file name databases for the |
| 7 |
GNU version of |
| 8 |
.BR locate . |
| 9 |
The file name databases contain lists of files that were in |
| 10 |
particular directory trees when the databases were last updated. |
| 11 |
.P |
| 12 |
There can be multiple databases. Users can select which databases |
| 13 |
\fBlocate\fP searches using an environment variable or command line |
| 14 |
option; see \fBlocate\fP(1). The system administrator can choose the |
| 15 |
file name of the default database, the frequency with which the |
| 16 |
databases are updated, and the directories for which they contain |
| 17 |
entries. Normally, file name databases are updated by running the |
| 18 |
\fBupdatedb\fP program periodically, typically nightly; see |
| 19 |
\fBupdatedb\fP(1). |
| 20 |
. |
| 21 |
.SH GNU LOCATE02 database format |
| 22 |
This is the default format of databases produced by |
| 23 |
.BR updatedb . |
| 24 |
The |
| 25 |
.B updatedb |
| 26 |
program runs |
| 27 |
.B frcode |
| 28 |
to compress the list of file names using front-compression, which |
| 29 |
reduces the database size by a factor of 4 to 5. Front-compression |
| 30 |
(also known as incremental encoding) works as follows. |
| 31 |
.P |
| 32 |
The database entries are a sorted list (case-insensitively, for users' |
| 33 |
convenience). Since the list is sorted, each entry is likely to share |
| 34 |
a prefix (initial string) with the previous entry. Each database |
| 35 |
entry begins with an signed offset-differential count byte, which is |
| 36 |
the additional number of characters of prefix of the preceding entry |
| 37 |
to use beyond the number that the preceding entry is using of its |
| 38 |
predecessor. (The counts can be negative.) Following the count is a |
| 39 |
null-terminated ASCII remainder \(em the part of the name that follows |
| 40 |
the shared prefix. |
| 41 |
.P |
| 42 |
If the offset-differential count is larger than can be stored in a |
| 43 |
signed byte (\(+-127), the byte has the value 0x80 (binary 10000000) |
| 44 |
and the actual count follows in a 2-byte word, with the high byte |
| 45 |
first (network byte order). This count can also be negative (the sign |
| 46 |
bit being in the first of the two bytes). |
| 47 |
.P |
| 48 |
Every database begins with a dummy entry for a file called `LOCATE02', |
| 49 |
which \fBlocate\fP checks for to ensure that the database file has the |
| 50 |
correct format; it ignores the entry in doing the search. |
| 51 |
.P |
| 52 |
Databases cannot be concatenated together, even if the first |
| 53 |
(dummy) entry is trimmed from all but the first database. This |
| 54 |
is because the offset-differential count in the first entry of the |
| 55 |
second and following databases will be wrong. |
| 56 |
.P |
| 57 |
In the future, the data within the locate database may not be sorted |
| 58 |
in any particular order. To obtain sorted results, pipe the output of |
| 59 |
.B locate |
| 60 |
through |
| 61 |
.BR "sort -f" . |
| 62 |
. |
| 63 |
.SH slocate database format |
| 64 |
The |
| 65 |
.B slocate |
| 66 |
program uses a database format similar to, but not quite the same as, |
| 67 |
GNU |
| 68 |
.BR locate . |
| 69 |
The first byte of the database specifies its |
| 70 |
.I security |
| 71 |
.IR level . |
| 72 |
If the security level is 0, |
| 73 |
.B slocate |
| 74 |
will read, match and print filenames on the basis of the information |
| 75 |
in the database only. However, if the security level byte is 1, |
| 76 |
.B slocate |
| 77 |
omits entries from its output if the invoking user is unable to access |
| 78 |
them. The second byte of the database is zero. The second byte is |
| 79 |
followed by the first database entry. The first entry in the database |
| 80 |
is not preceded by any differential count or dummy entry. Instead |
| 81 |
the differential count for the first item is assumed to be zero. |
| 82 |
.P |
| 83 |
Starting with the second entry (if any) in the database, data is |
| 84 |
interpreted as for the GNU LOCATE02 format. |
| 85 |
. |
| 86 |
.SH Old Locate Database format |
| 87 |
There is also an old database format, used by Unix |
| 88 |
.B locate |
| 89 |
and |
| 90 |
.B find |
| 91 |
programs and earlier releases of the GNU ones. \fBupdatedb\fP runs |
| 92 |
programs called \fBbigram\fP and \fBcode\fP to produce old-format |
| 93 |
databases. The old format differs from the above description in the |
| 94 |
following ways. Instead of each entry starting with an |
| 95 |
offset-differential count byte and ending with a null, byte values |
| 96 |
from 0 through 28 indicate offset-differential counts from -14 through |
| 97 |
14. The byte value indicating that a long offset-differential count |
| 98 |
follows is 0x1e (30), not 0x80. The long counts are stored in host |
| 99 |
byte order, which is not necessarily network byte order, and host |
| 100 |
integer word size, which is usually 4 bytes. They also represent a |
| 101 |
count 14 less than their value. The database lines have no |
| 102 |
termination byte; the start of the next line is indicated by its first |
| 103 |
byte having a value \(<= 30. |
| 104 |
.P |
| 105 |
In addition, instead of starting with a dummy entry, the old database |
| 106 |
format starts with a 256 byte table containing the 128 most common |
| 107 |
bigrams in the file list. A bigram is a pair of adjacent bytes. |
| 108 |
Bytes in the database that have the high bit set are indexes (with the |
| 109 |
high bit cleared) into the bigram table. The bigram and |
| 110 |
offset-differential count coding makes these databases 20\(en25% smaller |
| 111 |
than the new format, but makes them not 8-bit clean. Any byte in a |
| 112 |
file name that is in the ranges used for the special codes is replaced |
| 113 |
in the database by a question mark, which not coincidentally is the |
| 114 |
shell wildcard to match a single character. |
| 115 |
. |
| 116 |
.SH EXAMPLE |
| 117 |
.nf |
| 118 |
|
| 119 |
Input to \fBfrcode\fP: |
| 120 |
.\" with nulls changed to newlines: |
| 121 |
/usr/src |
| 122 |
/usr/src/cmd/aardvark.c |
| 123 |
/usr/src/cmd/armadillo.c |
| 124 |
/usr/tmp/zoo |
| 125 |
|
| 126 |
Length of the longest prefix of the preceding entry to share: |
| 127 |
0 /usr/src |
| 128 |
8 /cmd/aardvark.c |
| 129 |
14 rmadillo.c |
| 130 |
5 tmp/zoo |
| 131 |
|
| 132 |
.fi |
| 133 |
Output from \fBfrcode\fP, with trailing nulls changed to newlines |
| 134 |
and count bytes made printable: |
| 135 |
.nf |
| 136 |
0 LOCATE02 |
| 137 |
0 /usr/src |
| 138 |
8 /cmd/aardvark.c |
| 139 |
6 rmadillo.c |
| 140 |
\-9 tmp/zoo |
| 141 |
|
| 142 |
(6 = 14 - 8, and -9 = 5 - 14) |
| 143 |
.fi |
| 144 |
. |
| 145 |
.SH "REPORTING BUGS" |
| 146 |
GNU findutils online help: <https://www.gnu.org/software/findutils/#get-help> |
| 147 |
.br |
| 148 |
Report any translation bugs to <https://translationproject.org/team/> |
| 149 |
.PP |
| 150 |
Report any other issue via the form at the GNU Savannah bug tracker: |
| 151 |
.RS |
| 152 |
<https://savannah.gnu.org/bugs/?group=findutils> |
| 153 |
.RE |
| 154 |
General topics about the GNU findutils package are discussed at the |
| 155 |
.I bug\-findutils |
| 156 |
mailing list: |
| 157 |
.RS |
| 158 |
<https://lists.gnu.org/mailman/listinfo/bug-findutils> |
| 159 |
.RE |
| 160 |
. |
| 161 |
.SH COPYRIGHT |
| 162 |
Copyright \(co 1994\(en2024 Free Software Foundation, Inc. |
| 163 |
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. |
| 164 |
.br |
| 165 |
This is free software: you are free to change and redistribute it. |
| 166 |
There is NO WARRANTY, to the extent permitted by law. |
| 167 |
. |
| 168 |
.SH "SEE ALSO" |
| 169 |
.BR find (1), |
| 170 |
.BR locate (1), |
| 171 |
.BR xargs (1), |
| 172 |
.BR locatedb (5) |
| 173 |
.PP |
| 174 |
Full documentation <https://www.gnu.org/software/findutils/locatedb> |
| 175 |
.br |
| 176 |
or available locally via: |
| 177 |
.B info locatedb |