CONTENTS

• NAME
• SYNOPSIS
• DESCRIPTION
  • Tie
• STATIC METHODS
  • GDBM_version
• ERROR HANDLING
  • $GDBM_File::gdbm_errno
  • gdbm_check_syserr
• DATABASE METHODS
  • close
  • errno
  • syserrno
  • strerror
  • clear_error
  • needs_recovery
  • reorganize
  • sync
  • count
  • flags
  • dbname
  • cache_size
  • block_size
  • sync_mode
  • centfree
  • coalesce
  • mmap
  • mmapsize
  • recover
  • convert
  • dump
  • load
• CRASH TOLERANCE
  • crash_tolerance_status
  • failure_atomic
  • latest_snapshot
• AVAILABILITY
• SECURITY AND PORTABILITY
• SEE ALSO

#NAME

GDBM_File - Perl5 access to the gdbm library.

#SYNOPSIS

use GDBM_File;
[$db =] tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
            or die "$GDBM_File::gdbm_errno";
# Use the %hash...

$e = $db->errno;
$e = $db->syserrno;
$str = $db->strerror;
$bool = $db->needs_recovery;

$db->clear_error;

$db->reorganize;
$db->sync;

$n = $db->count;

$n = $db->flags;

$str = $db->dbname;

$db->cache_size;
$db->cache_size($newsize);

$n = $db->block_size;

$bool = $db->sync_mode;
$db->sync_mode($bool);

$bool = $db->centfree;
$db->centfree($bool);

$bool = $db->coalesce;
$db->coalesce($bool);

$bool = $db->mmap;

$size = $db->mmapsize;
$db->mmapsize($newsize);

$db->recover(%args);

untie %hash ;

#DESCRIPTION

GDBM_File is a module which allows Perl programs to make use of the facilities provided by the GNU gdbm library. If you intend to use this module you should really have a copy of the GDBM manual at hand. The manual is avaialble online at https://www.gnu.org.ua/software/gdbm/manual.

Most of the gdbm functions are available through the GDBM_File interface.

Unlike Perl's built-in hashes, it is not safe to delete the current item from a GDBM_File tied hash while iterating over it with each. This is a limitation of the gdbm library.

#Tie

Use the Perl built-in tie to associate a GDBM database with a Perl hash:

tie %hash, 'GDBM_File', $filename, $flags, $mode;

Here, $filename is the name of the database file to open or create. $flags is a bitwise OR of access mode and optional modifiers. Access mode is one of:

#GDBM_READER

Open existing database file in read-only mode.

#GDBM_WRITER

Open existing database file in read-write mode.

#GDBM_WRCREAT

If the database file exists, open it in read-write mode. If it doesn't, create it first and open read-write.

#GDBM_NEWDB

Create new database and open it read-write. If the database already exists, truncate it first.

A number of modifiers can be OR'd to the access mode. Most of them are rarely needed (see https://www.gnu.org.ua/software/gdbm/manual/Open.html for a complete list), but one is worth mentioning. The GDBM_NUMSYNC modifier, when used with GDBM_NEWDB, instructs GDBM to create the database in extended (so called numsync) format. This format is best suited for crash-tolerant implementations. See CRASH TOLERANCE below for more information.

The $mode parameter is the file mode for creating new database file. Use an octal constant or a combination of S_I* constants from the Fcntl module. This parameter is used if $flags is GDBM_NEWDB or GDBM_WRCREAT.

On success, tie returns an object of class GDBM_File. On failure, it returns undef. It is recommended to always check the return value, to make sure your hash is successfully associated with the database file. See ERROR HANDLING below for examples.

#STATIC METHODS

#GDBM_version

$str = GDBM_File->GDBM_version;
@ar = GDBM_File->GDBM_version;

Returns the version number of the underlying libgdbm library. In scalar context, returns the library version formatted as string:

MINOR.MAJOR[.PATCH][ (GUESS)]

where MINOR, MAJOR, and PATCH are version numbers, and GUESS is a guess level (see below).

In list context, returns a list:

( MINOR, MAJOR, PATCH [, GUESS] )

The GUESS component is present only if libgdbm version is 1.8.3 or earlier. This is because earlier releases of libgdbm did not include information about their version and the GDBM_File module has to implement certain guesswork in order to determine it. GUESS is a textual description in string context, and a positive number indicating how rough the guess is in list context. Possible values are:

#1 - exact guess

The major and minor version numbers are guaranteed to be correct. The actual patchlevel is most probably guessed right, but can be 1-2 less than indicated.

#2 - approximate

The major and minor number are guaranteed to be correct. The patchlevel is set to the upper bound.

#3 - rough guess

The version is guaranteed to be not newer than MAJOR.MINOR.

#ERROR HANDLING

#$GDBM_File::gdbm_errno

When referenced in numeric context, retrieves the current value of the gdbm_errno variable, i.e. a numeric code describing the state of the most recent operation on any gdbm database. Each numeric code has a symbolic name associated with it. For a comprehensive list of these, see https://www.gnu.org.ua/software/gdbm/manual/Error-codes.html. Notice, that this list includes all error codes defined for the most recent version of gdbm. Depending on the actual version of the library GDBM_File is built with, some of these may be missing.

In string context, $gdbm_errno returns a human-readable description of the error. If necessary, this description includes the value of $!. This makes it possible to use it in diagnostic messages. For example, the usual tying sequence is

tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640
     or die "$GDBM_File::gdbm_errno";

The following, more complex, example illustrates how you can fall back to read-only mode if the database file permissions forbid read-write access:

use Errno qw(EACCES);
unless (tie(%hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640)) {
    if ($GDBM_File::gdbm_errno == GDBM_FILE_OPEN_ERROR
        && $!{EACCES}) {
        if (tie(%hash, 'GDBM_File', $filename, GDBM_READER, 0640)) {
            die "$GDBM_File::gdbm_errno";
        }
    } else {
        die "$GDBM_File::gdbm_errno";
    }
}

#gdbm_check_syserr

if (gdbm_check_syserr(gdbm_errno)) ...

Returns true if the system error number ($!) gives more information on the cause of the error.

#DATABASE METHODS

#close

$db->close;

Closes the database. Normally you would just do untie. However, you will need to use this function if you have explicitly assigned the result of tie to a variable, and wish to release the database to another users. Consider the following code:

$db = tie %hash, 'GDBM_File', $filename, GDBM_WRCREAT, 0640;
# Do something with %hash or $db...
untie %hash;
$db->close;

In this example, doing untie alone is not enough, since the database would remain referenced by $db, and, as a consequence, the database file would remain locked. Calling $db->close ensures the database file is closed and unlocked.

#errno

$db->errno

Returns the last error status associated with this database. In string context, returns a human-readable description of the error. See also $GDBM_File::gdbm_errno variable above.

#syserrno

$db->syserrno

Returns the last system error status (C errno variable), associated with this database,

#strerror

$db->strerror

Returns textual description of the last error that occurred in this database.

#clear_error

$db->clear_error

Clear error status.

#needs_recovery

$db->needs_recovery

Returns true if the database needs recovery.

#reorganize

$db->reorganize;

Reorganizes the database.

#sync

$db->sync;

Synchronizes recent changes to the database with its disk copy.

#count

$n = $db->count;

Returns number of keys in the database.

#flags

$db->flags;

Returns flags passed as 4th argument to tie.

#dbname

$db->dbname;

Returns the database name (i.e. 3rd argument to tie.