1package ODBM_File;
2
3use strict;
4use warnings;
5
6require Tie::Hash;
7use XSLoader ();
8
9our @ISA = qw(Tie::Hash);
10our $VERSION = "1.07";
11
12XSLoader::load 'ODBM_File', $VERSION;
13
141;
15
16__END__
17
18=head1 NAME
19
20ODBM_File - Tied access to odbm files
21
22=head1 SYNOPSIS
23
24 use Fcntl;   # For O_RDWR, O_CREAT, etc.
25 use ODBM_File;
26
27  # Now read and change the hash
28  $h{newkey} = newvalue;
29  print $h{oldkey};
30  ...
31
32  untie %h;
33
34=head1 DESCRIPTION
35
36C<ODBM_File> establishes a connection between a Perl hash variable and
37a file in ODBM_File format;.  You can manipulate the data in the file
38just as if it were in a Perl hash, but when your program exits, the
39data will remain in the file, to be used the next time your program
40runs.
41
42Use C<ODBM_File> with the Perl built-in C<tie> function to establish
43the connection between the variable and the file.  The arguments to
44C<tie> should be:
45
46=over 4
47
48=item 1.
49
50The hash variable you want to tie.
51
52=item 2.
53
54The string C<"ODBM_File">.  (Ths tells Perl to use the C<ODBM_File>
55package to perform the functions of the hash.)
56
57=item 3.
58
59The name of the file you want to tie to the hash.
60
61=item 4.
62
63Flags.  Use one of:
64
65=over 2
66
67=item C<O_RDONLY>
68
69Read-only access to the data in the file.
70
71=item C<O_WRONLY>
72
73Write-only access to the data in the file.
74
75=item C<O_RDWR>
76
77Both read and write access.
78
79=back
80
81If you want to create the file if it does not exist, add C<O_CREAT> to
82any of these, as in the example.  If you omit C<O_CREAT> and the file
83does not already exist, the C<tie> call will fail.
84
85=item 5.
86
87The default permissions to use if a new file is created.  The actual
88permissions will be modified by the user's umask, so you should
89probably use 0666 here. (See L<perlfunc/umask>.)
90
91=back
92
93=head1 DIAGNOSTICS
94
95On failure, the C<tie> call returns an undefined value and probably
96sets C<$!> to contain the reason the file could not be tied.
97
98=head2 C<odbm store returned -1, errno 22, key "..." at ...>
99
100This warning is emitted when you try to store a key or a value that
101is too long.  It means that the change was not recorded in the
102database.  See BUGS AND WARNINGS below.
103
104=head1 BUGS AND WARNINGS
105
106There are a number of limits on the size of the data that you can
107store in the ODBM file.  The most important is that the length of a
108key, plus the length of its associated value, may not exceed 1008
109bytes.
110
111See L<perlfunc/tie>, L<perldbmfilter>, L<Fcntl>
112
113=cut
114