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