Mailutils dbm

The mailutils dbm tool manages DBM files using libmu_dbm. The invocation syntax is:

 mailutils dbm command [options] file [keys]

or

 mailutils dbm [options] command file [keys]

where command selects the operation mode, options modify the tool behavior and file specifies the DBM file to operate upon. Some commands allow for optional keys to be specified.

The file argument can be either a DBM file name or a Database URL.

Create a Database

The create command and its synonym load instruct the tool to create a new database:

 mailutils dbm create file.db

If the argument file already exists, it will be truncated prior to adding new records to it.

The data to populate the database with are read from the standard input. The dbm tool supports several formats for these data, which are discussed later. In the simplest case (a so called format 0.0) each input line must consist of two fields separated by any amount of whitespace. The first field is treated as a key and the second one as the corresponding value.

The usual way to read data from a file is, of course, by redirecting the file to the standard input as in:

 mailutils dbm create file.db < input.txt

There is also a special option for that purpose: --file (-f). Thus, the following command is equivalent to the one above:

 mailutils dbm create --file input.txt file.db 

The --file option has the advantage that it allows, in conjunction with another options, for copying input file metadata (owner UID, GID and file mode) to the created database. For example, the following command ensures that the created database file will have the same metadata as the input file:

 mailutils dbm create --file input.txt --copy-permissions file.db

The --copy-permissions (-P) option is the one that does the job.

There are also other ways to control mode and ownership of the created database, which are described below.

More advanced dump formats (e.g. 1.0) carry additional information about the file, including its original name, ownership and mode. If input is in one of these formats, the file name argument becomes optional. If it is not supplied, the name stored in the input stream will be used. For example, supposing that the file users.dump is in format 1.0, the following command suffices to restore the original filename, ownership, mode and, of course, data:

 mailutils dbm create --file users.dump

Add Records to a Database

The add command adds records to a database. Records are read from the standard input and must be formatted as for create command.

 mailutils dbm add file.db

If the argument file does not exist, it will be created.

Adding a record with a key which is already present in the database produces an error. To replace existing records, use the replace command instead.

The same options that affect the behavior of create apply to add and replace as well, e.g.:

 mailutils dbm replace --file input.txt --copy-permissions file.db

Delete Records

To delete records, use the delete command. It reads a list of keys to delete to be specified as arguments in the command line:

 mailutils dbm delete file.db foo bar

The command above will delete from file.db records with keys foo and bar.

It is not an error to attempt to delete a key that does not exist in the database, although such use will produce a warning message.

By default, keys are matched literally. It is also possible to use various pattern matching techniques, depending on the option specified.

The --glob (-G) option instructs the tool to use UNIX globbing pattern matching. For example, the command below will delete all keys starting with foo and ending with a decimal digit:

 mailutils dbm delete file.db 'foo*[0-9]'

(note the quoting necessary to prevent shell from interpreting the metacharacters itself).

Another option, --regex (-R) instructs mailutils to treat keys as extended regular expressions:

 mailutils dbm delete --regex file.db 'foo.*[0-9]{1,3}'

Both options are affected by the --ignore-case (-i) option, which turns on case-insensitive matching.

Using pattern matching to delete records can be a risky operation as selecting a wrong pattern will lead to removing wrong records. It is recommended to first use the list mode described below to verify that the patterns match the right keys.

List the Database

The list command lists the content of the database:

 mailutils dbm list file.db

By default, entire content is listed on the standard output in format 0.0.

If supplied more than one command line argument, this mode treats the rest of arguments after the database file name as the keys to look for and lists only records with these keys:

 $ mailutils dbm list file.db foo bar
 foo 1
 bar 56

The --glob and --regex options instruct the tool to use UNIX globbing or extended regular expression matching, correspondingly. These are described in detail above.

Dump the Database

The dump subcommand dumps the database to the standard output in a format suitable for backup or sending over the network (a version 1.0 format).

 mailutils dbm dump file.db > file.dump

The produced file is suitable for input to the create (load) command. Among other uses, this provides for an easy way to convert databases between various formats supported by Mailutils. For example this is how to convert the database file file.db to the GDBM database new.db:

 mailutils dbm dump file.db | mailutils dbm create gdbm://new.db

Both list and dump subcommands share the same set of options. In fact, they are pretty similar, except that use different defaults. The list subcommand is oriented to produce a human-readable output, whereas the dump subcommand is oriented towards backup purposes.

Dump Formats

As of version 2.99.99, mailutils dbm supports three formats for dumping DBM databases. All three are line-oriented. Comments are introduced with a sharp (#) sign in the column 0 of a line, followed by at least one white space character (space or tab). Sharp sign followed by a colon (#:) introduces a pragmatic comment, which carries some additional information to the loader.

The version 0.0 format is suitable for databases whose records contain only ASCII data. In this format, each record occupies a separate line, which consists of the key and value separated by one or more whitespace characters. Empty lines are ignored. For example:

 $ mailutils dbm list /etc/mail/users.db
 root    guessme
 smith   pAssword
 qed     fooBar

Output in version 0.0 format is human readable and can be used as input to the popauth utility. However, version 0.0 has serious drawbacks. First of all, it is not suitable for databases that contain binary data. Secondly, it cannot properly handle keys beginning with a sharp sign or containing whitespace characters. The version 1.0 format is free from these drawbacks.

The version 1.0 format begins with a header containing important information about the file, such as its file name, ownership and file mode. This information is stored in pragmatic comments and allows mailutils dbm load to easily recreate an exact copy of the file. The following comments are defined:

#:version=1.0

Indicates that the data that follow are in version 1.0 format.

#:filename=s

Original database file name, without directory parts.

#:uid=n

Owner UID.

#:user=s

Owner name.

#:gid=n

Owner GID

#:group=s

Owner group name.

#:mode=o

File mode in octal

Following this header are actual data. Each record is output in two parts: key and value. Each part begins with a #:len=n construct on a line by itself, where n is the length of the data in decimal. This line is followed by one or more lines of the actual data, encoded in base64. The data are formatted so that each line does not exceed 76 bytes in length (not counting the terminating newline). An example of this format follows:

# Database dump file created by GNU Mailutils 2.99.93 on Tue Nov  1 13:28:03 2011
#:version=1.0
#:file=users.db
#:uid=0,user=root,gid=25,group=mail,mode=640
#:len=6
c21pdGgA
#:len=9
cEFzc3dvcmQA
#:len=5
cm9vdAA=
#:len=8
Z3Vlc3NtZQA=
#:len=4
cWVkAA==
#:len=7
Zm9vQmFyAA==

The third format called C is designed to allow programmers to create input data for mailutils load using conventional means. This format represents both key and content as C strings (hence its name), with usual C (literal and octal) escapes to represent non-printable characters. Records are separated with a single newline character.

An example dump in this format follows:

# Database dump file created by GNU Mailutils 2.99.95 on Sun Nov 27 02:12:13 2011
#:version=C
#:file=users.db
#:uid=1000,user=gray,gid=100,group=users,mode=600
smith\000
pAssword\000

root\000
guessme\000

qed\000
fooBar\000

Exit Codes

The table below summarizes exit codes used by mailutils dbm:

Code	Symbolic name	Meaning
0	EX_OK	Successful termination
64	EX_USAGE	Command line usage error
65	EX_DATAERR	Error in user-supplied data: the input file is badly formatted, or some of the data supplied in the command line are invalid (e.g. user name, uid or the like), etc.
66	EX_NOINPUT	Cannot open input file
67	EX_NOUSER	No such user or UID when trying to set output file ownership
69	EX_UNAVAILABLE	Operation cannot be performed due to some kind of problem (e.g. access to the file denied, etc.)
70	EX_SOFTWARE	Internal software error
74	EX_IOERR	Input/output error

See also

• mailutils (utility)