cdb(1)							      General Commands Manual							    cdb(1)

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|-] [-p perms] [-weru0] dbname [infile...]

DESCRIPTION

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

   Query
       cdb -q finds given key in a given dbname cdb file, and writes associated 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 and write a record with a given number num starting with 1 -- 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 complete, 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).  Note tmpname must be  in  the
	      same filesystem as output file, as cdb uses rename(2) to finalize the database creation procedure.  If tmpname is a single dash (-),
	      no temp file will be created, database will be built in-place.  This mode is useful when the final renaming is done by the caller.

       -p perms
	      permissions for the newly created file (usually an octal number, like 0644).  By default the  permissions  are  0666  (with  current
	      process umask applied).  If this option is specified, current umask value has no effect.

       -w     warn about duplicate keys.

       -e     abort on duplicate keys (implies -w).

       -r     replace  existing  key  with new one in case of duplicate.  This may require database file rewrite to remove old records, and can be
	      slow.

       -0     zero-fill existing records when duplicate records are added.  This is faster than -r, but leaves extra zeros in the database file in
	      case of duplicates.

       -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 analyze dbfile and print summary to standard 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
       greater 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

       where  "+", ",", ":", "-", ">" and "
" (newline) 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 () and so on.

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

       (note vlen and val 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:

       -0     zero-fill duplicate records in create (-c) mode.

       -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 (use single dash (-) as tempfile to stop using temp 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.

								     Jan 2009								    cdb(1)