| \section{\module{gdbm} --- |
| GNU's reinterpretation of dbm} |
| |
| \declaremodule{builtin}{gdbm} |
| \platform{Unix} |
| \modulesynopsis{GNU's reinterpretation of dbm.} |
| |
| |
| % Note that if this section appears on the same page as the first |
| % paragraph of the dbm module section, makeindex will produce the |
| % warning: |
| % |
| % ## Warning (input = lib.idx, line = 1184; output = lib.ind, line = 852): |
| % -- Conflicting entries: multiple encaps for the same page under same key. |
| % |
| % This is because the \bimodindex{gdbm} and \refbimodindex{gdbm} |
| % entries in the .idx file are slightly different (the \bimodindex{} |
| % version includes "|textbf" at the end to make the defining occurance |
| % bold). There doesn't appear to be anything that can be done about |
| % this; it's just a little annoying. The warning can be ignored, but |
| % the index produced uses the non-bold version. |
| |
| This module is quite similar to the \module{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). |
| |
| Appending \character{f} to the flag opens the database in fast mode; |
| altered data will not automatically be written to the disk after every |
| change. This results in faster writes to the database, but may result |
| in an inconsistent database if the program crashes while the database |
| is still open. Use the \method{sync()} method to force any unwritten |
| data to be written to the disk. |
| |
| 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} |
| |