[p5sagit/p5-mst-13.2.git] / ext / ODBM_File / ODBM_File.pm

package ODBM_File;

use strict;

require Tie::Hash;
use XSLoader ();

our @ISA = qw(Tie::Hash);
our $VERSION = "1.02";

XSLoader::load 'ODBM_File', $VERSION;

1;

__END__

=head1 NAME

ODBM_File - Tied access to odbm files

=head1 SYNOPSIS

 use Fcntl;   # For O_RDWR, O_CREAT, etc.
 use ODBM_File;

  # Now read and change the hash
  $h{newkey} = newvalue;
  print $h{oldkey}; 
  ...
 
  untie %h;
 
=head1 DESCRIPTION
 
C<ODBM_File> establishes a connection between a Perl hash variable and
a file in ODBM_File format;.  You can manipulate the data in the file
just as if it were in a Perl hash, but when your program exits, the
data will remain in the file, to be used the next time your program
runs.

Use C<ODBM_File> with the Perl built-in C<tie> function to establish
the connection between the variable and the file.  The arguments to
C<tie> should be:

=over 4

=item 1.

The hash variable you want to tie.

=item 2. 

The string C<"ODBM_File">.  (Ths tells Perl to use the C<ODBM_File>
package to perform the functions of the hash.)

=item 3. 

The name of the file you want to tie to the hash.  

=item 4.

Flags.  Use one of:

=over 2

=item C<O_RDONLY>

Read-only access to the data in the file.

=item C<O_WRONLY>

Write-only access to the data in the file.

=item C<O_RDWR>

Both read and write access.

=back

If you want to create the file if it does not exist, add C<O_CREAT> to
any of these, as in the example.  If you omit C<O_CREAT> and the file
does not already exist, the C<tie> call will fail.

=item 5.

The default permissions to use if a new file is created.  The actual
permissions will be modified by the user's umask, so you should
probably use 0666 here. (See L<perlfunc/umask>.)

=back

=head1 DIAGNOSTICS

On failure, the C<tie> call returns an undefined value and probably
sets C<$!> to contain the reason the file could not be tied.

=head2 C<odbm store returned -1, errno 22, key "..." at ...>

This warning is emmitted when you try to store a key or a value that
is too long.  It means that the change was not recorded in the
database.  See BUGS AND WARNINGS below.

=head1 BUGS AND WARNINGS

There are a number of limits on the size of the data that you can
store in the ODBM file.  The most important is that the length of a
key, plus the length of its associated value, may not exceed 1008
bytes.

See L<perlfunc/tie>, L<perldbmfilter>, L<Fcntl>

=cut
Commit	Line	Data
a0d0e21e	1	package ODBM_File;
a0d0e21e	2
96318ac8	3	use strict;
96318ac8	4
96318ac8	5	require Tie::Hash;
cb50131a	6	use XSLoader ();
a0d0e21e	7
cb50131a	8	our @ISA = qw(Tie::Hash);
cb50131a	9	our $VERSION = "1.02";
c07a80fd	10
146174a9	11	XSLoader::load 'ODBM_File', $VERSION;
a0d0e21e	12
	13	1;
	14
	15	__END__
a5f75d66	16
	17	=head1 NAME
	18
	19	ODBM_File - Tied access to odbm files
	20
	21	=head1 SYNOPSIS
	22
22d4bb9c	23	use Fcntl; # For O_RDWR, O_CREAT, etc.
a5f75d66	24	use ODBM_File;
a5f75d66	25
22d4bb9c	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.
a5f75d66	40
22d4bb9c	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:
a5f75d66	44
22d4bb9c	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.
a5f75d66	109
22d4bb9c	110	See L<perlfunc/tie>, L<perldbmfilter>, L<Fcntl>
a5f75d66	111
a5f75d66	112	=cut