man cdb (Commandes) - Constant DataBase manipulation tool

NAME

cdb - Constant DataBase manipulation tool

SYNOPSYS

cdb -q [-m] [-n num] dbname key

cdb -d [-m] [dbname|-]

cdb -l [-m] [dbname|-]

cdb -s [dbname|-]

cdb -c [-m] [-t tmpname] [-weru] dbname [infile...]

DESCRIPTION

cdb used to query, dump, list, analize or create CDB (Constant DataBase) files. Format of cdb described in cdb(5) manpage. This manual page corresponds to version 0.74 of tinycdb package.

Query

cdb -q finds given key in a given dbname cdb file, and writes assotiated value to standard output if found (and exits with zero), or exits with non-zero if not found. dbname must be seekable file, and stdin can not be used as input. By default, cdb will print all records found. Options recognized in query mode:

-nnum
causes cdb to find write record with a given number num starting with 1 (only applies to a case when there are many records with a given key).
-m
newline will be added after every value printed. By default, multiple values will be written without any delimiter.

Dump/List

cdb -d dumps contents, and cdb -l lists keys of cdbfile (or standard input if not specified) to standard output, in format controlled by presence of -m option. See subsection "Formats" below. Output from cdb -d can be used as an input for cdb -c.

Create

Cdb database created in two stages: temporary database is created, and after it is complets, it gets atomically renamed to permanent place. This avoids requirements for locking between readers and writers (or creaters). cdb -c will attempt to create cdb in file tmpname (or dbname with ".tmp" appended if no -t option given) and then rename it to dbname. It will read supplied infiles (or standard input if none specified). Options recognized in create mode:

-t tmpname
use given tmpname as temporary file. Defaults to dbname.tmp (i.e. with output file with .tmp added).
-w
warn about duplicate keys.
-e
abort on duplicate keys (implies -w).
-r
replace existing key with new one in case of duplicate. Note that old record will be in file anyway, but not in index.
-u
do not add duplicate records.
-m
interpret input as a sequence of lines, one record per line, with value separated from a key by space or tab characters, instead of native cdb format (see "Input/Output Format" below).

Note that using any option that requires duplicate checking will slow creation process significantly, especially for large databases.

Statistics

cdb -s will analize dbfile and print summary to standart output. Statistics include: total number of rows in a file, minimum, average and maximum key and value lengths, hash tables (max 256) and entries used, number of hash collisions (that is, more than one key point to the same hash table entry), minimum, average and maximum hash table size (of non-empty tables), and number of keys that sits at 10 different distances from it's calculated hash table index -- keys in distance 0 requires only one hash table lookup, 1 - two and so on; more keys at greather distance means slower database search.

Input/Output Format

By default, cdb expects (for create operation) or writes (for dump/list) native cdb format data. Cdb native format is a sequence of records in a form:

+klen,vlen:key->val\n

where "+", ",", ":", "-", ">" and "\n" are literal characters, klen and vlen are length of key and value as decimal numbers, and key and val are key and value themselves. Series of records terminated by an empty line. This is the only format where key and value may contain any character including newline, zero (\0) and so on.

When -l option requested (list keys mode), cdb will produce slightly modified output in a form:

+klen:key\n

(note vlen and vIval are omitted, together with surrounding delimiters).

If -m option is given, cdb will expect or produce one line for every record (newline is a record delimiter), and every line should contain optional whitespace, key, whitespace and value up to end of line. Lines started with hash character (#) and empty lines are ignored. This is the same format as mkmap(1) utility expects.

OPTIONS SUMMARY

Here is a short summary of all options accepted by cdb utility:

-c
create mode.
-d
dump mode.
-e
abort (error) on duplicate key in create (-c) mode.
-h
print short help and exit.
-l
list mode.
-m
input or output is in "map" format, not in native cdb format. In query mode, add a newline after every value written.
-nnum
find and print numth record in query (-q) mode.
-q
query mode.
-r
replace duplicate keys in create (-c) mode.
-s
statistics mode.
-t tempfile
specify temporary file when creating (-c) cdb file.
-u
do not insert duplicate keys (unique) in create (-c) mode.
-w
warn about duplicate keys in create (-c) mode.

AUTHOR

The tinycdb package written by Michael Tokarev <mjt@corpit.ru>, based on ideas and shares file format with original cdb library by Dan Bernstein.

SEE ALSO

cdb(5), cdb(3).

LICENCE

Public domain.