
Table of Contents
=================

1    Introduction
1.1    Installation
1.2    Uninstallation
2    Using ISOFS
2.1    Quick Start
2.2    ISODrive
2.3    MapISO
2.4    isofsdmn
3    ISOFS Notification Semaphore
4    Building ISOFS
5    About ISOFS
5.1    Known problems and limitations
5.2    History
5.3    License


1 Introduction
==============

ISOFS is an installable filesystem for OS/2 for seamless read only
access to the contents of ISO image files, as suitable for burning on
CD, or as extracted from CD.

This file system is based on the sources of AEFS a cryptographic file
system written by Eelco Dolstra.  See Credits below for further
information.


1.1 Installation
----------------

The suggested method is to use WarpIN, which will modify your
CONFIG.SYS file and create a folder on your desktop containing objects
for the documentation and the drive mapping utilities.

IMPORTANT: v1.1.0 installs its files in different directories than
previous versions and is unable to remove the old files.  Please
UNINSTALL any previous version before installing this package.

To install manually, add the following line to your CONFIG.SYS file
and then reboot.

      IFS=<install-path>\stubfsd.ifs ISOFS

This line loads the FSD (file system driver), which is just a stub
that passes requests to the daemon (isofsdmn) which does the real
work.

You can also add the following line to config.sys to have the daemon
load during startup.  In most cases, this isn't necessary since
isodrive always starts it if needed, and mapiso will start it on
demand is you use the -s switch.

      RUN=<install-path>\isofsdmn.exe


1.2 Uninstallation
------------------

The suggested method is to use WarpIN, which will remove the entries
added during installation from your CONFIG.SYS file and will also
remove the ISOFS folder from your desktop.

To uninstall manually, remove the following lines from your CONFIG.SYS
file and then reboot.

      IFS=<install-path>\stubfsd.ifs ISOFS
      RUN=<install-path>\isofsdmn.exe


2 Using ISOFS
=============

This section describes the three programs in the ISOFS package:

- ISODrive - a control panel that lets you mount and unmount ISO files
  and control options.

- MapISO - a command line program for mounting and unmounting ISOs
  well suited for use in scripts.

- isofsdmn - a background program (daemon) that does the actual work
  of reading ISO files.


2.1 Quick Start
---------------

To access an ISO file as a volume, you must mount it as a drive and
assign it a letter.  Once that's done, you can copy, extract or view
files contained in the image as if they were on your hard disk.  When
you have finished using the volume, you can unmount it.

Mounting and unmounting can be done several ways:

WPS     Double-click on the ISO file.  isodrive will pop up a
        confirmation dialog then mount it.  When you're done with the
        volume, again double-click on the file; this time an unmount
        confirmation will appear.

ISODRIVE
        Open the app and press the [+] (plus) button.  Enter the file
        name or use the File Open dialog, select a drive letter, then
        press [Mount].  When done, reopen the app, select the file
        from the main listing, then press the [-] (minus) button.

MAPISO  From a command prompt (or script) enter a line like this:

              mapiso -s X: <drive>:\<path>\<filename>

        This will start isofsdmn if necessary, then mount the file as
        drive X:.  To unmount the volume, use:

              mapiso X: -d


2.2 ISODrive
------------

ISODrive is an easy to use interface for ISOFS.  With it you can mount
and unmount ISO files, and control the popups that appear when you
double-click an ISO file.

The main window contains a list of currently mounted ISO files along
with the drive letters they've been assigned.  Below that are buttons
to mount and unmount drives, and to configure its options.

Mount [ + ]
        Enter the name of an ISO file or press the file dialog button
        ([...]) to search for one.  Select a drive letter, then press
        [Mount].  If successful, the file name and drive will appear
        in the main window's listing.

        There are two additional options available that very few users
        need, so they are hidden.  Press the [<] button to reveal
        them:
        CODEPAGE: this controls the translation of Unicode file names.
        Set it if accented characters in file names are displayed
        incorrectly.
        OFFSET: to access a secondary session on a multi-session CD,
        enter its offset in sectors from the beginning of the disk.

Unmount [ - ]
        First, select the drive you want to unmount from the listing
        in the main window, then press the [-] button.  After
        confirming the information shown in the dialog, press
        [Unmount].  The file name and drive should disappear from the
        main window's listing.

        Note: normally, ISOFS will refuse to unmount a drive if there
        are any open files on it.  If you MUST unmount such a drive,
        check Emergency unmount first (this is the same as the --force
        command line option).

Options

        - AUTOMOUNT: if you supply ISODrive with a file name but no
          drive letter (e.g.  when double-clicking on an ISO file),
          this feature will automatically mount the file using the
          next available drive letter.  When disabled, ISODrive will
          open instead.

        - CONFIRM: before mounting or unmounting a file, ISODrive will
          pop up a dialog to have you confirm the action.

        - ADVISE: should the mount/unmount operation fail, ISODrive
          will pop up a dialog to advise you of the error.

ISODrive also offers a variety of command line switches to tailor its
operation.  It supports all of the flags used by mapiso (see next
section) plus these extras:

-a, --auto
        Enable AutoMount; this overrides your setting in Options.

-n, --noauto
        Disable AutoMount; this overrides your setting in Options.


2.3 MapISO
----------

The mapiso program attaches an ISO file to a drive letter.  The syntax
is:

mapiso <option>* <drive-letter>: <path>

The options are:

-o <nnnn>, --offset <nnnn>
        Specify the offset of the session on the CD.  This means the
        sector where the session starts on the CD.  For the first
        session on a CD the offset is 0, and may be omitted.  This
        option is experimental.

-j <codepage>, --jcharset <codepage>
        Translation codepage for the unicode names of Joliet CDs.  If
        this switch is omitted the default system codepage is used.

-s, --start
        Starts the daemon process isofsdmn if it isn't running
        already.  This switch only works when mounting an ISO - it can
        not be used by itself.

-h, --help
        Print help and exit.

-v, --version
        Print version information and exit.

The mapiso program is also used to detach a drive letter from an ISO
file.  The syntax is:

mapiso <option>* <drive-letter>: -d

mapiso <option>* <drive-letter>: --detach

The options are:

-f, --force
        Detach the file system even if there are open files, active
        searches, or current directories for this drive.  This might
        not be entirely safe.

Examples:

Map a file on drive X: using codepage 850:

              mapiso --jcharset cp850 X: c:\directory\isoimage.raw

Map another file on drive Y: using the default system codepage:

              mapiso y: c:\directory\another_isoimage.raw 

Mount the same file on drive Z: using codepage 850:

              mapiso -j cp850 z: c:\directory\another_isoimage.raw

Mount CD-ROM drive S: on drive Z: using codepage 850:

              mapiso -j cp850 z: \\.\S:

You may access all these mounted drives in parallel.


2.4 isofsdmn
------------

The isofsdmn program is the file system daemon.  The syntax is:

isofsdmn <option>*

It is typically started by ISODrive the first time you mount an ISO
file.  It can also be started from CONFIG.SYS by a RUN statement (NOT
a CALL statement) or from a script using the detach command.

The options are:

-q, --quit
        Kills the running daemon process.  This will also detach any
        mapped drives from their related ISO files.

--logfile <filename>
        Write log messages to the file specified by <filename>.  By
        default, messages are written to standard error (which is the
        nul device if the daemon is started from CONFIG.SYS or using
        detach).

--loglevel <n>
        Set the severity threshold of log messages.  Only messages
        with a severity lower than or equal to the log level are
        actually written to the log file.  The levels are:

        1       Fatal

        2       Evil (i.e.  not fatal but worse than a 'normal' error)

        3       Error

        4       Warning

        7       Information

        9       Debug

-h, --help
        Print help and exit.

-v, --version
        Print version information and exit.


3 ISOFS Notification Semaphore
==============================

Each time isofsdmn.exe successfully mounts or unmounts a drive, it
attempts to open an event semaphore named \SEM32\ISOFS\MOUNT.  If it
exists, the daemon posts the semaphore then closes it.

To access these notifications, a client should create this event sem
if it doesn't exist yet.  Do NOT use any semaphore options except the
DC_SEM_SHARED flag.  If the sem already exists, open it.  Clients
should always reset the event sem when it is posted and should ignore
ERROR_ALREADY_RESET return codes.


4 Building ISOFS
================

The makefiles require GNU make.

To build the FSD (stubfsd.ifs) you need Microsoft C 6.00.
You also need the FSD helper library and header file, which are now
included in this package in directory ifsinf.

To build the daemon and the support programs you need a current
version of gcc, available from various locations.

In general it isn't necessary to rebuild the FSD.  Unless you find a
bug that needs to be fixed, you can use the precompiled FSD in this
package.  Do not use earlier versions as they contain several bugs
that have now been fixed.


5 About ISOFS
=============

This software was written by Paul Ratcliffe.  Send bug reports,
patches, or other comments to <paul@orac12.clara34.co56.uk78> (remove
the numbers).

http://home.clara.net/orac/os2.htm#isofs

This file system is based on AEFS a cryptographic file system written
by Eelco Dolstra <edolstra@students.cs.uu.nl>, and ISOFS 0.2.1 by
Chris Wohlgemuth.
Without that work, this version of ISOFS wouldn't have been possible!

The charset conversion was taken from the cdrecord package by J.
Schilling.

The routines for iso9660 access were originally written by Eric
Youngdale (1993), Copyright 1993 Yggdrasil Computing, Incorporated.


5.1 Known problems and limitations
----------------------------------

- Although ISO files can now exceed 2GB, individual files within are
  still limited to 2GB.  This may change in the future.

- Only single session images are supported.  This may also change in
  the future.

- There is no caching or read ahead implemented, so the file system
  isn't as fast as theoretically possible, but I think it's reasonably
  fast.


5.2 History
-----------

V1.1.0 27 Feb 2017
        Added ISODrive, a GUI control panel for ISOFS.  This replaces
        the 'automap.cmd' found in previous versions.
        Added a new feature that enables clients to receive
        notification of ISOFS mount/unmount events via a named shared
        event sempahore.
        Fixed libc panic caused by attempts to free a memory
        allocation twice.
        Fixed failures when clients tried to read EAs for files that
        have none (i.e.  any file contained in the ISO).
        Fixed crash during boot when no filesystem name is specified
        in config.sys; 'ISOFS' is now the default value.
        Fixed a bug that might cause applications to hang when
        accessing an ISOFS drive if isofsdmn.exe had been started from
        config.sys.
        Refactored and reformatted code in files where bugs were
        found.
        Updated Makefiles and eliminated standalone 'getopt' library
        which is now part of libc.
        Updates provided by Rich Walsh.

V1.0.4 27 Nov 2017
        Interim version not released to the public.

V1.0.3 7 Jan 2007
        Fixed access to raw drives (\\.\X:) in Mapiso.
        Fixed bug which allowed reading beyond end of files.
        Increased daemon file handle count to allow more ISO images to
        be mapped simultaneously.
        Added utility to attach and detach ISOs automatically.

V1.0.2 28 Jan 2006
        Allow ISO images greater than 2GB to be read.

V1.0.1 23 Jul 2005
        Mapiso now accepts relative pathnames rather than only fully
        qualified ones.
        Fixed major memory leak in the daemon.
        Fixed errors in the documentation.

V1.0.0 18 Dec 2004
        Major rewrite to clean up some of the code and add support for
        High Sierra images and ISO-9660 images without Joliet.
        ISOFS is now maintained by Paul Ratcliffe.

V0.2.1 02.10.2001
        Added support for file and directory times which was still
        missing.
        Found the solution for the missing notebook pages.  You have
        to tell OS/2 that there's support for EAs even if that's not
        true.

V0.2.0 25.08.2001
        Fixed mainly a memory leak and the still broken extended
        attribute handling.
        Some more bugs are fixed I forgot ;-).
        Added more descriptive error messages to mntisofs so it's
        easier to find out what's going wrong.
        This seems to be the first really stable release.

V0.1.5 03.10.2000
        Added missing filesystem driver to the archive.

V0.1.3 30.09.2000
        Fixed broken extended attribute handling which caused the WPS
        to crash.
        Added support for volume label.

V0.1.1 20.08.2000
        First release


5.3 License
-----------

ISOFS 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, or (at your option) any later
version.

ISOFS 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 ISOFS; see the file COPYING.  If not, write to the Free
Software Foundation, 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.
