dbm tools - shell access to dbm files


These tools provide shell-level access to Unix dbm(3) files, including ndbm(3) and gdbm(3) variants. The tools support storing, fetching, listing, and deleting the nodes in dbm databases. (There is a general presumption, however, that the keys and to some extent the data are printable text. These tools are of only limited utility for dbm files containing arbitrary binary data.)

There are five tools: dbmstore, dbmfetch, dbmdump, dbmdelete, and dbmutil. The first four map to the basic dbm operations: store, fetch, first/next (i.e. ``list'' or ``dump'') and delete. dbmutil combines all these functions and adds a few others, and can be used in an interactive mode, or to process scripts of dbm commands.

The tools can be compiled in (at least) three different ways: for the old dbm(3) library, for the related Berkeley ndbm(3) library, and for the GNU gdbm(3) library. In the most general case, the tools when compiled with the dbm library have names beginning with ``dbm'' (as mentioned in the previous paragraph), the tools when compiled with the ndbm library have names beginning with ``ndbm'', and when compiled with the gdbm library have names beginning with ``gdbm''. In practice, however, there is no difference in file formats between the dbm and ndbm libraries, so there is little point in compiling both the ``dbm...'' and ``ndbm...'' sets; the choice will be constrained only by which of the libraries is available. (Furthermore, the gdbm library can emulate the dbm and ndbm libraries at the function call level, but using its own file format underneath, so on systems without a true dbm or ndbm library, but with gdbm and its emulations standing in for both, all three sets of tools will end up using the same file format, and therefore only one of the three is strictly needed.)

Although these tools are, as mentioned, intended for use with dbm files containing plaintext keys and values, there is one consideration if the dbm files are also being accessed by other C programs, namely: do the keys and values as stored in the dbm files contain terminating `\0' characters? They need not have them (because the dbm machinery maintains explicit lengths for both), but storing the \0 characters explicitly makes it easier for a C program to treat a fetched datum as a string. Therefore, these tools can be told to use or not use extra \0 characters at the end of keys and values. By default, extra \0 characters will not be used (that is, will not be appended to keys and values when storing data, and will not be appended to keys when looking up data), but each tool accepts a -n flag instructing it to append \0 (``null'') characters in all of these situations.

(In a few cases, controlled either by command-line flags or conditional compilation options in the source code, the tools can intuit whether or not the extra \0 characters are present, without having to be explicitly told.)

There are also a few provisions made for data values which are not so much text strings, but miniature text files, with trailing and perhaps internal newline characters. There are also a few provisions made for data values (but not keys) which contain arbitrary binary data.

dbm and ndbm databases are stored as a pair of files, with names ending in ``.dir'' and ``.pag''. When naming the dbm file to be accessed by these tools, either suffix is optional. That is, for a dbm database stored in the files ``x.dir'' and ``x.pag'', the file name given to these tools may be either ``x'', ``x.dir'', or ``x.pag''. (What actually happens is that these tools strip off a .dir or .pag suffix, if present, before handing the name to the underlying dbm or ndbm database opening function; the underlying dbm or ndbm code then re-appends the suffixes, as required.) For gdbm databases, on the other hand, only one file is used, with no preordained suffix name, so for the gdbm versions of these tools, the file name handed to the tool much match the actual gdbm file name.

In most cases, the dbm file(s) are created automatically, if required (typically when attempting to store data into a dbm file which does not yet exist).

Here are individual man pages for each of the commands: