=pod

=head1 NAME

B<dos33> - tool for accessing files inside an Apple DOS 3.3 disk image

=head1 SYNOPSIS

B<dos33> [-h] [-y] <disk_image> <command> [arguments]

=head1 DESCRIPTION

B<dos33> operates on Apple DOS 3.3 .dsk images, and allows copying files
to/from the image as well as common DOS operations.

=head1 OPTIONS

=over

=item -h

Show built-in help message

=item -y

Answer "yes" to all confirmation prompts

=back

=head1 COMMANDS

All commands are case-insensitive. Filenames within the image are
case-sensitive. No globbing/wildcarding is done on files in the image.

=over

=item CATALOG

Same as the DOS 3.3 CATALOG command. Lists the directory of the disk, with
file name, type, lock status, and size in sectors.

In case of duplicate filenames in the image, the first file listed in
B<CATALOG> output will be the one operated on by the B<LOAD>, B<DELETE>,
B<LOCK>, and B<UNLOCK> commands.

=item LOAD B<apple_file> B<[local_file]>

Copies a file out of the image, to the local filesystem. If B<local_file>
is given, it will be used as the name of the output file, otherwise the
file will be named the same as B<apple_file>.

File contents are always copied verbatim. Text files will be in Apple
II encoding, and can be converted to UNIX style text files with the
B<dos33_text2ascii(1)> utility. BLOADable files (object code or binary
data) will begin with a 4-byte header, giving the load address and length
(minus the header) of the file in standard 6502 LSB/MSB format.

=item SAVE B<type> B<local_file> B<[apple_file]>

Copies a file into the image. If B<apple_file> is given, it will
be used as the name, otherwise the file will be named the same as
B<local_file>. No checking is done on the filename, so it's possible to
create files with illegal names, as far as DOS 3.3 is concerned.

If the file already exists in the image, you will be prompted whether
to overwrite it. Use the B<-y> option to suppress the prompt and always
overwrite.

B<type> is one of the standard DOS 3.3 filetype characters:

=over

=item I

Integer BASIC program

=item A

Applesoft BASIC program

=item B

Binary file (possibly BLOADable)

=item T

Text file (including EXEC batch files)

=item S

Source? Sequential? Rarely used.

=item R

Relocatable object module. Rarely used.

=item N

B<dos33> uses this character as a replacement for the "new A", aka
0x20. In DOS 3.3's CATALOG command, these files show up as A. Rarely
used.

=item L

B<dos33> uses this character as a replacement for the "new B", aka
0x40. In DOS 3.3's CATALOG command, these files show up as B. Rarely
used.

=back

Filetype characters are case-insensitive in B<dos33>.

File contents are always copied verbatim, so e.g. text files need to
already be in Apple II encoding (bit 7 set on each character, and 0x8d
used for end-of-line). A UNIX style text file can be converted with
B<tr(1)>, with a command like:

tr '\n\040-\177' '\215\240-\377' < unix.txt > apple.txt

To make an Apple BLOAD/BRUN object file from a raw binary, use the
B<make_b(1)> utility.

No checking is done on the file contents to see whether they make sense
for the filetype given, so it's possible to e.g. store a text file with
type A, or an Applesoft file with type B (binary). This isn't really a
very useful thing to do, so try to avoid it.

=item DELETE B<apple_file>

Deletes a file inside the image. The file must exist and not be locked.
=item LOCK B<apple_file>

Locks (write-protects) a file inside the image. Locked files have a B<*>
in the first column of B<CATALOG> output. Locked files may not be written
to, deleted, or renamed.

=item UNLOCK B<apple_file>

Unlocks a file inside the image.

=item RENAME B<apple_file_old> B<apple_file_new>

Renames a file inside the image. No checking is done whether the new
name already exists, so it's possible to create multiple files with the
same name.

=item UNDELETE B<apple_file>

Undoes a B<DELETE>. This is only possible if the file's data sectors haven't
already been overwritten with data from newer files. You will need to know
the filename of the deleted file, which can be found in B<DUMP>'s output.

=item DUMP

Shows detailed information on the filesystem and files on the
disk. Displays the VTOC, free sector bitmap, directory entries (including
the ones for deleted files), and a hex dump of each sector marked "used"
in the bitmap.

=back

=head1 SEE ALSO

=over

=item dos33fsprogs(1)

=item a2tools(1)

=back

=head1 WEBSITE

http://www.deater.net/weave/vmwprod/apple/

=head1 AUTHORS

B<dos33fstools> written by Vince Weaver <vince _at_ deater.net>.

This manual page written by B. Watson for the SlackBuilds.org project,
but it may be used by anyone.
