ext/SDBM_File/SDBM_File.pm

   1 package SDBM_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.03" ;
  11
  12 XSLoader::load 'SDBM_File', $VERSION;
  13
  14 1;
  15
  16 __END__
  17
  18 =head1 NAME
  19
  20 SDBM_File - Tied access to sdbm files
  21
  22 =head1 SYNOPSIS
  23
  24  use Fcntl;   # For O_RDWR, O_CREAT, etc.
  25  use SDBM_File;
  26
  27  tie(%h, 'SDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
  28    or die "Couldn't tie SDBM 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
  39 C<SDBM_File> establishes a connection between a Perl hash variable and
  40 a file in SDBM_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<SDBM_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<"SDBM_File">.  (Ths tells Perl to use the C<SDBM_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<sdbm 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 SDBM 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