Doc/lib/libgdbm.tex

   1 \section{\module{gdbm} ---
   2          GNU's reinterpretation of dbm}
   3
   4 \declaremodule{builtin}{gdbm}
   5   \platform{Unix}
   6 \modulesynopsis{GNU's reinterpretation of dbm.}
   7
   8
   9 This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm}
  10 module, but uses \code{gdbm} instead to provide some additional
  11 functionality.  Please note that the file formats created by
  12 \code{gdbm} and \code{dbm} are incompatible.
  13
  14 The \module{gdbm} module provides an interface to the GNU DBM
  15 library.  \code{gdbm} objects behave like mappings
  16 (dictionaries), except that keys and values are always strings.
  17 Printing a \code{gdbm} object doesn't print the keys and values, and
  18 the \method{items()} and \method{values()} methods are not supported.
  19
  20 The module defines the following constant and functions:
  21
  22 \begin{excdesc}{error}
  23 Raised on \code{gdbm}-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{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
  29 Open a \code{gdbm} database and return a \code{gdbm} object.  The
  30 \var{filename} argument is the name of the database file.
  31
  32 The optional \var{flag} argument can be
  33 \code{'r'} (to open an existing database for reading only --- default),
  34 \code{'w'} (to open an existing database for reading and writing),
  35 \code{'c'} (which creates the database if it doesn't exist), or
  36 \code{'n'} (which always creates a new empty database).
  37
  38 The following additional characters may be appended to the flag to
  39 control how the database is opened:
  40
  41 \begin{itemize}
  42 \item \code{'f'} --- Open the database in fast mode.  Writes to the database
  43                      will not be syncronized.
  44 \item \code{'s'} --- Synchronized mode. This will cause changes to the database
  45                      will be immediately written to the file.
  46 \item \code{'u'} --- Do not lock database.
  47 \end{itemize}
  48
  49 Not all flags are valid for all versions of \code{gdbm}.  The
  50 module constant \code{open_flags} is a string of supported flag
  51 characters.  The exception \exception{error} is raised if an invalid
  52 flag is specified.
  53
  54 The optional \var{mode} argument is the \UNIX{} mode of the file, used
  55 only when the database has to be created.  It defaults to octal
  56 \code{0666}.
  57 \end{funcdesc}
  58
  59 In addition to the dictionary-like methods, \code{gdbm} objects have the
  60 following methods:
  61
  62 \begin{funcdesc}{firstkey}{}
  63 It's possible to loop over every key in the database using this method
  64 and the \method{nextkey()} method.  The traversal is ordered by
  65 \code{gdbm}'s internal hash values, and won't be sorted by the key
  66 values.  This method returns the starting key.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{nextkey}{key}
  70 Returns the key that follows \var{key} in the traversal.  The
  71 following code prints every key in the database \code{db}, without
  72 having to create a list in memory that contains them all:
  73
  74 \begin{verbatim}
  75 k = db.firstkey()
  76 while k != None:
  77     print k
  78     k = db.nextkey(k)
  79 \end{verbatim}
  80 \end{funcdesc}
  81
  82 \begin{funcdesc}{reorganize}{}
  83 If you have carried out a lot of deletions and would like to shrink
  84 the space used by the \code{gdbm} file, this routine will reorganize
  85 the database.  \code{gdbm} will not shorten the length of a database
  86 file except by using this reorganization; otherwise, deleted file
  87 space will be kept and reused as new (key, value) pairs are added.
  88 \end{funcdesc}
  89
  90 \begin{funcdesc}{sync}{}
  91 When the database has been opened in fast mode, this method forces any
  92 unwritten data to be written to the disk.
  93 \end{funcdesc}
  94
  95
  96 \begin{seealso}
  97   \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  98   \seemodule{whichdb}{Utility module used to determine the type of an
  99                       existing database.}
 100 \end{seealso}