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 functions are supplied to verify whether the database file is safe to use:

  int mu_dbm_safety_set_flags (mu_dbm_file_t db, int flags);

Defines the set of safety checks to run on this file. The flags argument has the same meaning as the mode argument to mu_file_safety_check.

The configured safety checks can be queried using the following function:

  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); int mu_dbm_safety_set_owner (mu_dbm_file_t db, uid_t uid); int mu_dbm_safety_check (mu_dbm_file_t db);

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.