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

FreeBSD Manual Pages


home | help
DBTOOL(1)	      User Contributed Perl Documentation	     DBTOOL(1)

       dbtool -	a tool for storing key/value pairs in a	hash database

	dbtool -d database [DirusSfwVhtRFpP] [-k key] [-v value]

       This manual page	documents the program dbtool. dbtool can be used to
       store and retrieve data in a key/value format in	a hash database. Perl
       compatible regular expressions are supported both for storing and
       retrieving of data. It's	main advantages	are the	ability	to maintain
       huge amounts of data and	speed.

       -D  Dump	all key/value pairs of the database. Keys and values will be
	   separated by	whitespace or by the character specified by -F.

       -f  Enable force	mode, which has	the following causes:

	       Keys (and the associated	value) will be overwritten if it
	       already exists.

	       Key/value will be created if it does not	exist.

       -F -separator
	   Optional field separator. The default separator is one whitespace.
	   Use -F in conjunction with -D to specify an alternate output	field
	   separator or	with -i	if data	is read	in from	STDIN (without -k and

       -h  Prints out a	short help message to STDERR and exits.

       -i  Insert data.	The -k and -v options are required. You	will get an
	   error message if the	key already exists. Use	-f to avoid such a
	   message and let dbtool overwrite the	key instead.
	    If both key	(-k) and value (-v) are	not provided, dbtool will read
	   in the data from STDIN. The default input separator is one
	   whitespace. The first field (separated by whitespace) will be
	   considered as the key and the rest of the input line	will be
	   considered as the value associated with the key. You	can provide an
	   alternate input field separator using the option -F.
	    It is also possible	to separate the	key and	value of an input line
	   using a regular expression with the -t option(see below).

       -k key
	   Use key as the key. Use -k in conjunction with -i, -u, -r, -s or

       -r  Remove data.	Only the key to	be removed (-k)	is required.

       -R  Reverse the meaning of the expression provided with -t. By default
	   dbtool will use the first match as the key and the second one as
	   the value. With -R this will	be reversed.

       -s  Search for a	key specified by -k. The associated value will be
	   printed to STDOUT. You can use -w to	get the	key too	separated by
	   whitespace or by the	parameter of -F. You can only search for keys,
	   not for values.

       -S  Search for a	key. The parameter to the option -k will be considered
	   as a	perl compatible	regular	expression. It is possible to get
	   multiple results, which will	be printed to STDOUT separated by
	   newline. Otherwise -S behaves like -s.

       -t expression
	   Use expression to decide which part of an input line	has to be used
	   as the key and which	one as the value. The regular expression must
	   contain two parts surrounded	by round parenthesis'. See the section
	   EXAMPLES for	some uses of -t. This option can only be used in
	   conjunction with -i without -k and -v.

       -u  Update data.	A key (-k) and a value (-v) is required. You will get
	   an error message if the key does not	exist. You can use the option
	   -f to avoid such a message and to insert the	data if	it does	not
	   exist instead.

       -p  Use encrypted database. dbtool will ask you for the passphrase,
	   unless the environment variable DB_PASSPHRASE is set.

       -P passphrase
	   Use encrypted database. Specify the passphrase on the commandline.

       -v value
	   Use value as	the value associated with some key. Use	-v in
	   conjunction with -i,	-u or -r.

       -V  Print out the version of dbtool.

       -w  Print search	results	together with the associated keys separated by
	   whitespace or the parameter of -F.

       Regular expressions are provided	using the PCRE Library.	It supports
       most of the features which perl provides. See the section XDIFFERENCES
       FROM PERLX in the PCRE manpage. You can also take a look	to the perl
       regular expression man page with	the following command:

	perldoc	perlre

       (which requires perl to be installed).

       As of version 1.4 dbtool	supports encrypted databases. See the
       descriptions of the options -p and -P. The algorithm used for
       encryption is Rijndael block cipher encryption.

       dbtool does not use the passphrase which	the user supplies. It uses
       instead the MD5 digest of the passphrase	as the encryption key.

       Please note, that dbtool	itself does not	distinguish between encrypted
       or unencrypted databases. That means, you will get strange results if
       you try to access an encrypted database without the options -p or -P
       being set.

       dbtool by default will only encrypt the values of a database, not the
       keys.  This might change	in future versions.


	    dbtool -d test.db -i -k "test" -v "blah blah blah"

	   Insert the key  "test" which	is associated to the value "blah blah
	   blah" into test.db.


	    dbtool -d test.db -u -f -k "test" -v "blubber"

	   Update the key "test" even if it does not exist with	"blubber".


	    dbtool -d test.db -r -k "test"

	   Remove the entry to which the key "test" points.


	    dbtool -d test.db -S -k "^\d\d"

	   Search for all keys which start at least with two digits.


	    dbtool -d test.db -D | grep	-i "tom"

	   Dump	out the	whole database test.db and search for "tom". This
	   method allows you to	search for values.


	    cat	/etc/passwd | dbtool -d	test.db	-i -f -t "^(.+?):.*:(\d+?):$"

	   In this example we store the	contents of the	file passwd in a hash
	   database. The username will be the key of an	entry and the userid
	   will	be the associated value. The key must be any character from
	   the beginning of a line until the first appearance of a colon.  The
	   value must be one or	more digits after the 2nd colon	until the next

	    ^^^^^^   ^^
	    |	     |
	    |	     o--- value
	    o------------ key


	    find /home -ls | dbtool -d catalog.dbm -i -f -R -t "^(.+?) (\/.*)$"

	   In this example the output of the unix command 'find	/home -ls'
	   will	be used	as input for dbtool. The key for an entry will begin
	   on the first	appearance of a	slash character	until the end of the
	   line. Everything in front of	it will	be the value (because of the

	    302	 12 -rw------- 1 scip  scip    9734 Feb	11  2000 /home/scip/D/lrk5/README
	    (---------------[ value ]--------------------------) (--------[ key	]-------)

	   I use this command in my backup script for creating a catalog of
	   all saved files and it's attributes.

       Report bugs on <> or mail to

       Copyright (c) 2000-2015 T.v. Dein.  This	is free	software; see the
       source for copying conditions.  There is	NO warranty; not even for

       perldoc perlre
	   Perl	regular	expressions.
	   The homepage	of the PCRE library.

       dbtool can be downloaded	from

       T.v. Dein>

perl v5.14.2			  2015-05-16			     DBTOOL(1)


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

home | help