diff options
| -rw-r--r-- | ext/SDBM_File/SDBM_File.pm | 75 |
1 files changed, 27 insertions, 48 deletions
diff --git a/ext/SDBM_File/SDBM_File.pm b/ext/SDBM_File/SDBM_File.pm index ca181b79bd..dcb12bcde9 100644 --- a/ext/SDBM_File/SDBM_File.pm +++ b/ext/SDBM_File/SDBM_File.pm @@ -40,69 +40,48 @@ SDBM_File - Tied access to sdbm files =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 +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. If the page file -name is supplied, this becomes the directory file name. +=head2 Tie -=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> +Use C<SDBM_File> with the Perl built-in C<tie> function to establish +the connection between the variable and the file. -Write-only access to the data in the file. + tie %hash, 'SDBM_File', $basename, $modeflags, $perms; -=item C<O_RDWR> + tie %hash, 'SDBM_File', $dirfilename, $modeflags, $perms, $pagfilename; -Both read and write access. +C<$basename> is the base filename for the database. The database is two +files with ".dir" and ".pag" extensions appended to C<$basename>, -=back + $basename.dir (or .sdbm_dir on VMS, per DIRFEXT constant) + $basename.pag -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. +The two filenames can also be given separately in full as C<$dirfilename> +and C<$pagfilename>. This suits for two files without ".dir" and ".pag" +extensions, perhaps for example two files from L<File::Temp>. -=item 5. +C<$modeflags> can be the following constants from the C<Fcntl> module (in +the style of the L<open(2)> system call), -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>.) + O_RDONLY read-only access + O_WRONLY write-only access + O_RDWR read and write access -=item 6. +If you want to create the file if it does not already exist then bitwise-OR +(C<|>) C<O_CREAT> too. If you omit C<O_CREAT> and the database does not +already exist then the C<tie> call will fail. -Optionally, the name of the data page file (normally F<< -I<filename>.pag >>. If this is supplied, then the first filename is -treated as the directory file (normally F<< I<filename>.dir >> based -on the first filename parameter). + O_CREAT create database if doesn't already exist -=back +C<$perms> is the file permissions bits to use if new database files are +created. This parameter is mandatory even when not creating a new database. +The permissions will be reduced by the user's umask so the usual value here +would be 0666, or if some very private data then 0600. (See +L<perlfunc/umask>.) =head1 EXPORTS |