1cdb(1)                      General Commands Manual                     cdb(1)
2
3
4

NAME

6       cdb - Constant DataBase manipulation tool
7

SYNOPSYS

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
15

DESCRIPTION

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
21
22   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
29
30       -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
33
34       -m     newline will be added after every value  printed.   By  default,
35              multiple values will be written without any delimiter.
36
37
38   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
44
45   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
54
55       -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
64
65       -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
71
72       -w     warn about duplicate keys.
73
74
75       -e     abort on duplicate keys (implies -w).
76
77
78       -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
82
83       -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
87
88       -u     do not add duplicate records.
89
90
91       -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
95
96       Note  that  using any option that requires duplicate checking will slow
97       creation process significantly, especially for large databases.
98
99
100   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
111
112   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
123       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
128       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
134

OPTIONS SUMMARY

136       Here is a short summary of all options accepted by cdb utility:
137
138
139       -0     zero-fill duplicate records in create (-c) mode.
140
141       -c     create mode.
142
143       -d     dump mode.
144
145       -e     abort (error) on duplicate key in create (-c) mode.
146
147       -h     print short help and exit.
148
149       -l     list mode.
150
151       -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
154       -nnum  find and print numth record in query (-q) mode.
155
156       -q     query mode.
157
158       -r     replace duplicate keys in create (-c) mode.
159
160       -s     statistics mode.
161
162       -t tempfile
163              specify temporary file when creating (-c) cdb file  (use  single
164              dash (-) as tempfile to stop using temp file).
165
166       -u     do not insert duplicate keys (unique) in create (-c) mode.
167
168       -w     warn about duplicate keys in create (-c) mode.
169
170

AUTHOR

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
176

SEE ALSO

178       cdb(5), cdb(3).
179
180

LICENCE

182       Public domain.
183
184
185
186
187                                   Jan 2009                             cdb(1)
Impressum