{
    "mode": "info",
    "parameter": "gdbm",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/gdbm/json",
    "generated": "2026-06-15T13:43:43Z",
    "sections": {
        "The GNU database manager": {
            "content": "GNU 'dbm' ('GDBM') is a library of functions implementing a hashed\ndatabase on a disk file.  This manual documents GNU 'dbm' Version 1.23.\nThe software was originally written by Philip A. Nelson.  This document\nwas originally written by Pierre Gaumond from texts written by Phil.\n\n* Menu:\n\n* Copying::                    Your rights.\n* Intro::                      Introduction to GNU dbm.\n\nFunctions:\n\n* Open::                       Opening the database.\n* Close::                      Closing the database.\n* Count::                      Counting records in the database.\n* Store::                      Inserting and replacing records in the database.\n* Fetch::                      Searching records in the database.\n* Delete::                     Removing records from the database.\n* Sequential::                 Sequential access to records.\n* Reorganization::             Database reorganization.\n* Sync::                       Insure all writes to disk have competed.\n* Database format::            GDBM database formats.\n* Flat files::                 Export and import to Flat file format.\n* Errors::                     Error handling.\n* Database consistency::       Structural and logical consistency.\n* Recovery::                   Recovery from fatal errors.\n* Crash Tolerance::            Ensuring recovery to a consistent state.\n* Options::                    Setting internal options.\n* Locking::                    File locking.\n* Variables::                  Useful global variables.\n* Additional functions::       Functions for verifying internal structures.\n* Error codes::                Error codes returned by GDBM calls.\n* Compatibility::              Compatibility with UNIX dbm and ndbm.\n\nPrograms\n\n* gdbmtool::                   Examine and modify a GDBM database.\n* gdbmdump::                  Dump the database into a flat file.\n* gdbmload::                  Load the database from a flat file.\n* Exit codes::                 Exit codes returned by GDBM utilities.\n\nOther topics:\n\n* Bugs::                       Problems and bugs.\n* Resources::                  Additional resources,\n\n* GNU Free Documentation License::      Document license.\n* Index::                       Index\n\n-- The Detailed Node Listing --\n\nCompatibility with standard 'dbm' and 'ndbm'\n\n* ndbm::  NDBM interface functions.\n* dbm::   DBM interface functions.\n\nExamine and modify a GDBM database\n\n* invocation::\n* shell::\n\ngdbmtool interactive mode\n\n* variables::      shell variables.\n* commands::       shell commands.\n* definitions::    how to define structured data.\n* startup files::\n\n\nFile: gdbm.info,  Node: Copying,  Next: Intro,  Prev: Top,  Up: Top\n",
            "subsections": []
        },
        "1 Copying Conditions": {
            "content": "This library is \"free\"; this means that everyone is free to use it and\nfree to redistribute it on a free basis.  GNU 'dbm' ('GDBM') is not in\nthe public domain; it is copyrighted and there are restrictions on its\ndistribution, but these restrictions are designed to permit everything\nthat a good cooperating citizen would want to do.  What is not allowed\nis to try to prevent others from further sharing any version of 'GDBM'\nthat they might get from you.\n\nSpecifically, we want to make sure that you have the right to give\naway copies of 'GDBM', that you receive source code or else can get it\nif you want it, that you can change these functions or use pieces of\nthem in new free programs, and that you know you can do these things.\n\nTo make sure that everyone has such rights, we have to forbid you to\ndeprive anyone else of these rights.  For example, if you distribute\ncopies of 'GDBM', you must give the recipients all the rights that you\nhave.  You must make sure that they, too, receive or can get the source\ncode.  And you must tell them their rights.\n\nAlso, for our own protection, we must make certain that everyone\nfinds out that there is no warranty for anything in the 'GDBM'\ndistribution.  If these functions are modified by someone else and\npassed on, we want their recipients to know that what they have is not\nwhat we distributed, so that any problems introduced by others will not\nreflect on our reputation.\n\n'GDBM' is currently distributed under the terms of the GNU General\nPublic License, Version 3.  (NOT under the GNU General Library Public\nLicense.)  A copy the GNU General Public License is included with the\ndistribution of 'GDBM'.\n\nFile: gdbm.info,  Node: Intro,  Next: Open,  Prev: Copying,  Up: Top\n",
            "subsections": []
        },
        "2 Introduction to GNU 'dbm'": {
            "content": "GNU 'dbm' ('GDBM') is a library of database functions that use\nextensible hashing and work similar to the standard UNIX 'dbm'\nfunctions.  These routines are provided to a programmer needing to\ncreate and manipulate a hashed database.  ('GDBM' is NOT a complete\ndatabase package for an end user.)\n\nThe basic use of 'GDBM' is to store key/data pairs in a data file.\nEach key must be unique and each key is paired with only one data item.\nThe keys can not be directly accessed in sorted order.  The basic unit\nof data in 'GDBM' is the structure:\n\ntypedef struct\n{\nchar *dptr;\nint  dsize;\n} datum;\n\nThis structure allows for arbitrary sized keys and data items.  In\nparticular, zero-length keys or data ('dsize = 0') are allowed.\nHowever, the 'dptr' field is required to point to a valid memory\nlocation.  In other words, 'dptr' cannot be NULL. Note also that its\ntype is 'char *' for purely historic reasons.  You can use any C data\ntype (either scalar or aggregate) both as for key and for data.\n\nThe key/data pairs are stored in a 'GDBM' disk file, called a \"gdbm\ndatabase\".  An application must open a 'GDBM' database to be able\nmanipulate the keys and data contained in it.  'GDBM' allows an\napplication to have multiple databases open at the same time.  When an\napplication opens a 'GDBM' database, it is designated as a 'reader' or a\n'writer'.  A 'GDBM' database can be opened by at most one writer at a\ntime.  However, many readers may open the database simultaneously.\nReaders and writers can not open the 'GDBM' database at the same time.\n\nSpeaking about \"application\" we usually mean a separate process.\nHowever, it is entirely normal for a multi-thread program to operate as\na 'GDBM' reader in one thread and writer in another, provided, of\ncourse, that the two threads don't operate on the same database\nsimultaneously.\n\nTo use the 'GDBM' functions, the programmer must first include the\nheader file 'gdbm.h'.\n\nThis file defines, among others, the 'GDBMFILE' data type, an opaque\npointer to the structure that represents the opened 'GDBM' database.  To\naccess the database, the programmer must first open it using the\n'gdbmopen' function.  The function takes several arguments, the name of\nthe database file being one of them, and returns a 'GDBMFILE' object on\nsuccess.  This object is then passed to other functions in order to\nmanipulate the database.  When the database is no longer needed, the\nprogrammer \"closes\" it using the 'gdbmclose' call.\n\nThese and other functions are discussed in detail in chapters that\nfollow.  Here we show an example illustrating the use of 'GDBM' to look\nup a key in the database.\n\n#include <stdio.h>\n#include <string.h>\n#include <gdbm.h>\n\nint\nmain (int argc, char argv)\n{\nGDBMFILE gdbf;     /* Database file object pointer */\ndatum key, content; /* Key and content data */\nint status = 0;     /* Exit status of the program: 0 - OK, 1 - key\nnot found, 2 - error. */\n\n/*\n* Validate arguments.\n*/\nif (argc != 3)\n{\nfprintf (stderr, \"usage: %s DBFILE KEY\\n\", argv[0]);\nreturn 2;\n}\n\n/*\n* Open the database.  The GDBMREADER flag indicates that we only\n* intend to read from it.\n*/\ngdbf = gdbmopen (argv[1], 0, GDBMREADER, 0, NULL);\nif (gdbf == NULL)\n{\nfprintf (stderr, \"can't open database: %s\\n\",\ngdbmstrerror (gdbmerrno));\n}\n\n/*\n* Prepare the lookup key.  Notice, that the terminating \\0 character\n* is not counted in the dsize computation.\n*/\nkey.dptr = argv[2];\nkey.dsize = strlen (argv[2]);\n\n/*\n* Look up the key in the database.\n*/\ncontent = gdbmfetch (gdbf, key);\n\n/*\n* Analyze the return.\n*/\nif (content.dptr != NULL)\n{\n/*\n* The key is found.  Print the content on the stdout and\n* indicate success.\n*/\nfwrite (content.dptr, content.dsize, 1, stdout);\nputchar ('\\n');\nstatus = 0;\n}\nelse if (gdbmerrno == GDBMITEMNOTFOUND)\n{\n/*\n* There is no such key in the database.\n*/\nfprintf (stderr, \"no such key\\n\");\nstatus = 1;\n}\nelse\n{\n/*\n* An error occurred.\n*/\nfprintf (stderr, \"%s\\n\", gdbmdbstrerror (gdbf));\nstatus = 2;\n}\n\n/*\n* Close the database and return.\n*/\ngdbmclose (gdbf);\nreturn status;\n}\n\nTo compile this example, run\n\ncc -oexample example.c -lgdbm\n\nTo run it, you will need an example database.  The easiest way to\ncreate it is by using the 'gdbtool' program, which is part of the 'GDBM'\npackage (*note gdbmtool::):\n\n$ gdbmtool test.gdbm store foo bar\n\nThis creates database file 'test.gdbm' and stores a single record in it.\nThe record's key is 'foo', and the value is 'bar'.  Now you can run the\nexample program to see how it works:\n\n$ ./example test.gdbm foo\nbar\n$ ./example test.gdbm baz\nno such key\n\nFile: gdbm.info,  Node: Open,  Next: Close,  Prev: Intro,  Up: Top\n",
            "subsections": []
        },
        "3 Opening the database": {
            "content": "-- gdbm interface: GDBMFILE gdbmopen (const char *NAME, int\nBLOCKSIZE, int FLAGS, int MODE, void (*FATALFUNC)(const char\n*))\nOpens or creates a 'GDBM' database file.\n\nThe arguments are:\n\nNAME\nThe name of the file (the complete name, 'GDBM' does not\nappend any characters to this name).\n\nBLOCKSIZE\nThis parameter is used only when 'gdbmopen' has to create a\nnew database file and represents the size of a single transfer\nfrom disk to memory.  If its value is less than 512, the file\nsystem block size is used instead.  The size is adjusted so\nthat the block can hold exact number of directory entries, so\nthat the effective block size can be slightly greater than\nrequested.  However, if the 'GDBMBSEXACT' flag is set and the\nsize needs to be adjusted, the function will return with error\nstatus, setting the 'gdbmerrno' variable to\n'GDBMBLOCKSIZEERROR'.\n\nFLAGS\nIf 'flags' is set to 'GDBMREADER', the user wants to just\nread the database and any call to 'gdbmstore' or\n'gdbmdelete' will fail.  Many readers can access the database\nat the same time.  If 'flags' is set to 'GDBMWRITER', the\nuser wants both read and write access to the database and\nrequires exclusive access.  If 'flags' is set to\n'GDBMWRCREAT', the user wants both read and write access to\nthe database and wants it created if it does not already\nexist.  If 'flags' is set to 'GDBMNEWDB', the user want a new\ndatabase created, regardless of whether one existed, and wants\nread and write access to the new database.  If an existing\ndatabase file is opened with the 'GDBMNEWDB' flag, the\nexisting data are destroyed, and an empty database structure\nis created in its place.\n\nThe following constants may also be logically or'd into the\ndatabase flags:\n\n-- gdbmopen flag: GDBMCLOEXEC\nSet the close-on-exec flag on the database file\ndescriptor.  The 'libc' must support the 'OCLOEXEC' flag\n(*note (open(2))OCLOEXEC::).\n\n-- gdbmopen flag: GDBMNOLOCK\nDon't lock the database file.  Use this flag if you\nintend to do locking separately.  *Note Locking::.\n\n-- gdbmopen flag: GDBMNOMMAP\nDisable memory mapping mechanism.  Note, that this\ndegrades performance.\n\n-- gdbmopen flag: GDBMPREREAD\nWhen mapping 'GDBM' file to memory, read its contents\nimmediately, instead of when needed (\"prefault reading\").\nThis can be advantageous if you open a read-only\ndatabase and are going to do a lot of look-ups on it.  In\nthis case entire database will be pre-read and look-ups\nwill operate on an in-memory copy.  In contrast,\n'GDBMPREREAD' should not be used if you open a database\n(even in read-only mode) only to do a couple of look-ups.\nFinally, never use 'GDBMPREREAD' when opening a database\nfor updates, especially for inserts: this will degrade\nperformance.\n\nThis flag has no effect if 'GDBMNOMMAP' is given, or if\nthe operating system does not support prefault reading.\nIt is known to work on Linux and FreeBSD kernels.\n\n-- gdbmopen flag: GDBMXVERIFY\nEnable additional consistency checks.  With this flag,\neventual corruptions of the database are discovered when\nopening it, instead of when a corrupted structure is read\nduring normal operation.  However, on large databases, it\ncan slow down the opening process.\n\n*Note Additional functions::.\n\nThe following additional flags are valid when the database is\nopened for writing (i.e.  together with 'GDBMWRITER',\n'GDBMWRCREAT', or 'GDBMNEWDB'):\n\n-- gdbmopen flag: GDBMSYNC\nSynchronize all database operations to disk immediately.\nNotice, that this option entails severe performance\ndegradation and does not necessarily ensure that the\nresulting database state is consistent.  In general, we\ndiscourage its use (*note Sync::).  *Note Crash\nTolerance::, for a discussion of how to ensure database\nconsistency with minimal performance overhead.\n\n-- gdbmopen flag: GDBMFAST\nA reverse of 'GDBMSYNC'.  Synchronize writes only when\nneeded.  This is the default.  The flag is provided for\ncompatibility with previous versions of 'GDBM'.\n\nThe following flags can be used together with 'GDBMNEWDB'.\nThey also take effect when used with 'GDBMWRCREAT', if the\nrequested database file doesn't exist:\n\n-- gdbmopen flag: GDBMBSEXACT\nIf this flag is set and the requested BLOCKSIZE cannot\nbe used without adjustment, 'gdbmopen' will refuse to\ncreate the databases.  In this case it will set the\n'gdbmerrno' variable to 'GDBMBLOCKSIZEERROR' and\nreturn 'NULL'.\n\n-- gdbmopen flag: GDBMNUMSYNC\nUseful only together with 'GDBMNEWDB', this bit\ninstructs 'gdbmopen' to create new database in \"extended\ndatabase format\", a format best suitable for effective\ncrash recovery.  *Note Numsync::, for a detailed\ndiscussion of this format, and *note Crash Tolerance::,\nfor a discussion of crash recovery.\n\nMODE\nFile mode(1), which is used if the file is created.\n\nFATALFUNC\nThis parameter is deprecated and must always be 'NULL'.\n\nEarly versions of 'GDBM' (prior to 1.13) lacked proper error\nhandling and would abort on any \"fatal\" error (such as out of\nmemory condition, disk write error, or the like).  In these\nversions, 'fatalfunc' was provided as a hook, allowing the\ncaller to do proper cleanup before such abnormal exit.  As of\nversion 1.23, this functionality is deprecated, although still\nsupported for backward compatibility.\n\nThe return value, is the pointer needed by all other functions to\naccess that 'GDBM' file.  If the return is the 'NULL' pointer,\n'gdbmopen' was not successful.  The errors can be found in\n'gdbmerrno' variable (*note gdbmerrno: Variables.).  Available\nerror codes are discussed in *note Error codes::.\n\nIn all of the following calls, the parameter DBF refers to the\npointer returned from 'gdbmopen' (or 'gdbmfdopen', described\nbelow).\n\n-- gdbm interface: GDBMFILE gdbmfdopen (int FD, const char *NAME,\nint BLOCKSIZE, int FLAGS, int MODE, void (*FATALFUNC)(const\nchar *))\n\nAlternative function for opening a 'GDBM' database.  The FD\nargument is the file descriptor of the database file obtained by a\ncall to 'open'(2), 'creat'(2) or similar functions.  The descriptor\nis not dup'ed, and will be closed when the returned 'GDBMFILE' is\nclosed.  Use 'dup'(2) if that is not desirable.\n\nIn case of error, the function behaves like 'gdbmopen' and does\nnot close FD.  This can be altered by the following value passed\nin the FLAGS argument:\n\n-- gdbmopen flag: GDBMCLOERROR\nClose FD before exiting on error.\n\n-- gdbm interface: int gdbmcopymeta (GDBMFILE DST, GDBMFILE SRC)\nCopy file ownership and mode from SRC to DST.\n\n---------- Footnotes ----------\n\n(1) *Note (chmod(2))chmod::, and *Note open a file: (open(2))open.\n\nFile: gdbm.info,  Node: Close,  Next: Count,  Prev: Open,  Up: Top\n",
            "subsections": []
        },
        "4 Closing the database": {
            "content": "It is important that every file opened is also closed.  This is needed\nto properly update its disk structure and maintain a consistent locking\nstate on the file.\n\n-- gdbm interface: int gdbmclose (GDBMFILE DBF)\nThis function closes the 'GDBM' file and frees all memory\nassociated with it.  The parameter is:\n\nDBF\nThe pointer returned by 'gdbmopen'.\n\n'Gdbmclose' returns 0 on success.  On error, it sets 'gdbmerrno'\nand system 'errno' variables to the codes describing the error and\nreturns -1.\n\nFile: gdbm.info,  Node: Count,  Next: Store,  Prev: Close,  Up: Top\n",
            "subsections": []
        },
        "5 Number of Records": {
            "content": "-- gdbm interface: int gdbmcount (GDBMFILE DBF, gdbmcountt *PCOUNT)\nCounts the number of records in the database DBF.  On success,\nstores it in the memory location pointed to by PCOUNT and returns\n0.  On error, sets 'gdbmerrno' (if relevant, also 'errno') and\nreturns -1.\n\n-- gdbm interface: int gdbmbucketcount (GDBMFILE DBF, sizet\n*PCOUNT)\nCounts the number of buckets in the database DBF.  On success,\nstores it in the memory location pointed to by PCOUNT and return 0.\nOn error, sets 'gdbmerrno' (if relevant, also 'errno') and returns\n-1.\n\nFile: gdbm.info,  Node: Store,  Next: Fetch,  Prev: Count,  Up: Top\n",
            "subsections": []
        },
        "6 Inserting and replacing records in the database": {
            "content": "-- gdbm interface: int gdbmstore (GDBMFILE DBF, datum KEY, datum\nCONTENT, int FLAG)\nThe function 'gdbmstore' inserts or replaces records in the\ndatabase.\n\nThe parameters are:\n\nDBF\nThe pointer returned by 'gdbmopen'.\nKEY\nThe search key.\nCONTENT\nThe data to be associated with the key.\nFLAG\nDefines the action to take when the key is already in the\ndatabase.  The value 'GDBMREPLACE' asks that the old data be\nreplaced by the new CONTENT.  The value 'GDBMINSERT' asks\nthat an error be returned and no action taken if the KEY\nalready exists.\n\nThis function can return the following values:\n\n0\nSuccess.  The value of CONTENT is keyed by KEY in the\ndatabase.\n\n-1\nAn error occurred which prevented the item from being stored\nin the database.  Examine the 'gdbmerrno' variable to\ndetermine the actual cause of the error.\n\n+1\nThe item was not stored because the argument FLAG was\n'GDBMINSERT' and the KEY was already in the database.  The\n'gdbmerrno' variable is set to 'GDBMCANNOTREPLACE'.\n\nIf the function returns -1, 'gdbmerrno' can have the following\nvalues:\n\n'GDBMREADERCANTSTORE'\nDatabase was open in read-only mode, i.e.  with the\n'GDBMREADER' flag.  *Note Open::.\n\n'GDBMMALFORMEDDATA'\nEither KEY or CONTENT had their 'dptr' field set to 'NULL'.\n\nIt is OK to have a \"zero-length\" key or content, i.e.  a datum\nwith 'dsize' set to 0, but the 'dptr' field must always be a\nnon-NULL value.\n\n'GDBMBADHASHTABLE'\nDatabase hash table is malformed.  This usually means that\nsome error in the application or the library caused memory\noverrun.  The database is marked as needing recovery.  All\nfurther calls on this database will return with 'gdbmerror'\nset to 'GDBMNEEDRECOVERY'.  *Note Recovery::, for a\ndiscussion of database recovery process.\n\n'GDBMBADDIRENTRY'\nDatabase directory entry is corrupted.  The database is marked\nas needing recovery.  *Note Recovery::.\n\n'GDBMBADBUCKET'\nDatabase bucket is corrupted.  The database is marked as\nneeding recovery.  *Note Recovery::.\n\n'GDBMBADAVAIL'\nDatabase available storage index is corrupted.  The database\nis marked as needing recovery.  *Note Recovery::.\n\n'GDBMFILESEEKERROR'\nA seek error occurred on the underlying disk file.  Examine\nthe system 'errno' variable for more detail.\n\nIf you store data for a KEY that is already in the data base, 'GDBM'\nreplaces the old data with the new data if called with 'GDBMREPLACE'.\nYou do not get two data items for the same 'key' and you do not get an\nerror from 'gdbmstore'.\n\nThe size of datum in 'GDBM' is restricted only by the maximum value\nfor an object of type 'int' (type of the 'dsize' member of 'datum').\n\nFile: gdbm.info,  Node: Fetch,  Next: Delete,  Prev: Store,  Up: Top\n",
            "subsections": []
        },
        "7 Searching for records in the database": {
            "content": "-- gdbm interface: datum gdbmfetch (GDBMFILE DBF, datum KEY)\nLooks up a given KEY and returns the information associated with\nit.  The 'dptr' field in the structure that is returned points to a\nmemory block allocated by 'malloc'.  It is the caller's\nresponsibility to free it when no longer needed.\n\nIf the 'dptr' is 'NULL', inspect the value of the 'gdbmerrno'\nvariable (*note gdbmerrno: Variables.).  If it is\n'GDBMITEMNOTFOUND', no data was found.  Any other value means an\nerror occurred.  Use 'gdbmstrerror' function to convert\n'gdbmerrno' to a human-readable string.\n\nThe parameters are:\n\nDBF\nThe pointer returned by 'gdbmopen'.\nKEY\nThe search key.\n\nAn example of using this function:\n\ncontent = gdbmfetch (dbf, key);\nif (content.dptr == NULL)\n{\nif (gdbmerrno == GDBMITEMNOTFOUND)\nfprintf(stderr, \"key not found\\n\");\nelse\nfprintf(stderr, \"error: %s\\n\", gdbmdbstrerror (dbf));\n}\nelse\n{\n/* do something with content.dptr */\n}\n\nYou may also search for a particular key without retrieving it:\n\n-- gdbm interface: int gdbmexists (GDBMFILE DBF, datum KEY)\nChecks whether the KEY exists in the database DBF.\n\nIf KEY is found, returns 'true' ('1').  If it is not found, returns\n'false' ('0') and sets 'gdbmerrno' to 'GDBMNOERROR' ('0').\n\nOn error, returns '0' and sets 'gdbmerrno' to a non-'0' error\ncode.\n\nThe parameters are:\n\nDBF\nThe pointer returned by 'gdbmopen'.\nKEY\nThe search key.\n\nFile: gdbm.info,  Node: Delete,  Next: Sequential,  Prev: Fetch,  Up: Top\n",
            "subsections": []
        },
        "8 Removing records from the database": {
            "content": "To remove some data from the database, use the 'gdbmdelete' function.\n\n-- gdbm interface: int gdbmdelete (GDBMFILE DBF, datum KEY)\nDeletes the data associated with the given KEY, if it exists in the\ndatabase DBF.\n\nThe parameters are:\n\nDBF\nThe pointer returned by 'gdbmopen'.\nDATUM KEY\nThe search key.\n\nThe function returns '-1' if the item is not present or if an error\nis encountered.  Examine the 'gdbmerrno' variable or the return\nfrom 'gdbmlasterrno (DBF)' to know the reason.\n\nThe return of '0' marks a successful delete.\n\nFile: gdbm.info,  Node: Sequential,  Next: Reorganization,  Prev: Delete,  Up: Top\n",
            "subsections": []
        },
        "9 Sequential access to records": {
            "content": "The next two functions allow for accessing all items in the database.\nThis access is not 'key' sequential, but it is guaranteed to visit every\n'key' in the database once.  The order has to do with the hash values.\n'gdbmfirstkey' starts the visit of all keys in the database.\n'gdbmnextkey' finds and reads the next entry in the hash structure for\n'dbf'.\n\n-- gdbm interface: datum gdbmfirstkey (GDBMFILE DBF)\nInitiate sequential access to the database DBF.  The returned value\nis the first key accessed in the database.  If the 'dptr' field in\nthe returned datum is 'NULL', inspect the 'gdbmerrno' variable\n(*note gdbmerrno: Variables.).  The value of 'GDBMITEMNOTFOUND'\nmeans that the database contains no data.  Other value means an\nerror occurred.\n\nOn success, 'dptr' points to a memory block obtained from 'malloc',\nwhich holds the key value.  The caller is responsible for freeing\nthis memory block when no longer needed.\n\n-- gdbm interface: datum gdbmnextkey (GDBMFILE DBF, datum PREV)\nThis function continues iteration over the keys in DBF, initiated\nby 'gdbmfirstkey'.  The parameter PREV holds the value returned\nfrom a previous call to 'gdbmnextkey' or 'gdbmfirstkey'.\n\nThe function returns next key from the database.  If the 'dptr'\nfield in the returned datum is 'NULL' inspect the 'gdbmerrno'\nvariable (*note gdbmerrno: Variables.).  The value of\n'GDBMITEMNOTFOUND' means that all keys in the database has been\nvisited.  Any other value means an error occurred.\n\nOtherwise, 'dptr' points to a memory block obtained from 'malloc',\nwhich holds the key value.  The caller is responsible for freeing\nthis memory block when no longer needed.\n\nThese functions are intended to visit the database in read-only\nalgorithms, for instance, to validate the database or similar\noperations.  The usual algorithm for sequential access is:\n\nkey = gdbmfirstkey (dbf);\nwhile (key.dptr)\n{\ndatum nextkey;\n\n/* do something with the key */\n...\n\n/* Obtain the next key */\nnextkey = gdbmnextkey (dbf, key);\n/* Reclaim the memory used by the key */\nfree (key.dptr);\n/* Use nextkey in the next iteration. */\nkey = nextkey;\n}\n\nDon't use 'gdbmdelete' or 'gdbmstore' in such a loop.  File\nvisiting is based on a \"hash table\".  The 'gdbmdelete' function\nre-arranges the hash table to make sure that any collisions in the table\ndo not leave some item \"un-findable\".  The original key order is not\nguaranteed to remain unchanged in all instances.  So it is possible that\nsome key will not be visited or will be visited twice, if a loop like\nthe following is executed:\n\nkey = gdbmfirstkey (dbf);\nwhile (key.dptr)\n{\ndatum nextkey;\nif (some condition)\n{\ngdbmdelete (dbf, key);\n}\nnextkey = gdbmnextkey (dbf, key);\nfree (key.dptr);\nkey = nextkey;\n}\n\nFile: gdbm.info,  Node: Reorganization,  Next: Sync,  Prev: Sequential,  Up: Top\n",
            "subsections": []
        },
        "10 Database reorganization": {
            "content": "The following function should be used very seldom.\n\n-- gdbm interface: int gdbmreorganize (GDBMFILE DBF)\nReorganizes the database.\n\nThe parameter is:\n\nDBF\nThe pointer returned by 'gdbmopen'.\n\nIf you have had a lot of deletions and would like to shrink the space\nused by the 'GDBM' file, this function will reorganize the database.\nThis results, in particular, in shortening the length of a 'GDBM' file\nby removing the space occupied by deleted records.\n\nThis reorganization requires creating a new file and inserting all\nthe elements in the old file DBF into the new file.  The new file is\nthen renamed to the same name as the old file and DBF is updated to\ncontain all the correct information about the new file.  If an error is\ndetected, the return value is negative.  The value zero is returned\nafter a successful reorganization.\n\nFile: gdbm.info,  Node: Sync,  Next: Database format,  Prev: Reorganization,  Up: Top\n",
            "subsections": []
        },
        "11 Database Synchronization": {
            "content": "Normally, 'GDBM' functions don't flush changed data to the disk\nimmediately after a change.  This allows for faster writing of databases\nat the risk of having a corrupted database if the application terminates\nin an abnormal fashion.  The following function allows the programmer to\nmake sure the disk version of the database has been completely updated\nwith all changes to the current time.\n\n-- gdbm interface: int gdbmsync (GDBMFILE DBF)\nSynchronizes the changes in DBF with its disk file.  The parameter\nis a pointer returned by 'gdbmopen'.\n\nThis function would usually be called after a complete set of\nchanges have been made to the database and before some long waiting\ntime.  This set of changes should preserve application-level\ninvariants.  In other words, call 'gdbmsync' only when the\ndatabase is in a consistent state with regard to the application\nlogic, a state from which you are willing and able to recover.  You\ncan think about all database operations between two consecutive\n'gdbmsync' calls as constituting a single \"transaction\".  *Note\nSynchronizing the Database::, for a detailed discussion about how\nto properly select the synchronization points.\n\nThe 'gdbmclose' function automatically calls the equivalent of\n'gdbmsync' so no call is needed if the database is to be closed\nimmediately after the set of changes have been made.\n\n'Gdbmsync' returns 0 on success.  On error, it sets 'gdbmerrno'\nand system 'errno' variables to the codes describing the error and\nreturns -1.\n\nOpening the database with 'GDBMSYNC' flag ensures that 'gdbmsync'\nfunction will be called after each change, thereby flushing the changes\nto disk immediately.  You are advised against using this flag, however,\nbecause it incurs a severe performance penalty, while giving only a\nmoderate guarantee that the structural consistency of the database\nwill be preserved in case of failure, and that only unless the failure\noccurs while being in the 'fsync' call.  For the ways to ensure proper\nlogical consistency of the database, see *note Crash Tolerance::.\n\nFile: gdbm.info,  Node: Database format,  Next: Flat files,  Prev: Sync,  Up: Top\n",
            "subsections": []
        },
        "12 Changing database format": {
            "content": "As of version 1.23, 'GDBM' supports databases in two formats: \"standard\"\nand \"extended\".  The standard format is used most often.  The \"extended\"\ndatabase format is used to provide additional crash resistance (*note\nCrash Tolerance::).\n\nDepending on the value of the FLAGS parameter in a call to\n'gdbmopen' (*note GDBMNUMSYNC: Open.), a database can be created in\neither format.\n\nThe format of an existing database can be changed using the\n'gdbmconvert' function:\n\n-- gdbm interface: int gdbmconvert (GDBMFILE DBF, int FLAG)\nChanges the format of the database file DBF.  Allowed values for\nFLAG are:\n\n'0'\nConvert database to the standard format.\n\n'GDBMNUMSYNC'\nConvert database to the extended \"numsync\" format (*note\nNumsync::).\n\nOn success, the function returns 0.  In this case, it should be\nfollowed by a call to 'gdbmsync' (*note Sync::) or 'gdbmclose'\n(*note Close::) to ensure the changes are written to the disk.\n\nOn error, returns -1 and sets the 'gdbmerrno' variable (*note\ngdbmerrno: Variables.).\n\nIf the database is already in the requested format, the function\nreturns success (0) without doing anything.\n\nFile: gdbm.info,  Node: Flat files,  Next: Errors,  Prev: Database format,  Up: Top\n",
            "subsections": []
        },
        "13 Export and Import": {
            "content": "'GDBM' databases can be converted into so-called \"flat format\" files.\nSuch files cannot be used for searching, their sole purpose is to keep\nthe data from the database for restoring it when the need arrives.\nThere are two flat file formats, which differ in the way they represent\nthe data and in the amount of meta-information stored.  Both formats can\nbe used, for example, to migrate between the different versions of\n'GDBM' databases.  Generally speaking, flat files are safe to send over\nthe network, and can be used to recreate the database on another\nmachine.  The recreated database is guaranteed to have the same format\nand contain the same set of key/value pairs as the database from which\nthe flat file was created.  However, it will not constitute a\nbyte-to-byte equivalent of the latter.  Various internal structures in\nthe database can differ.  In particular, ordering of key/value pairs can\nbe different and the table of available file space will most probably\ndiffer, too.  For databases in extended format, the 'numsync' counter\nwill be reset to 0 (*note Numsync::).  These details are not visible to\nthe application programmer, and are mentioned here only for completeness\nsake.\n\nThe fact that the restored database contains the same set of\nkey/value pairs does not necessarily mean, however, that it can be used\nin the same way as the original one.  For example, if the original\ndatabase contained non-ASCII data (e.g. C structures, integers etc.),\nthe recreated database can be of any use only if the target machine has\nthe same integer size and byte ordering as the source one and if its C\ncompiler uses the same packing conventions as the one which generated C\nwhich populated the original database.  In general, such binary\ndatabases are not portable between machines, unless you follow some\nstringent rules on what data is written to them and how it is\ninterpreted.\n\n'GDBM' version 1.23 supports two flat file formats.  The \"binary\"\nflat file format was first implemented in version 1.9.1.  This format\nstores only key/data pairs, it does not keep information about the\ndatabase file itself.  As its name implies, files in this format are\nbinary files.  This format is supported for backward compatibility.\n\nThe \"ascii\" flat file format encodes all data in Base64 and stores\nnot only key/data pairs, but also the original database file metadata,\nsuch as file name, mode and ownership.  Files in this format can be sent\nwithout additional encapsulation over transmission channels that\nnormally allow only ASCII data, such as, e.g. SMTP. Due to additional\nmetadata they allow for restoring an exact copy of the database,\nincluding file ownership and privileges, which is especially important\nif the database in question contained some security-related data.\n\nWe call a process of creating a flat file from a database \"exporting\"\nor \"dumping\" this database.  The reverse process, creating the database\nfrom a flat file is called \"importing\" or \"loading\" the database.\n\n-- gdbm interface: int gdbmdump (GDBMFILE DBF, const char *FILENAME,\nint FORMAT, int OPENFLAGS, int MODE)\nDumps the database file to the named file in requested format.\nArguments are:\n\nDBF\nA pointer to the source database, returned by a prior call to\n'gdbmopen'.\n\nFILENAME\nName of the dump file.\n\nFORMAT\nOutput file format.  Allowed values are:\n'GDBMDUMPFMTBINARY' to create a binary dump and\n'GDBMDUMPFMTASCII' to create an ASCII dump file.\n\nOPENFLAGS\nHow to create the output file.  If FLAG is 'GDBMWRCREAT' the\nfile will be created if it does not exist.  If it does exist,\nthe 'gdbmdump' will fail.\n\nIf FLAG is 'GDBMNEWDB', the function will create a new output\nfile, replacing it if it already exists.\n\nMODE\nThe permissions to use when creating the output file (*note\nopen a file: (open(2))open.).\n\n-- gdbm interface: int gdbmload (GDBMFILE *PDBF, const char\n*FILENAME, int FLAG, int METAMASK, unsigned long *ERRLINE)\nLoads data from the dump file FILENAME into the database pointed to\nby PDBF.  The latter can point to 'NULL', in which case the\nfunction will try to create a new database.  If it succeeds, the\nfunction will return, in the memory location pointed to by PDBF, a\npointer to the newly created database.  If the dump file carries no\ninformation about the original database file name, the function\nwill set 'gdbmerrno' to 'GDBMNODBNAME' and return '-1',\nindicating failure.\n\nThe FLAG has the same meaning as the FLAG argument to the\n'gdbmstore' function (*note Store::).\n\nThe METAMASK argument can be used to disable restoring certain\nbits of file's meta-data from the information in the input dump\nfile.  It is a binary OR of zero or more of the following:\n\nGDBMMETAMASKMODE\nDo not restore file mode.\n\nGDBMMETAMASKOWNER\nDo not restore file owner.\n\nThe function returns 0 upon successful completion or -1 on fatal\nerrors and 1 on mild (non-fatal) errors.\n\nIf a fatal error occurs, 'gdbmerrno' will be set to one of the\nfollowing values:\n\nGDBMFILEOPENERROR\nInput file (FILENAME) cannot be opened.  The 'errno' variable\ncan be used to get more detail about the failure.\n\nGDBMMALLOCERROR\nNot enough memory to load data.\n\nGDBMFILEREADERROR\nReading from FILENAME failed.  The 'errno' variable can be\nused to get more detail about the failure.\n\nGDBMMALFORMEDDATA\nGDBMILLEGALDATA\nInput contained malformed data, i.e.  it is not a valid 'GDBM'\ndump file.  This often means that the dump file got corrupted\nduring the transfer.\n\nThe 'GDBMILLEGALDATA' is an alias for this error code,\nmaintained for backward compatibility.\n\nGDBMITEMNOTFOUND\nThis error can occur only when the input file is in ASCII\nformat.  It indicates that the data part of the record about\nto be read lacked length specification.  Application\ndevelopers are advised to treat this error equally as\n'GDBMMALFORMEDDATA'.\n\nMild errors mean that the function was able to successfully load\nand restore the data, but was unable to change the database file\nmetadata afterwards.  The table below lists possible values for\n'gdbmerrno' in this case.  To get more detail, inspect the system\n'errno' variable.\n\nGDBMERRFILEOWNER\nThe function was unable to restore database file owner.\n\nGDBMERRFILEMODE\nThe function was unable to restore database file mode\n(permission bits).\n\nIf an error occurs while loading data from an input file in ASCII\nformat, the number of line in which the error occurred will be\nstored in the location pointed to by the ERRLINE parameter, unless\nit is 'NULL'.\n\nIf the line information is not available or applicable, ERRLINE\nwill be set to '0'.\n\n-- gdbm interface: int gdbmdumptofile (GDBMFILE DBF, FILE *FP, int\nFORMAT)\nThis is an alternative entry point to 'gdbmdump' (which see).\nArguments are:\n\nDBF\nA pointer to the source database, returned by a call to\n'gdbmopen'.\n\nFP\nFile to write the data to.\n\nFORMAT\nFormat of the dump file.  See the FORMAT argument to the\n'gdbmdump' function.\n\n-- gdbm interface: int gdbmloadfromfile (GDBMFILE *PDBF, FILE *FP,\nint REPLACE, int METAMASK, unsigned long *LINE)\nThis is an alternative entry point to 'gdbmload'.  It writes the\noutput to FP which must be a file open for writing.  The rest of\narguments is the same as for 'gdbmload' (excepting of course FLAG,\nwhich is not needed in this case).\n\n-- gdbm interface: int gdbmexport (GDBMFILE DBF, const char\n*EXPORTFILE, int FLAG, int MODE)\nThis function is retained for compatibility with GDBM 1.10 and\nearlier.  It dumps the database to a file in binary dump format and\nis equivalent to\n\ngdbmdump(DBF, EXPORTFILE, GDBMDUMPFMTBINARY, FLAG, MODE)\n\n-- gdbm interface: int gdbmexporttofile (GDBMFILE DBF, FILE *FP)\nThis is an alternative entry point to 'gdbmexport'.  This function\nwrites to file FP a binary dump of the database DBF.\n\n-- gdbm interface: int gdbmimport (GDBMFILE DBF, const char\n*IMPORTFILE, int FLAG)\nThis function is retained for compatibility with 'GDBM' 1.10 and\nearlier.  It loads the file IMPORTFILE, which must be a binary flat\nfile, into the database DBF and is equivalent to the following\nconstruct:\n\nDBF = gdbmopen (IMPORTFILE, 0,\nFLAG == GDBMREPLACE ?\nGDBMWRCREAT : GDBMNEWDB,\n0600, NULL);\ngdbmload (&DBF, EXPORTFILE, 0, FLAG, NULL)\n\n-- gdbm interface: int gdbmimportfromfile (GDBMFILE DBF, FILE *FP,\nint FLAG)\nAn alternative entry point to 'gdbmimport'.  Reads the binary dump\nfrom the file FP and stores the key/value pairs to DBF.  *Note\nStore::, for a description of FLAG.\n\nThis function is equivalent to:\n\nDBF = gdbmopen (IMPORTFILE, 0,\nFLAG == GDBMREPLACE ?\nGDBMWRCREAT : GDBMNEWDB,\n0600, NULL);\ngdbmloadfromfile (DBF, FP, FLAG, 0, NULL);\n\nFile: gdbm.info,  Node: Errors,  Next: Database consistency,  Prev: Flat files,  Up: Top\n",
            "subsections": []
        },
        "14 Error handling": {
            "content": "The global variable 'gdbmerrno' (*note gdbmerrno: Variables.) keeps\nthe error code of the most recent error encountered by 'GDBM' functions.\n\nTo convert this code to human-readable string, use the following\nfunction:\n\n-- gdbm interface: const char * gdbmstrerror (gdbmerror ERRNO)\nConverts ERRNO (an integer value) into a human-readable descriptive\ntext.  Returns a pointer to a static string.  The caller must not\nfree the returned pointer or alter the string it points to.\n\nDetailed information about the most recent error that occurred while\noperating on a 'GDBM' file is stored in the 'GDBMFILE' object itself.\nTo retrieve it, the following functions are provided:\n\n-- gdbm interface: gdbmerror gdbmlasterrno (GDBMFILE DBF)\nReturns the code of the most recent error encountered when\noperating on DBF.\n\nWhen 'gdbmlasterrno' called immediately after the failed\nfunction, its return equals the value of the 'gdbmerrno' variable.\nHowever, 'gdbmerrno' can be changed if any 'GDBM' functions\n(operating on another databases) were called afterwards, and\n'gdbmlasterrno' will always return the code of the last error\nthat occurred while working with that database.\n\n-- gdbm interface: int gdbmlastsyserr (GDBMFILE DBF)\nReturns the value of the system 'errno' variable associated with\nthe most recent error.\n\nNotice, that not all 'GDBM' errors have an associated system error\ncode.  The following are the ones that have:\n\n* GDBMFILEOPENERROR\n* GDBMFILEWRITEERROR\n* GDBMFILESEEKERROR\n* GDBMFILEREADERROR\n* GDBMFILESTATERROR\n* GDBMBACKUPFAILED\n* GDBMBACKUPFAILED\n* GDBMFILECLOSEERROR\n* GDBMFILESYNCERROR\n* GDBMFILETRUNCATEERROR\n\nFor other errors, 'gdbmlastsyserr' will return 0.\n\n-- gdbm interface: int gdbmchecksyserr (gdbmerrno ERR)\nReturns '1', if the system 'errno' value should be inspected to get\nmore info on the error described by 'GDBM' error code ERR.\n\nTo get a human-readable description of the recent error for a\nparticular database file, use the 'gdbmdbstrerror' function:\n\n-- gdbm interface: const char * gdbmdbstrerror (GDBMFILE DBF)\nReturns textual description of the most recent error encountered\nwhen operating on the database DBF.  The resulting string is often\nmore informative than what would be returned by\n'gdbmstrerror(gdbmlasterrno(DBF))'.  In particular, if there is\na system error associated with the recent failure, it will be\ndescribed as well.\n\n-- gdbm interface: void gdbmclearerror (GDBMFILE DBF)\nClears the error state for the database DBF.  Normally, this\nfunction is called upon the entry to any 'GDBM' function.\n\nCertain errors (such as write error when saving stored key) can leave\ndatabase file in inconsistent state (*note Database consistency::).\nWhen such a critical error occurs, the database file is marked as\nneeding recovery.  Subsequent calls to any 'GDBM' functions for that\ndatabase file (except 'gdbmrecover'), will return immediately with\n'GDBM' error code 'GDBMNEEDRECOVERY'.  Additionally, the following\nfunction can be used to check the state of the database file:\n\n-- gdbm interface: int gdbmneedsrecovery (GDBMFILE DBF)\nReturns '1' if the database file DBF is in inconsistent state and\nneeds recovery.\n\nTo restore structural consistency of the database, use the\n'gdbmrecover' function (*note Recovery::).\n\nCrash tolerance provides a better way of recovery, because it\nrestores both structural and logical consistency.  *Note Crash\nTolerance::, for a detailed discussion,\n\nFile: gdbm.info,  Node: Database consistency,  Next: Recovery,  Prev: Errors,  Up: Top\n",
            "subsections": []
        },
        "15 Database consistency": {
            "content": "In the chapters that follow we will cover different aspects of \"database\nconsistency\" and ways to maintain it.  Speaking about consistency, it is\nimportant to distinguish between two different aspects of it: structural\nand logical consistency.\n\n\"Structural consistency\" means that all internal structures of the\ndatabase are in good order, contain valid data and are coherent with one\nanother.  Structural consistency means that the database is in good\nshape \"technically\", but it does not imply that the data it contains are\nin any way meaningful.\n\n\"Logical consistency\" means that the data stored in the database are\ncoherent with respect to the application logic.  Usually this implies\nthat structural consistency is observed as well.\n\nFor as long as the program is free from memory management errors and\neach opened database is properly closed before the program terminates,\nstructural consistency is maintained.  Maintaining logical consistency\nis more complex task and its maintenance is entirely the responsibility\nof the application programmer.  *Note Crash Tolerance::, for a detailed\ndiscussion.\n\nBoth consistency aspects can suffer as a result of both application\nerrors that cause the program to terminate prematurely without properly\nsaving the database, and hardware errors, such as disk failures or power\noutages.  When such situations occur, it becomes necessary to \"recover\nthe database\".\n\nIn the next chapter we will discuss how to recover structural\nconsistency of a database.\n\nFile: gdbm.info,  Node: Recovery,  Next: Crash Tolerance,  Prev: Database consistency,  Up: Top\n",
            "subsections": []
        },
        "16 Recovering structural consistency": {
            "content": "Certain errors (such as write error when saving stored key) can leave\ndatabase file in \"structurally inconsistent state\".  When such a\ncritical error occurs, the database file is marked as needing recovery.\nSubsequent calls to any GDBM functions for that database file (except\n'gdbmrecover'), will return immediately with 'GDBM' error code\n'GDBMNEEDRECOVERY'.\n\nTo escape from this state and bring the database back to operational\nstate, use the following function:\n\n-- gdbm interface: int gdbmrecover (GDBMFILE DBF, gdbmrecovery\n*RCVR, int FLAGS)\nCheck the database file DBF and fix eventual errors.  The RCVR\nargument points to a structure that has \"input members\", providing\nadditional information to alter the behavior of 'gdbmrecover', and\n\"output members\", which are used to return additional statistics\nabout the recovery process (RCVR can be 'NULL' if no such\ninformation is needed).\n\nEach input member has a corresponding flag bit, which must be set\nin FLAGS, in order to instruct the function to use it.\n\nThe 'gdbmrecover' type is defined as:\n\ntypedef struct gdbmrecoverys\n{\n/* Input members.\nThese are initialized before call to gdbmrecover.\nThe flags argument specifies which of them are initialized. */\nvoid (*errfun) (void *data, char const *fmt, ...);\nvoid *data;\nsizet maxfailedkeys;\nsizet maxfailedbuckets;\nsizet maxfailures;\n\n/* Output members.\nThe gdbmrecover function fills these before returning. */\nsizet recoveredkeys;\nsizet recoveredbuckets;\nsizet failedkeys;\nsizet failedbuckets;\nchar *backupname;\n} gdbmrecovery;\n\nThe \"input members\" modify the behavior of 'gdbmrecover':\n\n-- input member of gdbmrecovery: void (*errfun) (void *DATA, char\nconst *FMT, ...)\nIf the 'GDBMRCVRERRFUN' flag bit is set, 'errfun' points to\na function that will be called upon each recoverable or\nnon-fatal error that occurred during the recovery.  The 'data'\nfield of 'gdbmrecovery' will be passed to it as its first\nargument.  The FMT argument is a 'printf'-like (*note\n(printf(3))Format of the format string::), format string.  The\nrest of arguments supply parameters for that format.\n\n-- input member of gdbmrecovery: void * data\nSupplies first argument for the 'errfun' invocations.\n\n-- input member of gdbmrecovery: sizet maxfailedkeys\nIf 'GDBMRCVRMAXFAILEDKEYS' is set, this member sets the\nlimit on the number of keys that cannot be retrieved.  If the\nnumber of failed keys becomes equal to 'maxfailedkeys',\nrecovery is aborted and error is returned.\n\n-- input member of gdbmrecovery: sizet maxfailedbuckets\nIf 'GDBMRCVRMAXFAILEDBUCKETS' is set, this member sets the\nlimit on the number of buckets that cannot be retrieved or\nthat contain bogus information.  If the number of failed\nbuckets becomes equal to 'maxfailedbuckets', recovery is\naborted and error is returned.\n\n-- output member of gdbmrecovery: sizet maxfailures\nIf 'GDBMRCVRMAXFAILURES' is set, this member sets the limit\nof failures that are tolerated during recovery.  If the number\nof errors becomes equal to 'maxfailures', recovery is aborted\nand error is returned.\n\nThe following members are filled on output, upon successful return\nfrom the function:\n\n-- output member of gdbmrecovery: sizet recoveredkeys\nNumber of recovered keys.\n\n-- output member of gdbmrecovery: sizet recoveredbuckets\nNumber of recovered buckets.\n\n-- output member of gdbmrecovery: sizet failedkeys\nNumber of key/data pairs that could not be retrieved.\n\n-- output member of gdbmrecovery: sizet failedbuckets\nNumber of buckets that could not be retrieved.\n\n-- output member of gdbmrecovery: char * backupname\nName of the file keeping the copy of the original database, in\nthe state prior to recovery.  It is filled if the\nGDBMRCVRBACKUP flag is set.  The string is allocated using\nthe 'malloc' call.  The caller is responsible for freeing that\nmemory when no longer needed.\n\nBy default, 'gdbmrecovery' first checks the database for\ninconsistencies and attempts recovery only if some were found.  The\nspecial flag bit 'GDBMRCVRFORCE' instructs 'gdbmrecovery' to omit\nthis check and to perform database recovery unconditionally.\n\nFile: gdbm.info,  Node: Crash Tolerance,  Next: Options,  Prev: Recovery,  Up: Top\n",
            "subsections": []
        },
        "17 Crash Tolerance": {
            "content": "Crash tolerance is a new (as of release 1.21) feature that can be\nenabled at compile time, and used in environments with appropriate\nsupport from the OS and the filesystem.  As of version 1.23, this means\na Linux kernel 5.12.12 or later and a filesystem that supports reflink\ncopying, such as XFS, BtrFS, or OCFS2.  If these prerequisites are met,\ncrash tolerance code will be enabled automatically by the 'configure'\nscript when building the package.\n\nThe crash-tolerance mechanism, when used correctly, guarantees that a\nlogically consistent (*note Database consistency::) recent state of\napplication data can be recovered following a crash.  Specifically, it\nguarantees that the state of the database file corresponding to the most\nrecent successful 'gdbmsync' call can be recovered.\n\nIf the new mechanism is used correctly, crashes such as power\noutages, OS kernel panics, and (some) application process crashes will\nbe tolerated.  Non-tolerated failures include physical destruction of\nstorage devices and corruption due to bugs in application logic.  For\nexample, the new mechanism won't help if a pointer bug in your\napplication corrupts 'GDBM''s private in-memory data which in turn\ncorrupts the database file.\n\nIn the following sections we will describe how to enable crash\ntolerance in your application and what to do if a crash occurs.\n\nThe design rationale of the crash tolerance mechanism is described in\ndetail in the article, 'Crashproofing the Original NoSQL Key-Value\nStore', by Terence Kelly, 'ACM Queue magazine', July/August 2021,\navailable from the ACM Digital Library\n(https://queue.acm.org/DrillBits5/).  If you have difficulty retrieving\nthis paper, please contact the author at <tpkelly@acm.org>,\n<tpkelly@cs.princeton.edu>, or <tpkelly@eecs.umich.edu>.\n\n* Menu:\n\n* Filesystems supporting crash tolerance::\n* Enabling crash tolerance::\n* Synchronizing the Database::\n* Crash recovery::\n* Manual crash recovery::\n* Performance Impact::\n* Availability::\n* Numsync::\n* Crash Tolerance API::\n\nFile: gdbm.info,  Node: Filesystems supporting crash tolerance,  Next: Enabling crash tolerance,  Up: Crash Tolerance\n",
            "subsections": [
                {
                    "name": "17.1 Using Proper Filesystem",
                    "content": "Use a filesystem that supports reflink copying.  Currently XFS, BtrFS,\nand OCFS2 support reflink.  You can create such a filesystem if you\ndon't have one already.  (Note that reflink support may require that\nspecial options be specified at the time of filesystem creation; this is\ntrue of XFS.) The most conventional way to create a filesystem is on a\ndedicated storage device.  However it is also possible to create a\nfilesystem within an ordinary file on some other filesystem.\n\nFor example, the following commands, executed as root, will create a\nsmallish XFS filesystem inside a file on another filesystem:\n\nmkdir XFS\ncd XFS\ntruncate --size 512m XFSfile\nmkfs -t xfs -m crc=1 -m reflink=1 XFSfile\nmkdir XFSmountpoint\nmount -o loop XFSfile XFSmountpoint\n\nThe XFS filesystem is now available in directory 'XFSmountpoint'.\nNow, create a directory where your unprivileged user account may create\nand delete files:\n\ncd XFSmountpoint\nmkdir test\nchown USER:GROUP test\n\n(where USER and GROUP are the user and group names of the unprivileged\naccount the application uses).\n\nReflink copying via 'ioctl(FICLONE)' should work for files in and\nbelow this directory.  You can test reflink copying using the GNU 'cp'\nprogram:\n\ncp --reflink=always file1 file2\n\n*Note reflink: (coreutils)cp invocation.\n\nYour GNU dbm database file and two \"snapshot\" files described below\nmust all reside on the same reflink-capable filesystem.\n\nFile: gdbm.info,  Node: Enabling crash tolerance,  Next: Synchronizing the Database,  Prev: Filesystems supporting crash tolerance,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.2 Enabling crash tolerance",
                    "content": "Open a GNU dbm database with 'gdbmopen'.  Whenever possible, use the\nextended 'GDBM' format (*note Numsync::).  Generally speaking, this\nmeans using the 'GDBMNUMSYNC' flag when creating the database.  Unless\nyou know what you are doing, do not specify the 'GDBMSYNC' flag when\nopening the database.  The reason is that you want your application to\nexplicitly control when 'gdbmsync' is called; you don't want an\nimplicit sync on every database operation (*note Sync::).\n\nRequest crash tolerance by invoking the following interface:\n\nint gdbmfailureatomic (GDBMFILE DBF, const char *EVEN,\nconst char *ODD);\n\nThe EVEN and ODD arguments are the pathnames of two files that will\nbe created and filled with \"snapshots\" of the database file.  These two\nfiles must not exist when 'gdbmfailureatomic' is called and must\nreside on the same reflink-capable filesystem as the database file.\n\nAfter you call 'gdbmfailureatomic', every call to 'gdbmsync' will\nmake an efficient reflink snapshot of the database file in either the\nEVEN or the ODD snapshot file; consecutive 'gdbmsync' calls alternate\nbetween the two, hence the names.  The permission bits and 'mtime'\ntimestamps on the snapshot files determine which one contains the state\nof the database file corresponding to the most recent successful\n'gdbmsync'.  *Note Crash recovery::, for discussion of crash recovery.\n\nFile: gdbm.info,  Node: Synchronizing the Database,  Next: Crash recovery,  Prev: Enabling crash tolerance,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.3 Synchronizing the Database",
                    "content": "When your application knows that the state of the database is consistent\n(i.e., all relevant application-level invariants hold), you may call\n'gdbmsync'.  For example, if your application manages bank accounts,\ntransferring money from one account to another should maintain the\ninvariant that the sum of the two accounts is the same before and after\nthe transfer: It is correct to decrement account 'A' by $7, increment\naccount 'B' by $7, and then call 'gdbmsync'.  However it is not\ncorrect to call 'gdbmsync' between the decrement of 'A' and the\nincrement of 'B', because a crash immediately after that call would\ndestroy money.  The general rule is simple, sensible, and memorable:\nCall 'gdbmsync' only when the database is in a state from which you are\nwilling and able to recover following a crash.  (If you think about it\nyou'll realize that there's never any other moment when you'd really\nwant to call 'gdbmsync', regardless of whether crash-tolerance is\nenabled.  Why on earth would you push the state of an inconsistent\nunrecoverable database down to durable media?).\n\nFile: gdbm.info,  Node: Crash recovery,  Next: Manual crash recovery,  Prev: Synchronizing the Database,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.4 Crash recovery",
                    "content": "If a crash occurs, the snapshot file (EVEN or ODD) containing the\ndatabase state reflecting the most recent successful 'gdbmsync' call is\nthe snapshot file whose permission bits are read-only and whose\nlast-modification timestamp is greatest.  If both snapshot files are\nreadable, we choose the one with the most recent last-modification\ntimestamp.  Modern operating systems record timestamps in nanoseconds,\nwhich gives sufficient confidence that the timestamps of the two\nsnapshots will differ.  However, one can't rule out the possibility that\nthe two snapshot files will both be readable and have identical\ntimestamps(1).  To cope with this, 'GDBM' version 1.21 introduced the\nnew \"extended database format\", which stores in the database file header\nthe number of synchronizations performed so far.  This number can\nreliably be used to select the most recent snapshot, independently of\nits timestamp.  We strongly suggest using this new format when writing\ncrash-tolerant applications.  *Note Numsync::, for a detailed\ndiscussion.\n\nThe 'gdbmlatestsnapshot' function is provided, that selects the\nright snapshot among the two.  Invoke it as:\n\nconst char *recoveryfile = NULL;\nresult = gdbmlatestsnapshot (even, odd, &recoveryfile);\n\nwhere EVEN and ODD are names of the snapshot files.  On success, it\nstores the pointer to the most recent snapshot file name in\nRECOVERYFILE and returns 'GDBMSNAPSHOTOK'.  To finalize the recovery,\nrename this file to the name of your database file and re-open it using\n'gdbmopen'.  You should discard the remaining snapshot.\n\nIf an error occurs, 'gdbmlatestsnapshot' returns one of the\nfollowing error codes.\n\n-- gdbmlatestsnapshot: GDBMSNAPSHOTBAD\nNeither snapshot file is readable.  This means that the crash has\noccurred before 'gdbmfailureatomic' completed.  In this case, it\nis best to fall back on a safe backup copy of the data file.\n\n-- gdbmlatestsnapshot: GDBMSNAPSHOTERR\nSystem error occurred in 'gdbmlatestsnapshot'.  Examine the\nsystem 'errno' variable for details.  Its possible values are:\n\n'EACCES'\nThe file mode of one of the snapshot files was incorrect.\nEach snapshot file can be either readable (0400) or writable\n(0200), but not both.  This probably means that someone\ntouched one or both snapshot files after the crash and before\nyour attempt to recover from it.  This case needs additional\ninvestigation.  If you're sure that the only change someone\nmade to the files is altering their modes, and your database\nis in \"numsync\" format (*note Numsync::), you can reset the\nmodes to 0400 and retry the recovery.\n\nThis error can also be returned by underlying 'stat' call,\nmeaning that search permission was denied for one of the\ndirectories in the path prefix of a snapshot file name.  That\nagain means that someone has messed with permissions after the\ncrash.\n\n'EINVAL'\nSome arguments passed to 'gdbmlatestsnapshot' were not\nvalid.  It is a programmer's error which means that your\napplication needs to be fixed.\n\n'ENOSYS'\nFunction is not implemented.  This means 'GDBM' was built\nwithout crash-tolerance support.\n\n'Other value (EBADF, EFAULT, etc)'\nAn error occurred when trying to 'stat' the snapshot file.\n*Note (stat(2))ERRORS::, for a discussion of possible 'errno'\nvalues.\n\n-- gdbmlatestsnapshot: GDBMSNAPSHOTSAME\nFile modes and modification dates of both snapshot files are\nexactly the same.  This can happen only if numsync is not available\n(*note Numsync::).\n\n-- gdbmlatestsnapshot: GDBMSNAPSHOTSUSPICIOUS\nFor the database in extended \"numsync\" format (*note Numsync::):\nthe 'numsync' values of the two snapshot differ by more than one.\nCheck the arguments to the 'gdbmlatestsnapshot' function.  The\nmost probably reason of such an error is that the EVEN and ODD\nparameters point to snapshot files belonging to different database\nfiles.\n\nIf you get any of these errors, we strongly suggest to undertake\n\"manual recovery\".\n\n---------- Footnotes ----------\n\n(1) This can happen, for example, if the storage is very fast and the\nsystem clock is low-resolution, or if the system administrator sets the\nsystem clock backwards.  In the latter case one can end up with the most\nrecent snapshot file having modification time earlier than that of the\nobsolete snapshot.\n\nFile: gdbm.info,  Node: Manual crash recovery,  Next: Performance Impact,  Prev: Crash recovery,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.5 Manual crash recovery",
                    "content": "\"Manual recovery\" is usually performed with the help of the 'gdbmtool'\nutility.  Start 'gdbmtool' in read-only mode (the '-r') option.  Once in\nthe command shell, issue the following command:\n\nsnapshot A B\n\nwhere A and B are names of the two snapshot files you configured using\nthe 'gdbmfailureatomic' function.  This command investigates both\nfiles and prints out detailed diagnostics.\n\nIts output begins with a line listing one of the error codes above,\nfollowed by a colon and a textual description of the error.  The lines\nthat follow show details for each snapshot file.\n\nEach snapshot description begins with the snapshot file name followed\nby a colon and four fields, in this order:\n\n1. File permission bits in octal.\n2. File permission bits in 'ls -l' notation.\n3. Modification timestamp.\n4. Numsync counter.  For databases in standard 'GDBM' format, this\nfield is 'N/A'.  If the counter cannot be obtained because of\nerror, this field is '?'.\n\nAny errors or inconsistencies discovered are reported in the lines\nthat follow, one error per line.  Here's an example of the 'snapshot'\ncommand output, describing the 'GDBMSNAPSHOTERR' condition:\n\ngdbmtool> snapshot even.dbf odd.dbf\nGDBMSNAPSHOTERR: Error selecting snapshot.\neven.dbf: 200 -w------- 1627820627.485681330 ?\nodd.dbf: 600 rw------- 1627820627.689503918 301\nodd.dbf: ERROR: bad file mode\n\nLine 2 lists the meta-data of the snapshot 'even.dbf'.  The 'numsync'\nfield contains question mark because the file permissions (write-only)\nprevented 'gdbmtool' from opening it.\n\nThe lines for 'odd.dbf' show the actual reason for the error: bad\nfile mode (read-write).  Apparently, the file mode has been changed\nmanually after the crash.  The timestamp of the file, which is more\nrecent than that of 'even.dbf', suggests that it might be used for\nrecovery.  To confirm this guess, change the mode of the 'even.dbf' to\nread-only and repeat the 'snapshot' command:\n\ngdbmtool> ! chmod 400 even.dbf\ngdbmtool> snapshot even.dbf odd.dbf\nGDBMSNAPSHOTERR: Error selecting snapshot.\neven.dbf: 400 r-------- 1627820627.485681330 300\nodd.dbf: 600 rw------- 1627820627.689503918 301\nodd.dbf: ERROR: bad file mode\n\nThis shows the numsync value of the 'even.dbf' file, which is exactly\none less than that of 'odd.dbf'.  This means that the latter should be\nselected for recovery.\n\nFor completeness sake, you can change the mode of 'odd.dbf' to\nread-only as well and repeat the 'snapshot' command.  In this case you\nwill see:\n\ngdbmtool> ! chmod 400 odd.dbf\ngdbmtool> snapshot even.dbf odd.dbf\nGDBMSNAPSHOTOK: Selected the most recent snapshot.\nodd.dbf: 400 r-------- 1627820627.689503918 301\n\nFile: gdbm.info,  Node: Performance Impact,  Next: Availability,  Prev: Manual crash recovery,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.6 Performance Impact",
                    "content": "The purpose of a parachute is not to hasten descent.  Crash tolerance is\na safety mechanism, not a performance accelerator.  Reflink copying is\ndesigned to be as efficient as possible, but making snapshots of the GNU\ndbm database file on every 'gdbmsync' call entails overheads.  The\nperformance impact of 'GDBM' crash tolerance will depend on many factors\nincluding the type and configuration of the underlying storage system,\nhow often the application calls 'gdbmsync', and the extent of changes\nto the database file between consecutive calls to 'gdbmsync'.\n\nFile: gdbm.info,  Node: Availability,  Next: Numsync,  Prev: Performance Impact,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.7 Availability",
                    "content": "To ensure that application data can survive the failure of one or more\nstorage devices, replicated storage (e.g., RAID) may be used beneath the\nreflink-capable filesystem.  Some cloud providers offer block storage\nservices that mimic the interface of individual storage devices but that\nare implemented as high-availability fault-tolerant replicated\ndistributed storage systems.  Installing a reflink-capable filesystem\natop a high-availability storage system is a good starting point for a\nhigh-availability crash-tolerant 'GDBM'.\n\nFile: gdbm.info,  Node: Numsync,  Next: Crash Tolerance API,  Prev: Availability,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.8 Numsync Extension",
                    "content": "In *note Crash recovery::, we have shown that for database recovery, one\nshould select the snapshot whose permission bits are read-only and whose\nlast-modification timestamp is greatest.  However, there may be cases\nwhen a crash occurs at such a time that both snapshot files remain\nreadable.  It may also happen, that their permissions had been reset to\nread-only and/or modification times inadvertently changed before\nrecovery.  To make it possible to select the right snapshot in such\ncases, a new \"extended database format\" was introduced in 'GDBM' version\n1.21.  This format adds to the database header the 'numsync' field,\nwhich holds the number of synchronizations the database underwent before\nbeing closed or abandoned due to a crash.\n\nA readable snapshot is a consistent copy of the database at a given\npoint of time.  Thus, if both snapshots of a database in extended format\nare readable, it will suffice to examine their 'numsync' counters and\nselect the one whose 'numsync' is greater.  That's what the\n'gdbmlatestsnapshot' function does in this case.\n\nIt is worth noticing, that the two counters should differ exactly by\none.  If the difference is greater than that, 'gdbmlatestsnapshot'\nwill return a special status code, 'GDBMSNAPSHOTSUSPICIOUS'.  If,\nduring a recovery attempt, you get this status code, we recommend to\nproceed with the manual recovery (*note Manual crash recovery::).\n\nTo create a database in extended format, call 'gdbmopen' with both\n'GDBMNEWDB' and 'GDBMNUMSYNC' flags:\n\ndbf = gdbmopen(dbfile, 0, GDBMNEWDB|GDBMNUMSYNC, 0600, NULL);\n\nNotice, that this flag must always be used together with 'GDBMNEWDB'\n(*note Open::).  It is silently ignored when used together with another\nopening flag.\n\nA standard 'GDBM' database can be converted to the extended format\nand vice versa.  To convert an existing database to the extended format,\nuse the 'gdbmconvert' function (*note Database format::):\n\nrc = gdbmconvert(dbf, GDBMNUMSYNC);\n\nYou can do the same using the 'gdbmtool' utility (*note upgrade:\ncommands.):\n\ngdbmtool DBNAME upgrade\n\nTo convert a database from extended format back to the standard\n'GDBM' format, do:\n\nrc = gdbmconvert(dbf, 0);\n\nTo do the same from the command line, run:\n\ngdbmtool DBNAME downgrade\n\nFile: gdbm.info,  Node: Crash Tolerance API,  Prev: Numsync,  Up: Crash Tolerance\n"
                },
                {
                    "name": "17.9 Crash Tolerance API",
                    "content": "-- gdbm interface: int gdbmfailureatomic (GDBMFILE DBF, const char\n*EVEN, const char *ODD)\nEnables crash tolerance for the database file DBF.  The EVEN and\nODD arguments are the pathnames of two files that will be created\nand filled with snapshots of the database file.  These two files\nmust not exist when 'gdbmfailureatomic' is called and must reside\non the same reflink-capable filesystem as the database file.\n\nReturns 0 on success.  On failure, returns -1 and sets 'gdbmerrno'\nto one of the following values:\n\n'GDBMERRUSAGE'\nImproper function usage.  Either EVEN or ODD is 'NULL', or\nthey point to the same string.\n\n'GDBMNEEDRECOVERY'\nThe database needs recovery.  *Note Recovery::.\n\n'GDBMERRSNAPSHOTCLONE'\nFailed to clone the database file into a snapshot.  Examine\nthe system 'errno' variable for details.\n\nIf one of the following error codes is returned, examine the system\n'errno' variable for details:\n\n'GDBMERRREALPATH'\nCall to 'realpath' function failed.  'realpath' is used to\ndetermine actual path names of the snapshot files.\n\n'GDBMFILEOPENERROR'\nUnable to create snapshot file.\n\n'GDBMFILESYNCERROR'\nFailed to sync a snapshot file or one of directories in its\npathname, during initial synchronization.\n\n'GDBMFILECLOSEERROR'\nFailed to close a snapshot file or one of directories in its\npathname, during initial synchronization.\n\n'GDBMERRFILEMODE'\nThe 'fchmod' call on one of the snapshot files failed.\n\nNotes:\n\n* It is not an error to call 'gdbmfailureatomic' several\ntimes.  Each subsequent call closes the previously configured\nsnapshot files and installs new ones instead.\n\n* Crash tolerance settings are cleared by functions\n'gdbmrecover' (*note Recovery::) and 'gdbmreorganize' (*note\nReorganization::).  In case of 'gdbmrecover', it should not\nbe a problem, because if you enabled crash tolerance, the\nprocedure described in *note Crash recovery:: is the preferred\nway of recovering the database.  If, however, you decided to\ncall either function even though you had enabled crash\ntolerance previously, be sure to call 'gdbmfailureatomic'\nagain with the same arguments as before (provided that the\ncall returns successfully).\n\n-- gdbm interface: int gdbmlatestsnapshot (const char *EVEN, const\nchar *ODD, const char RETVAL)\nSelects between two snapshots, EVEN and ODD, the one to be used for\ncrash recovery.  On success, stores a pointer to the selected\nfilename in the memory location pointed to by RETVAL and returns\n'GDBMSNAPSHOTOK'.  If neither snapshot file is usable, the\nfunction returns 'GDBMSNAPSHOTBAD'.  If a system error occurs, it\nreturns 'GDBMSNAPSHOTERR' and sets 'errno' to the error code\ndescribing the problem.  Finally, in the unlikely case that it\ncannot select between the two snapshots (this means they are both\nreadable and have exactly the same 'mtime' timestamp), the function\nreturns 'GDBMSNAPSHOTSAME'.\n\nIf the 'numsync' extension is enabled (*note Numsync::), the\nfunction can also return the 'GDBMSNAPSHOTSUSPICIOUS' status\ncode.  This happens when the 'numsync' counters in the two\nsnapshots differ by more than one.\n\n*Note Crash recovery::, for a detailed description of possible\nreturn codes and their interpretation.\n\nIf any value other than 'GDBMSNAPSHOTOK' is returned, it is\nguaranteed that the function did not touch RETVAL.  In this case it\nis recommended to switch to manual recovery procedure, letting the\nuser examine the snapshots and take the appropriate action.  *note\nManual crash recovery::, for details.\n\nFile: gdbm.info,  Node: Options,  Next: Locking,  Prev: Crash Tolerance,  Up: Top\n"
                }
            ]
        },
        "18 Setting options": {
            "content": "'GDBM' supports the ability to set certain options on an already open\ndatabase.\n\n-- gdbm interface: int gdbmsetopt (GDBMFILE DBF, int OPTION, void\n*VALUE, int SIZE)\nSets an option on the database or returns the value of an option.\n\nThe parameters are:\n\nDBF\nThe pointer returned by 'gdbmopen'.\nOPTION\nThe option to be set or retrieved.\nVALUE\nA pointer to the value to which OPTION will be set or where to\nplace the option value (depending on the option).\nSIZE\nThe length of the data pointed to by VALUE.\n\nThe return value will be '-1' upon failure, or '0' upon success.\nThe global variable 'gdbmerrno' will be set upon failure.\n\nThe valid options are:\n\n-- Option: GDBMSETCACHESIZE\n-- Option: GDBMCACHESIZE\nSet the size of the internal bucket cache.  The VALUE should point\nto a 'sizet' holding the desired cache size, or the constant\n'GDBMCACHEAUTO', to adjust the cache size automatically.\n\nBy default, a newly open database is configured to dynamically\naccommodate the cache size to the number of index buckets in the\ndatabase file.  This provides for the best performance.\n\nIf another VALUE is set, it is adjusted to the nearest larger power\nof two.\n\nUse this option if you wish to limit the memory usage at the\nexpense of performance.  If you chose to do so, please bear in mind\nthat cache becomes effective when its size is greater then 2/3 of\nthe number of index bucket counts in the database.  The best\nperformance results are achieved when cache size equals the number\nof buckets.  For example:\n\nsizet bn;\ngdbmbucketcount (dbf, &bn);\nret = gdbmsetopt (dbf, GDBMSETCACHESIZE, &bn, sizeof (bn));\n\nTo request the automatically adjustable cache size, use the\nconstant 'GDBMCACHEAUTO':\n\nsizet bn = GDBMCACHEAUTO;\nret = gdbmsetopt (dbf, GDBMSETCACHESIZE, &bn, sizeof (bn));\n\n-- Option: GDBMGETCACHESIZE\nReturn the actual size of the internal bucket cache.  The VALUE\nshould point to a 'sizet' variable, where the size will be stored.\n\n-- Option: GDBMSETCACHEAUTO\nControls whether the cache size will be adjusted automatically as\nneeded.  The VALUE should point to an integer: 'TRUE' to enable\nautomatic cache adjustment and 'FALSE' to disable it.\n\nThe following two calls are equivalent:\n\nint t = TRUE;\ngdbmsetopt (dbf, GDBMSETCACHEAUTO, &t, sizeof (t));\n\nsizet n = GDBMCACHEAUTO;\ngdbmsetopt (dbf, GDBMSETCACHESIZE, &n, sizeof (n));\n\n-- Option: GDBMGETCACHEAUTO\nReturn the state of the automatic cache size adjustment.  The VALUE\nshould point to an integer which, upon successful return, will have\nthe value 'TRUE' if the automatic cache size adjustment is enabled\nand 'FALSE' otherwise.\n\n-- Option: GDBMGETFLAGS\nReturn the flags describing the state of the database.  The VALUE\nshould point to an 'int' variable where to store the flags.  On\nsuccess, its value will be similar to the flags used when opening\nthe database (*note gdbmopen: Open.), except that it will reflect\nthe current state (which may have been altered by another calls to\n'gdbmsetopt').\n\n-- Option: GDBMGETDBFORMAT\nReturn the database format.  The VALUE should point to an 'int'\nvariable.  Upon successful return, it will be set to '0' if the\ndatabase is in standard format and 'GDBMNUMSYNC' if it is in\nextended format.  *Note Database format::.\n\n-- Option: GDBMGETDIRDEPTH\nReturns the \"directory depth\": the number of initial (most\nsignificant) bits in hash value that are interpreted as index to\nthe directory.  The actual directory size can be computed as '1 <<\nVALUE'.\n\nThe VALUE argument should point to an 'int'.\n\n-- Option: GDBMGETBUCKETSIZE\nReturns the \"bucket capacity\": maximum number of keys per bucket\n('int').\n\n-- Option: GDBMFASTMODE\nEnable or disable the \"fast writes mode\", i.e. writes without\nsubsequent synchronization.  The VALUE should point to an integer:\n'TRUE' to enable fast mode, and 'FALSE' to disable it.\n\nThis option is retained for compatibility with previous versions of\n'GDBM'.  Its effect is the reverse of 'GDBMSETSYNCMODE'.\n\n-- Option: GDBMSETSYNCMODE\n-- Option: GDBMSYNCMODE\nTurn on or off file system synchronization operations.  This\nsetting defaults to off.  The VALUE should point to an integer:\n'TRUE' to turn synchronization on, and 'FALSE' to turn it off.\n\nNote, that this option is a reverse of 'GDBMFASTMODE', i.e.\ncalling 'GDBMSETSYNCMODE' with 'TRUE' has the same effect as\ncalling 'GDBMFASTMODE' with 'FALSE'.\n\nThe 'GDBMSYNCMODE' option is provided for compatibility with\nearlier versions.\n\n-- Option: GDBMGETSYNCMODE\nReturn the current synchronization status.  The VALUE should point\nto an 'int' where the status will be stored.\n\n-- Option: GDBMSETCENTFREE\n-- Option: GDBMCENTFREE\nNOTICE: This feature is still under study.\n\nSet central free block pool to either on or off.  The default is\noff, which is how previous versions of 'GDBM' handled free blocks.\nIf set, this option causes all subsequent free blocks to be placed\nin the global pool, allowing (in theory) more file space to be\nreused more quickly.  The VALUE should point to an integer: 'TRUE'\nto turn central block pool on, and 'FALSE' to turn it off.\n\nThe 'GDBMCENTFREE' option is provided for compatibility with\nearlier versions.\n\n-- Option: GDBMSETCOALESCEBLKS\n-- Option: GDBMCOALESCEBLKS\nNOTICE: This feature is still under study.\n\nSet free block merging to either on or off.  The default is off,\nwhich is how previous versions of 'GDBM' handled free blocks.  If\nset, this option causes adjacent free blocks to be merged.  This\ncan become a CPU expensive process with time, though, especially if\nused in conjunction with GDBMCENTFREE. The VALUE should point to\nan integer: 'TRUE' to turn free block merging on, and 'FALSE' to\nturn it off.\n\n-- Option: GDBMGETCOALESCEBLKS\nReturn the current status of free block merging.  The VALUE should\npoint to an 'int' where the status will be stored.\n\n-- Option: GDBMSETMAXMAPSIZE\nSets maximum size of a memory mapped region.  The VALUE should\npoint to a value of type 'sizet', 'unsigned long' or 'unsigned'.\nThe actual value is rounded to the nearest page boundary (the page\nsize is obtained from 'sysconf(SCPAGESIZE)').\n\n-- Option: GDBMGETMAXMAPSIZE\nReturn the maximum size of a memory mapped region.  The VALUE\nshould point to a value of type 'sizet' where to return the data.\n\n-- Option: GDBMSETMMAP\nEnable or disable memory mapping mode.  The VALUE should point to\nan integer: 'TRUE' to enable memory mapping or 'FALSE' to disable\nit.\n\n-- Option: GDBMGETMMAP\nCheck whether memory mapping is enabled.  The VALUE should point to\nan integer where to return the status.\n\n-- Option: GDBMGETDBNAME\nReturn the name of the database disk file.  The VALUE should point\nto a variable of type 'char'.  A pointer to the newly allocated\ncopy of the file name will be placed there.  The caller is\nresponsible for freeing this memory when no longer needed.  For\nexample:\n\nchar *name;\n\nif (gdbmsetopt (dbf, GDBMGETDBNAME, &name, sizeof (name)))\n{\nfprintf (stderr, \"gdbmsetopt failed: %s\\n\",\ngdbmstrerror (gdbmerrno));\n}\nelse\n{\nprintf (\"database name: %s\\n\", name);\nfree (name);\n}\n\n-- Option: GDBMGETBLOCKSIZE\nReturn the block size in bytes.  The VALUE should point to 'int'.\n\nFile: gdbm.info,  Node: Locking,  Next: Variables,  Prev: Options,  Up: Top\n",
            "subsections": []
        },
        "19 File Locking": {
            "content": "With locking disabled (if 'gdbmopen' was called with 'GDBMNOLOCK'),\nthe user may want to perform their own file locking on the database file\nin order to prevent multiple writers operating on the same file\nsimultaneously.\n\nIn order to support this, the 'gdbmfdesc' routine is provided.\n\n-- gdbm interface: int gdbmfdesc (GDBMFILE DBF)\nReturns the file descriptor of the database DBF.  This value can be\nused as an argument to 'flock', 'lockf' or similar calls.\n\nFile: gdbm.info,  Node: Variables,  Next: Additional functions,  Prev: Locking,  Up: Top\n",
            "subsections": []
        },
        "20 Useful global variables": {
            "content": "The following global variables and constants are available:\n\n-- Variable: gdbmerror gdbmerrno\nThis variable contains error code from the last failed 'GDBM' call.\n*Note Error codes::, for a list of available error codes and their\ndescriptions.\n\nUse 'gdbmstrerror' (*note Errors::) to convert it to a descriptive\ntext.\n\n-- Variable: const char * gdbmerrlist[]\nThis variable is an array of error descriptions, which is used by\n'gdbmstrerror' to convert error codes to human-readable text\n(*note Errors::).  You can access it directly, if you wish so.  It\ncontains 'GDBMMAXERRNO + 1' elements and can be directly indexed\nby the error code to obtain a corresponding descriptive text.\n\n-- Variable: int const gdbmsyserr[]\nArray of boolean values indicating, for each 'GDBM' error code,\nwhether the value of 'errno'(3) variable is meaningful for this\nerror code.  *Note gdbmchecksyserr::.\n\n-- Constant: GDBMMINERRNO\nThe minimum error code used by 'GDBM'.\n\n-- Constant: GDBMMAXERRNO\nThe maximum error code used by 'GDBM'.\n\n-- Variable: const char * gdbmversion\nA string containing the version information.\n\n-- Variable: int const gdbmversionnumber[3]\nThis variable contains the 'GDBM' version numbers:\n\n0                             Major number\n1                             Minor number\n2                             Patchlevel number\n\nAdditionally, the following constants are defined in the 'gdbm.h'\nfile:\n\nGDBMVERSIONMAJOR\nMajor number.\n\nGDBMVERSIONMINOR\nMinor number.\n\nGDBMVERSIONPATCH\nPatchlevel number.\n\nThese can be used to verify whether the header file matches the\nlibrary.\n\nTo compare two split-out version numbers, use the following function:\n\n-- gdbm interface: int gdbmversioncmp (int const A[3], int const\nB[3])\nCompare two version numbers.  Return '-1' if A is less than B, '1'\nif A is greater than B and '0' if they are equal.\n\nComparison is done from left to right, so that:\n\na = { 1, 8, 3 };\nb = { 1, 8, 3 };\ngdbmversioncmp (a, b) => 0\n\na = { 1, 8, 3 };\nb = { 1, 8, 2 };\ngdbmversioncmp (a, b) => 1\n\na = { 1, 8, 3 };\nb = { 1, 9. 0 };\ngdbmversioncmp (a, b) => -1\n\nFile: gdbm.info,  Node: Additional functions,  Next: Error codes,  Prev: Variables,  Up: Top\n",
            "subsections": []
        },
        "21 Additional functions": {
            "content": "-- gdbm interface: int gdbmavailverify (GDBMFILE DBF)\nVerify if the available block stack is in consistent state.  On\nsuccess, returns 0.  If any errors are encountered, sets the\n'gdbmerrno' to 'GDBMBADAVAIL', marks the database as needing\nrecovery (*note Recovery::) and return -1.\n\nFile: gdbm.info,  Node: Error codes,  Next: Compatibility,  Prev: Additional functions,  Up: Top\n",
            "subsections": []
        },
        "22 Error codes": {
            "content": "This chapter summarizes error codes which can be set by the functions in\n'GDBM' library.\n\n-- Error Code: GDBMNOERROR\nNo error occurred.\n\n-- Error Code: GDBMMALLOCERROR\nMemory allocation failed.  Not enough memory.\n\n-- Error Code: GDBMBLOCKSIZEERROR\nThis error is set by the 'gdbmopen' function (*note Open::), if\nthe value of its BLOCKSIZE argument is incorrect and the\n'GDBMBSEXACT' flag is set.\n\n-- Error Code: GDBMFILEOPENERROR\nThe library was not able to open a disk file.  This can be set by\n'gdbmopen' (*note Open::), 'gdbmdump' ('gdbmexport') and\n'gdbmload' ('gdbmimport') functions (*note Flat files::).\n\nInspect the value of the system 'errno' variable to get more\ndetailed diagnostics.\n\n-- Error Code: GDBMFILEWRITEERROR\nWriting to a disk file failed.  This can be set by 'gdbmopen'\n(*note Open::), 'gdbmdump' ('gdbmexport') and 'gdbmload'\n('gdbmimport') functions.\n\nInspect the value of the system 'errno' variable to get more\ndetailed diagnostics.\n\n-- Error Code: GDBMFILESEEKERROR\nPositioning in a disk file failed.  This can be set by 'gdbmopen'\n(*note Open::) function.\n\nInspect the value of the system 'errno' variable to get a more\ndetailed diagnostics.\n\n-- Error Code: GDBMFILEREADERROR\nReading from a disk file failed.  This can be set by 'gdbmopen'\n(*note Open::), 'gdbmdump' ('gdbmexport') and 'gdbmload'\n('gdbmimport') functions.\n\nInspect the value of the system 'errno' variable to get a more\ndetailed diagnostics.\n\n-- Error Code: GDBMBADMAGICNUMBER\nThe file given as argument to 'gdbmopen' function is not a valid\n'GDBM' file: it has a wrong magic number.\n\n-- Error Code: GDBMEMPTYDATABASE\nThe file given as argument to 'gdbmopen' function is not a valid\n'GDBM' file: it has zero length.\n\n-- Error Code: GDBMCANTBEREADER\nThis error code is set by the 'gdbmopen' function if it is not\nable to lock file when called in 'GDBMREADER' mode (*note\nGDBMREADER: Open.).\n\n-- Error Code: GDBMCANTBEWRITER\nThis error code is set by the 'gdbmopen' function if it is not\nable to lock file when called in writer mode (*note Open::).\n\n-- Error Code: GDBMREADERCANTDELETE\nSet by the 'gdbmdelete' (*note Delete::) if it attempted to\noperate on a database that is open in read-only mode (*note\nGDBMREADER: Open.).\n\n-- Error Code: GDBMREADERCANTSTORE\nSet by the 'gdbmstore' (*note Store::) if it attempted to operate\non a database that is open in read-only mode (*note GDBMREADER:\nOpen.).\n\n-- Error Code: GDBMREADERCANTREORGANIZE\nSet by the 'gdbmreorganize' (*note Reorganization::) if it\nattempted to operate on a database that is open in read-only mode\n(*note GDBMREADER: Open.).\n\n-- Error Code: GDBMITEMNOTFOUND\nRequested item was not found.  This error is set by 'gdbmdelete'\n(*note Delete::) and 'gdbmfetch' (*note Fetch::) when the\nrequested KEY value is not found in the database.\n\n-- Error Code: GDBMREORGANIZEFAILED\nThe 'gdbmreorganize' function is not able to create a temporary\ndatabase.  *Note Reorganization::.\n\n-- Error Code: GDBMCANNOTREPLACE\nCannot replace existing item.  This error is set by the\n'gdbmstore' if the requested KEY value is found in the database\nand the FLAG parameter is not 'GDBMREPLACE'.  *Note Store::, for a\ndetailed discussion.\n\n-- Error Code: GDBMMALFORMEDDATA\n-- Error Code: GDBMILLEGALDATA\nInput data was malformed in some way.  When returned by\n'gdbmload', this means that the input file was not a valid 'GDBM'\ndump file (*note gdbmload function::).  When returned by\n'gdbmstore', this means that either KEY or CONTENT parameter had\nits 'dptr' field set to 'NULL' (*note Store::).\n\nThe 'GDBMILLEGALDATA' is an alias for this error code, maintained\nfor backward compatibility.  Its use in modern applications is\ndiscouraged.\n\n-- Error Code: GDBMOPTALREADYSET\nRequested option can be set only once and was already set.  As of\nversion 1.23, this error code is no longer used.  In prior versions\nit could have been returned by the 'gdbmsetopt' function when\nsetting the 'GDBMCACHESIZE' value.\n\n-- Error Code: GDBMOPTBADVAL\n-- Error Code: GDBMOPTILLEGAL\nThe OPTION argument is not valid or the VALUE argument points to an\ninvalid value in a call to 'gdbmsetopt' function.  *Note\nOptions::.\n\n'GDBMOPTILLEGAL' is an alias for this error code, maintained for\nbackward compatibility.  Modern applications should not use it.\n\n-- Error Code: GDBMBYTESWAPPED\nThe 'gdbmopen' function (*note Open::) attempts to open a database\nwhich is created on a machine with different byte ordering.\n\n-- Error Code: GDBMBADFILEOFFSET\nThe 'gdbmopen' function (*note Open::) sets this error code if the\nfile it tries to open has a wrong magic number.\n\n-- Error Code: GDBMBADOPENFLAGS\nSet by the 'gdbmdump' ('gdbmexport') function if supplied an\ninvalid FLAGS argument.  *Note Flat files::.\n\n-- Error Code: GDBMFILESTATERROR\nGetting information about a disk file failed.  The system 'errno'\nwill give more details about the error.\n\nThis error can be set by the following functions: 'gdbmopen',\n'gdbmreorganize'.\n\n-- Error Code: GDBMFILEEOF\nEnd of file was encountered where more data was expected to be\npresent.  This error can occur when fetching data from the database\nand usually means that the database is truncated or otherwise\ncorrupted.\n\nThis error can be set by any 'GDBM' function that does I/O. Some of\nthese functions are: 'gdbmdelete', 'gdbmexists', 'gdbmfetch',\n'gdbmdump', 'gdbmload', 'gdbmexport', 'gdbmimport',\n'gdbmreorganize', 'gdbmfirstkey', 'gdbmnextkey', 'gdbmstore'.\n\n-- Error Code: GDBMNODBNAME\nOutput database name is not specified.  This error code is set by\n'gdbmload' (*note gdbmload: gdbmload function.) if the first\nargument points to 'NULL' and the input file does not specify the\ndatabase name.\n\n-- Error Code: GDBMERRFILEOWNER\nThis error code is set by 'gdbmload' if it is unable to restore\ndatabase file owner.  It is a mild error condition, meaning that\nthe data have been restored successfully, only changing the target\nfile owner failed.  Inspect the system 'errno' variable to get a\nmore detailed diagnostics.\n\n-- Error Code: GDBMERRFILEMODE\nThis error code is set by 'gdbmload' if it is unable to restore\ndatabase file mode.  It is a mild error condition, meaning that the\ndata have been restored successfully, only changing the target file\nowner failed.  Inspect the system 'errno' variable to get a more\ndetailed diagnostics.\n\n-- Error Code: GDBMNEEDRECOVERY\nDatabase is in inconsistent state and needs recovery.  Call\n'gdbmrecover' if you get this error.  *Note Recovery::, for a\ndetailed description of recovery functions.\n\n-- Error Code: GDBMBACKUPFAILED\nThe GDBM engine is unable to create backup copy of the file.\n\n-- Error Code: GDBMDIROVERFLOW\nBucket directory would overflow the size limit during an attempt to\nsplit hash bucket.  This error can occur while storing a new key.\n\n-- Error Code: GDBMBADBUCKET\nInvalid index bucket is encountered in the database.  Database\nrecovery is needed (*note Recovery::).\n\n-- Error Code: GDBMBADHEADER\nThis error is set by 'gdbmopen' and 'gdbmfdopen', if the first\nblock read from the database file does not contain a valid 'GDBM'\nheader.\n\n-- Error Code: GDBMBADAVAIL\nThe available space stack is invalid.  This error can be set by\n'gdbmopen' and 'gdbmfdopen', if the extended database\nverification was requested ('GDBMXVERIFY').  It is also set by the\n'gdbmavailverify' function (*note Additional functions::).\n\nDatabase recovery is needed (*note Recovery::).\n\n-- Error Code: GDBMBADHASHTABLE\nHash table in a bucket is invalid.  This error can be set by the\nfollowing functions: 'gdbmdelete', 'gdbmexists', 'gdbmfetch',\n'gdbmfirstkey', 'gdbmnextkey', and 'gdbmstore'.\n\nDatabase recovery is needed (*note Recovery::).\n\n-- Error Code: GDBMBADDIRENTRY\nBad directory entry found in the bucket.  The database recovery is\nneeded (*note Recovery::).\n\n-- Error Code: GDBMFILECLOSEERROR\nThe 'gdbmclose' function was unable to close the database file\ndescriptor.  The system 'errno' variable contains the corresponding\nerror code.\n\n-- Error Code: GDBMFILESYNCERROR\nCached content couldn't be synchronized to disk.  Examine the\n'errno' variable to get more info,\n\nDatabase recovery is needed (*note Recovery::).\n\n-- Error Code: GDBMFILETRUNCATEERROR\nFile cannot be truncated.  Examine the 'errno' variable to get more\ninfo.\n\nThis error is set by 'gdbmopen' and 'gdbmfdopen' when called\nwith the 'GDBMNEWDB' flag.\n\n-- Error Code: GDBMBUCKETCACHECORRUPTED\nThe bucket cache structure is corrupted.  Database recovery is\nneeded (*note Recovery::).\n\n-- Error Code: GDBMBADHASHENTRY\nThis error is set during sequential access (*note Sequential::), if\nthe next hash table entry does not contain the expected key.  This\nmeans that the bucket is malformed or corrupted and the database\nneeds recovery (*note Recovery::).\n\n-- Error Code: GDBMERRSNAPSHOTCLONE\nSet by the 'gdbmfailureatomic' function if it was unable to clone\nthe database file into a snapshot.  Inspect the system 'errno'\nvariable for the underlying cause of the error.  If 'errno' is\n'EINVAL' or 'ENOSYS', crash tolerance settings will be removed from\nthe database.\n\n*Note Crash Tolerance API::.\n\n-- Error Code: GDBMERRREALPATH\nSet by the 'gdbmfailureatomic' function if the call to 'realpath'\nfunction failed.  'realpath' is used to determine actual path names\nof the snapshot files.  Examine the system 'errno' variable for\ndetails.\n\n*Note Crash Tolerance API::.\n\n-- Error Code: GDBMERRUSAGE\nFunction usage error.  That includes invalid argument values, and\nthe like.\n\nFile: gdbm.info,  Node: Compatibility,  Next: gdbmtool,  Prev: Error codes,  Up: Top\n",
            "subsections": []
        },
        "23 Compatibility with standard 'dbm' and 'ndbm'": {
            "content": "'Gdbm' includes a compatibility layer, which provides traditional 'ndbm'\nand older 'dbm' functions.  The layer is compiled and installed if the\n'--enable-libgdbm-compat' option is used when configuring the package.\n\nThe compatibility layer consists of two header files: 'ndbm.h' and\n'dbm.h' and the 'libgdbmcompat' library.\n\nOlder programs using 'ndbm' or 'dbm' interfaces can use\n'libgdbmcompat' without any changes.  To link a program with the\ncompatibility library, add the following two options to the 'cc'\ninvocation: '-lgdbm -lgdbmcompat'.  The '-L' option may also be\nrequired, depending on where 'GDBM' is installed, e.g.:\n\ncc ... -lgdbm -lgdbmcompat\n\nDatabases created and manipulated by the compatibility interfaces\nconsist of two different files: 'FILE.dir' and 'FILE.pag'.  This is\nrequired by the POSIX specification and corresponds to the traditional\nusage.  Note, however, that despite the similarity of the naming\nconvention, actual data stored in these files has not the same format as\nin the databases created by other 'dbm' or 'ndbm' libraries.  In other\nwords, you cannot access a standard UNIX 'dbm' file with GNU 'dbm'!\n\nCompatibility interface includes only functions required by POSIX\n(*note ndbm::) or present in the traditional DBM implementation (*note\ndbm::).  Advanced 'GDBM' features, such as crash tolerance, cannot be\nused with such databases.\n\nGNU 'dbm' files are not 'sparse'.  You can copy them with the usual\n'cp' command and they will not expand in the copying process.\n\n* Menu:\n\n* ndbm::  NDBM interface functions.\n* dbm::   DBM interface functions.\n\nFile: gdbm.info,  Node: ndbm,  Next: dbm,  Up: Compatibility\n",
            "subsections": [
                {
                    "name": "23.1 NDBM interface functions",
                    "content": "The functions below implement the POSIX 'ndbm' interface:\n\n-- ndbm: DBM * dbmopen (char *FILE, int FLAGS, int MODE)\nOpens a database.  The FILE argument is the full name of the\ndatabase file to be opened.  The function opens two files:\n'FILE.pag' and 'FILE.dir'.  The FLAGS and MODE arguments have the\nsame meaning as the second and third arguments of 'open' (*note\n(open(2))open::), except that a database opened for write-only\naccess opens the files for read and write access and the behavior\nof the 'OAPPEND' flag is unspecified.\n\nThe function returns a pointer to the 'DBM' structure describing\nthe database.  This pointer is used to refer to this database in\nall operations described below.\n\nAny error detected will cause a return value of 'NULL' and an\nappropriate value will be stored in 'gdbmerrno' (*note\nVariables::).\n\n-- ndbm: void dbmclose (DBM *DBF)\nCloses the database.  The DBF argument must be a pointer returned\nby an earlier call to 'dbmopen'.\n\n-- ndbm: datum dbmfetch (DBM *DBF, datum KEY)\nReads a record from the database with the matching key.  The KEY\nargument supplies the key that is being looked for.\n\nIf no matching record is found, the 'dptr' member of the returned\ndatum is 'NULL'.  Otherwise, the 'dptr' member of the returned\ndatum points to the memory managed by the compatibility library.\nThe application should never free it.\n\n-- ndbm: int dbmstore (DBM *DBF, datum KEY, datum CONTENT, int MODE)\nWrites a key/value pair to the database.  The argument DBF is a\npointer to the 'DBM' structure returned from a call to 'dbmopen'.\nThe KEY and CONTENT provide the values for the record key and\ncontent.  The MODE argument controls the behavior of 'dbmstore' in\ncase a matching record already exists in the database.  It can have\none of the following two values:\n\n'DBMREPLACE'\nReplace existing record with the new one.\n\n'DBMINSERT'\nThe existing record is left unchanged, and the function\nreturns '1'.\n\nIf no matching record exists in the database, new record will be\ninserted no matter what the value of the MODE is.\n\n-- ndbm: int dbmdelete (DBM *DBF, datum KEY)\nDeletes the record with the matching key from the database.  If the\nfunction succeeds, '0' is returned.  Otherwise, if no matching\nrecord is found or if an error occurs, '-1' is returned.\n\n-- ndbm: datum dbmfirstkey (DBM *DBF)\nInitializes iteration over the keys from the database and returns\nthe first key.  Note, that the word 'first' does not imply any\nspecific ordering of the keys.\n\nIf there are no records in the database, the 'dptr' member of the\nreturned datum is 'NULL'.  Otherwise, the 'dptr' member of the\nreturned datum points to the memory managed by the compatibility\nlibrary.  The application should never free it.\n\n-- ndbm: datum dbmnextkey (DBM *DBF)\nContinues the iteration started by 'dbmfirstkey'.  Returns the\nnext key in the database.  If the iteration covered all keys in the\ndatabase, the 'dptr' member of the returned datum is 'NULL'.\nOtherwise, the 'dptr' member of the returned datum points to the\nmemory managed by the compatibility library.  The application\nshould never free it.\n\nThe usual way of iterating over all the records in the database is:\n\nfor (key = dbmfirstkey (dbf); key.ptr; key = dbmnextkey (dbf))\n{\n/* do something with the key */\n}\n\nThe loop above should not try to delete any records from the\ndatabase, otherwise the iteration is not guaranteed to cover all\nthe keys.  *Note Sequential::, for a detailed discussion of this.\n\n-- ndbm: int dbmerror (DBM *DBF)\nReturns the error condition of the database: '0' if no errors\noccurred so far while manipulating the database, and a non-zero\nvalue otherwise.\n\n-- ndbm: void dbmclearerr (DBM *DBF)\nClears the error condition of the database.\n\n-- ndbm: int dbmdirfno (DBM *DBF)\nReturns the file descriptor of the 'dir' file of the database.  It\nis guaranteed to be different from the descriptor returned by the\n'dbmpagfno' function (see below).\n\nThe application can lock this descriptor to serialize accesses to\nthe database.\n\n-- ndbm: int dbmpagfno (DBM *DBF)\nReturns the file descriptor of the 'pag' file of the database.  See\nalso 'dbmdirfno'.\n\n-- ndbm: int dbmrdonly (DBM *DBF)\nReturns '1' if the database DBF is open in a read-only mode and '0'\notherwise.\n\nFile: gdbm.info,  Node: dbm,  Prev: ndbm,  Up: Compatibility\n"
                },
                {
                    "name": "23.2 DBM interface functions",
                    "content": "The functions below are provided for compatibility with the old UNIX\n'DBM' interface.  Only one database at a time can be manipulated using\nthem.\n\n-- dbm: int dbminit (char *FILE)\nOpens a database.  The FILE argument is the full name of the\ndatabase file to be opened.  The function opens two files:\n'FILE.pag' and 'FILE.dir'.  If any of them does not exist, the\nfunction fails.  It never attempts to create the files.\n\nThe database is opened in the read-write mode, if its disk\npermissions permit.\n\nThe application must ensure that the functions described below in\nthis section are called only after a successful call to 'dbminit'.\n\n-- dbm: int dbmclose (void)\nCloses the database opened by an earlier call to 'dbminit'.\n\n-- dbm: datum fetch (datum KEY)\nReads a record from the database with the matching key.  The KEY\nargument supplies the key that is being looked for.\n\nIf no matching record is found, the 'dptr' member of the returned\ndatum is 'NULL'.  Otherwise, the 'dptr' member of the returned\ndatum points to the memory managed by the compatibility library.\nThe application should never free it.\n\n-- dbm: int store (datum KEY, datum CONTENT)\nStores the key/value pair in the database.  If a record with the\nmatching key already exists, its content will be replaced with the\nnew one.\n\nReturns '0' on success and '-1' on error.\n\n-- dbm: int delete (datum KEY)\nDeletes a record with the matching key.\n\nIf the function succeeds, '0' is returned.  Otherwise, if no\nmatching record is found or if an error occurs, '-1' is returned.\n\n-- dbm: datum firstkey (void)\nInitializes iteration over the keys from the database and returns\nthe first key.  Note, that the word 'first' does not imply any\nspecific ordering of the keys.\n\nIf there are no records in the database, the 'dptr' member of the\nreturned datum is 'NULL'.  Otherwise, the 'dptr' member of the\nreturned datum points to the memory managed by the compatibility\nlibrary.  The application should never free it.\n\n-- dbm: datum nextkey (datum KEY)\nContinues the iteration started by a call to 'firstkey'.  Returns\nthe next key in the database.  If the iteration covered all keys in\nthe database, the 'dptr' member of the returned datum is 'NULL'.\nOtherwise, the 'dptr' member of the returned datum points to the\nmemory managed by the compatibility library.  The application\nshould never free it.\n\nFile: gdbm.info,  Node: gdbmtool,  Next: gdbmdump,  Prev: Compatibility,  Up: Top\n"
                }
            ]
        },
        "24 Examine and modify a GDBM database": {
            "content": "The 'gdbmtool' utility allows you to view and modify an existing 'GDBM'\ndatabase or to create a new one.\n\nWhen invoked without arguments, it tries to open a database file\ncalled 'junk.gdbm', located in the current working directory.  You can\nchange this default by supplying the name of the database as argument to\nthe program, e.g.:\n\n$ gdbmtool file.db\n\nThe database will be opened in read-write mode, unless the '-r'\n('--read-only') option is specified, in which case it will be opened\nonly for reading.\n\nIf the database does not exist, 'gdbmtool' will create it.  There is\na special option '-n' ('--newdb'), which instructs the utility to create\na new database.  If it is used and if the database already exists, it\nwill be deleted, so use it sparingly.\n\n* Menu:\n\n* invocation::\n* shell::\n\nFile: gdbm.info,  Node: invocation,  Next: shell,  Up: gdbmtool\n",
            "subsections": [
                {
                    "name": "24.1 gdbmtool invocation",
                    "content": "When started without additional arguments, 'gdbmtool' operates on the\ndefault database 'junk.gdbm'.  Otherwise, the first argument supplies\nthe name of the database to operate upon.  If neither any additional\narguments nor the '-f' ('--file') option are given, 'gdbmtool' opens\nstarts interactive shell and receives commands directly from the human\noperator.\n\nIf more than one argument is given, all arguments past the database\nname are parsed as 'gdbmtool' commands (*note shell::, for a description\nof available commands) and executed in turn.  All commands, except the\nlast one, should be terminated with semicolons.  Semicolon after the\nlast command is optional.  Note, that semicolons should be escaped in\norder to prevent them from being interpreted by the shell.\n\nFinally, if the '-f' ('--file') option is supplied, its argument\nspecifies the name of the disk file with 'gdbmtool' script.  The program\nwill open that file and read commands from it.\n\nThe following table summarizes all 'gdbmtool' command line options:\n\n'-b SIZE'\n'--block-size=SIZE'\nSet block size.\n\n'-c SIZE'\n'--cache-size=SIZE'\nSet cache size.\n\n'-d FD'\n'--db-descriptor=FD'\nUse the database referred to by the file descriptor FD.  This must\nbe a valid open file descriptor, obtained by a call to 'open'\n(*note open a file: (open(2))open.), 'creat' or a similar function.\nThe database will be opened using 'gdbmfdopen' (*note\ngdbmfdopen::).\n\nThis option is intended for use by automatic test suites.\n\n'-f FILE'\n'--file FILE'\nRead commands from FILE, instead of the standard input.\n\n'-h'\n'--help'\nPrint a concise help summary.\n\n'-N'\n'--norc'\nDon't read startup files (*note startup files::).\n\n'-n'\n'--newdb'\nCreate the database.\n\n'-l'\n'--no-lock'\nDisable file locking.\n\n'-m'\n'--no-mmap'\nDisable memory mapping.\n\n'-T'\n'--timing'\nPrint time spent in each command.  This is equivalent to setting\nthe 'timing' variable.  *Note timing: variables.\n\n'-t'\n'--trace'\nEnable command tracing.  This is equivalent to setting the 'trace'\nvariable.  *Note trace: variables.\n\n'-q'\n'--quiet'\nDon't print the usual welcome banner at startup.  This is the same\nas setting the variable 'quiet' in the startup file.  *Note\nquiet::.\n\n'-r'\n'--read-only'\nOpen the database in read-only mode.\n\n'-s'\n'--synchronize'\nSynchronize to the disk after each write.\n\n'-V'\n'--version'\nPrint program version and licensing information and exit.\n\n'--usage'\nPrint a terse invocation syntax summary along with a list of\navailable command line options.\n\n'-x'\n'--extended'\n'--numsync'\nCreate new database in extended (numsync) format (*note Numsync::).\nThis option sets the 'format' variable to 'numsync'.  *Note format\nvariable::.\n\nFile: gdbm.info,  Node: shell,  Prev: invocation,  Up: gdbmtool\n"
                },
                {
                    "name": "24.2 gdbmtool interactive mode",
                    "content": "After successful startup, 'gdbmtool' starts a loop, in which it reads\ncommands from the standard input, executes them and prints results on\nthe standard output.  If the standard input is attached to a console,\n'gdbmtool' runs in interactive mode, which is indicated by its \"prompt\":\n\ngdbmtool>\n\nThe utility finishes when it reads the 'quit' command (see below) or\ndetects end-of-file on its standard input, whichever occurs first.\n\nA 'gdbmtool' command consists of a \"command verb\", optionally\nfollowed by \"arguments\", separated by any amount of white space and\nterminated with a newline or semicolon.  A command verb can be entered\neither in full or in an abbreviated form, as long as that abbreviation\ndoes not match any other verb.  For example, 'co' can be used instead of\n'count' and 'ca' instead of 'cache'.\n\nAny sequence of non-whitespace characters appearing after the command\nverb forms an argument.  If the argument contains whitespace or\nunprintable characters it must be enclosed in double quotes.  Within\ndouble quotes the usual \"escape sequences\" are understood, as shown in\nthe table below:\n\nSequence               Replaced with\n\\a                     Audible bell character (ASCII 7)\n\\b                     Backspace character (ASCII 8)\n\\f                     Form-feed character (ASCII 12)\n\\n                     Newline character (ASCII 10)\n\\r                     Carriage return character (ASCII\n13)\n\\t                     Horizontal tabulation character\n(ASCII 9)\n\\v                     Vertical tabulation character\n(ASCII 11)\n\\\\                     Single slash\n\\\"                     Double quote\n\nTable 24.1: Backslash escapes\n\nIn addition, a backslash immediately followed by the end-of-line\ncharacter effectively removes that character, allowing to split long\narguments over several input lines.\n\nCommand parameters may be optional or mandatory.  If the number of\nactual arguments is less than the number of mandatory parameters,\n'gdbmtool' will prompt you to supply missing arguments.  For example,\nthe 'store' command takes two mandatory parameters, so if you invoked it\nwith no arguments, you would be prompted twice to supply the necessary\ndata, as shown in example below:\n\ngdbmtool> store\nkey? three\ndata? 3\n\nHowever, such prompting is possible only in interactive mode.  In\nnon-interactive mode (e.g. when running a script), all arguments must be\nsupplied with each command, otherwise 'gdbmtool' will report an error\nand exit immediately.\n\nIf the package is compiled with GNU Readline, the input line can be\nedited (*note Command Line Editing: (readline)Command Line Editing.).\n\n* Menu:\n\n* variables::      shell variables.\n* commands::       shell commands.\n* definitions::    how to define structured data.\n* startup files::\n\nFile: gdbm.info,  Node: variables,  Next: commands,  Up: shell\n\n\nA number of 'gdbmtool' parameters is kept in its internal variables.  To\nexamine or modify variables, use the 'set' command (*note set::).\n\n-- gdbmtool variable: bool confirm\nWhether to ask for confirmation before certain destructive\noperations, such as truncating the existing database.\n\nDefault is 'true'.\n\n-- gdbmtool variable: string delim1\nA string used to delimit fields of a structured datum on output\n(*note definitions::).\n\nDefault is ',' (a comma).  This variable cannot be unset.\n\n-- gdbmtool variable: string delim2\nA string used to delimit array items when printing a structured\ndatum (*note definitions::).\n\nDefault is ',' (a comma).  This variable cannot be unset.\n\n-- gdbmtool variable: string errorexit\n-- gdbmtool variable: bool errorexit\nComma-delimited list of 'GDBM' error codes which cause program\ntermination.  Error codes are specified via their canonical names\n(*note Error codes::).  The 'GDBM' prefix can be omitted.  Code\nname comparison is case-insensitive.  Each error code can\noptionally be prefixed with minus sign, to indicate that it should\nbe removed from the resulting list, or with plus sign (which is\nallowed for symmetry).  A special code 'all' stands for all\navailable error codes.\n\nIn boolean context, the 'true' value is equivalent to 'all', and\n'false' (i.e.  variable unset) is equivalent to '-all'.\n\n-- gdbmtool variable: string errormask\n-- gdbmtool variable: bool errormask\nComma-delimited list of 'GDBM' error codes which are masked, i.e.\nwhich won't trigger a diagnostic message if they occur.  The syntax\nis the same as described for 'errorexit'.\n\n-- gdbmtool variable: string pager\nThe name and command line of the pager program to pipe output to.\nThis program is used in interactive mode when the estimated number\nof output lines is greater then the number of lines on your screen.\n\nThe default value is inherited from the environment variable\n'PAGER'.  Unsetting this variable disables paging.\n\n-- gdbmtool variable: string ps1\nPrimary prompt string.  Its value can contain \"conversion\nspecifiers\", consisting of the '%' character followed by another\ncharacter.  These specifiers are expanded in the resulting prompt\nas follows:\n\n%f                            name of the current database file\n%p                            program invocation name\n%P                            package name ('GDBM')\n%v                            program version\n%                            single space character\n%%                            %\n\nThe default value is '%p>%', i.e.  the program name, followed by a\n\"greater than\" sign, followed by a single space.\n\n-- gdbmtool variable: string ps2\nSecondary prompt.  See 'ps1' for a description of its value.  This\nprompt is displayed before reading the second and subsequent lines\nof a multi-line command.\n\nThe default value is '%>%'.\n\n-- gdbmtool variable: bool timing\nWhen each command terminates, print an additional line listing\ntimes spent in that command.  The line is formatted as follows:\n\n[reorganize r=0.070481 u=0.000200 s=0.000033]\n\nHere, 'reorganize' is the name of the command that finished, the\nnumber after 'r=' is real time spent executing the command, the\nnumber after 'u=' is the user CPU time used and the number after\n's=' is the system CPU time used.\n\n-- gdbmtool variable: bool trace\nEnable command tracing.  This is similar to the shell '-t' option:\nbefore executing each command, 'gdbmtool' will print on standard\nerror a line starting with a plus sign and followed by the command\nname and its arguments.\n\n-- gdbmtool variable: bool quiet\nWhether to display a welcome banner at startup.  To affect\n'gdbmtool', this variable should be set in a startup script file\n(*note startup files::).  *Note -q option::.\n\nThe following variables control how the database is opened:\n\n-- gdbmtool variable: numeric blocksize\nSets the block size.  *Note blocksize: Open.  Unset by default.\n\n-- gdbmtool variable: numeric cachesize\nSets the cache size.  *Note GDBMSETCACHESIZE: Options.\n\nThis variable affects the currently opened database immediately.\nIt is also used by 'open' command.\n\nTo enable automatic cache size selection, unset this variable.\nThis is the default.\n\n-- gdbmtool variable: string filename\nName of the database file.  If the 'open' command is called without\nargument (e.g.  called implicitly), this variable names the\ndatabase file to open.  If 'open' is called with file name\nargument, upon successful opening of the database the 'filename'\nvariable is initialized with its file name.\n\nThis variable cannot be unset.\n\n-- gdbmtool variable: number fd\nFile descriptor of the database file to open.  If this variable is\nset, its value must be an open file descriptor referring to a\n'GDBM' database file.  The 'open' command will use 'gdbmfdopen'\nfunction to use this file (*note gdbmfdopen::).  When this\ndatabase is closed, the descriptor will be closed as well and the\n'fd' variable will be unset.\n\nSee also the '-d' ('--db-descriptor') command line option in *note\ninvocation::.\n\n-- gdbmtool variable: string format\nDefines the format in which new databases will be created.  Allowed\nvalues are:\n\n'standard'\nDatabases will be created in standard format.  This is the\nformat used by all 'GDBM' versions prior to 1.21.  This value\nis the default.\n\n'numsync'\nExtended format, best for crash-tolerant applications.  *Note\nNumsync::, for a discussion of this format.\n\n-- gdbmtool variable: string open\nOpen mode.  The following values are allowed:\n\nnewdb\nTruncate the database if it exists or create a new one.  Open\nit in read-write mode.\n\nTechnically, this sets the 'GDBMNEWDB' flag in call to\n'gdbmopen'.  *Note GDBMNEWDB: Open.\nwrcreat\nrw\nOpen the database in read-write mode.  Create it if it does\nnot exist.  This is the default.\n\nTechnically speaking, it sets the 'GDBMWRCREAT' flag in call\nto 'gdbmopen'.  *Note GDBMWRCREAT: Open.\nreader\nreadonly\nOpen the database in read-only mode.  Signal an error if it\ndoes not exist.\n\nThis sets the 'GDBMREADER' flag (*note GDBMREADER: Open.).\n\nAttempting to set any other value or to unset this variable results\nin error.\n\n-- gdbmtool variable: number filemode\nFile mode (in octal) for creating new database files and database\ndumps.\n\n-- gdbmtool variable: bool lock\nLock the database.  This is the default.\n\nSetting this variable to false or unsetting it results in passing\n'GDBMNOLOCK' flag to 'gdbmopen' (*note GDBMNOLOCK: Open.).\n\n-- gdbmtool variable: bool mmap\nUse memory mapping.  This is the default.\n\nSetting this variable to false or unsetting it results in passing\n'GDBMNOMMAP' flag to 'gdbmopen' (*note GDBMNOMMAP: Open.).\n\n-- gdbmtool variable: bool sync\nFlush all database writes on disk immediately.  Default is false.\n*Note GDBMSYNC: Open.\n\n-- gdbmtool variable: bool coalesce\nEnables the coalesce mode, i.e.  merging of the freed blocks of\n'GDBM' files with entries in available block lists.  This provides\nfor effective memory management at the cost of slight increase in\nexecution time when calling 'gdbmdelete'.  *Note\nGDBMSETCOALESCEBLKS: Options.\n\nThis variable affects the currently opened database immediately and\nwill be used by 'open' command, when it is invoked.\n\n-- gdbmtool variable: bool centfree\nSet to 'true', enables the use of central free block pool in newly\nopened databases.  *Note GDBMSETCENTFREE: Options.\n\nThis variable affects the currently opened database immediately and\nwill be used by 'open' command, when it is invoked.\n\nThe following commands are used to list or modify the variables:\n\n-- command verb: set [ASSIGNMENTS]\nWhen used without arguments, lists all variables and their values.\nUnset variables are shown after a comment sign ('#').  For string\nand numeric variables, values are shown after an equals sign.  For\nboolean variables, only the variable name is displayed if the\nvariable is 'true'.  If it is 'false', its name is prefixed with\n'no'.\n\nFor example:\n\n# blocksize is unset\n# cachesize is unset\nnocentfree\nnocoalesce\nconfirm\ndelim1=\",\"\ndelim2=\",\"\n# fd is unset\nfilemode=644\nfilename=\"junk.gdbm\"\nformat=\"standard\"\nlock\nmmap\nopen=\"wrcreat\"\npager=\"less\"\nps1=\"%p>%\"\nps2=\"%>%\"\n# quiet is unset\nnosync\n\nIf used with arguments, the 'set' command alters the specified\nvariables.  In this case, arguments are variable assignments in the\nform 'NAME=VALUE'.  For boolean variables, the VALUE is interpreted\nas follows: if it is numeric, '0' stands for 'false', any non-zero\nvalue stands for 'true'.  Otherwise, the values 'on', 'true', and\n'yes' denote 'true', and 'off', 'false', 'no' stand for 'false'.\nAlternatively, only the name of a boolean variable can be supplied\nto set it to 'true', and its name prefixed with 'no' can be used to\nset it to false.  For example, the following command sets the\n'delim2' variable to ';' and the 'confirm' variable to 'false':\n\nset delim2=\";\" noconfirm\n\n-- command verb: unset VARIABLES\nUnsets the listed variables.  The effect of unsetting depends on\nthe variable.  Unless explicitly described in the discussion of the\nvariables above, unsetting a boolean variable is equivalent to\nsetting it to 'false'.  Unsetting a string variable is equivalent\nto assigning it an empty string.\n\nFile: gdbm.info,  Node: commands,  Next: definitions,  Prev: variables,  Up: shell\n\n\n-- command verb: avail\nPrint the \"avail list\".\n\n-- command verb: bucket NUM\nPrint the bucket number NUM and set it as the current one.\n\n-- command verb: cache\nPrint the bucket cache.\n\n-- command verb: close\nClose the currently open database.\n\n-- command verb: count\nPrint the number of entries in the database.\n\n-- command verb: current\nPrint the current bucket.\n\n-- command verb: debug [[+-]TOKEN...]\nIf 'GDBM' is configured with additional debugging, this statement\nqueries or sets 'GDBM' internal debugging level.  This is intended\nfor debugging and testing purposes and requires good knowledge of\n'GDBM' internals.  The use of this command is not recommended.\n\n-- command verb: delete KEY\nDelete record with the given KEY\n\n-- command verb: dir\nPrint hash directory.\n\n-- command verb: downgrade\nDowngrade the database from extended to the standard database\nformat.  *Note Numsync::.\n\n-- command verb: export FILE-NAME [truncate] [binary|ascii]\nExport the database to the flat file FILE-NAME.  *Note Flat\nfiles::, for a description of the flat file format and its\npurposes.  This command will not overwrite an existing file, unless\nthe 'truncate' parameter is also given.  Another optional argument\ndetermines the type of the dump (*note Flat files::).  By default,\nASCII dump is created.\n\nThe global variable 'filemode' specifies the permissions to use for\nthe created output file.\n\n-- command verb: fetch KEY\nFetch and display the record with the given KEY.\n\n-- command verb: first\nFetch and display the first record in the database.  Subsequent\nrecords can be fetched using the 'next' command (see below).  *Note\nSequential::, for more information on sequential access.\n\n-- command verb: hash KEY\nCompute and display the hash value for the given KEY.\n\n-- command verb: header\nPrint file header.\n\n-- command verb: help\n-- command verb: ?\nPrint a concise command summary, showing each command verb with its\nparameters and a short description of what it does.  Optional\narguments are enclosed in square brackets.\n\n-- command verb: import FILE-NAME [replace] [nometa]\nImport data from a flat dump file FILE-NAME (*note Flat files::).\nIf the word 'replace' is given as an argument, any records with the\nsame keys as the already existing ones will replace them.  The word\n'nometa' turns off restoring meta-information from the dump file.\n\n-- command verb: history\n-- command verb: history COUNT\n-- command verb: history N COUNT\nShows the command history list with line numbers.  When used\nwithout arguments, shows entire history.  When used with one\nargument, displays COUNT last commands from the history.  With two\narguments, displays COUNT commands starting from Nth command.\nCommand numbering starts with 1.\n\nThis command is available only if 'GDBM' was compiled with GNU\nReadline.  The history is saved in file '.gdbmtoolhistory' in the\nuser's home directory.  If this file exists upon startup, it is\nread to populate the history.  Thus, command history is preserved\nbetween 'gdbmtool' invocations.\n\n-- command verb: list\nList the contents of the database.\n\n-- command verb: next [KEY]\nSequential access: fetch and display the next record.  If the KEY\nis given, the record following the one with this key will be\nfetched.\n\nIssuing several 'next' commands in row is rather common.  A\nshortcut is provided to facilitate such use: if the last entered\ncommand was 'next', hitting the 'Enter' key repeats it without\narguments.\n\nSee also 'first', above.\n\n*Note Sequential::, for more information on sequential access.\n\n-- command verb: open FILENAME\n-- command verb: open\nOpen the database file FILENAME.  If used without arguments, the\ndatabase name is taken from the variable 'filename'.\n\nIf successful, any previously open database is closed and the\n'filename' variable is updated.  Otherwise, if the operation fails,\nthe currently opened database remains unchanged.\n\nThis command takes additional information from the following\nvariables:\n\n'filename'\nName of the database to open, if no argument is given.\n\n'fd'\nFile descriptor to use.  If set, this must be an open file\ndescriptor referring to a valid database file.  The database\nwill be opened using 'gdbmfdopen' (*note gdbmfdopen::).\nThe file descriptor will be closed and the variable unset upon\nclosing the database.\n\n'filemode'\nSpecifies the permissions to use in case a new file is\ncreated.\n\n'open'\nThe database access mode.  *Note The OPEN variable: openvar,\nfor a list of its values.\n\n'lock'\nWhether or not to lock the database.  Default is 'on'.\n\n'mmap'\nUse the memory mapping.  Default is 'on'.\n\n'sync'\nSynchronize after each write.  Default is 'off'.\n\n*Note open parameters::, for a detailed description of these\nvariables.\n\n-- command verb: perror [CODE]\nDescribe the given 'GDBM' error code.\n\nThe description occupies one or two lines.  The second line is\npresent if the system error number should be checked when handling\nthis code.  In this case, the second line states 'Examine errno'.\n\nIf CODE is omitted, the latest error that occurred in the current\ndatabase is described.  Second line of the output (if present),\ncontains description of the latest system error.\n\nExample:\n\ngdbmtool> perror 3\nGDBM error code 3: \"File open error\"\nExamine errno.\n\n-- command verb: quit\nClose the database and quit the utility.\n\n-- command verb: recover [OPTIONS]\nRecover the database from structural inconsistencies.  *Note\nDatabase consistency::.\n\nThe following OPTIONS are understood:\n\n'backup'\nCreate a backup copy of the original database.\n\n'max-failed-buckets=N'\nAbort recovery process if N buckets could not be recovered.\n\n'max-failed-keys=N'\nAbort recovery process if N keys could not be recovered.\n\n'max-failures=N'\nAbort recovery process after N failures.  A \"failure\" in this\ncontext is either a key or a bucket that failed to be\nrecovered.\n\n'summary'\nPrint the recovery statistics at the end of the run.  The\nstatistics includes number of successfully recovered, failed\nand duplicate keys and the number of recovered and failed\nbuckets.\n\n'verbose'\nVerbosely list each error encountered.\n\n-- command verb: reorganize\nReorganize the database (*note Reorganization::).\n\n-- command verb: shell COMMAND\n-- command verb: ! COMMAND\nExecute COMMAND via current shell.  If COMMAND is empty, shell is\nstarted without additional arguments.  Otherwise, it is run as\n'$SHELL -c COMMAND'.\n\nFor convenience, COMMAND is not parsed as 'gdbmtool' command line.\nIt is passed to the shell verbatim.  It can include newline\ncharacters if these are preceded by a backslash or appear within\nsingly or doubly quoted strings.\n\nWhen using '!' form, be sure to separate it from COMMAND by\nwhitespace, otherwise it will be treated as readline \"event\nspecifier\".\n\n-- command verb: snapshot FILENAME FILENAME\nAnalyze two snapshot files and select the most recent of them.  In\ncase of error, display a detailed diagnostics and meta-information\nof both snapshots.\n\n*Note Manual crash recovery::, for a detailed discussion.\n\n-- command verb: source FILENAME\nRead 'gdbmtool' commands from the file FILENAME.\n\n-- command verb: status\nPrint current program status.  The following example shows the\ninformation displayed:\n\nDatabase file: junk.gdbm\nDatabase is open\ndefine key string\ndefine content string\n\nThe two 'define' strings show the defined formats for key and\ncontent data.  *Note definitions::, for a detailed discussion of\ntheir meaning.\n\n-- command verb: store KEY DATA\nStore the DATA with KEY in the database.  If KEY already exists,\nits data will be replaced.\n\n-- command verb: sync\nSynchronize the database with the disk storage (*note Sync::).\n\n-- command verb: upgrade\nUpgrade the database from standard to extended database format.\n*Note Numsync::.\n\n-- command verb: version\nPrint the version of 'gdbm'.\n\nFile: gdbm.info,  Node: definitions,  Next: startup files,  Prev: commands,  Up: shell\n\n\n'GDBM' databases are able to keep data of any type, both in the key and\nin the content part of a record.  Quite often these data are structured,\ni.e.  they consist of several fields of various types.  'Gdbmtool'\nprovides a mechanism for handling such kind of records.\n\nThe 'define' command defines a record structure.  The general syntax\nis:\n\ndefine WHAT DEFINITION\n\nwhere WHAT is 'key' to defining the structure of key data and 'content'\nto define the structure of the content records.\n\nThe DEFINITION can be of two distinct formats.  In the simplest case\nit is a single data type.  For example,\n\ndefine content int\n\ndefines content records consisting of a single integer field.  Supported\ndata types are:\n\nchar\nSingle byte (signed).\nshort\nSigned short integer.\nushort\nUnsigned short integer.\nint\nSigned integer.\nunsigned\nuint\nUnsigned integer.\nlong\nSigned long integer.\nulong\nUnsigned long integer.\nllong\nSigned long long integer.\nullong\nUnsigned long long integer.\nfloat\nA floating point number.\ndouble\nDouble-precision floating point number.\nstring\nArray of bytes.\nstringz\nNull-terminated string, trailing null being part of the string.\n\nAll numeric data types (integer as well as floating point) have the\nsame respective widths as in C language on the host where the database\nfile resides.\n\nThe 'string' and 'stringz' are special.  Both define a string of\nbytes, similar to 'char x[]' in C. The former defines an array of bytes,\nthe latter - a null-terminated string.  This makes a difference, in\nparticular, when the string is the only part of datum.  Consider the\nfollowing two definitions:\n\n1. 'define key string'\n2. 'define key stringz'\n\nNow, suppose we want to store the string \"ab\" in the key.  Using the\ndefinition (1), the 'dptr' member of 'GDBM' 'datum' will contain two\nbytes: 'a', and 'b'.  Consequently, the 'dsize' member will have the\nvalue 2.  Using the definition (2), the 'dptr' member will contain three\nbytes: 'a', 'b', and ASCII 0.  The 'dsize' member will have the value 3.\n\nThe definition (1) is the default for both key and content.\n\nThe second form of the 'define' statement is similar to the C\n'struct' statement and allows for defining structural data.  In this\nform, the DEFINITION part is a comma-separated list of data types and\nvariables enclosed in curly braces.  In contrast to the rest of 'gdbm'\ncommands, this command is inherently multiline and is terminated with\nthe closing curly brace.  For example:\n\ndefine content {\nint status,\npad 8,\nchar id[3],\nstring name\n}\n\nThis defines a structure consisting of three members: an integer\n'status', an array of 3 bytes 'id', and an array of bytes 'name'.\nNotice the 'pad' statement: it allows to introduce padding between\nstructure members.  Another useful statement is 'offset': it specifies\nthat the member following it begins at the given offset in the\nstructure.  Assuming the size of 'int' is 8 bytes, the above definition\ncan also be written as\n\ndefine content {\nint status,\noffset 16,\nchar id[3],\nstring name\n}\n\nNOTE: The 'string' type can reasonably be used only if it is the\nlast or the only member of the data structure.  That's because it\nprovides no information about the number of elements in the array, so it\nis interpreted to contain all bytes up to the end of the datum.\n\nWhen displaying the structured data, 'gdbmtool' precedes each value\nwith the corresponding field name and delimits parts of the structure\nwith the string defined in the 'delim1' variable (*note variables::).\nArray elements are delimited using the string from 'delim2'.  For\nexample:\n\ngdbmtool> fetch foo\nstatus=2,id={ a, u, x },name=\"quux\"\n\nTo supply a structured datum as an argument to a 'gdbmtool' command,\nuse the same notation, e.g.:\n\ngdbmtool> store newkey { status=2, id={a,u,x}, name=\"quux\" }\n\nThe order in which the fields are listed is not significant.  The\nabove command can as well be written as:\n\ngdbmtool> store newkey { id={a,u,x}, status=2, name=\"quux\" }\n\nYou are not required to supply all defined fields.  Any number of\nthem can be omitted, provided that at least one remains.  The omitted\nfields are filled with 0:\n\ngdbmtool> store newkey { name=\"bar\" }\ngdbmtool> fetch newkey\nstatus=0,id={ ,, },name=bar\n\nYet another way to supply structured data to a command is by listing\nthe value for each field in the order they are defined, without field\nnames:\n\ngdbmtool> store newkey { 2, {a,u,x}, \"quux\" }\n\nFile: gdbm.info,  Node: startup files,  Prev: definitions,  Up: shell\n\n\nUpon startup 'gdbmtool' looks for a file named '.gdbmtoolrc' first in\nthe current working directory and, if not found, in the home directory\nof the user who started the command.\n\nIf found, this file is read and interpreted as a list of 'gdbmtool'\ncommands.  This allows you to customize the program behavior.\n\nFollowing is an example startup file which disables the welcome\nbanner, sets command line prompt to contain the name of the database\nfile in parentheses and defines the structure of the database content\nrecords:\n\nset quiet\nset ps1=\"(%f) \"\ndefine key stringz\ndefine content {\nint time,\npad 4,\nint status\n}\n\nFile: gdbm.info,  Node: gdbmdump,  Next: gdbmload,  Prev: gdbmtool,  Up: Top\n"
                }
            ]
        },
        "25 The 'gdbmdump' utility": {
            "content": "The 'gdbmdump' utility creates a flat file dump of a 'GDBM' database\n(*note Flat files::).  It takes one mandatory argument: the name of the\nsource database file.  The second argument, if given, specifies the name\nof the output file.  If not given, 'gdbmdump' will produce the dump on\nthe standard output.\n\nFor example, the following invocation creates a dump of the database\n'file.db' in the file 'file.dump':\n\n$ gdbmdump file.db file.dump\n\nBy default the utility creates dumps in ASCII format (*note ASCII:\nFlat files.).  Another format can be requested using the '--format'\n('-H') option.\n\nThe 'gdbmdump' utility understands the following command line\noptions:\n\n'-H FMT'\n'--format=FMT'\nSelect output format.  Valid values for FMT are: 'binary' or '0' to\nselect binary dump format, and 'ascii' or '1' to select ASCII\nformat.\n\n'-h'\n'--help'\nPrint a concise help summary.\n\n'-V'\n'--version'\nPrint program version and licensing information and exit.\n\n'--usage'\nPrint a terse invocation syntax summary along with a list of\navailable command line options.\n\nFile: gdbm.info,  Node: gdbmload,  Next: Exit codes,  Prev: gdbmdump,  Up: Top\n",
            "subsections": []
        },
        "26 The 'gdbmload' utility": {
            "content": "The 'gdbmload' utility restores a 'GDBM' database from a flat file.\nThe utility requires at least one argument: the name of the input flat\nfile.  If it is '-', the standard input will be read.  The format of the\ninput file is detected automatically.\n\nBy default the utility attempts to restore the database under its\noriginal name, as stored in the input file.  It will fail to do so if\nthe input is in binary format.  In that case, the name of the database\nmust be given as the second argument.\n\nIn general, if two arguments are given, the second one is treated as\nthe name of the database to create, overriding the file name specified\nin the flat file.\n\nThe utility understands the following command line arguments:\n\n'-b NUM'\n'--block-size=NUM'\nSets block size.  *Note blocksize: Open.\n\n'-c NUM'\n'--cache-size=NUM'\nSets cache size.  *Note GDBMSETCACHESIZE: Options.\n\n'-M'\n'--mmap'\nUse memory mapping.\n\n'-m MODE'\n'--mode=MODE'\nSets the file mode.  The argument is the desired file mode in\noctal.\n\n'-n'\n'--no-meta'\nDo not restore file meta-data (ownership and mode) from the flat\nfile.\n\n'-r'\n'--replace'\nReplace existing keys.\n\n'-u USER[:GROUP]'\n'--user=USER[:GROUP]'\nSet file owner.  The USER can be either a valid user name or UID.\nSimilarly, the GROUP is either a valid group name or GID. If GROUP\nis not given, the main group of USER is used.\n\nUser and group parts can be separated by a dot, instead of the\ncolon.\n\n'-h'\n'--help'\nPrint a concise help summary.\n\n'-V'\n'--version'\nPrint program version and licensing information and exit.\n\n'--usage'\nPrint a terse invocation syntax summary along with a list of\navailable command line options.\n\nFile: gdbm.info,  Node: Exit codes,  Next: Bugs,  Prev: gdbmload,  Up: Top\n",
            "subsections": []
        },
        "27 Exit codes": {
            "content": "All 'GDBM' utilities return uniform exit codes.  These are summarized in\nthe table below:\n\n0                      Successful termination.\n1                      A fatal error occurred.\n2                      Program was unable to restore file ownership or\nmode.\n3                      Command line usage error.\n\nFile: gdbm.info,  Node: Bugs,  Next: Resources,  Prev: Exit codes,  Up: Top\n",
            "subsections": []
        },
        "28 Problems and bugs": {
            "content": "If you have problems with GNU 'dbm' or think you've found a bug, please\nreport it.  Before reporting a bug, make sure you've actually found a\nreal bug.  Carefully reread the documentation and see if it really says\nyou can do what you're trying to do.  If it's not clear whether you\nshould be able to do something or not, report that too; it's a bug in\nthe documentation!\n\nBefore reporting a bug or trying to fix it yourself, try to isolate\nit to the smallest possible input file that reproduces the problem.\nThen send us the input file and the exact results 'GDBM' gave you.  Also\nsay what you expected to occur; this will help us decide whether the\nproblem was really in the documentation.\n\nOnce you've got a precise problem, send e-mail to <bug-gdbm@gnu.org>.\n\nPlease include the version number of GNU 'dbm' you are using.  You\ncan get this information by printing the variable 'gdbmversion' (*note\nVariables::).\n\nNon-bug suggestions are always welcome as well.  If you have\nquestions about things that are unclear in the documentation or are just\nobscure features, please report them too.\n\nYou may contact the authors and maintainers by e-mail: Philip Nelson\n<phil@cs.wwu.edu>, Jason Downs <downsj@downsj.com>, Sergey Poznyakoff\n<gray@gnu.org> or <gray@gnu.org.ua>.\n\nCrash tolerance support written by Terence Kelly <tpkelly@acm.org>,\n<tpkelly@cs.princeton.edu>, or <tpkelly@eecs.umich.edu>.\n\nFile: gdbm.info,  Node: Resources,  Next: GNU Free Documentation License,  Prev: Bugs,  Up: Top\n",
            "subsections": []
        },
        "29 Additional resources": {
            "content": "For the latest updates and pointers to additional resources, visit\n<http://www.gnu.org/software/gdbm>.\n\nIn particular, a copy of 'GDBM' documentation in various formats is\navailable online at <http://www.gnu.org/software/gdbm/manual.html>.\n\nLatest versions of 'GDBM' can be downloaded from anonymous FTP:\n<ftp://ftp.gnu.org/gnu/gdbm>, or via HTTP from\n<http://ftp.gnu.org/gnu/gdbm>, or via HTTPS from\n<https://ftp.gnu.org/gnu/gdbm>, or from any GNU mirror worldwide.  See\n<http://www.gnu.org/order/ftp.html>, for a list of mirrors.\n\nTo track 'GDBM' development, visit\n<http://puszcza.gnu.org.ua/projects/gdbm>.\n\nFile: gdbm.info,  Node: GNU Free Documentation License,  Next: Index,  Prev: Resources,  Up: Top\n",
            "subsections": []
        },
        "Appendix A GNU Free Documentation License": {
            "content": "Version 1.3, 3 November 2008\n\nCopyright (C) 2000-2002, 2007-2008, 2011, 2017-2022 Free\nSoftware Foundation, Inc.\n<http://fsf.org/>\n\nEveryone is permitted to copy and distribute verbatim copies\nof this license document, but changing it is not allowed.\n\n0. PREAMBLE\n\nThe purpose of this License is to make a manual, textbook, or other\nfunctional and useful document \"free\" in the sense of freedom: to\nassure everyone the effective freedom to copy and redistribute it,\nwith or without modifying it, either commercially or\nnoncommercially.  Secondarily, this License preserves for the\nauthor and publisher a way to get credit for their work, while not\nbeing considered responsible for modifications made by others.\n\nThis License is a kind of \"copyleft\", which means that derivative\nworks of the document must themselves be free in the same sense.\nIt complements the GNU General Public License, which is a copyleft\nlicense designed for free software.\n\nWe have designed this License in order to use it for manuals for\nfree software, because free software needs free documentation: a\nfree program should come with manuals providing the same freedoms\nthat the software does.  But this License is not limited to\nsoftware manuals; it can be used for any textual work, regardless\nof subject matter or whether it is published as a printed book.  We\nrecommend this License principally for works whose purpose is\ninstruction or reference.\n\n1. APPLICABILITY AND DEFINITIONS\n\nThis License applies to any manual or other work, in any medium,\nthat contains a notice placed by the copyright holder saying it can\nbe distributed under the terms of this License.  Such a notice\ngrants a world-wide, royalty-free license, unlimited in duration,\nto use that work under the conditions stated herein.  The\n\"Document\", below, refers to any such manual or work.  Any member\nof the public is a licensee, and is addressed as \"you\".  You accept\nthe license if you copy, modify or distribute the work in a way\nrequiring permission under copyright law.\n\nA \"Modified Version\" of the Document means any work containing the\nDocument or a portion of it, either copied verbatim, or with\nmodifications and/or translated into another language.\n\nA \"Secondary Section\" is a named appendix or a front-matter section\nof the Document that deals exclusively with the relationship of the\npublishers or authors of the Document to the Document's overall\nsubject (or to related matters) and contains nothing that could\nfall directly within that overall subject.  (Thus, if the Document\nis in part a textbook of mathematics, a Secondary Section may not\nexplain any mathematics.)  The relationship could be a matter of\nhistorical connection with the subject or with related matters, or\nof legal, commercial, philosophical, ethical or political position\nregarding them.\n\nThe \"Invariant Sections\" are certain Secondary Sections whose\ntitles are designated, as being those of Invariant Sections, in the\nnotice that says that the Document is released under this License.\nIf a section does not fit the above definition of Secondary then it\nis not allowed to be designated as Invariant.  The Document may\ncontain zero Invariant Sections.  If the Document does not identify\nany Invariant Sections then there are none.\n\nThe \"Cover Texts\" are certain short passages of text that are\nlisted, as Front-Cover Texts or Back-Cover Texts, in the notice\nthat says that the Document is released under this License.  A\nFront-Cover Text may be at most 5 words, and a Back-Cover Text may\nbe at most 25 words.\n\nA \"Transparent\" copy of the Document means a machine-readable copy,\nrepresented in a format whose specification is available to the\ngeneral public, that is suitable for revising the document\nstraightforwardly with generic text editors or (for images composed\nof pixels) generic paint programs or (for drawings) some widely\navailable drawing editor, and that is suitable for input to text\nformatters or for automatic translation to a variety of formats\nsuitable for input to text formatters.  A copy made in an otherwise\nTransparent file format whose markup, or absence of markup, has\nbeen arranged to thwart or discourage subsequent modification by\nreaders is not Transparent.  An image format is not Transparent if\nused for any substantial amount of text.  A copy that is not\n\"Transparent\" is called \"Opaque\".\n\nExamples of suitable formats for Transparent copies include plain\nASCII without markup, Texinfo input format, LaTeX input format,\nSGML or XML using a publicly available DTD, and standard-conforming\nsimple HTML, PostScript or PDF designed for human modification.\nExamples of transparent image formats include PNG, XCF and JPG.\nOpaque formats include proprietary formats that can be read and\nedited only by proprietary word processors, SGML or XML for which\nthe DTD and/or processing tools are not generally available, and\nthe machine-generated HTML, PostScript or PDF produced by some word\nprocessors for output purposes only.\n\nThe \"Title Page\" means, for a printed book, the title page itself,\nplus such following pages as are needed to hold, legibly, the\nmaterial this License requires to appear in the title page.  For\nworks in formats which do not have any title page as such, \"Title\nPage\" means the text near the most prominent appearance of the\nwork's title, preceding the beginning of the body of the text.\n\nThe \"publisher\" means any person or entity that distributes copies\nof the Document to the public.\n\nA section \"Entitled XYZ\" means a named subunit of the Document\nwhose title either is precisely XYZ or contains XYZ in parentheses\nfollowing text that translates XYZ in another language.  (Here XYZ\nstands for a specific section name mentioned below, such as\n\"Acknowledgements\", \"Dedications\", \"Endorsements\", or \"History\".)\nTo \"Preserve the Title\" of such a section when you modify the\nDocument means that it remains a section \"Entitled XYZ\" according\nto this definition.\n\nThe Document may include Warranty Disclaimers next to the notice\nwhich states that this License applies to the Document.  These\nWarranty Disclaimers are considered to be included by reference in\nthis License, but only as regards disclaiming warranties: any other\nimplication that these Warranty Disclaimers may have is void and\nhas no effect on the meaning of this License.\n\n2. VERBATIM COPYING\n\nYou may copy and distribute the Document in any medium, either\ncommercially or noncommercially, provided that this License, the\ncopyright notices, and the license notice saying this License\napplies to the Document are reproduced in all copies, and that you\nadd no other conditions whatsoever to those of this License.  You\nmay not use technical measures to obstruct or control the reading\nor further copying of the copies you make or distribute.  However,\nyou may accept compensation in exchange for copies.  If you\ndistribute a large enough number of copies you must also follow the\nconditions in section 3.\n\nYou may also lend copies, under the same conditions stated above,\nand you may publicly display copies.\n\n3. COPYING IN QUANTITY\n\nIf you publish printed copies (or copies in media that commonly\nhave printed covers) of the Document, numbering more than 100, and\nthe Document's license notice requires Cover Texts, you must\nenclose the copies in covers that carry, clearly and legibly, all\nthese Cover Texts: Front-Cover Texts on the front cover, and\nBack-Cover Texts on the back cover.  Both covers must also clearly\nand legibly identify you as the publisher of these copies.  The\nfront cover must present the full title with all words of the title\nequally prominent and visible.  You may add other material on the\ncovers in addition.  Copying with changes limited to the covers, as\nlong as they preserve the title of the Document and satisfy these\nconditions, can be treated as verbatim copying in other respects.\n\nIf the required texts for either cover are too voluminous to fit\nlegibly, you should put the first ones listed (as many as fit\nreasonably) on the actual cover, and continue the rest onto\nadjacent pages.\n\nIf you publish or distribute Opaque copies of the Document\nnumbering more than 100, you must either include a machine-readable\nTransparent copy along with each Opaque copy, or state in or with\neach Opaque copy a computer-network location from which the general\nnetwork-using public has access to download using public-standard\nnetwork protocols a complete Transparent copy of the Document, free\nof added material.  If you use the latter option, you must take\nreasonably prudent steps, when you begin distribution of Opaque\ncopies in quantity, to ensure that this Transparent copy will\nremain thus accessible at the stated location until at least one\nyear after the last time you distribute an Opaque copy (directly or\nthrough your agents or retailers) of that edition to the public.\n\nIt is requested, but not required, that you contact the authors of\nthe Document well before redistributing any large number of copies,\nto give them a chance to provide you with an updated version of the\nDocument.\n\n4. MODIFICATIONS\n\nYou may copy and distribute a Modified Version of the Document\nunder the conditions of sections 2 and 3 above, provided that you\nrelease the Modified Version under precisely this License, with the\nModified Version filling the role of the Document, thus licensing\ndistribution and modification of the Modified Version to whoever\npossesses a copy of it.  In addition, you must do these things in\nthe Modified Version:\n\nA. Use in the Title Page (and on the covers, if any) a title\ndistinct from that of the Document, and from those of previous\nversions (which should, if there were any, be listed in the\nHistory section of the Document).  You may use the same title\nas a previous version if the original publisher of that\nversion gives permission.\n\nB. List on the Title Page, as authors, one or more persons or\nentities responsible for authorship of the modifications in\nthe Modified Version, together with at least five of the\nprincipal authors of the Document (all of its principal\nauthors, if it has fewer than five), unless they release you\nfrom this requirement.\n\nC. State on the Title page the name of the publisher of the\nModified Version, as the publisher.\n\nD. Preserve all the copyright notices of the Document.\n\nE. Add an appropriate copyright notice for your modifications\nadjacent to the other copyright notices.\n\nF. Include, immediately after the copyright notices, a license\nnotice giving the public permission to use the Modified\nVersion under the terms of this License, in the form shown in\nthe Addendum below.\n\nG. Preserve in that license notice the full lists of Invariant\nSections and required Cover Texts given in the Document's\nlicense notice.\n\nH. Include an unaltered copy of this License.\n\nI. Preserve the section Entitled \"History\", Preserve its Title,\nand add to it an item stating at least the title, year, new\nauthors, and publisher of the Modified Version as given on the\nTitle Page.  If there is no section Entitled \"History\" in the\nDocument, create one stating the title, year, authors, and\npublisher of the Document as given on its Title Page, then add\nan item describing the Modified Version as stated in the\nprevious sentence.\n\nJ. Preserve the network location, if any, given in the Document\nfor public access to a Transparent copy of the Document, and\nlikewise the network locations given in the Document for\nprevious versions it was based on.  These may be placed in the\n\"History\" section.  You may omit a network location for a work\nthat was published at least four years before the Document\nitself, or if the original publisher of the version it refers\nto gives permission.\n\nK. For any section Entitled \"Acknowledgements\" or \"Dedications\",\nPreserve the Title of the section, and preserve in the section\nall the substance and tone of each of the contributor\nacknowledgements and/or dedications given therein.\n\nL. Preserve all the Invariant Sections of the Document, unaltered\nin their text and in their titles.  Section numbers or the\nequivalent are not considered part of the section titles.\n\nM. Delete any section Entitled \"Endorsements\".  Such a section\nmay not be included in the Modified Version.\n\nN. Do not retitle any existing section to be Entitled\n\"Endorsements\" or to conflict in title with any Invariant\nSection.\n\nO. Preserve any Warranty Disclaimers.\n\nIf the Modified Version includes new front-matter sections or\nappendices that qualify as Secondary Sections and contain no\nmaterial copied from the Document, you may at your option designate\nsome or all of these sections as invariant.  To do this, add their\ntitles to the list of Invariant Sections in the Modified Version's\nlicense notice.  These titles must be distinct from any other\nsection titles.\n\nYou may add a section Entitled \"Endorsements\", provided it contains\nnothing but endorsements of your Modified Version by various\nparties--for example, statements of peer review or that the text\nhas been approved by an organization as the authoritative\ndefinition of a standard.\n\nYou may add a passage of up to five words as a Front-Cover Text,\nand a passage of up to 25 words as a Back-Cover Text, to the end of\nthe list of Cover Texts in the Modified Version.  Only one passage\nof Front-Cover Text and one of Back-Cover Text may be added by (or\nthrough arrangements made by) any one entity.  If the Document\nalready includes a cover text for the same cover, previously added\nby you or by arrangement made by the same entity you are acting on\nbehalf of, you may not add another; but you may replace the old\none, on explicit permission from the previous publisher that added\nthe old one.\n\nThe author(s) and publisher(s) of the Document do not by this\nLicense give permission to use their names for publicity for or to\nassert or imply endorsement of any Modified Version.\n\n5. COMBINING DOCUMENTS\n\nYou may combine the Document with other documents released under\nthis License, under the terms defined in section 4 above for\nmodified versions, provided that you include in the combination all\nof the Invariant Sections of all of the original documents,\nunmodified, and list them all as Invariant Sections of your\ncombined work in its license notice, and that you preserve all\ntheir Warranty Disclaimers.\n\nThe combined work need only contain one copy of this License, and\nmultiple identical Invariant Sections may be replaced with a single\ncopy.  If there are multiple Invariant Sections with the same name\nbut different contents, make the title of each such section unique\nby adding at the end of it, in parentheses, the name of the\noriginal author or publisher of that section if known, or else a\nunique number.  Make the same adjustment to the section titles in\nthe list of Invariant Sections in the license notice of the\ncombined work.\n\nIn the combination, you must combine any sections Entitled\n\"History\" in the various original documents, forming one section\nEntitled \"History\"; likewise combine any sections Entitled\n\"Acknowledgements\", and any sections Entitled \"Dedications\".  You\nmust delete all sections Entitled \"Endorsements.\"\n\n6. COLLECTIONS OF DOCUMENTS\n\nYou may make a collection consisting of the Document and other\ndocuments released under this License, and replace the individual\ncopies of this License in the various documents with a single copy\nthat is included in the collection, provided that you follow the\nrules of this License for verbatim copying of each of the documents\nin all other respects.\n\nYou may extract a single document from such a collection, and\ndistribute it individually under this License, provided you insert\na copy of this License into the extracted document, and follow this\nLicense in all other respects regarding verbatim copying of that\ndocument.\n\n7. AGGREGATION WITH INDEPENDENT WORKS\n\nA compilation of the Document or its derivatives with other\nseparate and independent documents or works, in or on a volume of a\nstorage or distribution medium, is called an \"aggregate\" if the\ncopyright resulting from the compilation is not used to limit the\nlegal rights of the compilation's users beyond what the individual\nworks permit.  When the Document is included in an aggregate, this\nLicense does not apply to the other works in the aggregate which\nare not themselves derivative works of the Document.\n\nIf the Cover Text requirement of section 3 is applicable to these\ncopies of the Document, then if the Document is less than one half\nof the entire aggregate, the Document's Cover Texts may be placed\non covers that bracket the Document within the aggregate, or the\nelectronic equivalent of covers if the Document is in electronic\nform.  Otherwise they must appear on printed covers that bracket\nthe whole aggregate.\n\n8. TRANSLATION\n\nTranslation is considered a kind of modification, so you may\ndistribute translations of the Document under the terms of section\n4.  Replacing Invariant Sections with translations requires special\npermission from their copyright holders, but you may include\ntranslations of some or all Invariant Sections in addition to the\noriginal versions of these Invariant Sections.  You may include a\ntranslation of this License, and all the license notices in the\nDocument, and any Warranty Disclaimers, provided that you also\ninclude the original English version of this License and the\noriginal versions of those notices and disclaimers.  In case of a\ndisagreement between the translation and the original version of\nthis License or a notice or disclaimer, the original version will\nprevail.\n\nIf a section in the Document is Entitled \"Acknowledgements\",\n\"Dedications\", or \"History\", the requirement (section 4) to\nPreserve its Title (section 1) will typically require changing the\nactual title.\n\n9. TERMINATION\n\nYou may not copy, modify, sublicense, or distribute the Document\nexcept as expressly provided under this License.  Any attempt\notherwise to copy, modify, sublicense, or distribute it is void,\nand will automatically terminate your rights under this License.\n\nHowever, if you cease all violation of this License, then your\nlicense from a particular copyright holder is reinstated (a)\nprovisionally, unless and until the copyright holder explicitly and\nfinally terminates your license, and (b) permanently, if the\ncopyright holder fails to notify you of the violation by some\nreasonable means prior to 60 days after the cessation.\n\nMoreover, your license from a particular copyright holder is\nreinstated permanently if the copyright holder notifies you of the\nviolation by some reasonable means, this is the first time you have\nreceived notice of violation of this License (for any work) from\nthat copyright holder, and you cure the violation prior to 30 days\nafter your receipt of the notice.\n\nTermination of your rights under this section does not terminate\nthe licenses of parties who have received copies or rights from you\nunder this License.  If your rights have been terminated and not\npermanently reinstated, receipt of a copy of some or all of the\nsame material does not give you any rights to use it.\n\n10. FUTURE REVISIONS OF THIS LICENSE\n\nThe Free Software Foundation may publish new, revised versions of\nthe GNU Free Documentation License from time to time.  Such new\nversions will be similar in spirit to the present version, but may\ndiffer in detail to address new problems or concerns.  See\n<http://www.gnu.org/copyleft/>.\n\nEach version of the License is given a distinguishing version\nnumber.  If the Document specifies that a particular numbered\nversion of this License \"or any later version\" applies to it, you\nhave the option of following the terms and conditions either of\nthat specified version or of any later version that has been\npublished (not as a draft) by the Free Software Foundation.  If the\nDocument does not specify a version number of this License, you may\nchoose any version ever published (not as a draft) by the Free\nSoftware Foundation.  If the Document specifies that a proxy can\ndecide which future versions of this License can be used, that\nproxy's public statement of acceptance of a version permanently\nauthorizes you to choose that version for the Document.\n\n11. RELICENSING\n\n\"Massive Multiauthor Collaboration Site\" (or \"MMC Site\") means any\nWorld Wide Web server that publishes copyrightable works and also\nprovides prominent facilities for anybody to edit those works.  A\npublic wiki that anybody can edit is an example of such a server.\nA \"Massive Multiauthor Collaboration\" (or \"MMC\") contained in the\nsite means any set of copyrightable works thus published on the MMC\nsite.\n\n\"CC-BY-SA\" means the Creative Commons Attribution-Share Alike 3.0\nlicense published by Creative Commons Corporation, a not-for-profit\ncorporation with a principal place of business in San Francisco,\nCalifornia, as well as future copyleft versions of that license\npublished by that same organization.\n\n\"Incorporate\" means to publish or republish a Document, in whole or\nin part, as part of another Document.\n\nAn MMC is \"eligible for relicensing\" if it is licensed under this\nLicense, and if all works that were first published under this\nLicense somewhere other than this MMC, and subsequently\nincorporated in whole or in part into the MMC, (1) had no cover\ntexts or invariant sections, and (2) were thus incorporated prior\nto November 1, 2008.\n\nThe operator of an MMC Site may republish an MMC contained in the\nsite under CC-BY-SA on the same site at any time before August 1,\n2009, provided the MMC is eligible for relicensing.\n",
            "subsections": [
                {
                    "name": "ADDENDUM: How to use this License for your documents",
                    "content": "To use this License in a document you have written, include a copy of\nthe License in the document and put the following copyright and license\nnotices just after the title page:\n\nCopyright (C)  YEAR  YOUR NAME.\nPermission is granted to copy, distribute and/or modify this document\nunder the terms of the GNU Free Documentation License, Version 1.3\nor any later version published by the Free Software Foundation;\nwith no Invariant Sections, no Front-Cover Texts, and no Back-Cover\nTexts.  A copy of the license is included in the section entitled ``GNU\nFree Documentation License''.\n\nIf you have Invariant Sections, Front-Cover Texts and Back-Cover\nTexts, replace the \"with...Texts.\"  line with this:\n\nwith the Invariant Sections being LIST THEIR TITLES, with\nthe Front-Cover Texts being LIST, and with the Back-Cover Texts\nbeing LIST.\n\nIf you have Invariant Sections without Cover Texts, or some other\ncombination of the three, merge those two alternatives to suit the\nsituation.\n\nIf your document contains nontrivial examples of program code, we\nrecommend releasing these examples in parallel under your choice of free\nsoftware license, such as the GNU General Public License, to permit\ntheir use in free software.\n\nFile: gdbm.info,  Node: Index,  Prev: GNU Free Documentation License,  Up: Top\n"
                }
            ]
        },
        "Index": {
            "content": "* Menu:\n\n* !:                                     commands.            (line 204)\n* (*errfun) of gdbmrecovery:            Recovery.            (line  52)\n* --newdb, gdbmtool option:              gdbmtool.            (line  20)\n* --read-only, gdbmtool option:          gdbmtool.            (line  16)\n* -n, gdbmtool option:                   gdbmtool.            (line  20)\n* -r, gdbmtool option:                   gdbmtool.            (line  16)\n* .gdbmtoolrc:                           startup files.       (line   6)\n* ?:                                     commands.            (line  66)\n* GDBMMAXERRNO:                       Variables.           (line  31)\n* GDBMMINERRNO:                       Variables.           (line  28)\n* avail:                                 commands.            (line   6)\n* backupname of gdbmrecovery:          Recovery.            (line  99)\n* blocksize:                             variables.           (line 104)\n* bucket:                                commands.            (line   9)\n* cache:                                 commands.            (line  12)\n* cachesize:                             variables.           (line 107)\n* centfree:                              variables.           (line 205)\n* close:                                 commands.            (line  15)\n* close-on-exec:                         Open.                (line  49)\n* closing database:                      Close.               (line   6)\n* coalesce:                              variables.           (line 195)\n* command line options, gdbmtool:        invocation.          (line   6)\n* compatibility layer:                   Compatibility.       (line   6)\n* confirm:                               variables.           (line   9)\n* consistency, database:                 Database consistency.\n(line   6)\n* count:                                 commands.            (line  18)\n* creating a database, gdbmtool:         gdbmtool.            (line  20)\n* current:                               commands.            (line  21)\n* data of gdbmrecovery:                 Recovery.            (line  62)\n* database options:                      Options.             (line   6)\n* database reorganization:               Reorganization.      (line   6)\n* database synchronization:              Sync.                (line   6)\n* database, closing:                     Close.               (line   6)\n* database, opening or creating:         Open.                (line   6)\n* datum:                                 Intro.               (line  12)\n* DBM functions:                         dbm.                 (line   6)\n* dbm.h:                                 Compatibility.       (line  10)\n* dbmclose:                              dbm.                 (line  22)\n* dbminit:                               dbm.                 (line  10)\n* dbmclearerr:                          ndbm.                (line  95)\n* dbmclose:                             ndbm.                (line  25)\n* dbmdelete:                            ndbm.                (line  56)\n* dbmdirfno:                            ndbm.                (line  98)\n* dbmerror:                             ndbm.                (line  90)\n* dbmfetch:                             ndbm.                (line  29)\n* dbmfirstkey:                          ndbm.                (line  61)\n* DBMINSERT:                            ndbm.                (line  49)\n* dbmnextkey:                           ndbm.                (line  71)\n* dbmopen:                              ndbm.                (line   8)\n* dbmpagfno:                            ndbm.                (line 106)\n* dbmrdonly:                            ndbm.                (line 110)\n* DBMREPLACE:                           ndbm.                (line  46)\n* dbmstore:                             ndbm.                (line  38)\n* debug:                                 commands.            (line  24)\n* default database, gdbmtool:            gdbmtool.            (line   9)\n* delete:                                dbm.                 (line  41)\n* delete <1>:                            commands.            (line  30)\n* deleting records:                      Delete.              (line   6)\n* deletion in iteration loops:           Sequential.          (line  60)\n* delim1:                                variables.           (line  15)\n* delim2:                                variables.           (line  21)\n* dir:                                   commands.            (line  33)\n* dir file:                              Compatibility.       (line  21)\n* downgrade:                             commands.            (line  36)\n* error code, most recent:               Errors.              (line  21)\n* error codes:                           Error codes.         (line   6)\n* error strings:                         Errors.              (line   6)\n* errorexit:                             variables.           (line  27)\n* errorexit <1>:                         variables.           (line  28)\n* errormask:                             variables.           (line  41)\n* errormask <1>:                         variables.           (line  42)\n* exit code:                             Exit codes.          (line   6)\n* export:                                Flat files.          (line   6)\n* export <1>:                            commands.            (line  40)\n* failedbuckets of gdbmrecovery:       Recovery.            (line  96)\n* failedkeys of gdbmrecovery:          Recovery.            (line  93)\n* fd:                                    variables.           (line 125)\n* fetch:                                 dbm.                 (line  25)\n* fetch <1>:                             commands.            (line  51)\n* fetching records:                      Fetch.               (line   6)\n* filemode:                              variables.           (line 175)\n* filename:                              variables.           (line 116)\n* first:                                 commands.            (line  54)\n* firstkey:                              dbm.                 (line  47)\n* Flat file format:                      Flat files.          (line   6)\n* format:                                variables.           (line 136)\n* gdbm.h:                                Intro.               (line  45)\n* gdbmtool:                              gdbmtool.            (line   6)\n* gdbmavailverify:                     Additional functions.\n(line   6)\n* GDBMBACKUPFAILED:                    Error codes.         (line 180)\n* GDBMBADAVAIL:                        Error codes.         (line 196)\n* GDBMBADBUCKET:                       Error codes.         (line 187)\n* GDBMBADDIRENTRY:                    Error codes.         (line 211)\n* GDBMBADFILEOFFSET:                  Error codes.         (line 129)\n* GDBMBADHASHENTRY:                   Error codes.         (line 237)\n* GDBMBADHASHTABLE:                   Error codes.         (line 204)\n* GDBMBADHEADER:                       Error codes.         (line 191)\n* GDBMBADMAGICNUMBER:                 Error codes.         (line  51)\n* GDBMBADOPENFLAGS:                   Error codes.         (line 133)\n* GDBMBLOCKSIZEERROR:                 Error codes.         (line  15)\n* GDBMBSEXACT:                          Open.                (line 109)\n* GDBMBSEXACT <1>:                      Error codes.         (line  16)\n* GDBMBUCKETCACHECORRUPTED:           Error codes.         (line 233)\n* gdbmbucketcount:                     Count.               (line  12)\n* GDBMBYTESWAPPED:                     Error codes.         (line 125)\n* GDBMCACHESIZE:                        Options.             (line  31)\n* GDBMCANNOTREPLACE:                   Error codes.         (line  92)\n* GDBMCANTBEREADER:                   Error codes.         (line  59)\n* GDBMCANTBEWRITER:                   Error codes.         (line  64)\n* GDBMCENTFREE:                         Options.             (line 135)\n* gdbmchecksyserr:                     Errors.              (line  52)\n* gdbmclearerror:                      Errors.              (line  67)\n* GDBMCLOERROR:                         Open.                (line 162)\n* GDBMCLOEXEC:                          Open.                (line  48)\n* gdbmclose:                            Close.               (line  10)\n* GDBMCOALESCEBLKS:                     Options.             (line 149)\n* gdbmconvert:                          Database format.     (line  18)\n* gdbmcopymeta:                        Open.                (line 165)\n* gdbmcount:                            Count.               (line   6)\n* gdbmdbstrerror:                      Errors.              (line  59)\n* gdbmdelete:                           Delete.              (line   8)\n* gdbmdelete and sequential access:     Sequential.          (line  60)\n* GDBMDIROVERFLOW:                     Error codes.         (line 183)\n* gdbmdump:                             gdbmdump.           (line   6)\n* gdbmdump <1>:                         Flat files.          (line  56)\n* gdbmdumptofile:                     Flat files.          (line 163)\n* GDBMEMPTYDATABASE:                   Error codes.         (line  55)\n* gdbmerrlist[]:                        Variables.           (line  16)\n* gdbmerrno:                            Errors.              (line   6)\n* gdbmerrno <1>:                        Variables.           (line   8)\n* GDBMERRFILEMODE:                    Flat files.          (line 151)\n* GDBMERRFILEMODE <1>:                Error codes.         (line 168)\n* GDBMERRFILEOWNER:                   Flat files.          (line 148)\n* GDBMERRFILEOWNER <1>:               Error codes.         (line 161)\n* GDBMERRREALPATH:                     Error codes.         (line 252)\n* GDBMERRSNAPSHOTCLONE:               Error codes.         (line 243)\n* GDBMERRUSAGE:                        Error codes.         (line 260)\n* gdbmexists:                           Fetch.               (line  42)\n* gdbmexport:                           Flat files.          (line 186)\n* gdbmexporttofile:                   Flat files.          (line 194)\n* gdbmfailureatomic:                   Crash Tolerance API. (line   6)\n* GDBMFAST:                             Open.                (line 100)\n* GDBMFASTMODE:                         Options.             (line 109)\n* gdbmfdesc:                            Locking.             (line  13)\n* gdbmfdopen:                          Open.                (line 148)\n* gdbmfetch:                            Fetch.               (line   6)\n* GDBMFILE:                             Intro.               (line  48)\n* GDBMFILECLOSEERROR:                 Error codes.         (line 215)\n* GDBMFILEEOF:                         Error codes.         (line 144)\n* GDBMFILEOPENERROR:                  Error codes.         (line  20)\n* GDBMFILEREADERROR:                  Error codes.         (line  43)\n* GDBMFILESEEKERROR:                  Error codes.         (line  36)\n* GDBMFILESTATERROR:                  Error codes.         (line 137)\n* GDBMFILESYNCERROR:                  Error codes.         (line 220)\n* GDBMFILETRUNCATEERROR:              Error codes.         (line 226)\n* GDBMFILEWRITEERROR:                 Error codes.         (line  28)\n* gdbmfirstkey:                         Sequential.          (line  13)\n* GDBMGETBLOCKSIZE:                     Options.             (line 203)\n* GDBMGETBUCKETSIZE:                    Options.             (line 105)\n* GDBMGETCACHEAUTO:                     Options.             (line  77)\n* GDBMGETCACHESIZE:                     Options.             (line  60)\n* GDBMGETCOALESCEBLKS:                  Options.             (line 160)\n* GDBMGETDBFORMAT:                      Options.             (line  91)\n* GDBMGETDBNAME:                        Options.             (line 183)\n* GDBMGETDIRDEPTH:                      Options.             (line  97)\n* GDBMGETFLAGS:                         Options.             (line  83)\n* GDBMGETMAXMAPSIZE:                    Options.             (line 170)\n* GDBMGETMMAP:                          Options.             (line 179)\n* GDBMGETSYNCMODE:                      Options.             (line 130)\n* GDBMILLEGALDATA:                     Error codes.         (line  99)\n* gdbmimport:                           Flat files.          (line 198)\n* gdbmimportfromfile:                 Flat files.          (line 211)\n* GDBMINSERT:                           Store.               (line  20)\n* GDBMITEMNOTFOUND:                   Error codes.         (line  83)\n* gdbmlasterrno:                       Errors.              (line  21)\n* gdbmlastsyserr:                      Errors.              (line  32)\n* gdbmlatestsnapshot:                  Crash Tolerance API. (line  66)\n* gdbmload:                             gdbmload.           (line   6)\n* gdbmload <1>:                         Flat files.          (line  85)\n* gdbmloadfromfile:                   Flat files.          (line 179)\n* GDBMMALFORMEDDATA:                   Error codes.         (line  98)\n* GDBMMALLOCERROR:                     Error codes.         (line  12)\n* gdbmneedsrecovery:                   Errors.              (line  79)\n* GDBMNEEDRECOVERY:                    Error codes.         (line 175)\n* GDBMNEWDB:                            Open.                (line  30)\n* gdbmnextkey:                          Sequential.          (line  25)\n* GDBMNOLOCK:                           Open.                (line  53)\n* GDBMNOLOCK <1>:                       Locking.             (line   6)\n* GDBMNOMMAP:                           Open.                (line  57)\n* GDBMNODBNAME:                        Error codes.         (line 155)\n* GDBMNOERROR:                         Error codes.         (line   9)\n* GDBMNUMSYNC:                          Database format.     (line  25)\n* GDBMNUMSYNC <1>:                      Open.                (line 116)\n* gdbmopen:                             Open.                (line   6)\n* GDBMOPTALREADYSET:                  Error codes.         (line 110)\n* GDBMOPTBADVAL:                       Error codes.         (line 116)\n* GDBMOPTILLEGAL:                      Error codes.         (line 117)\n* GDBMPREREAD:                          Open.                (line  61)\n* GDBMRCVRBACKUP:                      Recovery.            (line 100)\n* GDBMRCVRERRFUN:                      Recovery.            (line  54)\n* GDBMRCVRFORCE:                       Recovery.            (line 106)\n* GDBMRCVRMAXFAILEDBUCKETS:          Recovery.            (line  72)\n* GDBMRCVRMAXFAILEDKEYS:             Recovery.            (line  66)\n* GDBMRCVRMAXFAILURES:                Recovery.            (line  79)\n* GDBMREADER:                           Open.                (line  30)\n* GDBMREADERCANTDELETE:               Error codes.         (line  68)\n* GDBMREADERCANTREORGANIZE:           Error codes.         (line  78)\n* GDBMREADERCANTSTORE:                Error codes.         (line  73)\n* gdbmrecover:                          Recovery.            (line  16)\n* gdbmreorganize:                       Reorganization.      (line   8)\n* GDBMREORGANIZEFAILED:                Error codes.         (line  88)\n* GDBMREPLACE:                          Store.               (line  20)\n* GDBMSETCACHEAUTO:                     Options.             (line  64)\n* GDBMSETCACHESIZE:                     Options.             (line  30)\n* GDBMSETCENTFREE:                      Options.             (line 134)\n* GDBMSETCOALESCEBLKS:                  Options.             (line 148)\n* GDBMSETMAXMAPSIZE:                    Options.             (line 164)\n* GDBMSETMMAP:                          Options.             (line 174)\n* gdbmsetopt:                           Options.             (line   9)\n* GDBMSETSYNCMODE:                      Options.             (line 117)\n* GDBMSNAPSHOTBAD:                     Crash Tolerance API. (line  68)\n* GDBMSNAPSHOTBAD <1>:                 Crash recovery.      (line  38)\n* GDBMSNAPSHOTERR:                     Crash Tolerance API. (line  68)\n* GDBMSNAPSHOTERR <1>:                 Crash recovery.      (line  43)\n* GDBMSNAPSHOTOK:                      Crash Tolerance API. (line  68)\n* GDBMSNAPSHOTSAME:                    Crash Tolerance API. (line  68)\n* GDBMSNAPSHOTSAME <1>:                Crash recovery.      (line  78)\n* GDBMSNAPSHOTSUSPICIOUS:              Crash Tolerance API. (line  79)\n* GDBMSNAPSHOTSUSPICIOUS <1>:          Crash recovery.      (line  83)\n* gdbmstore:                            Store.               (line   6)\n* gdbmstrerror:                         Errors.              (line  12)\n* GDBMSYNC:                             Open.                (line  91)\n* GDBMSYNC <1>:                         Sync.                (line  36)\n* gdbmsync:                             Sync.                (line  13)\n* GDBMSYNCMODE:                         Options.             (line 118)\n* gdbmsyserr[]:                         Variables.           (line  23)\n* gdbmversion:                          Variables.           (line  34)\n* gdbmversioncmp:                      Variables.           (line  63)\n* GDBMVERSIONMAJOR:                    Variables.           (line  49)\n* GDBMVERSIONMINOR:                    Variables.           (line  52)\n* gdbmversionnumber[3]:                Variables.           (line  37)\n* GDBMVERSIONPATCH:                    Variables.           (line  55)\n* GDBMWRCREAT:                          Open.                (line  30)\n* GDBMWRITER:                           Open.                (line  30)\n* GDBMXVERIFY:                          Open.                (line  78)\n* global error state:                    Errors.              (line   6)\n* GNU Readline:                          shell.               (line  65)\n* hash:                                  commands.            (line  59)\n* header:                                commands.            (line  62)\n* help:                                  commands.            (line  65)\n* history:                               commands.            (line  77)\n* history <1>:                           commands.            (line  78)\n* history <2>:                           commands.            (line  79)\n* import:                                Flat files.          (line   6)\n* import <1>:                            commands.            (line  71)\n* init file, gdbmtool:                   startup files.       (line   6)\n* interactive mode, gdbmtool:            shell.               (line   6)\n* iterating over records:                Sequential.          (line   6)\n* iteration and gdbmdelete:             Sequential.          (line  60)\n* iteration loop:                        Sequential.          (line  40)\n* iteration loop, using NDBM:            ndbm.                (line  79)\n* junk.gdbm:                             gdbmtool.            (line   9)\n* libgdbmcompat:                        Compatibility.       (line  10)\n* list:                                  commands.            (line  92)\n* lock:                                  variables.           (line 179)\n* locking:                               Locking.             (line   6)\n* logical consistency:                   Database consistency.\n(line  17)\n* looking up records:                    Fetch.               (line   6)\n* maxfailedbuckets of gdbmrecovery:   Recovery.            (line  71)\n* maxfailedkeys of gdbmrecovery:      Recovery.            (line  65)\n* maxfailures of gdbmrecovery:         Recovery.            (line  78)\n* mmap:                                  variables.           (line 185)\n* most recent error code:                Errors.              (line  21)\n* NDBM functions:                        ndbm.                (line   6)\n* ndbm.h:                                Compatibility.       (line  10)\n* next:                                  commands.            (line  95)\n* nextkey:                               dbm.                 (line  57)\n* number of records:                     Count.               (line   6)\n* open:                                  commands.            (line 109)\n* open <1>:                              commands.            (line 110)\n* open <2>:                              variables.           (line 149)\n* opening the database:                  Open.                (line   6)\n* options, database:                     Options.             (line   6)\n* pag file:                              Compatibility.       (line  21)\n* pager:                                 variables.           (line  47)\n* perror:                                commands.            (line 151)\n* ps1:                                   variables.           (line  55)\n* ps2:                                   variables.           (line  73)\n* quiet:                                 variables.           (line  97)\n* quit:                                  commands.            (line 168)\n* read-only mode, gdbmtool:              gdbmtool.            (line  16)\n* readline:                              shell.               (line  65)\n* record, deleting:                      Delete.              (line   6)\n* record, fetching:                      Fetch.               (line   6)\n* records, iterating over:               Sequential.          (line   6)\n* records, storing:                      Store.               (line   6)\n* records, testing existence:            Fetch.               (line  40)\n* recover:                               commands.            (line 171)\n* recoveredbuckets of gdbmrecovery:    Recovery.            (line  90)\n* recoveredkeys of gdbmrecovery:       Recovery.            (line  87)\n* reorganization, database:              Reorganization.      (line   6)\n* reorganize:                            commands.            (line 200)\n* sequential access:                     Sequential.          (line   6)\n* sequential access, using NDBM:         ndbm.                (line  79)\n* set:                                   variables.           (line 214)\n* shell:                                 commands.            (line 203)\n* snapshot:                              commands.            (line 218)\n* source:                                commands.            (line 225)\n* startup file, gdbmtool:                startup files.       (line   6)\n* status:                                commands.            (line 228)\n* store:                                 dbm.                 (line  34)\n* store <1>:                             commands.            (line 241)\n* storing records:                       Store.               (line   6)\n* structural consistency:                Database consistency.\n(line  11)\n* sync:                                  commands.            (line 245)\n* sync <1>:                              variables.           (line 191)\n* synchronization, database:             Sync.                (line   6)\n* timing:                                variables.           (line  80)\n* trace:                                 variables.           (line  91)\n* unset:                                 variables.           (line 257)\n* upgrade:                               commands.            (line 248)\n* variables, gdbmtool:                   variables.           (line   6)\n* version:                               commands.            (line 252)\n* version number:                        Variables.           (line  34)\n\n",
            "subsections": []
        }
    },
    "flags": [],
    "examples": [],
    "see_also": []
}