Libmu dbm

The library libmu_dbm provides a uniform and consistent interface to various DBM-like database managers. Presently (as of version 2.99.93), the following backend libraries are supported:

• GDBM
• Berkeley DB (BDB)
• Traditional NDBM

Note: The Tokyo Cabinet support was available in previous versions. It is not yet re-implemented via libmu_dbm, although it is possible that it will be.

Header Files and Libraries

The data types and function prototypes of libmu_dbm are declared in mailutils/dbm.h. Internal interfaces, which are of interest for implementors of new backends, are declared in mailutils/sys/dbm.h.

File loader arguments for linking programs with libmu_dbm can be obtained running:

 mu ldflags dbm

Data Types

A database file is represented by the mu_dbm_file_t type. It is an opaque type, declared as

  typedef struct _mu_dbm_file *mu_dbm_file_t;

A datum is a piece of information stored in the database. It is declared as:

  struct mu_dbm_datum
  {
    char *mu_dptr;               /* Data pointer */
    size_t mu_dsize;             /* Data size */
    void *mu_data;               /* Implementation-dependent data */
    struct mu_dbm_impl *mu_sys;  /* Pointer to implementation */
  };

Of all its fields, only mu_dptr and mu_dsize are of interest for application developers. The mu_dptr points to the actual data and mu_dsize keeps the number of bytes pointed to by mu_dptr.

When initializing an object of struct mu_dbm_datum type it is important to fill all the rest of its fields with zeros. The usual initialization sequence is therefore:

  struct mu_dbm_datum key;

  memset (&key, 0, sizeof key);
  key.mu_dptr = data;
  key.mu_dsize = size;

Creating a Database Object

A variable of type mu_dbm_file_t is created using the following functions:

  int mu_dbm_create_from_url (mu_url_t url, mu_dbm_file_t *db);
  int mu_dbm_create (char *name, mu_dbm_file_t *db);

The former function creates a database object from an URL supplied as its first argument. The latter one creates a database object from a file name or a URL in string form. On success both functions store a pointer to the initialized struct _mu_dbm_file in the memory location pointed to by the db parameter and return 0. On error, they return a Mailutils error code and do not touch db.

Safety Checking

The following function verifies whether the database file is safe to use:

  int mu_dbm_safety_check (mu_dbm_file_t db);

It returns 0 if the file is OK, or an error code describing the problem otherwise.

There are two ways to set safety criteria. First, they can be configured using the URL parameters when calling mu_dbm_create_from_url or mu_dbm_create. Second, they can be set using the following functions:

  int mu_dbm_safety_set_flags (mu_dbm_file_t db, int flags);
  int mu_dbm_safety_set_owner (mu_dbm_file_t db, uid_t uid);

The mu_dbm_safety_set_flags functions defines the set of safety criteria for this file. The flags argument has the same meaning as the mode argument to mu_file_safety_check. If it contains the MU_FILE_SAFETY_OWNER_MISMATCH bit, the file owner UID can be set using the mu_dbm_safety_set_owner function.

Whatever way was used to set them, the current safety criteria can be queried using the following two functions:

  int mu_dbm_safety_get_flags (mu_dbm_file_t db, int *flags);
  int mu_dbm_safety_get_owner (mu_dbm_file_t db, uid_t *uid);

Opening a Database

Once a mu_dbm_file_t is created, it can be opened:

  int mu_dbm_open (mu_dbm_file_t db, int flags, int mode);

The function mu_dbm_open opens a database described by db. The flags argument specifies how to open the database. The valid values (declared in mailutils/stream.h) are:

MU_STREAM_READ

Open database for reading only. If the database file does not exist, an error is returned.

MU_STREAM_RDWR

Open database for reading and writing. If the database file does not exist, it is created.

MU_STREAM_CREAT

Create an empty database and open it for reading and writing. If the database file already exists, all existing records will be removed from it.

The mode argument supplies the file mode for newly created files. Its meaning is the same as in chmod(2) call.

Database Lookups

  int mu_dbm_fetch (mu_dbm_file_t db, struct mu_dbm_datum const *key,
		    struct mu_dbm_datum *ret);

The mu_dbm_fetch functions looks up in the database db a record whose key matches key. If such a record is found, its associated data are stored in ret and 0 is returned. If there is no such key in the database, the function returns MU_ERR_NOENT. If an error occurs, it returns MU_ERR_FAILURE. The textual error description can then be obtained using mu_dbm_strerror.

The memory for data returned in ret is allocated by the library. To reclaim this memory, use the mu_dbm_datum_free function. If the ret parameter points to a datum initialized by a previous call to a libmu_dbm function (such as mu_dbm_fetch, mu_dbm_firstkey, etc.) it will be freed automatically. Therefore it is safe not to free existing datum before passing it as a third argument to mu_dbm_fetch.

It is important to notice, however, that the datum pointed to by ret must always be initialized. This means, in practice, that it should either be returned from another libmu_dbm library call or initialized manually. For example:

 1  struct mu_dbm_datum key, content;
 2  int rc;
 3   
 4  /* Initialize search key */
 5  memset (&key, 0, sizeof key);
 6  key.mu_dptr = "user";
 7  key.mu_dsize = 4;
 8  /* Initialize content */
 9  memset (&content, 0, sizeof content);
10  /* Look up the data */
11  rc = mu_dbm_fetch (db, &key, &content);
12  ...
13  /* Find another key: */
14  key.mu_dptr = "hostname";
15  key.mu_dsize = 8;
16  /* It is OK not to re-set content here, because it was initialized
17     by the previous call to mu_dbm_fetch and will be freed automatically. */
18  rc = mu_dbm_fetch (db, &key, &content);
19  ...
20  /* Free the content */
21  mu_dbm_datum_free (&content);

Closing the Database

An open database is closed using:

  int mu_dbm_close (mu_dbm_file_t db);

Unless intended for a subsequent re-opening, a closed database should be destroyed via a call to mu_dbm_destroy:

  void mu_dbm_destroy (mu_dbm_file_t *pdb);

This function reclaims the memory used by the mu_dbm_file_t object pointed to by its argument and initializes it to NULL before returning. Calling mu_dbm_destroy on an open database is OK: the function will call mu_dbm_close prior to freeing the memory. In fact, it is seldom necessary to call mu_dbm_close explicitly. Instead, it suffices to call mu_dbm_destroy once the database is no longer necessary.