1package NDBM_File;
2
3use strict;
4use warnings;
5
6require Tie::Hash;
7require XSLoader;
8
9our @ISA = qw(Tie::Hash);
10our $VERSION = "1.15";
11
12XSLoader::load();
13
141;
15
16__END__
17
18=head1 NAME
19
20NDBM_File - Tied access to ndbm files
21
22=head1 SYNOPSIS
23
24  use Fcntl;   # For O_RDWR, O_CREAT, etc.
25  use NDBM_File;
26
27  tie(%h, 'NDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
28    or die "Couldn't tie NDBM file 'filename': $!; aborting";
29
30  # Now read and change the hash
31  $h{newkey} = newvalue;
32  print $h{oldkey};
33  ...
34
35  untie %h;
36
37=head1 DESCRIPTION
38
39C<NDBM_File> establishes a connection between a Perl hash variable and
40a file in NDBM_File format;.  You can manipulate the data in the file
41just as if it were in a Perl hash, but when your program exits, the
42data will remain in the file, to be used the next time your program
43runs.
44
45Use C<NDBM_File> with the Perl built-in C<tie> function to establish
46the connection between the variable and the file.  The arguments to
47C<tie> should be:
48
49=over 4
50
51=item 1.
52
53The hash variable you want to tie.
54
55=item 2.
56
57The string C<"NDBM_File">.  (Ths tells Perl to use the C<NDBM_File>
58package to perform the functions of the hash.)
59
60=item 3.
61
62The name of the file you want to tie to the hash.
63
64=item 4.
65
66Flags.  Use one of:
67
68=over 2
69
70=item C<O_RDONLY>
71
72Read-only access to the data in the file.
73
74=item C<O_WRONLY>
75
76Write-only access to the data in the file.
77
78=item C<O_RDWR>
79
80Both read and write access.
81
82=back
83
84If you want to create the file if it does not exist, add C<O_CREAT> to
85any of these, as in the example.  If you omit C<O_CREAT> and the file
86does not already exist, the C<tie> call will fail.
87
88=item 5.
89
90The default permissions to use if a new file is created.  The actual
91permissions will be modified by the user's umask, so you should
92probably use 0666 here. (See L<perlfunc/umask>.)
93
94=back
95
96=head1 DIAGNOSTICS
97
98On failure, the C<tie> call returns an undefined value and probably
99sets C<$!> to contain the reason the file could not be tied.
100
101=head2 C<ndbm store returned -1, errno 22, key "..." at ...>
102
103This warning is emitted when you try to store a key or a value that
104is too long.  It means that the change was not recorded in the
105database.  See BUGS AND WARNINGS below.
106
107=head1 SECURITY AND PORTABILITY
108
109B<Do not accept NDBM files from untrusted sources.>
110
111On modern Linux systems these are typically GDBM files, which are not
112portable across platforms.
113
114The GDBM documentation doesn't imply that files from untrusted sources
115can be safely used with C<libgdbm>.
116
117Systems that don't use GDBM compatibilty for ndbm support will be
118using a platform specific library, possibly inherited from BSD
119systems, where it may or may not be safe to use an untrusted file.
120
121A maliciously crafted file might cause perl to crash or even expose a
122security vulnerability.
123
124=head1 BUGS AND WARNINGS
125
126There are a number of limits on the size of the data that you can
127store in the NDBM file.  The most important is that the length of a
128key, plus the length of its associated value, may not exceed 1008
129bytes.
130
131See L<perlfunc/tie>, L<perldbmfilter>, L<Fcntl>
132
133=cut
134