Parano...Header(3pm)

💖 Paranoid...Header — like, the manual page for Paranoid::IO::FileMultiplexer::Block::FileHeader (3pm)

okay bestie, so this is a User Contributed Perl Documentation page, and the whole vibe is: this class is the little file-header-block gremlin that lives inside the Paranoid::IO::FileMultiplexer machine. she's not for direct use, she's a supporting icon 🎀

---

✨ NAME ✨

Paranoid::IO::FileMultiplexer::Block::FileHeader — File Header Block. that's it, that's the name, periodt 💅

---

🌸 VERSION 🌸

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

---

🦋 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 🌈

so basically, bestie: this class is not meant to be used directly. it's a supporting cast member for Paranoid::IO::FileMultiplexer functionality — it provides the functionality necessary for manipulation of the file header block. 💅

it also does presume that whatever file it's being used on has already been opened in the appropriate mode, and that the Paranoid::IO flock stack has been enabled. and for the purposes of Paranoid::IO::FileMultiplexer, that whole setup thing? already done in that class. so not your problem, she's handled 🫶

---

👑 SUBROUTINES/METHODS 👑

🎀 new

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

this creates a new instance of a file header block object. she requires the filename in order to retrieve the cached file handle from Paranoid::IO, plus the size of the block. and she always writes to the first block of the file. the literal first block. no negotiation 💀

NOTE: creating an object does not automatically create the file and/or write a signature. you have to do that yourself using the methods below. she doesn't do it for you, she's not your mom 😭

⭐ blocks

$count = $obj->blocks;

returns the value of the blocks field in the file header. that's the total number of blocks allocated in the file to date. but heads up — this is only the cached value stored in the object. other methods down below are the ones that actually write and read the value from the file. iykyk ✨

💜 version

$ver = $obj->version;

returns the file format version as a string. simple, clean, iconic.

🌸 streams

%streams = $obj->streams;

returns a hash of streams allocated in the file, in the format of stream name => block number. cute little map, love that for us 🗺️

🦋 maxStreams

$max = $obj->maxStreams;

returns the maximum number of streams supported by this file header. the ceiling. the limit. the "that's enough bestie" number.

🍓 model

$stats = $obj->model;

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

• 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;

writes the file header signature to disk, and returns 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. ok? ok 💅

💖 readSig

$rv = $obj->readSig;

reads the file header signature from disk and performs basic validation that the information in it is acceptable. she validates that:

• the file size matches the block size * block count,
• 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. don't get it twisted 🙈

🧚 writeBlocks

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

writes the passed block count value to disk, and returns a boolean value denoting success. she did the thing, and she'll tell you if it worked ✨

💀 readBlocks

$count = $obj->readBlocks;

reads the block count field from disk and returns it. but if there are any errors reading or extracting the value, she returns undef. no value, no vibe, just undef 😭

🌟 incrBlocks

$rv = $obj->incrBlocks;

calls writeBlocks with a value of one greater than what's currently cached. one more. one more block. slay.

🌈 validateBlocks

$rv = $obj->validateBlocks;

compares the cached block count value to what's actually written in the file. super useful for determining whether an external process has potentially modified the file. a lil vibe check for your disk 🫶

🎀 writeStreams

$rv = $obj->writeStreams;

writes the stream index records to the header block, and returns a boolean denoting success. go off, index records 💅

👑 readStreams

$rv = $obj->readStreams;

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. she remembers now, bestie 💖

🎀 addStream

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

does some basic validation of the requested stream, and if it passes, updates the stream indices on the disk. gatekeeping the invalid streams, as she should ✨

---

🌸 DEPENDENCIES 🌸

• Fcntl
• Paranoid
• Paranoid::Debug
• Paranoid::Data
• Paranoid::IO
• Paranoid::IO::FileMultiplexer::Block
• Paranoid::IO::FileMultiplexer::Block::BATHeader
• Paranoid::IO::FileMultiplexer::Block::StreamHeader

---

💀 BUGS AND LIMITATIONS 💀

...and that's the whole section. it's giving silence. it's giving nothing. no known bugs or limitations were listed in this page, and honestly? she's thriving 🙈✨

---

💜 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:

1. 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
2. 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)

---

and that's a wrap, bestie 🫶 this was perl v5.38.2, dated 2024-03-07 — genuinely iconic, no notes, mwah 💅💖✨