ext/NDBM_File/NDBM_File.pm

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