101 lines
3.7 KiB
TeX
101 lines
3.7 KiB
TeX
\section{\module{gdbm} ---
|
|
GNU's reinterpretation of dbm}
|
|
|
|
\declaremodule{builtin}{gdbm}
|
|
\platform{Unix}
|
|
\modulesynopsis{GNU's reinterpretation of dbm.}
|
|
|
|
|
|
This module is quite similar to the \refmodule{dbm}\refbimodindex{dbm}
|
|
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.
|
|
|
|
The \module{gdbm} module provides an interface to the GNU DBM
|
|
library. \code{gdbm} objects behave like mappings
|
|
(dictionaries), except that keys and values are always strings.
|
|
Printing a \code{gdbm} object doesn't print the keys and values, and
|
|
the \method{items()} and \method{values()} methods are not supported.
|
|
|
|
The module defines the following constant and functions:
|
|
|
|
\begin{excdesc}{error}
|
|
Raised on \code{gdbm}-specific errors, such as I/O errors.
|
|
\exception{KeyError} is raised for general mapping errors like
|
|
specifying an incorrect key.
|
|
\end{excdesc}
|
|
|
|
\begin{funcdesc}{open}{filename, \optional{flag, \optional{mode}}}
|
|
Open a \code{gdbm} database and return a \code{gdbm} object. The
|
|
\var{filename} argument is the name of the database file.
|
|
|
|
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).
|
|
|
|
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
|
|
will not be syncronized.
|
|
\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.
|
|
|
|
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}
|
|
|
|
In addition to the dictionary-like methods, \code{gdbm} objects have the
|
|
following methods:
|
|
|
|
\begin{funcdesc}{firstkey}{}
|
|
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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nextkey}{key}
|
|
Returns the key that follows \var{key} in the traversal. The
|
|
following code prints every key in the database \code{db}, without
|
|
having to create a list in memory that contains them all:
|
|
|
|
\begin{verbatim}
|
|
k = db.firstkey()
|
|
while k != None:
|
|
print k
|
|
k = db.nextkey(k)
|
|
\end{verbatim}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{reorganize}{}
|
|
If you have carried out a lot of deletions and would like to shrink
|
|
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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{sync}{}
|
|
When the database has been opened in fast mode, this method forces any
|
|
unwritten data to be written to the disk.
|
|
\end{funcdesc}
|
|
|
|
|
|
\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}
|