1cdb(1) General Commands Manual cdb(1)
2
6 cdb - Constant DataBase manipulation tool
7
9 cdb -q [-m] [-n num] dbname key
10 cdb -d [-m] [dbname|-]
11 cdb -l [-m] [dbname|-]
12 cdb -s [dbname|-]
13 cdb -c [-m] [-t tmpname|-] [-p perms] [-weru0] dbname [infile...]
14
17 cdb used to query, dump, list, analyze or create CDB (Constant Data‐
18 Base) files. Format of cdb described in cdb(5) manpage. This manual
19 page corresponds to version 0.78 of tinycdb package.
20 Query
23 cdb -q finds given key in a given dbname cdb file, and writes associ‐
24 ated value to standard output if found (and exits with zero), or exits
25 with non-zero if not found. dbname must be seekable file, and stdin
26 can not be used as input. By default, cdb will print all records
27 found. Options recognized in query mode:
28 -nnum causes cdb to find and write a record with a given number num
31 starting with 1 — when there are many records with a given key.
32 -m newline will be added after every value printed. By default,
35 multiple values will be written without any delimiter.
36 Dump/List
39 cdb -d dumps contents, and cdb -l lists keys of cdbfile (or standard
40 input if not specified) to standard output, in format controlled by
41 presence of -m option. See subsection "Formats" below. Output from
42 cdb -d can be used as an input for cdb -c.
43 Create
46 Cdb database created in two stages: temporary database is created, and
47 after it is complete, it gets atomically renamed to permanent place.
48 This avoids requirements for locking between readers and writers (or
49 creaters). cdb -c will attempt to create cdb in file tmpname (or
50 dbname with ".tmp" appended if no -t option given) and then rename it
51 to dbname. It will read supplied infiles (or standard input if none
52 specified). Options recognized in create mode:
53 -t tmpname
56 use given tmpname as temporary file. Defaults to dbname.tmp
57 (i.e. with output file with .tmp added). Note tmpname must be
58 in the same filesystem as output file, as cdb uses rename(2) to
59 finalize the database creation procedure. If tmpname is a sin‐
60 gle dash (-), no temp file will be created, database will be
61 built in-place. This mode is useful when the final renaming is
62 done by the caller.
63 -p perms
66 permissions for the newly created file (usually an octal number,
67 like 0644). By default the permissions are 0666 (with current
68 process umask applied). If this option is specified, current
69 umask value has no effect.
70 -w warn about duplicate keys.
73 -e abort on duplicate keys (implies -w).
76 -r replace existing key with new one in case of duplicate. This
79 may require database file rewrite to remove old records, and can
80 be slow.
81 -0 zero-fill existing records when duplicate records are added.
84 This is faster than -r, but leaves extra zeros in the database
85 file in case of duplicates.
86 -u do not add duplicate records.
89 -m interpret input as a sequence of lines, one record per line,
92 with value separated from a key by space or tab characters,
93 instead of native cdb format (see "Input/Output Format" below).
94 Note that using any option that requires duplicate checking will slow
97 creation process significantly, especially for large databases.
98 Statistics
101 cdb -s will analyze dbfile and print summary to standard output. Sta‐
102 tistics include: total number of rows in a file, minimum, average and
103 maximum key and value lengths, hash tables (max 256) and entries used,
104 number of hash collisions (that is, more than one key point to the same
105 hash table entry), minimum, average and maximum hash table size (of
106 non-empty tables), and number of keys that sits at 10 different dis‐
107 tances from it's calculated hash table index — keys in distance 0
108 requires only one hash table lookup, 1 — two and so on; more keys at
109 greater distance means slower database search.
110 Input/Output Format
113 By default, cdb expects (for create operation) or writes (for
114 dump/list) native cdb format data. Cdb native format is a sequence of
115 records in a form:
116 +klen,vlen:key->val\n
117 where "+", ",", ":", "-", ">" and "\n" (newline) are literal charac‐
118 ters, klen and vlen are length of key and value as decimal numbers, and
119 key and val are key and value themselves. Series of records terminated
120 by an empty line. This is the only format where key and value may con‐
121 tain any character including newline, zero (\0) and so on.
122 When -l option requested (list keys mode), cdb will produce slightly
124 modified output in a form:
125 +klen:key\n
126 (note vlen and val are omitted, together with surrounding delimiters).
127 If -m option is given, cdb will expect or produce one line for every
129 record (newline is a record delimiter), and every line should contain
130 optional whitespace, key, whitespace and value up to end of line.
131 Lines started with hash character (#) and empty lines are ignored.
132 This is the same format as mkmap(1) utility expects.
133
136 Here is a short summary of all options accepted by cdb utility:
137 -0 zero-fill duplicate records in create (-c) mode.
140 -c create mode.
142 -d dump mode.
144 -e abort (error) on duplicate key in create (-c) mode.
146 -h print short help and exit.
148 -l list mode.
150 -m input or output is in "map" format, not in native cdb format.
152 In query mode, add a newline after every value written.
153 -nnum find and print numth record in query (-q) mode.
155 -q query mode.
157 -r replace duplicate keys in create (-c) mode.
159 -s statistics mode.
161 -t tempfile
163 specify temporary file when creating (-c) cdb file (use single
164 dash (-) as tempfile to stop using temp file).
165 -u do not insert duplicate keys (unique) in create (-c) mode.
167 -w warn about duplicate keys in create (-c) mode.
169
172 The tinycdb package written by Michael Tokarev <mjt@corpit.ru>, based
173 on ideas and shares file format with original cdb library by Dan Bern‐
174 stein.
175
178 cdb(5), cdb(3).
179
182 Public domain.
183 Jan 2009 cdb(1)