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

package SDBM_File;

use strict;

require Tie::Hash;
use XSLoader ();

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

XSLoader::load 'SDBM_File', $VERSION;

1;

__END__

=head1 NAME

SDBM_File - Tied access to sdbm files

=head1 SYNOPSIS

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

 tie(%h, 'SDBM_File', 'filename', O_RDWR|O_CREAT, 0666)
   or die "Couldn't tie SDBM file 'filename': $!; aborting";

 # Now read and change the hash
 $h{newkey} = newvalue;
 print $h{oldkey}; 
 ...

 untie %h;

=head1 DESCRIPTION

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