------------------------------------------------------------------------------

                   Lisa File System Shell Tool
                     Version 0.9.5  2007.01.30

                A Part of the Lisa Emulator Project

                Copyright (C) 2007 Ray A. Arachelian
                         All Rights Reserved

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License
    as published by the Free Software Foundation; either version 2
    of the License, or (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program;  if not, write to:

                 The Free Software Foundation, Inc.,
        59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

            or visit: http://www.gnu.org/licenses/gpl.html

    Contact me if you need other licensing options, etc.

    LICENSING NOTE: Portions of this code rely on the LZHUFF.C code
                    released to usenet under the following conditions:


LZHUF.C (c)1989 by Haruyasu Yoshizaki, Haruhiko Okumura, and Kenji Rikitake.
     All rights reserved. Permission granted for non-commercial use.

If your application does not meet the non-commercial use clause, you must
remove the #define USE_LZHUFF line from libdc42.c, and you may not use
the LZHUFF routines, or you'll have to build your own equivalents.  Sorry.
------------------------------------------------------------------------------

This code is unaffiliated with Apple, and Apple retains all trade marks for
itself, and all versions of the Disk Copy and DART programs.  Whenever you see
the text Disk Copy or DART, you are encouraged to visualize a trademark symbol
following it, and chant We all we all worship Steve Jobs" (just kidding!)

------------------------------------------------------------------------------

 Compile the code like this:

   gcc --static -I. libdc42.c lisafsh-tool.c -o lisafsh-tool
   strip lisafsh-tool
   upx --best lisafsh-tool    #if your system has upx

-----------------------------------------------------------------------------
Using lisafsh-tool:


lisafsh-tool file.dc42 to open an existing DiskCopy 4.2 image


lisafsh-tool file.DART to convert an existing DART image to file.DART.dc42
             and then open it


lisafsh-tool --new file.dc42 {size} to create a new DC42 image and open it.


Valid sizes are: 400k 800k 860k 720k 1440k 2880k 5m 10m 20m

  a default of 12 byte tags will be added to 400k/800k/860K images.

  if the image size is 720k/1440k/2880k - no tags will be added.

  if the image size is over 5mb, it will be created with 24 byte tags.


lisafsh-tool --new file.dc42 400k - create a single sided new virtual floppy

lisafsh-tool --new profile5.dc42 10m - creates a 10mb image suitable for use
               with LisaEm.


lisafsh-tool is similar to a shell program, however its goal is the
manipulation of Disk Copy 4.2 images.  The following are the commands you can
use to interact with it.


Note that lisafsh-tool relies on tag data to perform commands that marked by a
+ sign (the last few commands such as dir) as these involve Lisa file system
operations.

lisafsh-tool does not (yet) fully understand the Lisa's file systems, however,
there is enough information inside the tag data to help it along and almost
get there.

If you know the details that the Lisa file system uses for it's b-tree, (i.e.
the format of the b-tree blocks, how many bytes wide are each field, what the
fields are, how they are stored, how the FS knows the allocation of a specific
file without using tags, etc.) please let me know so that I may update this
tool.


!command        - shell out and run command

help            - displays a summary of commands

version         - displays version and copyright.

{sector#}       - jump and display a sector #. (press ENTER for next one.)
             i.e.  5  jumps to sector 5.

+|-{#}          - skip forward/backward by # of sectors.
             i.e. if the current sector is 5 and you type + and hit enter,
                 it will skip to sector 6.

editsector {offset} {hexdata...}
                - edit the current sector by writing the hex data at offset
                  the change is immediately written to the file.
             i.e. 'editsector 0x0F CA FE 01' writes bytes CA FE 01 offset 15

edittag    {offset} {hexdata...}
                - edit the current sector's tags by writing the hex data at the
                  the offset.  the change is immediately written to the file.
             i.e. 'editsector 4 00 00' writes bytes 0000 at offset 4
                  (the example marks the FILEID tag as an unallocated block)

difftoimg {filename.dc42}
                - compare the currently opened disk image to another.

loadsec {offset} {filename}
                - load 512 bytes from the file {filename} at {offset} into
                  the current sector number, and write that sector to the
                  currently opened disk image. {offset} may be hex/dec/octal
                  i.e. 'loadsec 0x1000 myfile.bin' opens the myfile.bin,
                  reads the 512 bytes at offset 4096-4607 into the current
                  sector, and writes the data to the currently opened image.

loadbin {offset} {filename}
                - load an entire file {filename} starting at {offset} into
                  the current sector number and subsequent sectors of the
                  currently opened disk image. {offset} may be hex/dec/octal
                  i.e. 'loadbin 0x1000 myfile.bin' opens the myfile.bin,
                  reads the first 512 bytes from offset 4096-4607 into the
                  current sector, the next into the next sectorm until the
                  end of file or last sector in the image is reached.


display         - display a sector

dump            - dump all sectors and tags in hex display (your terminal
                  will likely overflow.  Launch lisafsh-tool via a shell
                  script instead and redirect the ouput to a file.)

volname {newvolname}
                - if a new volume name is provided, it's written to the image
                  otherwise, the current volume name is displayed.  The default
                  volname is "-not a Macintosh disk-" for non MFS/HFS img's

quit            - exit lisafsh-tool, saving changes


The following commands will only work on (some) disk images in the Lisa file
system format.  The earlier versions did not use the same volume structure, so
they will not show file names.

n/p             + next/previous display in sorted chain (go to the next
                  sector inside of a file chain.)

tagdump         + dump tags

sorttagdump     + sort tags by file ID and sector #, then dump them

sortdump        + same as above, but also output actual sectors

bitmap          + show block allocation bitmap

extract         + extracts all files on disk based on tag data.
                  files are written to the current directory and named based
                  on the file id and Disk Copy image name.

dir             + list tag file ID's and extracted file names from catalog.



To use lisafsh-tool from a shell script (this is useful with one of the dump
commands for example), you can pass a single command via the command line, and
redirect lisafsh-tool's output like so:

 echo "sortdump" | lisafsh-tool myfloppy.dc42 >myfloppy.sorted-dump.txt

You can pass it a whole bunch of commands like so:

 cat commands.txt | lisafsh-tool myfloppy.dc42 >output.txt

Where commands is a text file containing a list of commands to be executed by
lisafsh-tool



In the interest of safety, you should consider that any changes you make to
the disk images are made immediately, and thus make backups of the disk images
you plan to operate on before launching lisafsh-tool.

(In real life, they might not always be saved if the program is killed.  This
is because on most systems, lisafsh-tool uses mmap'ped I/O.  On some systems
such as win32 it will make all changes to the disk image in memory, and save
it only on the quit command.)

