Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  DBTOOL (1)

.ds Aq ’


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:
insert Keys (and the associated value) will be overwritten if it already exists.
update 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 -v).
-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 -S.
-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 colon:

 ^^^^^^   ^^
 |        |
 |        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 -R):

 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 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


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


dbtool can be downloaded from


T.v. Dein <>
Search for    or go to Top of page |  Section 1 |  Main Index

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

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.