DBMUTIL(1)

NAME

dbmutil - perform arbitrary operations on a dbm file

SYNOPSIS

dbmutil [ options ] [ dbmfile [ command ] ]

DESCRIPTION

dbmutil performs arbitrary operations on a dbm file, subsuming the functionality of dbmstore, dbmfetch, dbmdump, and dbmdelete, and adding a few operations of its own.

The dbmfile parameter, if present, indicates a dbm file to be opened for processing. Otherwise, no dbm file is initially open, and the open command must be used before further operations can proceed.

If a command is mentioned on the command line, that command is performed immediately, and dbmutil exits. (The command can be any of the ones listed below.) Otherwise, dbmutil enters an interactive mode, accepting and executing multiple commands in succession.

There are several option flags accepted on dbmutil's invocation command line. (In addition, a few of its subcommands accept option flags of their own, as listed below). The overall dbmutil option flags are:

-c
Create dbm files if necessary.
-fast
(gdbmutil only) Use gdbm ``fast'' mode (default).
-i
Force interactive mode even if standard input is not a terminal.
-n
Append null (`\0') characters to all keys and values.
-nl
Newline mode: when creating nodes, append newlines to values that don't end with them, but when printing them, don't print an extra newline.
-nolock
(gdbmutil only) Use gdbm ``nolock'' mode.
-r
Open the database in read-only mode, thus preventing any operations (store, delete) which would modify it.
-sync
(gdbmutil only) Use gdbm ``sync'' mode.
-v
Verbose: print extra messages after (most) operations, explicitly recording actions and affected nodes.
-version
Print program's version number.
-?, -h
Print a brief usage summary / help message.

The available commands within dbmutil are as follows:

open
Open a dbm file. (The dbm file name is prompted for if interactive, or can be given directly on the command line.)
close
Close the currently-open dbm file.
fetch
Fetch (and print) a node from the open database. The key to be fetched is prompted for (if interactive), or may be entered on the command line.
There is one option flag: -x indicates that data values should be printed as hexadecimal strings.
store
Store a new value in the database. Both key and value are prompted for (if interactive), or can be entered on the command line:
	store key value
There are two option flags. -i indicates that an insert-only operation should performed, without replacing any existing datum under the same key. (This is the same function as performed by the insert command, below.) -x indicates that binary data values are being input as hexadecimal strings.
insert
Like store (and exactly like store -i): store a new key and value, but consider it an error (and do not replace) if a data node already exists under the given key.
replace
Like store, but consider it an error if the given key does not already exist.
enter
Like store, but the program waits for a multi-line data value to be entered, terminated by a `.' alone on a line. (Note: when fetching such values using fetch, you will probably want to have invoked dbmutil with the -nl option.)
first
(gdbmutil only) Print the first key in the first/next traversal order.
next
(gdbmutil only) Given a key, print the key that succeeds it in the first/next traversal order.
list
List all the keys in the database (in arbitrary order).
dump
Dump all the keys and values in the database, one per line, separated by tabs (but otherwise in an arbitrary order).
delete
Delete a node. The key of the node to be deleted is prompted for (if interactive), or can be entered on the command line.
exists
Determine (without necessarily fetching it) whether a given key exists.
read
Read a file (that is, an ordinary file in the filesystem) into a database node under a given key. The key and filename are prompted for (if interactive), or may be entered on the command line:
	read key file
write
Write a key's value out to a file in the filesystem. The key and filename are prompted for (if interactive), or may be entered on the command line:
	write key file
edit
Fetch a key's value to a temporary file in the filesystem, invoke the user's choice of $EDITOR on it, and store the edited text back into the database. The key is prompted for (if interactive), or may be entered on the command line:
	edit key
reorganize
(gdbmutil only) Rearrange the database file to reclaim internal space lost due to deletions.
sync
(gdbmutil only) Ensure that the database is synchronized with the underlying gdbm file.
quit
Quit dbmutil (same as exit).
exit
Exit dbmutil (same as quit).
version
Print the program's version number.
help
Print the list of available subcommands.

BUGS

If the gdbm emulation of the dbm or ndbm libraries is used, and if dbmutil is used without its -c option to access a dbm file which does not exist, the .dir and .pag files are created anyway, but with mode 000 (i.e. unreadable and unwritable).

HISTORY

This documentation corresponds to version 2.3 of the dbmtools package.

See http://www.eskimo.com/~scs/src/#dbmtools for possible updates.

SEE ALSO

dbmstore, dbmfetch, dbmdump, dbmdelete
dbm(3), ndbm(3), gdbm(3)

AUTHOR

Steve Summit, scs@eskimo.com