Please start by reading the file README.mkhybrid

[The original README file for mkisofs is README.mkisofs]

#	$Id: README.eltorito,v 1.1 2000/10/10 20:40:10 beck Exp $
What is El Torito?
------------------
Simply put, El Torito is a specification that says how a cdrom should
be formatted such that you can directly boot from it.

The "El Torito" spec says that ANY cdrom drive should work (scsi/eide)
as long as the BIOS supports El Torito. So far this has only been
tested with EIDE drives because none of the scsi controllers that has
been tested so far appears to support El Torito. The motherboard
definately has to support El Torito. The ones that do let you choose
booting from HD, Floppy, Network or CDROM.

How To Make Bootable CDs
------------------------

For the x86 platform, many BIOS's have begun to support bootable CDs.
The standard my patches for mkisofs is based on is called "El Torito".

The "El Torito" standard works by making the CD drive appear, through BIOS
calls, to be a normal floppy drive. This way you simply put an floppy
size image (exactly 1440k for a 1.44 meg floppy) somewhere in the
iso fs. In the headers of the iso fs you place a pointer to this image.
The BIOS will then grab this image from the CD and for all purposes it
acts as if it were booting from the floppy drive. This allows a working
LILO boot disk, for example, to simply be used as is.

It is simple then to make a bootable CD. First create a file, say "boot.img"
which is an exact image of the boot floppu currently in use. There is
at least one HOWTO on making bootable floppies. If you have a bootable
floppy handy, you can make a boot image with the command

dd if=/dev/fd0 of=boot.img bs=10k count=144

assuming the floppy is in the A: drive.

Place this image somewhere in the hierarchy which will be the source
for the iso9660 filesystem. It is a good idea to put all boot related
files in their own directory ("boot/" under the root of the iso9660 fs,
for example), but this is not necessary.

One caveat - Your boot floppy MUST load any initial ramdisk via LILO,
not the kernel ramdisk driver! This is because once the linux kernel
starts up, the BIOS emulation of the CD as a floppy disk is circumvented
and will fail miserably. LILO will load the initial ramdisk using BIOS
disk calls, so the emulation works as designed.

The "El Torito" specification requires a "boot catalog" to be created as
ll.
This is a 2048 byte file which is of no interest except it is required.
My patches to mkisofs will cause it to automatically create the
boot catalog. You must specify where the boot catalog will go in the
iso9660 filesystem. Usually it is a good idea to put it the same place
as the boot image, and a name like "boot.catalog" seems appropriate.


So we have our boot image in the file "boot.image", and we are going to
put it in the directory "boot/" under the root of the iso9660 filesystem.
We will have the boot catalog go in the same directory with the name
"boot.catalog". The command to create the iso9660 fs in the file
bootcd.iso is then

mkisofs -b boot/boot.imh -c boot/boot.catalog -o bootcd.iso .

The -b option specifies the boot image to be used (note the path is
relative to the root of the iso9660 disc), and the -c option is
for the boot catalog file.

Now burn the CD and its ready to boot!

CAVEATS
-------

I don't think this will work with multisession CDs.

If your bootable floppy image needs to access the boot floppy, it has
to do so through BIOS calls. This is because if your O/S tries to talk to
the floppy directly it will bypass the "floppy emulation" the El Torito spec
creates through BIOS. For example, under Linux it is possible to
have an initial RAM disk loaded when the kernel starts up. If you let the
kernel try to read in the initial RAM disk from floppy, it will fail
miserably because Linux is not using BIOS calls to access the floppy drive.
Instead of seeing the floppy image on the CD, Linux will be looking at
the actually floppy drive.

The solution is to have the initial boot loader, called LILO, load your
initial RAM disk for you.  LILO uses BIOS calls entirely for these
operations, so it can grab it from the emulated floppy image.

I don't think making a CD bootable renders it unreadable by non-El Torito
machines. The El Torito spec uses parts of the iso9660 filesystem which
were reserved for future use, so no existing code should care what it does.

Mkisofs currently stores identification records in the iso9660 filesystem
saying that the system is a x86 system. The El Torito spec also allows
one to write PowerPC or Mac id's instead. If you look at the code in write.c
you could figure out how to change what is written.

Making HFS bootable CDs

It *may* be possible to make the hybrid CD bootable on a Mac. As I do not
have easy access to a CD-R (nor a Mac) at the moment, I have not actually
created and written a bootable hybrid to CD - however, I *think* it will work!

A bootable HFS CD requires an Apple CD-ROM (or compatible) driver, a bootable
HFS partition and the necessary System, Finder, etc. files.

A driver can be obtained from any other Mac bootable CD-ROM using the
"apple_driver" utility (to make, type "make apple_driver"). This file can
then be used with the -boot-hfs-file option. See below for usage.

The HFS partition (i.e. the hybrid disk in our case) must contain a
suitable System Folder, again from another CD-ROM or disk.

For a partition to be bootable, it must have it's "boot block" set. The boot
block is in the first two blocks of a partition. For a non-bootable partition
the boot block is full of zeros. Normally, when a System file is copied to
partition on a Mac disk, the boot block is filled with a number of required
settings - unfortunately I don't know the full spec for the boot block ...

I'm guessing that this will work OK ...

Therefore, the utility "apple_driver" also extracts the boot block from the
first HFS partition it finds on the given CD-ROM and this is used for the
HFS partition created by mkhybrid.

To extract the driver and boot block:

apple_driver CDROM_device > HFS_driver_file

where CDROM_device is the device name used by the CD-ROM (e.g. /dev/cdrom)

The format of the HFS driver file is:

	HFS CD Label Block                              512 bytes
	Driver Partition Map (for 2048 byte blocks)     512 bytes
	Driver Partition Map (for 512 byte blocks)      512 bytes
	Empty                                           512 bytes
	Driver Partition                                N x 2048 bytes
	HFS Partition Boot Block                        1024 bytes

The Perl script "hdisk.pl" can be used to give a listing of what's on
a Mac CD. hdisk.pl is part of hfsutils.

A hybrid CD is made using the option "-boot-hfs-file" e.g.

mkhybrid -boot-hfs-file HFS_driver_file -o hfs.raw src_files/

The -boot-hfs-file implies the -hfs option.

PLEASE NOTE:

By using a driver from an Apple CD and copying Apple software to your CD,
you become liable to obey Apple Computer, Inc. Software License Agreements.

The driver code (both extracting the driver and creating partitions etc.
is based on code from "mkisofs 1.05 PLUS" by Andy Polyakov
<appro@fy.chalmers.se> (see http://fy.chalmers.se/~appro/mkisofs_plus.html)


Any comments, bug reports/fixes to the address below

James Pearson (j.pearson@ge.ucl.ac.uk)
18/5/98

Find file types by using a modified "magic" file

Based on file v3.22 by Ian F. Darwin (see libfile/LEGAL.NOTICE and
libfile/README.dist - File v3.22 can be found at many archive sites)

For each entry in the magic file, the "message" for the initial offset MUST
be 4 characters for the CREATOR and 4 characters for the TYPE - white space is
optional between them. Any other characters on this line are ignored.
Continuation lines (starting with a '>') are also ignored i.e. only the initial
offset lines are used.

e.g magic entry for a GIF file:

# off	type		test		message
#
# GIF image
0       string          GIF8            8BIM GIFf
>4      string          7a              \b, version 8%s,
>4      string          9a              \b, version 8%s,
>6      leshort         >0              %hd x
>8      leshort         >0              %hd,
#>10    byte            &0x80           color mapped,
#>10    byte&0x07       =0x00           2 colors
#>10    byte&0x07       =0x01           4 colors
#>10    byte&0x07       =0x02           8 colors
#>10    byte&0x07       =0x03           16 colors
#>10    byte&0x07       =0x04           32 colors
#>10    byte&0x07       =0x05           64 colors
#>10    byte&0x07       =0x06           128 colors
#>10    byte&0x07       =0x07           256 colors

Just the "8BIM" "GIFf" will be used whatever the type of GIF file it is.
The continuation lines are used by the "file" command, but ignored by
mkhybrid. They could be left out completely.

The complete format of the magic file is given in the magic man page (magic.5).

See the file "magic" for other examples

Use with the -magic magic_file option, where magic_file is a file
described above.

The magic file can be used with the mapping file (option -map) - the order
these options appear on the command line is important.  mkhybrid will try to
detect if the file is one of the Unix/Mac files (e.g. a CAP or Netatalk
file) first. If that fails, it will then use the magic and/or mapping
file e.g:

mkhybrid -o output.raw -map mapping -magic magic src_dir

The above will check filename extensions first, if that fails to set the
CREATOR/TYPE, the magic file will be used. To check the magic file
before the filename extensions, use:

mkhybrid -o output.raw -magic magic -map mapping src_dir


Using just a magic file - filename extensions will not be checked e.g:

mkhybrid -o output.raw -magic magic src_dir

For the magic method to work, each file must be opened and read twice
(once to find it's CREATOR/TYPE, and a second time to actually copy the
file to the CD image). Therefore the -magic option may significantly
increase processing time.

If a file's CREATOR/TYPE is not set via the magic and mapping matches,
then the file is given the default CREATOR/TYPE.

	mkhybrid v1.12b5.1 - make ISO9660/HFS shared hybrid CD volume

HFS hybrid code Copyright (C) James Pearson 1997, 1998, 1999
libhfs code Copyright (C) 1996, 1997 Robert Leslie
libfile code Copyright (c) Ian F. Darwin 1986, 1987, 1989,
	1990, 1991, 1992, 1994, 1995
mkisofs code Copyright 1993 Yggdrasil Computing, Incorporated

WARNING - this is Beta release code - please use with care!
If you find a bug, please report it to the address given below.

This code is based on a Beta release of mkisofs, so there may be
problems unrelated to my additions. However, I have found mkisofs
v1.12b5 to be very stable.

However, many people are using v1.12, so although it's called a "beta"
release, I would encourage people to use it ...
Most of the HFS features work fine, however, some are not fully tested.
These are marked as "Alpha" in the man page.

Please read the man page (mkhybrid.8, or mkhybrid_man.html) for information
on how to use mkhybrid.

Also see "ChangeLog.mkhybrid" for any minor changes/bug fixes

DESCRIPTION

mkhybrid is a pre-mastering utility that creates ISO9660/ROCKRIDGE/JOLIET/HFS
hybrid CDROM images. You will have to use some other CD-R package to write
the image to a CD.

INSTALLATION

To make/install, type "./configure", make any changes to the Makefile
and type "make"

This has been tested with gcc on SunOS 4.1.3 (see below), gcc on Linux
(Redhat v5.1), cc on IRIX 5.3/6.2 and gcc on Win95/WinNT4 using Cygnus'
cygwin (see README.win32)

If you are using SunOS 4.1.[34], then you need the following patches
to read CDs with associated files:

SunOS 4.1.3:		Patch 101832-05
SunOS 4.1.3_U1:		Patch 101833-02
SunOS 4.1.4:		Patch 102583-02


EXAMPLES

To create a HFS hybrid CD with the Joliet and Rock Ridge extensions or
the source directory cd_dir:

% mkhybrid -o cd.iso -r -J -hfs cd_dir

To create a HFS hybrid CD from the source directory cd_dir that contains
Netatalk Apple/Unix files:

% mkhybrid -o cd.iso --netatalk cd_dir

To create a HFS hybrid CD from the source directory cd_dir, giving all files
CREATOR and TYPES based on just their filename extensions listed in the file
"mapping".:

% mkhybrid -o cd.iso -no-mac-files -map mapping cd_dir

To create a CD with the 'Apple Extensions to ISO9660', from the source
direcories cd_dir and another_dir. Files in all the known Apple/Unix format
are decoded and any other files are given CREATOR and TYPE based on their
magic number given in the file "magic":

% mkhybird -o cd.iso -magic -apple cd_dir another_dir

The following example puts different files on the CD that all have
the name README, but have different contents when seen as a
ISO9660/RockRidge Joliet or HFS CD.

Current directory contains

% ls -F
README.hfs     README.joliet  README.unix    cd_dir/

The following command puts the contents of the directory "cd_dir" on the
CD along with the three README files - but only one will be seen from
each of the three filesystems:

% mkhybrid -o cd.iso -hfs -J -r \
        -hide README.hfs -hide README.joliet \
        -hide-joliet README.hfs -hide-joliet README.unix \
        -hide-hfs README.joliet -hide-hfs README.unix \
        README=README.hfs README=README.joliet README=README.unix \
        cd_dir

i.e. the file README.hfs will be seen as README on the HFS CD and the
other two README files will be hidden. Similarly for the Joliet and
ISO9660/RockRidge CD.

There are probably all sorts of stange results possible with
combinations of the hide options ...


Any comments, bug reports/fixes to the address below.

Please state the version, platform and command line used when submitting
a bug report - the output from "-log-file -v" would help.

James Pearson (j.pearson@ge.ucl.ac.uk)

#	$Id: README.mkisofs,v 1.1 2000/10/10 20:40:11 beck Exp $
Note:

	This program requires a lot of virtual memory to run since it
builds all of the directories in memory.  The exact requirements
depend upon a lot of things, but for Rock Ridge discs 12Mb would not
be unreasonable.  Without RockRidge and without the translation
tables, the requirements would be considerably less.

	The cdwrite utility is maintained separately from mkisofs by
yggdrasil.com.  It is enclosed here as a convenience, since the two programs
are often useful together.

*****************************
Notes for version 1.12

	Joliet support is now complete.  See the -J option.

	The file scanning code is much improved - mkisofs can use multiple
	sources of input files and merge them together to form the output
	image.  In addition, each source can be grafted at any point in the
	iso9660 image.

	The image writing code has been cleaned up to make it much easier
	to add custom extensions.

	The ADD_FILES feature has been removed as it didn't work well,
and it was hard to figure out.  The recent rearrangements in the
file scanning code would tend to solve these issues.

*****************************
Notes for version 1.11

	There is a feature which can be optionally compiled into
mkisofs that allows you to merge arbitrary directory trees into the
image you are creating.  You need to compile with -DADD_FILES for my
changes to take effect.   Thanks to Ross Biro biro@yggdrasil.com.

*****************************
Notes for version 1.10b1

	Big news is that multi-session capability is very close to being
	done.  There is still a missing interface to cdwrite that is
	used to determine the next writable address and the sector number
	of the last existing session.  Until we get the interface to cdwrite
	done, this is a beta version.

	Bug involving DST fixed (dates are always calculated, since some
	files may be DST and other ones would not be).

	Unfortunately the notes on some of the small patches got lost.

*****************************
Notes for version 1.06

	Jan-Piet Mens <jpm@mens.de> added support for the '-m' switch. This
	allows exclusion of shell-style globs from the CDROM.
	See manual mkisofs.8 for more information.

*****************************
Notes for version 1.05

	Added support for '-r' switch.  This is very similar to -R for
Rock Ridge, but echos of the development environment are removed
(i.e. uid/gid set to 0, and permissions of the files are canonicalized).
Useful in applications where a distribution medium is being produced.

*****************************
Notes for version 1.04

	No notes for 1.04.

*****************************
Notes for version 1.03

	No notes for 1.03.

*****************************
Notes for version 1.02.

	Minor bugfixes here and there.  Support for compiled in
defaults for many of the text fields in the volume header are now
present, and there is also support for a file ".mkisofsrc" that can
also read settings for these parameters.

	A short script "Configure" was added to allow us to set up special
compile options that depend upon the system that we are running on.
This should help stamp out the sphaghetti-isms that were starting to grow
up in various places in the code.

	You should get more meaningful error messages if you run out of
memory.

*****************************
Notes for version 1.1.

	The big news is that SUSP CE entries are now generated for
extremely long filenames and symlink names.  This virtually guarantees
that there is no limit (OK, well, about 600Mb) for file name lengths.
I have tested this as well as I can, and it seems to work with linux.
This would only be used very rarely I suspect.

	Also, I believe that support for VMS is done.  You must be
careful, because only Stream-LF and FIxed length record files can be
recorded.  The rest are rejected with error messages.  Perhaps I am
being too severe here.

	There is a bugfix in the sorting of entries on the disc - we
need to stop comparing once we reach the ';' character.

	There are four new options -z -d -D -l -V.  Some of these tell
mkisofs to relax some of the iso9660 restrictions, and many systems
apparently do not really seem to mind.  Use these with caution.

	Some diagnostic programs to scan disc images are in the diag
directory.  These are not as portable as mkisofs, and may have some
bugs.  Still they are useful because they can check for bugs that I might
have introduced as I add new features.

*****************************
Notes for version 1.0.

	In version 1.0, the date fields in the TF fields were fixed -
previously I was storing st_ctime as the file creation time instead of
the file attribute change time.  Thanks to Peter van der Veen for
pointing this out.  I have one slight concern with this change,
however.  The Young Minds software is definitely supplying 3 dates
(creation, modification and access), and I would strongly suspect that
they are incorrectly putting the file attribute change time in the
file creation slot.  I would be curious to see how the different RRIP
filesystems treat this.  Anyway, this is something to keep in the back
of your mind.

	The symlink handling was not quite correct in 0.99 - this is
now fixed.  Only some systems seemed to have been affected by this bug.

	A command line option is now present to allow you to
specifically exclude certain files from the distribution.

	The case where you do not have permissions to read a directory
is now handled better by mkisofs.  The directory that cannot be opened
is converted into a zero-length file, and processing continues normally.

	A few portability things have been fixed (hopefully).

#	$Id: README.session,v 1.1 2000/10/10 20:40:11 beck Exp $

	This release of mkisofs has basic support completed for
multiple sessions.  However, we still need some interaction
between cdrecord and mkisofs for this to work correctly. This is needed as
only cdrecord knows the different ways to gather these numbers for all
different drives. It may be that future versions of mkisofs will include
the needed support for MMC compliant drives.

	There are a few new options to mkisofs to allow for this.
The first one is "-M /dev/scd0", and is used so that mkisofs can examine
the entirety of the previous image so that it can figure out what additional
files need to be written in the new session. Note that there are operating
systems that don't allow to read from CD drives with a sector size
of 2048 bytes per sector. To use mkisofs on such an operating system, you
will need a version of mkisofs that includes the SCSI transport library
from cdrecord. Simply use the dev= syntax from cdrecord with -M in
such a case. It will tell mkisofs to use the SCSI transport library to
read from the CD instead of using the standard read() OS interface.

	There is also a temporary hack in mkisofs in the form of a '-C' option.
The -C option takes two numbers as input, which are delimited by commas.
For example, you could specify "-C 1000,1020", but you should never just
make up numbers to use here.  These numbers are determined from cdrecord.

	Note that if you use -C and omit -M, it effectively means that
you are writing a new session, starting at a non-zero block number,
and you are effectively ignoring all of the previous session contents.
When this session is sent to the writer, the new session effectively
"erases" the previous session.

	In practice you should be able to do something like:

mkisofs [other options] -C `cdrecord dev=b,t,l -msinfo` \
		-M /dev/cdblkdev

Replace 'b,t,l' by the aproriate numbers for SCSIbus, target and lun
of your drive.

Note: As of the 1.12b5 release, the multi-session technology has
matured quite significantly.  It is entirely possible that bugs
exists, or that further tweaks will be required somewhere along the
way to get things working correctly.  The data gathering mode of
cdrecord has been tested, and I believe it works correctly.  Caveat
Emptor.

[Mar 1, 1999].

mkhybrid can be compiled on Win9X/NT4 using Cygnus' cygwin
available from:

	http://sourceware.cygnus.com/cygwin/

To build, start a "bash" shell (open a DOS/Command window, cd to the required
directory and type "bash"), and type "./configure" and "make"

A pre-compiled current Win32 binary is available from:

	ftp://ftp.ge.ucl.ac.uk/pub/mkhfs/win32

To use the pre-compiled binary, extract the files from the Zip archive, put
the files cygwin1.dll, mount.exe and mkhybrid.exe in your WINDOWS directory
and from a Command/MS-DOS window type mkhybrid for usage (also see
mkhybrid_man.html).

mkhybrid is a Unix command line utility and knows nothing about DOS/WIN.
Therefore all directory names are given in Unix format (i.e. use '/' for a
directory separator, not '\'). To access files on another disk (i.e.
floppy, CDROM and network disk), you need to use the supplied "mount"
command e.g.

mount a: /a
mount d: /cdrom

i.e. files on the floppy disk are accessed as being in directory /a and
files on the CDROM are accessed as /cdrom (assuming your CDROM is drive d:)
e.g. the following command creates a CD image in the current directory
using a source directories on the CDROM drive, a sub-directory and the
floppy drive:

mkhybrid -o hfs.iso -h -J -r /cdrom/subdir dir1 /a

Please note: Starting with v1.12b5.0 the Win32 executable uses the b20.1
version of the cygwin DLL. If you are using an earlier version of mkhybrid,
then you will need this DLL as well.