1package SDBM_File;
2
3use strict;
4use warnings;
5
6require Tie::Hash;
7require XSLoader;
8
9our @ISA = qw(Tie::Hash);
10our $VERSION = "1.17";
11
12our @EXPORT_OK = qw(PAGFEXT DIRFEXT PAIRMAX);
13use Exporter "import";
14
15XSLoader::load();
16
171;
18
19__END__
20
21=head1 NAME
22
23SDBM_File - Tied access to sdbm files
24
25=head1 SYNOPSIS
26
27 use Fcntl;   # For O_RDWR, O_CREAT, etc.
28 use SDBM_File;
29
30 tie(%h, 'SDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
31   or die "Couldn't tie SDBM file 'filename': $!; aborting";
32
33 # Now read and change the hash
34 $h{newkey} = newvalue;
35 print $h{oldkey};
36 ...
37
38 untie %h;
39
40=head1 DESCRIPTION
41
42C<SDBM_File> establishes a connection between a Perl hash variable and
43a file in SDBM_File format.  You can manipulate the data in the file
44just as if it were in a Perl hash, but when your program exits, the
45data will remain in the file, to be used the next time your program
46runs.
47
48=head2 Tie
49
50Use C<SDBM_File> with the Perl built-in C<tie> function to establish
51the connection between the variable and the file.
52
53    tie %hash, 'SDBM_File', $basename, $modeflags, $perms;
54
55    tie %hash, 'SDBM_File', $dirfile,  $modeflags, $perms, $pagfilename;
56
57C<$basename> is the base filename for the database.  The database is two
58files with ".dir" and ".pag" extensions appended to C<$basename>,
59
60    $basename.dir     (or .sdbm_dir on VMS, per DIRFEXT constant)
61    $basename.pag
62
63The two filenames can also be given separately in full as C<$dirfile>
64and C<$pagfilename>.  This suits for two files without ".dir" and ".pag"
65extensions, perhaps for example two files from L<File::Temp>.
66
67C<$modeflags> can be the following constants from the C<Fcntl> module (in
68the style of the L<open(2)> system call),
69
70    O_RDONLY          read-only access
71    O_WRONLY          write-only access
72    O_RDWR            read and write access
73
74If you want to create the file if it does not already exist then bitwise-OR
75(C<|>) C<O_CREAT> too.  If you omit C<O_CREAT> and the database does not
76already exist then the C<tie> call will fail.
77
78    O_CREAT           create database if doesn't already exist
79
80C<$perms> is the file permissions bits to use if new database files are
81created.  This parameter is mandatory even when not creating a new database.
82The permissions will be reduced by the user's umask so the usual value here
83would be 0666, or if some very private data then 0600.  (See
84L<perlfunc/umask>.)
85
86=head1 EXPORTS
87
88SDBM_File optionally exports the following constants:
89
90=over
91
92=item *
93
94C<PAGFEXT> - the extension used for the page file, usually C<.pag>.
95
96=item *
97
98C<DIRFEXT> - the extension used for the directory file, C<.dir>
99everywhere but VMS, where it is C<.sdbm_dir>.
100
101=item *
102
103C<PAIRMAX> - the maximum size of a stored hash entry, including the
104length of both the key and value.
105
106=back
107
108These constants can also be used with fully qualified names,
109eg. C<SDBM_File::PAGFEXT>.
110
111=head1 DIAGNOSTICS
112
113On failure, the C<tie> call returns an undefined value and probably
114sets C<$!> to contain the reason the file could not be tied.
115
116=head2 C<sdbm store returned -1, errno 22, key "..." at ...>
117
118This warning is emitted when you try to store a key or a value that
119is too long.  It means that the change was not recorded in the
120database.  See BUGS AND WARNINGS below.
121
122=head1 SECURITY WARNING
123
124B<Do not accept SDBM files from untrusted sources!>
125
126The sdbm file format was designed for speed and convenience, not for
127portability or security.  A maliciously crafted file might cause perl to
128crash or even expose a security vulnerability.
129
130=head1 BUGS AND WARNINGS
131
132There are a number of limits on the size of the data that you can
133store in the SDBM file.  The most important is that the length of a
134key, plus the length of its associated value, may not exceed 1008
135bytes.
136
137See L<perlfunc/tie>, L<perldbmfilter>, L<Fcntl>
138
139=cut
140