Provided by: libparanoid-perl_2.10-1_all bug

NAME

       Paranoid::IO::FileMultiplexer::Block::FileHeader - File Header Block

VERSION

       $Id: lib/Paranoid/IO/FileMultiplexer/Block/FileHeader.pm, 2.10 2022/03/08 00:01:04 acorliss Exp $

SYNOPSIS

           $obj = Paranoid::IO::FileMultiplexer::Block::FileHeader->new(
                   $filename, $bsize);

           $count   = $obj->blocks;
           $version = $obj->version;
           %streams = $obj->streams;
           $max     = $obj->maxStreams;
           %model   = $obj->model;

           $rv = $obj->writeSig;
           $rv = $obj->readSig;
           $rv = $obj->writeBlocks;
           $count = $obj->readBlocks;
           $rv = $obj->incrBlocks;
           $rv = $obj->validateBlocks;

           $rv = $obj->writeStreams;
           $rv = $obj->readStreams;
           $rv = $obj->addStream($sname, $bn);

DESCRIPTION

       This class is not meant to be used directly, but as part of the Paranoid::IO::FileMultiplexer
       functionality.  This provides functionality necessary for manipulation of the file header block.

       This module does presume that whatever file it is being used on has already been opened in the
       appropriate mode, and that the Paranoid::IO flock stack has been enabled.  For the purposes of
       Paranoid::IO::FileMultiplexer, this is done in that class.

SUBROUTINES/METHODS

   new
           $obj =
               Paranoid::IO::FileMultiplexer::Block::FileHeader->new($file, $blockSize);

       This creates a new instance of a file header block object.  It requires the filename in order to retrieve
       the cached file handle from Paranoid::IO, and the size of the block.  This always writes to the first
       block of the file.

       NOTE: creating an object does not automatically create the file and/or write a signature.  That must be
       done using the methods below.

   blocks
           $count = $obj->blocks;

       This method returns the value of the blocks field in the file header.  This is the total number of blocks
       allocated in the file to date.  Note that this is only the cached value stored in the object.  Other
       methods are provided for writing and reading the value from the file.

   version
           $ver = $obj->version;

       This method returns the file format version as a string.

   streams
           %streams = $obj->streams;

       This method returns a hash of streams allocated in the file, in the format of stream name => block
       number.

   maxStreams
           $max = $obj->maxStreams;

       This method returns the maximum number of streams supported by this file header.

   model
           $stats = $obj->model;

       This method returns a hash with some basic statistical information on the file, in both raw and human-
       friendly values.  The information provided is as follows:

           Key             Description
           ---------------------------------------------------------------
           intSize         Size of Perl's native integers in bits
           curFileSize     Current file size in bytes
           curFSHuman      Current file size expressed w/unit suffixes
           curStreams      Current number of streams allocated
           maxFileSize     Maximum file size supported with Perl
           maxFSHuman      Maximum file size expressed w/unit suffixes
           maxStreams      Maximum number of streams that can be allocated
           maxStreamSize   Maximum stream size
           maxSSHuman      Maximum stream size expressed w/unit suffixes

   writeSig
           $rv = $obj->writeSig;

       This method writes the file header signature to disk, returning a boolean value denoting its success.
       Note that the signature contains the file format, version, block size, and number of allocated blocks,
       but not the list of allocated streams.

   readSig
           $rv = $obj->readSig;

       This method reads the file header signature from disk and performs basic validation that the information
       in it is acceptable.  It validates that the file size matches the block size * block count, that the
       block size is an acceptable value, and the file format and version are supported.

       If the method call was successful it will update the cached values in the object.  Note that this is only
       the signature values, not the stream index records.

   writeBlocks
           $rv = $obj->writeBlocks($count);

       This method writes the passed block count value to disk, and returns a boolean value denoting success.

   readBlocks
           $count = $obj->readBlocks;

       This method reads the block count field from disk and returns it.  If there are any errors reading or
       extracting the value, it will return undef.

   incrBlocks
           $rv = $obj->incrBlocks;

       This method calls writeBlocks with a value of one greater that what's currently cached.

   validateBlocks
           $rv = $obj->validateBlocks;

       This method compares the cached block count value to what's actually written in the file.  This is useful
       for determining whether an external process has potentially modified the file.

   writeStreams
           $rv = $obj->writeStreams;

       This method writes the stream index records to the header block, and returns a boolean denoting success.

   readStreams
           $rv = $obj->readStreams;

       This method reads the stream index records from the file, and returns a boolean value denoting success.
       If the read is successful, this will update the cached streams information in the object.

   addStream
           $rv = $obj->addStream($sname, $bn);

       This method does some basic validation of the requested stream, and if it passes, updates the stream
       indices on the disk.

DEPENDENCIES

       o   Fcntl

       o   Paranoid

       o   Paranoid::Debug

       o   Paranoid::Data

       o   Paranoid::IO

       o   Paranoid::IO::FileMultiplexer::Block

       o   Paranoid::IO::FileMultiplexer::Block::BATHeader

       o   Paranoid::IO::FileMultiplexer::Block::StreamHeader

BUGS AND LIMITATIONS

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is free software.  Similar to Perl, you can redistribute it and/or modify it under the
       terms of either:

         a)     the GNU General Public License
                <https://www.gnu.org/licenses/gpl-1.0.html> as published by the
                Free Software Foundation <http://www.fsf.org/>; either version 1
                <https://www.gnu.org/licenses/gpl-1.0.html>, or any later version
                <https://www.gnu.org/licenses/license-list.html#GNUGPL>, or
         b)     the Artistic License 2.0
                <https://opensource.org/licenses/Artistic-2.0>,

       subject to the following additional term:  No trademark rights to "Paranoid" have been or are conveyed
       under any of the above licenses.  However, "Paranoid" may be used fairly to describe this unmodified
       software, in good faith, but not as a trademark.

       (c) 2005 - 2021, Arthur Corliss (corliss@digitalmages.com) (tm) 2008 - 2021, Paranoid Inc.
       (www.paranoid.com)

perl v5.34.0                                       2022-03-Paranoid::IO::FileMultiplexer::Block::FileHeader(3pm)