{
    "mode": "perldoc",
    "parameter": "GDBM_File",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/GDBM_File/json",
    "generated": "2026-10-04T15:58:54Z",
    "synopsis": "use GDBMFile;\n[$db =] tie %hash, 'GDBMFile', $filename, GDBMWRCREAT, 0640\nor die \"$GDBMFile::gdbmerrno\";\n# Use the %hash...\n$e = $db->errno;\n$e = $db->syserrno;\n$str = $db->strerror;\n$bool = $db->needsrecovery;\n$db->clearerror;\n$db->reorganize;\n$db->sync;\n$n = $db->count;\n$n = $db->flags;\n$str = $db->dbname;\n$db->cachesize;\n$db->cachesize($newsize);\n$n = $db->blocksize;\n$bool = $db->syncmode;\n$db->syncmode($bool);\n$bool = $db->centfree;\n$db->centfree($bool);\n$bool = $db->coalesce;\n$db->coalesce($bool);\n$bool = $db->mmap;\n$size = $db->mmapsize;\n$db->mmapsize($newsize);\n$db->recover(%args);\nuntie %hash ;",
    "sections": {
        "NAME": {
            "content": "GDBMFile - Perl5 access to the gdbm library.\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use GDBMFile;\n[$db =] tie %hash, 'GDBMFile', $filename, GDBMWRCREAT, 0640\nor die \"$GDBMFile::gdbmerrno\";\n# Use the %hash...\n\n$e = $db->errno;\n$e = $db->syserrno;\n$str = $db->strerror;\n$bool = $db->needsrecovery;\n\n$db->clearerror;\n\n$db->reorganize;\n$db->sync;\n\n$n = $db->count;\n\n$n = $db->flags;\n\n$str = $db->dbname;\n\n$db->cachesize;\n$db->cachesize($newsize);\n\n$n = $db->blocksize;\n\n$bool = $db->syncmode;\n$db->syncmode($bool);\n\n$bool = $db->centfree;\n$db->centfree($bool);\n\n$bool = $db->coalesce;\n$db->coalesce($bool);\n\n$bool = $db->mmap;\n\n$size = $db->mmapsize;\n$db->mmapsize($newsize);\n\n$db->recover(%args);\n\nuntie %hash ;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "GDBMFile is a module which allows Perl programs to make use of the facilities provided by the\nGNU gdbm library. If you intend to use this module you should really have a copy of the GDBM\nmanual at hand. The manual is avaialble online at <https://www.gnu.org.ua/software/gdbm/manual>.\n\nMost of the gdbm functions are available through the GDBMFile interface.\n\nUnlike Perl's built-in hashes, it is not safe to \"delete\" the current item from a GDBMFile tied\nhash while iterating over it with \"each\". This is a limitation of the gdbm library.\n",
            "subsections": [
                {
                    "name": "Tie",
                    "content": "Use the Perl built-in tie to associate a GDBM database with a Perl hash:\n\ntie %hash, 'GDBMFile', $filename, $flags, $mode;\n\nHere, *$filename* is the name of the database file to open or create. *$flags* is a bitwise OR\nof *access mode* and optional *modifiers*. Access mode is one of:\n\nGDBMREADER\nOpen existing database file in read-only mode.\n\nGDBMWRITER\nOpen existing database file in read-write mode.\n\nGDBMWRCREAT\nIf the database file exists, open it in read-write mode. If it doesn't, create it first and\nopen read-write.\n\nGDBMNEWDB\nCreate new database and open it read-write. If the database already exists, truncate it\nfirst.\n\nA number of modifiers can be OR'd to the access mode. Most of them are rarely needed (see\n<https://www.gnu.org.ua/software/gdbm/manual/Open.html> for a complete list), but one is worth\nmentioning. The GDBMNUMSYNC modifier, when used with GDBMNEWDB, instructs GDBM to create the\ndatabase in *extended* (so called *numsync*) format. This format is best suited for\ncrash-tolerant implementations. See CRASH TOLERANCE below for more information.\n\nThe *$mode* parameter is the file mode for creating new database file. Use an octal constant or\na combination of \"SI*\" constants from the Fcntl module. This parameter is used if *$flags* is\nGDBMNEWDB or GDBMWRCREAT.\n\nOn success, tie returns an object of class GDBMFile. On failure, it returns undef. It is\nrecommended to always check the return value, to make sure your hash is successfully associated\nwith the database file. See ERROR HANDLING below for examples.\n"
                }
            ]
        },
        "STATIC METHODS": {
            "content": "GDBMversion\n$str = GDBMFile->GDBMversion;\n@ar = GDBMFile->GDBMversion;\n\nReturns the version number of the underlying libgdbm library. In scalar context, returns the\nlibrary version formatted as string:\n\nMINOR.MAJOR[.PATCH][ (GUESS)]\n\nwhere *MINOR*, *MAJOR*, and *PATCH* are version numbers, and *GUESS* is a guess level (see\nbelow).\n\nIn list context, returns a list:\n\n( MINOR, MAJOR, PATCH [, GUESS] )\n\nThe *GUESS* component is present only if libgdbm version is 1.8.3 or earlier. This is because\nearlier releases of libgdbm did not include information about their version and the GDBMFile\nmodule has to implement certain guesswork in order to determine it. *GUESS* is a textual\ndescription in string context, and a positive number indicating how rough the guess is in list\ncontext. Possible values are:\n\n1 - exact guess\nThe major and minor version numbers are guaranteed to be correct. The actual patchlevel is\nmost probably guessed right, but can be 1-2 less than indicated.\n\n2 - approximate\nThe major and minor number are guaranteed to be correct. The patchlevel is set to the upper\nbound.\n\n3 - rough guess\nThe version is guaranteed to be not newer than *MAJOR*.*MINOR*.\n",
            "subsections": []
        },
        "ERROR HANDLING": {
            "content": "$GDBMFile::gdbmerrno\nWhen referenced in numeric context, retrieves the current value of the gdbmerrno variable, i.e.\na numeric code describing the state of the most recent operation on any gdbm database. Each\nnumeric code has a symbolic name associated with it. For a comprehensive list of these, see\n<https://www.gnu.org.ua/software/gdbm/manual/Error-codes.html>. Notice, that this list includes\nall error codes defined for the most recent version of gdbm. Depending on the actual version of\nthe library GDBMFile is built with, some of these may be missing.\n\nIn string context, $gdbmerrno returns a human-readable description of the error. If necessary,\nthis description includes the value of $!. This makes it possible to use it in diagnostic\nmessages. For example, the usual tying sequence is\n\ntie %hash, 'GDBMFile', $filename, GDBMWRCREAT, 0640\nor die \"$GDBMFile::gdbmerrno\";\n\nThe following, more complex, example illustrates how you can fall back to read-only mode if the\ndatabase file permissions forbid read-write access:\n\nuse Errno qw(EACCES);\nunless (tie(%hash, 'GDBMFile', $filename, GDBMWRCREAT, 0640)) {\nif ($GDBMFile::gdbmerrno == GDBMFILEOPENERROR\n&& $!{EACCES}) {\nif (tie(%hash, 'GDBMFile', $filename, GDBMREADER, 0640)) {\ndie \"$GDBMFile::gdbmerrno\";\n}\n} else {\ndie \"$GDBMFile::gdbmerrno\";\n}\n}\n\ngdbmchecksyserr\nif (gdbmchecksyserr(gdbmerrno)) ...\n\nReturns true if the system error number ($!) gives more information on the cause of the error.\n",
            "subsections": []
        },
        "DATABASE METHODS": {
            "content": "close\n$db->close;\n\nCloses the database. Normally you would just do untie. However, you will need to use this\nfunction if you have explicitly assigned the result of tie to a variable, and wish to release\nthe database to another users. Consider the following code:\n\n$db = tie %hash, 'GDBMFile', $filename, GDBMWRCREAT, 0640;\n# Do something with %hash or $db...\nuntie %hash;\n$db->close;\n\nIn this example, doing untie alone is not enough, since the database would remain referenced by\n$db, and, as a consequence, the database file would remain locked. Calling $db->close ensures\nthe database file is closed and unlocked.\n\nerrno\n$db->errno\n\nReturns the last error status associated with this database. In string context, returns a\nhuman-readable description of the error. See also $GDBMFile::gdbmerrno variable above.\n\nsyserrno\n$db->syserrno\n\nReturns the last system error status (C \"errno\" variable), associated with this database,\n\nstrerror\n$db->strerror\n\nReturns textual description of the last error that occurred in this database.\n\nclearerror\n$db->clearerror\n\nClear error status.\n\nneedsrecovery\n$db->needsrecovery\n\nReturns true if the database needs recovery.\n\nreorganize\n$db->reorganize;\n\nReorganizes the database.\n\nsync\n$db->sync;\n\nSynchronizes recent changes to the database with its disk copy.\n\ncount\n$n = $db->count;\n\nReturns number of keys in the database.\n\nflags\n$db->flags;\n\nReturns flags passed as 4th argument to tie.\n\ndbname\n$db->dbname;\n\nReturns the database name (i.e. 3rd argument to tie.\n\ncachesize\n$db->cachesize;\n$db->cachesize($newsize);\n\nReturns the size of the internal GDBM cache for that database.\n\nCalled with argument, sets the size to *$newsize*.\n\nblocksize\n$db->blocksize;\n\nReturns the block size of the database.\n\nsyncmode\n$db->syncmode;\n$db->syncmode($bool);\n\nReturns the status of the automatic synchronization mode. Called with argument, enables or\ndisables the sync mode, depending on whether $bool is true or false.\n\nWhen synchronization mode is on (true), any changes to the database are immediately written to\nthe disk. This ensures database consistency in case of any unforeseen errors (e.g. power\nfailures), at the expense of considerable slowdown of operation.\n\nSynchronization mode is off by default.\n\ncentfree\n$db->centfree;\n$db->centfree($bool);\n\nReturns status of the central free block pool (0 - disabled, 1 - enabled).\n\nWith argument, changes its status.\n\nBy default, central free block pool is disabled.\n\ncoalesce\n$db->coalesce;\n$db->coalesce($bool);\n\nmmap\n$db->mmap;\n\nReturns true if memory mapping is enabled.\n\nThis method will croak if the libgdbm library is complied without memory mapping support.\n\nmmapsize\n$db->mmapsize;\n$db->mmapsize($newsize);\n\nIf memory mapping is enabled, returns the size of memory mapping. With argument, sets the size\nto $newsize.\n\nThis method will croak if the libgdbm library is complied without memory mapping support.\n\nrecover\n$db->recover(%args);\n\nRecovers data from a failed database. %args is optional and can contain following keys:\n\nerr => sub { ... }\nReference to code for detailed error reporting. Upon encountering an error, recover will\ncall this sub with a single argument - a description of the error.\n\nbackup => \\$str\nCreates a backup copy of the database before recovery and returns its filename in $str.\n\nmaxfailedkeys => $n\nMaximum allowed number of failed keys. If the actual number becomes equal to *$n*, recover\naborts and returns error.\n\nmaxfailedbuckets => $n\nMaximum allowed number of failed buckets. If the actual number becomes equal to *$n*,\nrecover aborts and returns error.\n\nmaxfailures => $n\nMaximum allowed number of failures during recovery.\n\nstat => \\%hash\nReturn recovery statistics in *%hash*. Upon return, the following keys will be present:\n\nrecoveredkeys\nNumber of successfully recovered keys.\n\nrecoveredbuckets\nNumber of successfully recovered buckets.\n\nfailedkeys\nNumber of keys that failed to be retrieved.\n\nfailedbuckets\nNumber of buckets that failed to be retrieved.\n\nconvert\n$db->convert($format);\n\nChanges the format of the database file referred to by $db.\n\nStarting from version 1.20, gdbm supports two database file formats: *standard* and *extended*.\nThe former is the traditional database format, used by previous gdbm versions. The *extended*\nformat contains additional data and is recommended for use in crash tolerant applications.\n\n<https://www.gnu.org.ua/software/gdbm/manual/Numsync.html>, for the discussion of both formats.\n\nThe $format argument sets the new desired database format. It is GDBMNUMSYNC to convert the\ndatabase from standard to extended format, and 0 to convert it from extended to standard format.\n\nIf the database is already in the requested format, the function returns success without doing\nanything.\n\ndump\n$db->dump($filename, %options)\n\nCreates a dump of the database file in *$filename*. Such file can be used as a backup copy or\nsent over a wire to recreate the database on another machine. To create a database from the dump\nfile, use the load method.\n\nGDBM supports two dump formats: old *binary* and new *ascii*. The binary format is not portable\nacross architectures and is deprecated. It is supported for backward compatibility. The ascii\nformat is portable and stores additional meta-data about the file. It was introduced with the\ngdbm version 1.11 and is the preferred dump format. The dump method creates ascii dumps by\ndefault.\n\nIf the named file already exists, the function will refuse to overwrite and will croak an error.\nIf it doesn't exist, it will be created with the mode 0666 modified by the current umask.\n\nThese defaults can be altered using the following *%options*:\n\nbinary => 1\nCreate dump in *binary* format.\n\nmode => *MODE*\nSet file mode to *MODE*.\n\noverwrite => 1\nSilently overwrite existing files.\n\nload\n$db->load($filename, %options)\n\nLoad the data from the dump file *$filename* into the database *$db*. The file must have been\npreviously created using the dump method. File format is recognized automatically. By default,\nthe function will croak if the dump contains a key that already exists in the database. It will\nsilently ignore the failure to restore database mode and/or ownership. These defaults can be\naltered using the following *%options*:\n\nreplace => 1\nReplace existing keys.\n\nrestoremode => 0 | 1\nIf *0*, don't try to restore the mode of the database file to that stored in the dump.\n\nrestoreowner => 0 | 1\nIf *0*, don't try to restore the owner of the database file to that stored in the dump.\n\nstricterrors => 1\nCroak if failed to restore ownership and/or mode.\n\nThe usual sequence to recreate a database from the dump file is:\n\nmy %hash;\nmy $db = tie %hash, 'GDBMFile', 'a.db', GDBMNEWDB, 0640;\n$db->load('a.dump');\n",
            "subsections": []
        },
        "CRASH TOLERANCE": {
            "content": "Crash tolerance is a new feature that, given appropriate support from the OS and the filesystem,\nguarantees that a logically consistent recent state of the database can be recovered following a\ncrash, such as power outage, OS kernel panic, or the like.\n\nCrash tolerance support appeared in gdbm version 1.21. The theory behind it is explained in\n\"Crashproofing the Original NoSQL Key-Value Store\", by Terence Kelly\n(<https://queue.acm.org/detail.cfm?id=3487353>). A detailed discussion of the gdbm\nimplementation is available in the GDBM Manual\n(<https://www.gnu.org.ua/software/gdbm/manual/Crash-Tolerance.html>). The information below\ndescribes the Perl interface.\n\nFor maximum robustness, we recommend to use *extended database format* for crash tolerant\ndatabases. To create a database in extended format, use the GDBMNEWDB|GDBMNUMSYNC when opening\nthe database, e.g.:\n\n$db = tie %hash, 'GDBMFile', $filename,\nGDBMNEWDB|GDBMNUMSYNC, 0640;\n\nTo convert existing database to the extended format, use the convert method, described above,\ne.g.:\n\n$db->convert(GDBMNUMSYNC);\n\ncrashtolerancestatus\nGDBMFile->crashtolerancestatus;\n\nThis static method returns the status of crash tolerance support. A non-zero value means crash\ntolerance is compiled in and supported by the operating system.\n\nfailureatomic\n$db->failureatomic($even, $odd)\n\nEnables crash tolerance for the database $db, Arguments are the pathnames of two files that will\nbe created and filled with *snapshots* of the database file. The two files must not exist when\nthis method is called and must reside on the same filesystem as the database file. This\nfilesystem must be support the *reflink* operation\n(https://www.gnu.org.ua/software/gdbm/manual/Filesystems-supporting-crash-tolerance.html>.\n\nAfter a successful call to failureatomic, every call to $db-sync> method will make an efficient\nreflink snapshot of the database file in one of these files; consecutive calls to sync alternate\nbetween the two, hence the names.\n\nThe most recent of these files can be used to recover the database after a crash. To select the\nright snapshot, use the latestsnapshot static method.\n\nlatestsnapshot\n$file = GDBMFile->latestsnapshot($even, $odd);\n\n($file, $error) = GDBMFile->latestsnapshot($even, $odd);\n\nGiven the two snapshot names (the ones used previously in a call to failureatomic), this method\nselects the one suitable for database recovery, i.e. the file which contains the most recent\ndatabase snapshot.\n\nIn scalar context, it returns the selected file name or undef in case of failure.\n\nIn array context, the returns a list of two elements: the file name and status code. On success,\nthe file name is defined and the code is GDBMSNAPSHOTOK. On error, the file name is undef, and\nthe status is one of the following:\n\nGDBMSNAPSHOTBAD\nNeither snapshot file is applicable. This means that the crash has occurred before a call to\nfailureatomic completed. In this case, it is best to fall back on a safe backup copy of the\ndata file.\n\nGDBMSNAPSHOTERR\nA system error occurred. Examine $! for details. See\n<https://www.gnu.org.ua/software/gdbm/manual/Crash-recovery.html> for a comprehensive list\nof error codes and their meaning.\n\nGDBMSNAPSHOTSAME\nThe file modes and modification dates of both snapshot files are exactly the same. This can\nhappen only for databases in standard format.\n\nGDBMSNAPSHOTSUSPICIOUS\nThe *numsync* counters of the two snapshots differ by more than one. The most probable\nreason is programmer's error: the two parameters refer to snapshots belonging to different\ndatabase files.\n",
            "subsections": []
        },
        "AVAILABILITY": {
            "content": "gdbm is available from any GNU archive. The master site is \"ftp.gnu.org\", but you are strongly\nurged to use one of the many mirrors. You can obtain a list of mirror sites from\n<http://www.gnu.org/order/ftp.html>.\n",
            "subsections": []
        },
        "SECURITY AND PORTABILITY": {
            "content": "GDBM files are not portable across platforms. If you wish to transfer a GDBM file over the wire,\ndump it to a portable format first.\n\nDo not accept GDBM files from untrusted sources.\n\nRobustness of GDBM against corrupted databases depends highly on its version. Versions prior to\n1.15 did not implement any validity checking, so that a corrupted or maliciously crafted\ndatabase file could cause perl to crash or even expose a security vulnerability. Versions\nbetween 1.15 and 1.20 were progressively strengthened against invalid inputs. Finally, version\n1.21 had undergone extensive fuzzy checking which proved its ability to withstand any kinds of\ninputs without crashing.\n",
            "subsections": []
        },
        "SEE ALSO": {
            "content": "",
            "subsections": [
                {
                    "name": "perl",
                    "content": ""
                }
            ]
        }
    },
    "summary": "GDBMFile - Perl5 access to the gdbm library.",
    "flags": [],
    "examples": [],
    "see_also": []
}