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.

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.