libmu_dbm

From Mailutils

(Difference between revisions)
Jump to: navigation, 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.

Contents

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]


Cite error: <ref> tags exist, but no <references/> tag was found
Personal tools