libgdbm.tex 3.68 KB
Newer Older
Fred Drake's avatar
Fred Drake committed
1
\section{\module{gdbm} ---
2
         GNU's reinterpretation of dbm}
3

4
\declaremodule{builtin}{gdbm}
5
  \platform{Unix}
6 7
\modulesynopsis{GNU's reinterpretation of dbm.}

Guido van Rossum's avatar
Guido van Rossum committed
8

9
This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm}
10 11 12
module, but uses \code{gdbm} instead to provide some additional
functionality.  Please note that the file formats created by
\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 18
Printing a \code{gdbm} object doesn't print the keys and values, and
the \method{items()} and \method{values()} methods are not supported.
19 20 21 22

The module defines the following constant and functions:

\begin{excdesc}{error}
23 24 25
Raised on \code{gdbm}-specific errors, such as I/O errors.
\exception{KeyError} is raised for general mapping errors like
specifying an incorrect key.
26 27
\end{excdesc}

28
\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
29 30
Open a \code{gdbm} database and return a \code{gdbm} object.  The
\var{filename} argument is the name of the database file.
31 32 33 34 35 36 37

The optional \var{flag} argument can be
\code{'r'} (to open an existing database for reading only --- default),
\code{'w'} (to open an existing database for reading and writing),
\code{'c'} (which creates the database if it doesn't exist), or
\code{'n'} (which always creates a new empty database).

38 39 40 41 42
The following additional characters may be appended to the flag to
control how the database is opened:

\begin{itemize}
\item \code{'f'} --- Open the database in fast mode.  Writes to the database
43
                     will not be synchronized.
44 45 46 47 48 49 50 51 52
\item \code{'s'} --- Synchronized mode. This will cause changes to the database
                     will be immediately written to the file.
\item \code{'u'} --- Do not lock database. 
\end{itemize}

Not all flags are valid for all versions of \code{gdbm}.  The
module constant \code{open_flags} is a string of supported flag
characters.  The exception \exception{error} is raised if an invalid
flag is specified.
53 54 55 56 57 58

The optional \var{mode} argument is the \UNIX{} mode of the file, used
only when the database has to be created.  It defaults to octal
\code{0666}.
\end{funcdesc}

59
In addition to the dictionary-like methods, \code{gdbm} objects have the
60 61 62
following methods:

\begin{funcdesc}{firstkey}{}
63 64 65 66
It's possible to loop over every key in the database using this method 
and the \method{nextkey()} method.  The traversal is ordered by
\code{gdbm}'s internal hash values, and won't be sorted by the key
values.  This method returns the starting key.
67 68 69 70
\end{funcdesc}

\begin{funcdesc}{nextkey}{key}
Returns the key that follows \var{key} in the traversal.  The
71 72 73
following code prints every key in the database \code{db}, without
having to create a list in memory that contains them all:

74
\begin{verbatim}
75 76
k = db.firstkey()
while k != None:
77
    print k
78
    k = db.nextkey(k)
79
\end{verbatim}
80 81 82 83
\end{funcdesc}

\begin{funcdesc}{reorganize}{}
If you have carried out a lot of deletions and would like to shrink
84 85 86 87
the space used by the \code{gdbm} file, this routine will reorganize
the database.  \code{gdbm} will not shorten the length of a database
file except by using this reorganization; otherwise, deleted file
space will be kept and reused as new (key, value) pairs are added.
88 89 90
\end{funcdesc}

\begin{funcdesc}{sync}{}
91
When the database has been opened in fast mode, this method forces any 
92 93 94
unwritten data to be written to the disk.
\end{funcdesc}

95 96 97 98 99 100

\begin{seealso}
  \seemodule{anydbm}{Generic interface to \code{dbm}-style databases.}
  \seemodule{whichdb}{Utility module used to determine the type of an
                      existing database.}
\end{seealso}