Difference between revisions of "Libmu dbm"

From Mailutils
Jump to navigationJump to search
(Created page with "{{DISPLAYTITLE:libmu_dbm}} FIXME")
 
Line 1: Line 1:
 
{{DISPLAYTITLE:libmu_dbm}}
 
{{DISPLAYTITLE:libmu_dbm}}
FIXME
+
 
 +
The library <tt>libmu_dbm</tt> provides a uniform and consistent interface to various <tt>DBM</tt>-like database managers.  Presently (as of version 2.99.93), the following backend libraries are supported:
 +
 
 +
* [http://www.gnu.org/software/gdbm GDBM]
 +
* [http://www.oracle.com/technetwork/database/berkeleydb/overview/index.html Berkeley DB] (BDB)
 +
* Traditional [http://en.wikipedia.org/wiki/Ndbm NDBM]
 +
 
 +
{{Note|The [http://fallabs.com/tokyocabinet/ Tokyo Cabinet] support was available in previous versions.  It is not yet re-implemented via <tt>libmu_dbm</tt>, although it is possible that it will be.}}
 +
 
 +
== Header Files and Libraries ==
 +
 
 +
The data types and function prototypes of <tt>libmu_dbm</tt> are declared in <tt>mailutils/dbm.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/dbm.h</ref>.  Internal interfaces, which are of interest for implementors of new backends, are declared in <tt>mailutils/sys/dbm.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/sys/dbm.h</ref>.
 +
 
 +
File loader arguments for linking programs with <tt>libmu_dbm</tt> can be obtained running:
 +
 
 +
  mu ldflags dbm
 +
 
 +
== Data Types ==
 +
 
 +
A ''database file'' is represented by the <tt>mu_dbm_file_t</tt> type.  It is an opaque type, declared as
 +
 
 +
<source lang="C">
 +
  typedef struct _mu_dbm_file *mu_dbm_file_t;
 +
</source>
 +
 
 +
A ''datum'' is a piece of information stored in the database.  It is declared as:
 +
 
 +
<source lang="C">
 +
  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 */
 +
  };
 +
</source>
 +
 
 +
Of all its fields, only <tt>mu_dptr</tt> and <tt>mu_dsize</tt> are of interest for application developers.  The <tt>mu_dptr</tt> points to the actual data and <tt>mu_dsize</tt> keeps the number of bytes pointed to by <tt>mu_dptr</tt>.
 +
 
 +
When initializing an object of <tt>struct mu_dbm_datum</tt> type it is important to fill all the rest of its fields with zeros.  The usual initialization sequence is therefore:
 +
 
 +
<source lang="C">
 +
  struct mu_dbm_datum key;
 +
 
 +
  memset (&key, 0, sizeof key);
 +
  key.mu_dptr = data;
 +
  key.mu_dsize = size;
 +
</source>
 +
 
 +
== Creating a Database Object ==
 +
 
 +
A variable of type <tt>mu_dbm_file_t</tt> is created using the following functions:
 +
 
 +
<source lang="C">
 +
  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);
 +
</source>
 +
 
 +
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 [[Database URL|URL]] in string form.  On success both functions store a pointer to the initialized <tt>struct _mu_dbm_file</tt> in the memory location pointed to by the '''db''' parameter and return 0.  On error, they return a [[Error Code|Mailutils error code]] and do not touch '''db'''.
 +
 
 +
== Safety Checking ==
 +
 
 +
The following functions are supplied to verify whether the database file is [[File Safety|safe to use]]:
 +
 
 +
<source lang="C">
 +
  int mu_dbm_safety_set_flags (mu_dbm_file_t db, int flags);
 +
</source>
 +
 
 +
Defines the set of safety checks to run on this file.  The '''flags''' argument
 +
has the same meaning as the [[File_Safety_Functions#MU_FILE_SAFETY|'''mode''']] argument to
 +
[[mu_file_safety_check]].
 +
 
 +
The configured safety checks can be queried using the following function:
 +
 
 +
<source lang="C">
 +
  int mu_dbm_safety_get_flags (mu_dbm_file_t db, int *flags);
 +
</source>
 +
 
 +
 
 +
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 <tt>mu_dbm_file_t</tt> is created, it can be opened:
 +
 
 +
<source lang="C">
 +
  int mu_dbm_open (mu_dbm_file_t db, int flags, int mode);
 +
</source>
 +
 
 +
The function <tt>mu_dbm_open</tt> opens a database described by '''db'''.  The '''flags''' argument specifies how to open the database.  The valid values (declared in <tt>mailutils/stream.h</tt><ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/stream.h</ref) 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 [http://www.manpagez.com/man/2/chmod/ chmod(2)] call.
 +
 
 +
==Notes==
 +
<references/>
 +
 
 +
[[Category:DBM]]
 +
[[Category:C API]]
 +
[[Category:LIbraries]]

Revision as of 18:10, 26 October 2011


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:

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[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<ref>http://git.gnu.org.ua/cgit/mailutils.git/tree/include/mailutils/stream.h</ref) 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.

Notes