Doc/lib/libdbm.tex

   1 \section{\module{dbm} ---
   2          Simple ``database'' interface}
   3
   4 \declaremodule{builtin}{dbm}
   5   \platform{Unix}
   6 \modulesynopsis{The standard ``database'' interface, based on ndbm.}
   7
   8
   9 The \module{dbm} module provides an interface to the \UNIX{}
  10 (\code{n})\code{dbm} library.  Dbm objects behave like mappings
  11 (dictionaries), except that keys and values are always strings.
  12 Printing a dbm object doesn't print the keys and values, and the
  13 \method{items()} and \method{values()} methods are not supported.
  14
  15 This module can be used with the ``classic'' ndbm interface, the BSD
  16 DB compatibility interface, or the GNU GDBM compatibility interface.
  17 On \UNIX, the \program{configure} script will attempt to locate the
  18 appropriate header file to simplify building this module.
  19
  20 The module defines the following:
  21
  22 \begin{excdesc}{error}
  23 Raised on dbm-specific errors, such as I/O errors.
  24 \exception{KeyError} is raised for general mapping errors like
  25 specifying an incorrect key.
  26 \end{excdesc}
  27
  28 \begin{datadesc}{library}
  29 Name of the \code{ndbm} implementation library used.
  30 \end{datadesc}
  31
  32 \begin{funcdesc}{open}{filename\optional{, flag\optional{, mode}}}
  33 Open a dbm database and return a dbm object.  The \var{filename}
  34 argument is the name of the database file (without the \file{.dir} or
  35 \file{.pag} extensions; note that the BSD DB implementation of the
  36 interface will append the extension \file{.db} and only create one
  37 file).
  38
  39 The optional \var{flag} argument must be one of these values:
  40
  41 \begin{tableii}{c|l}{code}{Value}{Meaning}
  42   \lineii{'r'}{Open existing database for reading only (default)}
  43   \lineii{'w'}{Open existing database for reading and writing}
  44   \lineii{'c'}{Open database for reading and writing, creating it if
  45                it doesn't exist}
  46   \lineii{'n'}{Always create a new, empty database, open for reading
  47                and writing}
  48 \end{tableii}
  49
  50 The optional \var{mode} argument is the \UNIX{} mode of the file, used
  51 only when the database has to be created.  It defaults to octal
  52 \code{0666}.
  53 \end{funcdesc}
  54
  55
  56 \begin{seealso}
  57   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  58   \seemodule{gdbm}{Similar interface to the GNU GDBM library.}
  59   \seemodule{whichdb}{Utility module used to determine the type of an
  60                       existing database.}
  61 \end{seealso}