home *** CD-ROM | disk | FTP | other *** search
/ PC World 2003 March / PCWorld_2003-03_cd.bin / Software / Topware / activeperl / ActivePerl / Perl / lib / SDBM_File.pm < prev    next >
Encoding:
Perl POD Document  |  2001-03-21  |  2.6 KB  |  117 lines
  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
  117.