Mac::Finder::DSStore::UseryContributed)Mac::Finder::DSStore::BuddyAllocator(3)

NAME

       Mac::Finder::DSStore::BuddyAllocator - Allocate space within a file

DESCRIPTION

       "Mac::Finder::DSStore::BuddyAllocator" implements a buddy-allocation
       scheme within a file. It's used by "Mac::Finder::DSStore" to read
       certain files created by the Macintosh Finder.

       The allocation methods do not perform any actual file I/O.  The
       contents of allocated blocks are read and written by the caller using
       methods on "BuddyAllocator::Block".  If the "allocate" and "free"
       methods are used, or if the "toc" hash is modified, "writeMetaData"
       must be called for the changes to be reflected in the file.

METHODS

       $allocator = Mac::Finder::DSStore::BuddyAllocator->open($fh)

       "open($fh)" constructs a new buddy allocator and initializes its state
       from the information in the file.  The file handle is retained by the
       allocator for future operations.

       $allocator = Mac::Finder::DSStore::BuddyAllocator->new($fh)

       Similar to "open", but does not read anything from the file. This can
       be used to create a new file from scratch.

       $allocator->close( )

       Closes the underlying file handle.

       $allocator->listBlocks($verbose)

       List all the blocks in order and see if there are any gaps or overlaps.
       If $verbose is true, then the blocks are listed to the current output
       filehandle. Returns true if the allocated and free blocks have no gaps
       or overlaps.

       $allocator->writeMetaData( )

       Writes the allocator's metadata (header block and root block) back to
       the file.


       Retrieves the file offset and size in bytes of a given block.  The
       offset doesn't include the 4-byte fudge.  In scalar context, just
       returns the offset.

       $blocknumber = $allocator->allocate($size, [$blocknumber])

       Allocates or re-allocates a block to be at least $size bytes long.  If
       $blocknumber is given, the specified block will be grown or shrunk if
       needed, otherwise a new block number will be chosen and given to the
       allocated block.

       Unlike the libc "realloc" function, this may move a block even if the
       block is not grown.

       $allocator->free($blocknumer)

       Releases the block number and the block associated with it back to the
       block pool.

ATTRIBUTES

       $allocator->{toc}

       "toc" holds a hashref whose keys are short strings and whose values are
       integers. This table of contents is read and written as part of the
       allocator's metadata but is not otherwise used by the allocator; users
       of the allocator use it to find their data within the file.

       $allocator->{fh}

       The file handle passed in to "open" or "new". If you find yourself
       needing to use this, you should probably try to extend the class so
       that you don't.

BuddyAllocator::Block

       "BuddyAllocator::Block" instances are returned by the "blockByNumber"
       and "getBlock" methods. They hold a pointer into the file and provide a
       handful of useful methods.

       (There are also two other classes, "WriteBlock" and "StringBlock",
       which might be returned instead. Think of this as an interface rather
       than as a concrete class.)

       $block->read(length, [format])

       Reads "length" bytes from the block (advancing the read pointer
       correspondingly). If "format" is specified, the bytes read are unpacked
       using the format; otherwise a byte string is returned.

       $block->length( )

       Returns the length (or size) of this block.
       $block->close([ zerofill ])

       This is generally a no-op, but if called on a writable block with
       "zerofill = true", then zeroes will be written from the current
       location to the end of the allocated block.

       $block->copyback( )

       Returns the block's contents as a string. For write blocks, this reads
       from the file. This is just here for debugging purposes and might
       change.

AUTHOR

       Written by Wim Lewis as part of the Mac::Finder::DSStore package.

       This file is copyright 2008 by Wim Lewis.  All rights reserved.  This
       program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.10.0 2010-Mac::Finder::DSStore::BuddyAllocator(3)