ext/ODBM_File/ODBM_File.pm

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