/ 
AppleII-LibA2-0.201
River stage zero No dependents
/ AppleII::Disk

NAME

AppleII::Disk - Block-level access to Apple II disk image files

VERSION

This document describes version 0.201 of AppleII::Disk, released September 12, 2015 as part of AppleII-LibA2 version 0.201.

SYNOPSIS

use AppleII::Disk;
my $disk = AppleII::Disk->new('image.dsk');
my $data = $disk->read_block(1);  # Read block 1
$disk->write_block(1, $data);     # And write it back :-)

DESCRIPTION

AppleII::Disk provides block-level access to the Apple II disk image files used by most Apple II emulators. (For information about Apple II emulators, try the Apple II Emulator Page at http://www.ecnet.net/users/mumbv/pages/apple2.shtml.) For a higher-level interface, use the AppleII::ProDOS module.

AppleII::Disk provides the following methods:

$disk = AppleII::Disk->new($filename, [$mode])

Constructs a new AppleII::Disk object. $filename is the name of the image file. The optional $mode is a string specifying how to open the image. It can consist of the following characters (case sensitive):

r  Allow reads (this is actually ignored; you can always read)
w  Allow writes
d  Disk image is in DOS 3.3 order
p  Disk image is in ProDOS order

If you don't specify 'd' or 'p', then the format is guessed from the filename. '.PO' and '.HDV' files are ProDOS order, and anything else is assumed to be DOS 3.3 order.

If you specify 'w' to allow writes, then the image file is created if it doesn't already exist.

$size = $disk->blocks([$newsize])

Gets or sets the size of the disk in blocks. $newsize is the new size of the disk in blocks. If $newsize is omitted, then the size is not changed. Returns the size of the disk image in blocks.

This refers to the logical size of the disk image. Blocks outside the physical size of the disk image read as all zeros. Writing to such a block will expand the image file.

When you create a new image file, you must use blocks to set its size before writing to it.

$contents = $disk->read_block($block)

Reads one block from the disk image. $block is the block number to read.

$contents = $disk->read_blocks(\@blocks)

Reads a sequence of blocks from the disk image. \@blocks is a reference to an array of block numbers. As a special case, block 0 cannot be read by this method. Instead, it returns a block full of 0 bytes. This is how sparse files are implemented. If you want to read the actual contents of block 0, you must call $disk->read_block(0) directly.

$contents = $disk->read_sector($track, $sector)

Reads one sector from the disk image. $track is the track number, and $sector is the DOS 3.3 logical sector number. This is currently implemented only for DOS 3.3 order images.

$disk->fully_allocate()

Expands the the physical size of the disk image file to match the logical size of the disk image. It will be expanded as a sparse file if the filesystem containing the image file supports sparse files.

$disk->write_block($block, $contents, [$pad])

Writes one block to the disk image. $block is the block number to write. $contents is the data to write. The optional $pad is a character to pad the block with (out to 512 bytes). If $pad is omitted or null, then $contents must be exactly 512 bytes.

$disk->write_blocks(\@blocks, $contents, [$pad])

Writes a sequence of blocks to the disk image. \@blocks is a reference to an array of block numbers to write. $contents is the data to write. It is broken up into 512 byte chunks and written to the blocks. The optional $pad is a character to pad the data with (out to a multiple of 512 bytes). If $pad is omitted or null, then $contents must be exactly 512 bytes times the number of blocks.

As a special case, block 0 cannot be written by this method. Instead, that block of $contents is just skipped. This is how sparse files are implemented. If you want to write the contents of block 0, you must call $disk->write_block directly.

$disk->write_sector($track, $sector, $contents, [$pad])

Writes one sector to the disk image. $track is the track number, and $sector is the DOS 3.3 logical sector number. $contents is the data to write. The optional $pad is a character to pad the sector with (out to 256 bytes). If $pad is omitted or null, then $contents must be exactly 256 bytes. This is currently implemented only for DOS 3.3 order images.

$padded = AppleII::Disk::pad_block($data, [$pad, [$length]])

Pads $data out to $length bytes with $pad. Returns the padded string; the original is not altered. Dies if $data is longer than $length. The default $pad is "\0", and the default $length is 512 bytes.

If $pad is the null string (not undef), just checks to make sure that $data is exactly $length bytes and returns the original string. Dies if $data is not exactly $length bytes.

pad_block is a subroutine, not a method, and is not exported. You probably don't need to call it directly anyway, because the write_XXX methods will call it for you.

CONFIGURATION AND ENVIRONMENT

AppleII::Disk requires no configuration files or environment variables.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

AUTHOR

Christopher J. Madsen <perl AT cjmweb.net>

Please report any bugs or feature requests to <bug-AppleII-LibA2 AT rt.cpan.org> or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=AppleII-LibA2.

You can follow or contribute to AppleII-LibA2's development at https://github.com/madsen/perl-libA2.

COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Christopher J. Madsen.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.