From aa6deeedb02c207b19af857cc6e0b47d8b5dd20c Mon Sep 17 00:00:00 2001 From: jay Date: Sat, 21 Apr 2007 15:21:15 +0000 Subject: [PATCH] Document the slocate database format --- ChangeLog | 6 ++++++ NEWS | 7 +++++++ configure.in | 2 +- locate/locatedb.5 | 61 ++++++++++++++++++++++++++++++++++++++++++++----------- 4 files changed, 63 insertions(+), 13 deletions(-) diff --git a/ChangeLog b/ChangeLog index 4ca4b82..f540745 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,11 @@ 2007-04-21 James Youngman + * find/locate/locatedb.5: Clarifications to the description of the + LOCATE02 format. Organised the material under a number of + headings. Documented the slocate database format. + +2007-04-21 James Youngman + * find/testuite/Makefile.am (EXTRA_DIST_EXP): added find/testsuite/find.posix/sv-bug-19617.exp diff --git a/NEWS b/NEWS index f505800..55e7943 100644 --- a/NEWS +++ b/NEWS @@ -1,4 +1,11 @@ GNU findutils NEWS - User visible changes. -*- outline -*- (allout) +* Major changes in release 4.3.5-CVS + +** Documentation Fixes + +The locatedb.5 manpage now documents the (default) LOCATE02 format +more clearly, and also documents the slocate database format. + * Major changes in release 4.3.4 ** Bug Fixes diff --git a/configure.in b/configure.in index c4e57ab..ee7e798 100644 --- a/configure.in +++ b/configure.in @@ -1,5 +1,5 @@ dnl Process this file with autoconf to produce a configure script. -AC_INIT([GNU findutils], 4.3.4, [bug-findutils@gnu.org]) +AC_INIT([GNU findutils], 4.3.5-CVS, [bug-findutils@gnu.org]) AC_CONFIG_AUX_DIR(build-aux) AM_INIT_AUTOMAKE diff --git a/locate/locatedb.5 b/locate/locatedb.5 index 8036049..a94905d 100644 --- a/locate/locatedb.5 +++ b/locate/locatedb.5 @@ -16,25 +16,33 @@ databases are updated, and the directories for which they contain entries. Normally, file name databases are updated by running the \fBupdatedb\fP program periodically, typically nightly; see \fBupdatedb\fP(1). -.P -\fBupdatedb\fP runs a program called \fBfrcode\fP to compress the list -of file names using front-compression, which reduces -the database size by a factor of 4 to 5. Front-compression (also -known as incremental encoding) works as follows. + +.SH GNU LOCATE02 database format +This is the default format of databases produced by +.BR updatedb . +The +.B updatedb +program runs +.B frcode +to compress the list of file names using front-compression, which +reduces the database size by a factor of 4 to 5. Front-compression +(also known as incremental encoding) works as follows. .P The database entries are a sorted list (case-insensitively, for users' convenience). Since the list is sorted, each entry is likely to share a prefix (initial string) with the previous entry. Each database -entry begins with an offset-differential count byte, which is the -additional number of characters of prefix of the preceding entry to -use beyond the number that the preceding entry is using of its +entry begins with an signed offset-differential count byte, which is +the additional number of characters of prefix of the preceding entry +to use beyond the number that the preceding entry is using of its predecessor. (The counts can be negative.) Following the count is a null-terminated ASCII remainder \(em the part of the name that follows the shared prefix. .P If the offset-differential count is larger than can be stored in a -byte (+/\-127), the byte has the value 0x80 and the count follows in a -2-byte word, with the high byte first (network byte order). +signed byte (+/\-127), the byte has the value 0x80 (binary 10000000) +and the actual count follows in a 2-byte word, with the high byte +first (network byte order). This count can also be negative (the sign +bit being in the first of the two bytes). .P Every database begins with a dummy entry for a file called `LOCATE02', which \fBlocate\fP checks for to ensure that the database file has the @@ -43,8 +51,37 @@ correct format; it ignores the entry in doing the search. Databases can not be concatenated together, even if the first (dummy) entry is trimmed from all but the first database. This is because the offset-differential count in the first entry of the -second and following databases will be wrong. +second and following databases will be wrong. .P +In the future, the data within the locate database may not be sorted +in any particular order. To obtain sorted results, pipe the output of +.B locate +through +.BR "sort -f" . +.SH slocate database format +The +.B slocate +program uses a database format similar to, but not quite the same as, +GNU +.BR locate . +The first byte of the database specifies its +.I security +.IR level . +If the security level is 0, +.B slocate +will read, match and print filenames on the basis of the information +in the database only. However, if the security level byte is 1, +.B slocate +omits entries from its output if the invoking user is unable to access +them. The second byte of the database is zero. The second byte is +followed by the first database entry. The first entry in the database +is not preceded by any differential count or dummy entry. Instead +the differential count for the first item is assumed to be zero. +.P +Starting with the second entry (if any) in the database, data is +interpreted as for the GNU LOCATE02 format. + +.SH Old Locate Database format There is also an old database format, used by Unix .B locate and @@ -102,7 +139,7 @@ and count bytes made printable: (6 = 14 \- 8, and \-9 = 5 \- 14) .fi .SH "SEE ALSO" -\fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBxargs\fP(1) +\fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBxargs\fP(1), \fBFinding Files\fP (on-line in Info, or printed) .SH "BUGS" .P -- 2.11.4.GIT