Perl Diver 2.31
Main Environment Variables Perl Default Values Perl Config - Summary Perl Config - Full Installed Modules List Directory uptime Docs

Module Documentation
Details and documentation about a specific module, including version and documentation (if available). Note that while links to perldoc.com and search.cpan.org are provided, the module may be part of a larger distribution. If you reach a File Not Found page on either site, please try the parent module.

SDBM_File

Name SDBM_File
Version 1.14
Located at /usr/lib64/perl5
File /usr/lib64/perl5/SDBM_File.pm
Is Core Yes
Search CPAN for this module SDBM_File
Documentation SDBM_File
Module Details SDBM_File

NAME

SDBM_File - Tied access to sdbm files


SYNOPSIS

 use Fcntl;   # For O_RDWR, O_CREAT, etc.
 use SDBM_File;
 tie(%h, 'SDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
   or die "Couldn't tie SDBM file 'filename': $!; aborting";
 # Now read and change the hash
 $h{newkey} = newvalue;
 print $h{oldkey}; 
 ...
 untie %h;


DESCRIPTION

SDBM_File establishes a connection between a Perl hash variable and a file in SDBM_File format. You can manipulate the data in the file just as if it were in a Perl hash, but when your program exits, the data will remain in the file, to be used the next time your program runs.

Tie

Use SDBM_File with the Perl built-in tie function to establish the connection between the variable and the file.

    tie %hash, 'SDBM_File', $basename, $modeflags, $perms;
    tie %hash, 'SDBM_File', $dirfile,  $modeflags, $perms, $pagfilename;

$basename is the base filename for the database. The database is two files with ``.dir'' and ``.pag'' extensions appended to $basename,

    $basename.dir     (or .sdbm_dir on VMS, per DIRFEXT constant)
    $basename.pag

The two filenames can also be given separately in full as $dirfile and $pagfilename. This suits for two files without ``.dir'' and ``.pag'' extensions, perhaps for example two files from the File::Temp manpage.

$modeflags can be the following constants from the Fcntl module (in the style of the open(2) system call),

    O_RDONLY          read-only access
    O_WRONLY          write-only access
    O_RDWR            read and write access

If you want to create the file if it does not already exist then bitwise-OR (|) O_CREAT too. If you omit O_CREAT and the database does not already exist then the tie call will fail.

    O_CREAT           create database if doesn't already exist

$perms is the file permissions bits to use if new database files are created. This parameter is mandatory even when not creating a new database. The permissions will be reduced by the user's umask so the usual value here would be 0666, or if some very private data then 0600. (See perlfunc/umask.)


EXPORTS

SDBM_File optionally exports the following constants:

  • PAGFEXT - the extension used for the page file, usually .pag.

  • DIRFEXT - the extension used for the directory file, .dir everywhere but VMS, where it is .sdbm_dir.

  • PAIRMAX - the maximum size of a stored hash entry, including the length of both the key and value.

These constants can also be used with fully qualified names, eg. SDBM_File::PAGFEXT.


DIAGNOSTICS

On failure, the tie call returns an undefined value and probably sets $! to contain the reason the file could not be tied.

sdbm store returned -1, errno 22, key "..." at ...

This warning is emitted when you try to store a key or a value that is too long. It means that the change was not recorded in the database. See BUGS AND WARNINGS below.


BUGS AND WARNINGS

There are a number of limits on the size of the data that you can store in the SDBM file. The most important is that the length of a key, plus the length of its associated value, may not exceed 1008 bytes.

See perlfunc/tie, perldbmfilter, Fcntl

Perl Diver brought to you by ScriptSolutions.com © 1997- 2024