This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Add PERL_NO_GET_CONTEXT to ODBM_File
[perl5.git] / ext / ODBM_File / ODBM_File.pm
CommitLineData
a0d0e21e
LW
1package ODBM_File;
2
96318ac8 3use strict;
698828ad 4use warnings;
96318ac8
PM
5
6require Tie::Hash;
da4061d3 7require XSLoader;
a0d0e21e 8
17f410f9 9our @ISA = qw(Tie::Hash);
040eaf47 10our $VERSION = "1.11";
c07a80fd 11
da4061d3 12XSLoader::load();
a0d0e21e
LW
13
141;
15
16__END__
a5f75d66
AD
17
18=head1 NAME
19
20ODBM_File - Tied access to odbm files
21
22=head1 SYNOPSIS
23
0fbd2a46 24 use Fcntl; # For O_RDWR, O_CREAT, etc.
a5f75d66
AD
25 use ODBM_File;
26
0fbd2a46
JH
27 # Now read and change the hash
28 $h{newkey} = newvalue;
29 print $h{oldkey};
30 ...
bbc7dcd2 31
0fbd2a46 32 untie %h;
bbc7dcd2 33
0fbd2a46 34=head1 DESCRIPTION
bbc7dcd2 35
0fbd2a46
JH
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.
a5f75d66 41
0fbd2a46
JH
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:
a5f75d66 45
0fbd2a46
JH
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
3c4b39be 100This warning is emitted when you try to store a key or a value that
0fbd2a46
JH
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.
a5f75d66 110
0fbd2a46 111See L<perlfunc/tie>, L<perldbmfilter>, L<Fcntl>
a5f75d66
AD
112
113=cut