Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
cdb(1)			    General Commands Manual			cdb(1)

       cdb - Constant DataBase manipulation tool

       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...]

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

       cdb  -q	finds given key	in a given dbname cdb file, and	writes associ-
       ated 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.

       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.

       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 db-
       name with ".tmp"	appended if no -t option given)	and then rename	it  to
       dbname.	It will	read supplied infiles (or standard input if none spec-
       ified).	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 sin-
	      gle 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,  in-
	      stead 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.

       cdb -s will analyze dbfile and print summary to standard	output.	  Sta-
       tistics	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 dis-
       tances from it's	calculated hash	table index -- keys in distance	0  re-
       quires  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:
       where "+", ",", ":", "-", ">" and "\n" (newline)	 are  literal  charac-
       ters, 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 con-
       tain 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:
       (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.

       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.

       The  tinycdb  package written by	Michael	Tokarev	<>, based
       on ideas	and shares file	format with original cdb library by Dan	 Bern-

       cdb(5), cdb(3).

       Public domain.

				   Jan 2009				cdb(1)


Want to link to this manual page? Use this URL:

home | help