libmu_dbm

From Mailutils

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

Header Files and Libraries

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

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^[3]