{ "content": [ { "type": "text", "text": "# gdbm (man)\n\n## NAME\n\nGDBM - The GNU database manager. Includes dbm and ndbm compatibility.\n\n## DESCRIPTION\n\nGNU dbm is a library of routines that manages data files that contain key/data pairs. The\naccess provided is that of storing, retrieval, and deletion by key and a non-sorted traversal\nof all keys. A process is allowed to use multiple data files at the same time.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (2 subsections)\n- **NOTICE**\n- **DESCRIPTION** (10 subsections)\n- **CRASH TOLERANCE**\n- **GLOBAL VARIABLES** (2 subsections)\n- **VERSIONING**\n- **ERROR CODES**\n- **DBM COMPATIBILITY ROUTINES** (6 subsections)\n- **LINKING**\n- **BUG REPORTS**\n- **SEE ALSO**\n- **AUTHORS**\n- **COPYRIGHT**\n- **CONTACTS**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "gdbm", "section": "", "mode": "man", "summary": "GDBM - The GNU database manager. Includes dbm and ndbm compatibility.", "synopsis": "", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [ { "name": "gdbmdump", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/gdbmdump/1/json" }, { "name": "gdbmload", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/gdbmload/1/json" }, { "name": "gdbmtool", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/gdbmtool/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 1, "subsections": [ { "name": "#include ", "lines": 23 }, { "name": "Crash Tolerance (see below):", "lines": 3 } ] }, { "name": "NOTICE", "lines": 13, "subsections": [] }, { "name": "DESCRIPTION", "lines": 4, "subsections": [ { "name": "Opening a database", "lines": 128 }, { "name": "Calling convention", "lines": 53 }, { "name": "Error functions", "lines": 32 }, { "name": "Closing the database", "lines": 5 }, { "name": "Database lookups", "lines": 18 }, { "name": "Iterating over the database", "lines": 47 }, { "name": "Updating the database", "lines": 21 }, { "name": "Recovering structural consistency", "lines": 15 }, { "name": "Export and import", "lines": 59 }, { "name": "Other functions", "lines": 116 } ] }, { "name": "CRASH TOLERANCE", "lines": 11, "subsections": [] }, { "name": "GLOBAL VARIABLES", "lines": 1, "subsections": [ { "name": "gdbm_error gdbm_errno", "lines": 7 }, { "name": "int const gdbm_version_number[3]", "lines": 2 } ] }, { "name": "VERSIONING", "lines": 22, "subsections": [] }, { "name": "ERROR CODES", "lines": 205, "subsections": [] }, { "name": "DBM COMPATIBILITY ROUTINES", "lines": 8, "subsections": [ { "name": "DBM compatibility routines", "lines": 7 }, { "name": "#include ", "lines": 4 }, { "name": "datum firstkey (void);", "lines": 1 }, { "name": "int dbmclose (void);", "lines": 1 }, { "name": "NDBM Compatibility routines:", "lines": 6 }, { "name": "#include ", "lines": 13 } ] }, { "name": "LINKING", "lines": 11, "subsections": [] }, { "name": "BUG REPORTS", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 13, "subsections": [] }, { "name": "CONTACTS", "lines": 17, "subsections": [] } ], "sections": { "NAME": { "content": "GDBM - The GNU database manager. Includes dbm and ndbm compatibility.\n", "subsections": [] }, "SYNOPSIS": { "content": "", "subsections": [ { "name": "#include ", "content": "extern gdbmerror gdbmerrno;\nextern char *gdbmversion;\nextern int gdbmversion[3];\nGDBMFILE gdbmopen (const char *name, int blocksize,\nint flags, int mode,\nvoid (*fatalfunc)(const char *));\nint gdbmclose (GDBMFILE dbf);\nint gdbmstore (GDBMFILE dbf, datum key, datum content, int flag);\ndatum gdbmfetch (GDBMFILE dbf, datum key);\nint gdbmdelete (GDBMFILE dbf, datum key);\ndatum gdbmfirstkey (GDBMFILE dbf);\ndatum gdbmnextkey (GDBMFILE dbf, datum key);\nint gdbmrecover (GDBMFILE dbf, gdbmrecovery *rcvr, intflags);\nint gdbmreorganize (GDBMFILE dbf);\nint gdbmsync (GDBMFILE dbf);\nint gdbmexists (GDBMFILE dbf, datum key);\nconst char *gdbmstrerror (gdbmerror errno);\nint gdbmsetopt (GDBMFILE dbf, int option, int value, int size);\nint gdbmfdesc (GDBMFILE dbf);\nint gdbmcount (GDBMFILE dbf, gdbmcountt *pcount);\nint gdbmbucketcount (GDBMFILE dbf, sizet *pcount);\nint gdbmavailverify (GDBMFILE dbf);\n" }, { "name": "Crash Tolerance (see below):", "content": "int gdbmfailureatomic (GDBMFILE dbf, const char *even, const char *odd);\nint gdbmlatestsnapshot (const char *even, const char *odd, const char result);\n" } ] }, "NOTICE": { "content": "This manpage is a short description of the GDBM library. For a detailed discussion, includ‐\ning examples and usage recommendations, refer to the GDBM Manual available in Texinfo format.\nTo access it, run:\n\ninfo gdbm\n\nThe documentation is also available online at\n\nhttps://www.gnu.org/software/gdbm/manual\n\nShould any discrepancies occur between this manpage and the GDBM Manual, the later shall be\nconsidered the authoritative source.\n", "subsections": [] }, "DESCRIPTION": { "content": "GNU dbm is a library of routines that manages data files that contain key/data pairs. The\naccess provided is that of storing, retrieval, and deletion by key and a non-sorted traversal\nof all keys. A process is allowed to use multiple data files at the same time.\n", "subsections": [ { "name": "Opening a database", "content": "A process that opens a gdbm file is designated as a \"reader\" or a \"writer\". Only one writer\nmay open a gdbm file and many readers may open the file. Readers and writers can not open\nthe gdbm file at the same time. The procedure for opening a gdbm file is:\n\nGDBMFILE gdbmopen (const char *name, int blocksize,\nint flags, int mode,\nvoid (*fatalfunc)(const char *));\n\nName is the name of the file (the complete name, gdbm does not append any characters to this\nname).\n\nBlocksize is the size of a single transfer from disk to memory. If the value is less than\n512, the file system block size is used instead. The size is adjusted so that the block can\nhold exact number of directory entries, so that the effective block size can be slightly\ngreater than requested. This adjustment is disabled if the GDBMBSEXACT flag is used.\n\nThe flags parameter is a bitmask, composed of the access mode and one or more modifier flags.\nThe access mode bit designates the process as a reader or writer and must be one of the fol‐\nlowing:\n\nGDBMREADER\nreader\n\nGDBMWRITER\nwriter\n\nGDBMWRCREAT\nwriter - if database does not exist create new one\n\nGDBMNEWDB\nwriter - create new database regardless if one exists\n\nAdditional flags (modifiers) can be combined with these values by bitwise OR. Not all of\nthem are meaningful with all access modes.\n\nFlags that are valid for any value of access mode are:\n\nGDBMCLOEXEC\nSet the close-on-exec flag on the database file descriptor.\n\nGDBMNOLOCK\nPrevents the library from performing any locking on the database file.\n\nGDBMNOMMAP\nInstructs gdbmopen to disable the use of mmap(2).\n\nGDBMPREREAD\nWhen mapping GDBM file to memory, read its contents immediately, instead of when\nneeded (prefault reading). This can be advantageous if you open a read-only database\nand are going to do a lot of look-ups on it. In this case entire database will be\nread at once and searches will operate on an in-memory copy. In contrast, GDBMPRE‐\nREAD should not be used if you open a database (even in read-only mode) only to re‐\ntrieve a couple of keys.\n\nFinally, never use GDBMPREREAD when opening a database for updates, especially for\ninserts: this will degrade performance.\n\nThis flag has no effect if GDBMNOMMAP is given, or if the operating system does not\nsupport prefault reading. It is known to work on Linux and FreeBSD kernels.\n\n\nGDBMXVERIFY\nEnable additional consistency checks. With this flag, eventual corruptions of the\ndatabase are discovered when opening it, instead of when a corrupted structure is read\nduring normal operation. However, on large databases, it can slow down the opening\nprocess.\n\nThe following additional flags are valid when the database is opened for writing\n(GDBMWRITER, GDBMWRCREAT, or GDBMNEWDB):\n\nGDBMSYNC\nCauses all database operations to be synchronized to the disk.\n\nNOTE: this option entails severe performance degradation and does not necessarily en‐\nsure that the resulting database state is consistent, therefore we discourage its use.\nFor a discussion of how to ensure database consistency with minimal performance over‐\nhead, see CRASH TOLERANCE below.\n\nGDBMFAST\nA reverse of GDBMSYNC: synchronize writes only when needed. This is the default.\nThis flag is provided only for compatibility with previous versions of GDBM.\n\nThe following flags can be used together with GDBMNEWDB. They also take effect when used\nwith GDBMWRCREAT, if the requested database file doesn't exist:\n\nGDBMBSEXACT\nIf this flag is set and the requested blocksize value cannot be used, gdbmopen will\nrefuse to create the database. In this case it will set the gdbmerrno variable to\nGDBMBLOCKSIZEERROR and return NULL.\n\nWithout this flag, gdbmopen will silently adjust the blocksize to a usable value, as\ndescribed above.\n\nGDBMNUMSYNC\nCreate new database in extended database format, a format best suited for effective\ncrash recovery. For a detailed discussion, see the CRASH RECOVERY chapter below.\n\nMode is the file mode (see chmod(2) and open(2)). It is used if the file is created.\n\nFatalfunc is a function to be called when gdbm if it encounters a fatal error. This parame‐\nter is deprecated and must always be NULL.\n\nThe return value is the pointer needed by all other routines to access that gdbm file. If\nthe return is the NULL pointer, gdbmopen was not successful. In this case, the reason of\nthe failure can be found in the gdbmerrno variable. If the following call returns true\n(non-zero value):\n\ngdbmchecksyserr(gdbmopen)\n\nthe system errno variable must be examined in order to obtain more detail about the failure.\n\nGDBMFILE gdbmfdopen (int FD, const char *name, int blocksize,\nint flags, int mode,\nvoid (*fatalfunc)(const char *));\n\nThis is an alternative entry point to gdbmopen. FD is a valid file descriptor obtained as a\nresult of a call to open(2) or creat(2). The function opens (or creates) a DBM database this\ndescriptor refers to. The descriptor is not dup'ed, and will be closed when the returned\nGDBMFILE is closed. Use dup (2) if that is not desirable.\n\nIn case of error, the function behaves like gdbmopen and does not close FD. This can be al‐\ntered by the following value passed in flags:\n\nGDBMCLOERROR\nClose FD before exiting on error.\n\nThe rest of arguments are the same as for gdbmopen.\n" }, { "name": "Calling convention", "content": "All GDBM functions take as their first parameter the database handle (GDBMFILE), returned\nfrom gdbmopen or gdbmfdopen.\n\nAny value stored in the GDBM database is described by datum, an aggregate type defined as:\n\ntypedef struct\n{\nchar *dptr;\nint dsize;\n} datum;\n\nThe dptr field points to the actual data. Its type is char * for historical reasons. Actu‐\nally it should have been typed void *. Programmers are free to store data of arbitrary com‐\nplexity, both scalar and aggregate, in this field.\n\nThe dsize field contains the number of bytes stored in dptr.\n\nThe datum type is used to describe both keys and content (values) in the database. Values of\nthis type can be passed as arguments or returned from GDBM function calls.\n\nGDBM functions that return datum indicate failure by setting its dptr field to NULL.\n\nFunctions returning integer value, indicate success by returning 0 and failure by returning a\nnon-zero value (the only exception to this rule is gdbmexists, for which the return value is\nreversed).\n\nIf the returned value indicates failure, the gdbmerrno variable contains an integer value\nindicating what went wrong. A similar value is associated with the dbf handle and can be ac‐\ncessed using the gdbmlasterrno function. Immediately after return from a function, both\nvalues are exactly equal. Subsequent GDBM calls with another dbf as argument may alter the\nvalue of the global gdbmerrno, but the value returned by gdbmlasterrno will always indi‐\ncate the most recent code of an error that occurred for that particular database. Program‐\nmers are encouraged to use such per-database error codes.\n\nSometimes the actual reason of the failure can be clarified by examining the system errno\nvalue. To make sure its value is meaningful for a given GDBM error code, use the\ngdbmchecksyserr function. The function takes error code as argument and returns 1 if the\nerrno is meaningful for that error, or 0 if it is irrelevant.\n\nSimilarly to gdbmerrno, the latest errno value associated with a particular database can be\nobtained using the gdbmlastsyserr function.\n\nThe gdbmclearerror clears the error indicator (both GDBM and system error codes) associated\nwith a database handle.\n\nSome critical errors leave the database in a structurally inconsistent state. If that hap‐\npens, all subsequent GDBM calls accessing that database will fail with the GDBM error code of\nGDBMNEEDRECOVERY (a special function gdbmneedsrecovery is also provided, which returns\ntrue if the database handle given as its argument is structurally inconsistent). To return\nsuch databases to consistent state, use the gdbmrecover function (see below).\n\nThe GDBMNEEDRECOVERY error cannot be cleared using gdbmclearerror.\n" }, { "name": "Error functions", "content": "This section describes the error handling functions outlined above.\n\ngdbmerror gdbmlasterrno (GDBMFILE dbf)\nReturns the error code of the most recent failure encountered when operating on dbf.\n\nint gdbmlastsyserr (GDBMFILE dbf)\nReturns the value of the system errno variable associated with the most recent failure\nthat occurred on dbf.\n\nNotice that not all gdbmerror codes have a relevant system error code. Use the fol‐\nlowing function to determine if a given code has.\n\nint gdbmchecksyserr (gdbmerror err)\nReturns 1, if system errno value should be checked to get more info on the error de‐\nscribed by GDBM code err.\n\nvoid gdbmclearerror (GDBMFILE dbf)\nClears the error state for the database dbf. This function is called implicitly upon\nentry to any GDBM function that operates on GDBMFILE.\n\nThe GDBMNEEDRECOVERY error cannot be cleared.\n\nint gdbmneedsrecovery (GDBMFILE dbf)\nReturn 1 if the database file dbf is in inconsistent state and needs recovery.\n\nconst char *gdbmstrerror (gdbmerror err)\nReturns a textual description of the error code err.\n\nconst char *gdbmdbstrerror (GDBMFILE dbf)\nReturns a textual description of the recent error in database dbf. This description\nincludes the system errno value, if relevant.\n" }, { "name": "Closing the database", "content": "It is important that every database file opened is also closed. This is needed to update the\nreader/writer count on the file. This is done by:\n\nint gdbmclose (GDBMFILE dbf);\n" }, { "name": "Database lookups", "content": "int gdbmexists (GDBMFILE dbf, datum key);\nIf the key is found within the database, the return value will be true (1). If noth‐\ning appropriate is found, false (0) is returned and gdbmerrno set to GDBMNOERROR.\n\nOn error, returns 0 and sets gdbmerrno.\n\ndatum gdbmfetch (GDBMFILE dbf, datum key);\nDbf is the pointer returned by gdbmopen. Key is the key data.\n\nIf the dptr element of the return value is NULL, the gdbmerrno variable should be ex‐\namined. The value of GDBMITEMNOTFOUND means no data was found for that key. Other\nvalue means an error occurred.\n\nOtherwise the return value is a pointer to the found data. The storage space for the\ndptr element is allocated using malloc(3). GDBM does not automatically free this\ndata. It is the programmer's responsibility to free this storage when it is no longer\nneeded.\n" }, { "name": "Iterating over the database", "content": "The following two routines allow for iterating over all items in the database. Such itera‐\ntion is not key sequential, but it is guaranteed to visit every key in the database exactly\nonce. (The order has to do with the hash values.)\n\ndatum gdbmfirstkey (GDBMFILE dbf);\nReturns first key in the database.\n\ndatum gdbmnextkey (GDBMFILE dbf, datum key);\nGiven a key, returns the database key that follows it. End of iteration is marked by\nreturning datum with dptr field set to NULL and setting the gdbmerrno value to\nGDBMITEMNOTFOUND.\n\nAfter successful return from both functions, dptr points to data allocated by malloc(3). It\nis the caller responsibility to free the data when no longer needed.\n\nA typical iteration loop looks like:\n\ndatum key, nextkey, content;\nkey = gdbmfirstkey (dbf);\nwhile (key.dptr)\n{\ncontent = gdbmfetch (dbf, key);\n/* Do something with key and/or content */\nnextkey = gdbmnextkey (dbf, key);\nfree (key.dptr);\nkey = nextkey;\n}\n\nThese functions are intended to visit the database in read-only algorithms. Avoid any data‐\nbase modifications within the iteration loop. File visiting is based on a hash table. The\ngdbmdelete and, in most cases, gdbmstore, functions rearrange the hash table to make sure\nthat any collisions in the table do not leave some item `un-findable'. Thus, a call to ei‐\nther of these functions changes the order in which the keys are ordered. Therefore, these\nfunctions should not be used when iterating over all the keys in the database. For example,\nthe following loop is wrong: it is possible that some keys will not be visited or will be\nvisited twice if it is executed:\n\nkey = gdbmfirstkey (dbf);\nwhile (key.dptr)\n{\nnextkey = gdbmnextkey (dbf, key);\nif (some condition)\ngdbmdelete ( dbf, key );\nfree (key.dptr);\nkey = nextkey;\n}\n" }, { "name": "Updating the database", "content": "int gdbmstore (GDBMFILE dbf, datum key, datum content, int flag);\nDbf is the pointer returned by gdbmopen. Key is the key data. Content is the data\nto be associated with the key. Flag can have one of the following values:\n\nGDBMINSERT\nInsert only, generate an error if key exists;\n\nGDBMREPLACE\nReplace contents if key exists.\n\nThe function returns 0 on success and -1 on failure. If the key already exists in the\ndatabase and the flag is GDBMINSERT, the function does not modify the database. It\nsets gdbmerrno to GDBMCANNOTREPLACE and returns 1.\n\nint gdbmdelete (GDBMFILE dbf, datum key);\nLooks up and deletes the given key from the database dbf.\n\nThe return value is 0 if there was a successful delete or -1 on error. In the latter\ncase, the gdbmerrno value GDBMITEMNOTFOUND indicates that the key is not present\nin the database. Other gdbmerrno values indicate failure.\n" }, { "name": "Recovering structural consistency", "content": "If a function leaves the database in structurally inconsistent state, it can be recovered us‐\ning the gdbmrecover function.\n\nint gdbmrecover (GDBMFILE dbf, gdbmrecovery * rcvr, int flags)\nCheck the database file DBF and fix eventual inconsistencies. The rcvr argument can\nbe used both to control the recovery and to return additional statistics about the\nprocess, as indicated by flags. For a detailed discussion of these arguments and\ntheir usage, see the GDBM Manual, chapter Recovering structural consistency.\n\nYou can pass NULL as rcvr and 0 as flags, if no such control is needed.\n\nBy default, this function first checks the database for inconsistencies and attempts\nrecovery only if some were found. The special flags bit GDBMRCVRFORCE instructs\ngdbmrecovery to skip this check and to perform database recovery unconditionally.\n" }, { "name": "Export and import", "content": "GDBM database files can be exported (dumped) to so called flat files or imported (loaded)\nfrom them. A flat file contains exactly the same data as the original database, but it can‐\nnot be used for searches or updates. Its purpose is to keep the data from the database for\nrestoring it when the need arrives. As such, flat files are used for backup purposes, and\nfor sending databases over the wire.\n\nAs of GDBM version 1.21, there are two flat file formats. The ASCII file format encodes all\ndata in Base64 and stores not only key/data pairs, but also the original database file meta‐\ndata, such as file name, mode and ownership. Files in this format can be sent without addi‐\ntional encapsulation over transmission channels that normally allow only ASCII data, such as,\ne.g. SMTP. Due to additional metadata they allow for restoring an exact copy of the data‐\nbase, including file ownership and privileges, which is especially important if the database\nin question contained some security-related data. This is the preferred format.\n\nAnother flat file format is the binary format. It stores only key/data pairs and does not\nkeep information about the database file itself. It cannot be used to copy databases between\ndifferent architectures. The binary format was introduced in GDBM version 1.9.1 and is re‐\ntained mainly for backward compatibility.\n\nThe following functions are used to export or import GDBM database files.\n\nint gdbmdump (GDBMFILE dbf, const char *filename,\nint format, int openflag, int mode)\nDumps the database file dbf to the file filename in requested format. Allowed values\nfor format are: GDBMDUMPFMTASCII, to create an ASCII dump file, and\nGDBMDUMPFMTBINARY, to create a binary dump.\n\nThe value of openflag tells gdbmdump what to do if filename already exists. If it\nis GDBMNEWDB, the function will create a new output file, replacing it if it already\nexists. If its value is GDBMWRCREAT, the file will be created if it does not exist.\nIf it does exist, gdbmdump will return error.\n\nThe file mode to use when creating the output file is defined by the mode parameter.\nIts meaning is the same as for open(2).\n\nint gdbmload (GDBMFILE *pdbf, const char *filename,\nint flag, int metamask, unsigned long *errline)\nLoads data from the dump file filename into the database pointed to by pdbf. If pdbf\nis NULL, the function will try to create a new database. On success, the new\nGDBMFILE object will be stored in the memory location pointed to by pdbf. If the\ndump file carries no information about the original database file name, the function\nwill set gdbmerrno to GDBMNODBNAME and return -1, indicating failure.\n\nOtherwise, if pdbf points to an already open GDBMFILE, the function will load data\nfrom filename into that database.\n\nThe flag parameter controls the function behavior if a key from the dump file already\nexists in the database. See the gdbmstore function for its possible values.\n\nThe metamask parameter can be used to disable restoring certain bits of file's meta-\ndata from the information in the input dump file. It is a binary OR of zero or more\nof the following:\n\nGDBMMETAMASKMODE\nDo not restore file mode.\n\nGDBMMETAMASKOWNER\nDo not restore file owner.\n" }, { "name": "Other functions", "content": "int gdbmreorganize (GDBMFILE dbf);\nIf you have had a lot of deletions and would like to shrink the space used by the GDBM\nfile, this routine will reorganize the database.\n\nint gdbmsync (GDBMFILE dbf);\nSynchronizes the changes in dbf with its disk file.\n\nIt will not return until the disk file state is synchronized with the in-memory state\nof the database.\n\nint gdbmsetopt (GDBMFILE dbf, int option, void *value, int size);\nQuery or change some parameter of an already opened database. The option argument de‐\nfines what parameter to set or retrieve. If the set operation is requested, value\npoints to the new value. Its actual data type depends on option. If the get opera‐\ntion is requested, value points to a memory region where to store the return value.\nIn both cases, size contains the actual size of the memory pointed to by value.\n\nPossible values of option are:\n\nGDBMSETCACHESIZE\nGDBMCACHESIZE\nSet the size of the internal bucket cache. The value should point to a sizet\nholding the desired cache size, or the constant GDBMCACHEAUTO, to select the\nbest cache size automatically.\n\nBy default, a newly open database is configured to adapt the cache size to the\nnumber of index buckets in the database file. This provides for the best perfor‐\nmance.\n\nUse this option if you wish to limit the memory usage at the expense of perfor‐\nmance. If you chose to do so, please bear in mind that cache becomes effective\nwhen its size is greater then 2/3 of the number of index bucket counts in the\ndatabase. The best performance results are achieved when cache size equals the\nnumber of buckets.\n\nGDBMGETCACHESIZE\nReturn the size of the internal bucket cache. The value should point to a sizet\nvariable, where the size will be stored.\n\nGDBMGETFLAGS\nReturn the flags describing current state of the database. The value should point\nto an int variable where to store the flags. On success, its value will be simi‐\nlar to the flags used when opening the database, except that it will reflect the\ncurrent state (which may have been altered by another calls to gdbmsetopt).\n\nGDBMFASTMODE\nEnable or disable the fast writes mode, similar to the GDBMFAST option to\ngdbmopen.\n\nThis option is retained for compatibility with previous versions of GDBM.\n\nGDBMSETSYNCMODE\nGDBMSYNCMODE\nTurn on or off immediate disk synchronization after updates. The value should\npoint to an integer: 1 to turn synchronization on, and 0 to turn it off.\n\nNOTE: setting this option entails severe performance degradation and does not nec‐\nessarily ensure that the resulting database state is consistent, therefore we dis‐\ncourage its use. For a discussion of how to ensure database consistency with min‐\nimal performance overhead, see CRASH TOLERANCE below.\n\nGDBMGETSYNCMODE\nReturn the current synchronization status. The value should point to an int where\nthe status will be stored.\n\nGDBMSETCENTFREE\nGDBMCENTFREE\nEnable or disable central free block pool. The default is off, which is how pre‐\nvious versions of GDBM handled free blocks. If set, this option causes all subse‐\nquent free blocks to be placed in the global pool, allowing (in theory) more file\nspace to be reused more quickly. The value should point to an integer: TRUE to\nturn central block pool on, and FALSE to turn it off.\n\nThe GDBMCENTFREE alias is provided for compatibility with earlier versions.\n\nGDBMSETCOALESCEBLKS\nGDBMCOALESCEBLKS\nSet free block merging to either on or off. The default is off, which is how pre‐\nvious versions of GDBM handled free blocks. If set, this option causes adjacent\nfree blocks to be merged. This can become a CPU expensive process with time,\nthough, especially if used in conjunction with GDBMCENTFREE. The value should\npoint to an integer: TRUE to turn free block merging on, and FALSE to turn it off.\n\nGDBMGETCOALESCEBLKS\nReturn the current status of free block merging. The value should point to an int\nwhere the status will be stored.\n\nGDBMSETMAXMAPSIZE\nSets maximum size of a memory mapped region. The value should point to a value of\ntype sizet, unsigned long or unsigned. The actual value is rounded to the near‐\nest page boundary (the page size is obtained from sysconf(SCPAGESIZE)).\n\nGDBMGETMAXMAPSIZE\nReturn the maximum size of a memory mapped region. The value should point to a\nvalue of type sizet where to return the data.\n\nGDBMSETMMAP\nEnable or disable memory mapping mode. The value should point to an integer: TRUE\nto enable memory mapping or FALSE to disable it.\n\nGDBMGETMMAP\nCheck whether memory mapping is enabled. The value should point to an integer\nwhere to return the status.\n\nGDBMGETDBNAME\nReturn the name of the database disk file. The value should point to a variable\nof type char. A pointer to the newly allocated copy of the file name will be\nplaced there. The caller is responsible for freeing this memory when no longer\nneeded.\n\nGDBMGETBLOCKSIZE\nReturn the block size in bytes. The value should point to int.\n\nint gdbmfdesc (GDBMFILE dbf);\nReturns the file descriptor of the database dbf.\n" } ] }, "CRASH TOLERANCE": { "content": "By default GNU dbm does not protect the integrity of its databases from corruption or de‐\nstruction due to failures such as power outages, operating system kernel panics, or applica‐\ntion process crashes. Such failures could damage or destroy the underlying database.\n\nStarting with release 1.21 GNU dbm includes a mechanism that, if used correctly, enables\npost-crash recovery to a consistent state of the underlying database. This mechanism re‐\nquires OS and filesystem support and must be requested when gdbm is compiled. The crash-tol‐\nerance mechanism is a \"pure opt-in\" feature, in the sense that it has no effects whatsoever\nexcept on those applications that explicitly request it. For details, see the chapter Crash\nTolerance in the GDBM manual.\n", "subsections": [] }, "GLOBAL VARIABLES": { "content": "", "subsections": [ { "name": "gdbm_error gdbm_errno", "content": "This variable contains code of the most recent error that occurred. Note, that it is\nnot C variable in the proper sense: you can use its value, assign any value to it, but\ntaking its address will result in syntax error. It is a per-thread memory location.\n\nconst char *gdbmversion\nA string containing the library version number and build date.\n" }, { "name": "int const gdbm_version_number[3]", "content": "This variable contains library version numbers: major, minor, and patchlevel.\n" } ] }, "VERSIONING": { "content": "The version information is kept in two places. The version of the library is kept in the\ngdbmversionnumber variable, described above. Additionally, the header file gdbm.h defines\nthe following macros:\n\nGDBMVERSIONMAJOR\nMajor version number.\n\nGDBMVERSIONMINOR\nMinor version number.\n\nGDBMVERSIONPATCH\nPatchlevel number. 0 means no patchlevel.\n\nYou can use this to compare whether your header file corresponds to the library the program\nis linked with.\n\nThe following function can be used to compare two version numbers:\n\nint gdbmversioncmp (int const a[3], int const b[3])\nCompare two version numbers formatted as gdbmversionnumber. Return negative number\nif a is older than b, positive number if a is newer than b, and 0 if they are equal.\n", "subsections": [] }, "ERROR CODES": { "content": "GDBMNOERROR\nNo error occurred.\n\nGDBMMALLOCERROR\nMemory allocation failed.\n\nGDBMBLOCKSIZEERROR\nThis error is set by the gdbmopen function, if the value of its blocksize argument\nis incorrect and the GDBMBSEXACT flag is set.\n\nGDBMFILEOPENERROR\nThe library was not able to open a disk file. This can be set by gdbmopen,\ngdbmfdopen, gdbmdump and gdbmload functions.\n\nInspect the value of the system errno variable to get more detailed diagnostics.\n\nGDBMFILEWRITEERROR\nWriting to a disk file failed. This can be set by gdbmopen, gdbmfdopen, gdbmdump\nand gdbmload functions.\n\nInspect the value of the system errno variable to get more detailed diagnostics.\n\nGDBMFILESEEKERROR\nPositioning in a disk file failed. This can be set by gdbmopen function.\n\nInspect the value of the system errno variable to get a more detailed diagnostics.\n\nGDBMFILEREADERROR\nReading from a disk file failed. This can be set by gdbmopen, gdbmdump and\ngdbmload functions.\n\nInspect the value of the system errno variable to get a more detailed diagnostics.\n\nGDBMBADMAGICNUMBER\nThe file given as argument to gdbmopen function is not a valid gdbm file: it has a\nwrong magic number.\n\nGDBMEMPTYDATABASE\nThe file given as argument to gdbmopen function is not a valid gdbm file: it has zero\nlength. This error is returned unless the flags argument has GDBMNEWDB bit set.\n\nGDBMCANTBEREADER\nThis error code is set by the gdbmopen function if it is not able to lock file when\ncalled in GDBMREADER mode.\n\nGDBMCANTBEWRITER\nThis error code is set by the gdbmopen function if it is not able to lock file when\ncalled in writer mode.\n\nGDBMREADERCANTDELETE\nSet by the gdbmdelete, if it attempted to operate on a database that is open in read-\nonly mode.\n\nGDBMREADERCANTSTORE\nSet by the gdbmstore if it attempted to operate on a database that is open in read-\nonly mode.\n\nGDBMREADERCANTREORGANIZE\nSet by the gdbmreorganize if it attempted to operate on a database that is open in\nread-only mode.\n\nGDBMITEMNOTFOUND\nRequested item was not found. This error is set by gdbmdelete and gdbmfetch when\nthe requested key value is not found in the database.\n\nGDBMREORGANIZEFAILED\nThe gdbmreorganize function is not able to create a temporary database.\n\nGDBMCANNOTREPLACE\nCannot replace existing item. This error is set by the gdbmstore if the requested\nkey value is found in the database and the flag parameter is not GDBMREPLACE.\n\nGDBMMALFORMEDDATA\nInput data was malformed in some way. When returned by gdbmload, this means that the\ninput file was not a valid gdbm dump file. When returned by gdbmstore, this means\nthat either key or content parameter had its dptr field set to NULL.\n\nThe GDBMILLEGALDATA is an alias for this error code, maintained for backward compat‐\nibility.\n\nGDBMOPTALREADYSET\nRequested option can be set only once and was already set. As of version 1.21, this\nerror code is no longer used. In prior versions it could have been returned by the\ngdbmsetopt function when setting the GDBMCACHESIZE value.\n\nGDBMOPTBADVAL\nThe option argument is not valid or the value argument points to an invalid value in a\ncall to gdbmsetopt function.\n\nGDBMOPTILLEGAL is an alias for this error code, maintained for backward compatibil‐\nity. Modern applications should not use it.\n\nGDBMBYTESWAPPED\nThe gdbmopen function attempts to open a database which is created on a machine with\ndifferent byte ordering.\n\nGDBMBADFILEOFFSET\nThe gdbmopen function sets this error code if the file it tries to open has a wrong\nmagic number.\n\nGDBMBADOPENFLAGS\nSet by the gdbmdump function if supplied an invalid flags argument.\n\nGDBMFILESTATERROR\nGetting information about a disk file failed. The system errno will give more details\nabout the error.\n\nThis error can be set by the following functions: gdbmopen, gdbmreorganize.\n\nGDBMFILEEOF\nEnd of file was encountered where more data was expected to be present. This error\ncan occur when fetching data from the database and usually means that the database is\ntruncated or otherwise corrupted.\n\nThis error can be set by any GDBM function that does I/O. Some of these functions\nare: gdbmdelete, gdbmexists, gdbmfetch, gdbmexport, gdbmimport, gdbmreorganize,\ngdbmfirstkey, gdbmnextkey, gdbmstore.\n\nGDBMNODBNAME\nOutput database name is not specified. This error code is set by gdbmload if the\nfirst argument points to NULL and the input file does not specify the database name.\n\nGDBMERRFILEOWNER\nThis error code is set by gdbmload if it is unable to restore the database file\nowner. It is a mild error condition, meaning that the data have been restored suc‐\ncessfully, only changing the target file owner failed. Inspect the system errno vari‐\nable to get a more detailed diagnostics.\n\nGDBMERRFILEMODE\nThis error code is set by gdbmload if it is unable to restore database file mode. It\nis a mild error condition, meaning that the data have been restored successfully, only\nchanging the target file owner failed. Inspect the system errno variable to get a\nmore detailed diagnostics.\n\nGDBMNEEDRECOVERY\nDatabase is in inconsistent state and needs recovery. Call gdbmrecover if you get\nthis error.\n\nGDBMBACKUPFAILED\nThe GDBM engine is unable to create backup copy of the file.\n\nGDBMDIROVERFLOW\nBucket directory would overflow the size limit during an attempt to split hash bucket.\nThis error can occur while storing a new key.\n\nGDBMBADBUCKET\nInvalid index bucket is encountered in the database. Database recovery is needed.\n\nGDBMBADHEADER\nThis error is set by gdbmopen and gdbmfdopen, if the first block read from the\ndatabase file does not contain a valid GDBM header.\n\nGDBMBADAVAIL\nThe available space stack is invalid. This error can be set by gdbmopen and\ngdbmfdopen, if the extended database verification was requested (GDBMXVERIFY). It\nis also set by the gdbmavailverify function.\n\nThe database needs recovery.\n\nGDBMBADHASHTABLE\nHash table in a bucket is invalid. This error can be set by the following functions:\ngdbmdelete, gdbmexists, gdbmfetch, gdbmfirstkey, gdbmnextkey, and gdbmstore.\n\nThe database needs recovery.\n\nGDBMBADDIRENTRY\nBad directory entry found in the bucket. The database recovery is needed.\n\nGDBMFILECLOSEERROR\nThe gdbmclose function was unable to close the database file descriptor. The system\nerrno variable contains the corresponding error code.\n\nGDBMFILESYNCERROR\nCached content couldn't be synchronized to disk. Examine the errno variable to get\nmore info,\n\nDatabase recovery is needed.\n\nGDBMFILETRUNCATEERROR\nFile cannot be truncated. Examine the errno variable to get more info.\n\nThis error is set by gdbmopen and gdbmfdopen when called with the GDBMNEWDB flag.\n\nGDBMBUCKETCACHECORRUPTED\nThe bucket cache structure is corrupted. Database recovery is needed.\n\nGDBMBADHASHENTRY\nThis error is set during sequential access (@pxref{Sequential}), if the next hash ta‐\nble entry does not contain the expected key. This means that the bucket is malformed\nor corrupted and the database needs recovery.\n\nGDBMERRSNAPSHOTCLONE\nSet by the gdbmfailureatomic function if it was unable to clone the database file\ninto a snapshot. Inspect the system errno variable for the underlying cause of the\nerror. If errno is EINVAL or ENOSYS, crash tolerance settings will be removed from\nthe database.\n\nGDBMERRREALPATH\nSet by the gdbmfailureatomic function if the call to realpath function failed. re‐\nalpath is used to determine actual path names of the snapshot files. Examine the sys‐\ntem errno variable for details.\n\nGDBMERRUSAGE\nFunction usage error. That includes invalid argument values, and the like.\n", "subsections": [] }, "DBM COMPATIBILITY ROUTINES": { "content": "GDBM includes a compatibility library libgdbmcompat, for use with programs that expect tra‐\nditional UNIX dbm or ndbm interfaces, such as, e.g. Sendmail. The library is optional and\nthus may be absent in some binary distributions.\n\nAs the detailed discussion of the compatibility API is beyond the scope of this document, be‐\nlow we provide only a short reference. For details, see the GDBM Manual, chapter Compatibil‐\nity with standard dbm and ndbm.\n", "subsections": [ { "name": "DBM compatibility routines", "content": "In dbm compatibility mode only one file may be opened at a time. All users are assumed to be\nwriters. If the database file is read only, it will fail as a writer, but will be opened as\na reader. All returned pointers in datum structures point to data that the compatibility li‐\nbrary will free. They should be treated as static pointers (as standard UNIX dbm does).\n\nThe following interfaces are provided:\n" }, { "name": "#include ", "content": "int dbminit (const char *name);\nint store (datum key, datum content);\ndatum fetch (datum key);\nint delete (datum key);" }, { "name": "datum firstkey (void);", "content": "datum nextkey (datum key);" }, { "name": "int dbmclose (void);", "content": "" }, { "name": "NDBM Compatibility routines:", "content": "In this mode, multiple databases can be opened. Each database is identified by a handle of\ntype DBM *. As in the original NDBM, all returned pointers in datum structures point to data\nthat will be freed by the compatibility library. They should be treated as static pointers.\n\nThe following interfaces are provided:\n" }, { "name": "#include ", "content": "DBM *dbmopen (const char *name, int flags, int mode);\nvoid dbmclose (DBM *file);\ndatum dbmfetch (DBM *file, datum key);\nint dbmstore (DBM *file, datum key, datum content, int flags);\nint dbmdelete (DBM *file, datum key);\ndatum dbmfirstkey (DBM *file);\ndatum dbmnextkey (DBM *file, datum key);\nint dbmerror (DBM *file);\nint dbmclearerr (DBM *file);\nint dbmpagfno (DBM *file);\nint dbmdirfno (DBM *file);\nint dbmrdonly (DBM *file);\n" } ] }, "LINKING": { "content": "This library is accessed by specifying -lgdbm as the last parameter to the compile line,\ne.g.:\n\ngcc -o prog prog.c -lgdbm\n\nIf you wish to use the dbm or ndbm compatibility routines, you must link in the gdbmcompat\nlibrary as well. For example:\n\ngcc -o prog proc.c -lgdbm -lgdbmcompat\n\n", "subsections": [] }, "BUG REPORTS": { "content": "Send bug reports to .\n", "subsections": [] }, "SEE ALSO": { "content": "gdbmdump(1), gdbmload(1), gdbmtool(1).\n", "subsections": [] }, "AUTHORS": { "content": "by Philip A. Nelson, Jason Downs and Sergey Poznyakoff; crash tolerance by Terence Kelly.\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 1990 - 2021 Free Software Foundation, Inc.\n\nGDBM is free software; you can redistribute it and/or modify it under the terms of the GNU\nGeneral Public License as published by the Free Software Foundation; either version 1, or (at\nyour option) any later version.\n\nGDBM is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without\neven the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with GDBM. If not,\nsee \n", "subsections": [] }, "CONTACTS": { "content": "You may contact the original author by:\ne-mail: phil@cs.wwu.edu\nus-mail: Philip A. Nelson\nComputer Science Department\nWestern Washington University\nBellingham, WA 98226\n\nYou may contact the current maintainers by:\ne-mail: downsj@downsj.com\nand\ne-mail: gray@gnu.org\n\nFor questions and feedback regarding crash tolerance, you may contact Terence Kelly at:\ne-mail: tpkelly @ { acm.org, cs.princeton.edu, eecs.umich.edu }\n\n\nGDBM October 18, 2021 GDBM(3)", "subsections": [] } } } }