libisoburn/doc/faq.wiki

### Libburnia Frequently Asked Questions

Please post your questions to
[GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso).

----------------------------------------------------------------------------
### Content:

Google favorites:

 [xorriso not found](#xorriso_not_found)

 [xorriso tutorial](#xorriso_tutorial)

 [xorriso create ISO image](#xorriso_create_iso)

Burning:

 [What is the difference between cdrskin and xorriso ?](#diff_cdrskin_xorriso)

 [What does that SCSI error message mean ?](#scsi_error)

 [Why is simultaneous burning with multiple drives so slow ?](#concurrent_burn)

Imaging:

 [Is there a way to edit files inside the ISO image ?](#edit_files)

 [For which architectures xorriso is able to create bootable images ?](#boot_arch)

 [How to enable booting from USB stick ?](#isohybrid)

 [What is partition offset feature all about?](#partition_offset)

 [Partition offset bad on Apple ?](#partition_offset_apple)

Development:

 [Where are the APIs of libburnia libraries described ?](#api_specs)

 [I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?](#gui_advise)

Miscellaneous:

 [Where to see examples ?](#example_links)

 [What personalities are supported by xorriso ?](#xorriso_aliases)

 [What is xorriso dialog mode useful for ?](#xorriso_dialog_mode)

 [Why is every second release missing ?](#version_numbers)


------------------------------------------------------------------------
### Google favorites
------------------------------------------------------------------------

##### xorriso not found <A NAME="xorriso_not_found">

This message is issued by programs which use [xorriso](Xorriso) for
producing ISO 9660 filesystem images. E.g. by GRUB2's grub-mkrescue.

Executable xorriso binaries are normally contained in software packages
named "libisoburn" or "xorriso".

If your operating system does not offer such a package, then consider
to get the [GNU xorriso](http://www.gnu.org/software/xorriso#download)
source tarball. For instructions read in its
[README file](http://www.gnu.org/software/xorriso/README_xorriso)
the paragraph "Compilation, First Glimpse, Installation".
With grub-mkrescue it is possible to use the resulting binary without further
installation. Just submit its absolute path with option `--xorriso=`. E.g.:
```
  grub-mkrescue --xorriso=$HOME/xorriso-1.3.8/xorriso/xorriso -o output.iso
```

##### xorriso tutorial <A NAME="xorriso_tutorial">

There is not much more than the
[man xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES)

Volunteers are wanted who make a collection of use cases, ask at bug-xorriso
for xorriso instructions to fulfill the needs, and describe both in a
user-readable manner.

Up to then, the GUI demo [xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/README-tcltk)
[(screenshot)](http://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif)
may serve as interactive exploration tool. It needs `xorriso` >= 1.2.6, `Tcl`,
`Tk` >= 8.4, optionally Tcl / Tk package `BWidget`.
```
  xorriso-tcltk --script_log_file -
```
starts the GUI and will log the essential xorriso commands in the start
terminal. I.e. click on "Scan for drives" and learn that this operation
is triggered by xorriso command `-devices`.

Click the rightmost mouse button while being over any of the GUI elements
in order to get the particular help text for that element.
Have [man xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
ready to learn what the particular commands mean.


##### xorriso create ISO image <A NAME="xorriso_create_iso">

```
  xorriso -outdev $HOME/result.iso \
          -map /home/me/sounds /sounds \
          -map /home/me/pictures /pictures
```
This points the output to file `$HOME/result.iso`, which should not yet exist.
Then it maps disk directory `/home/me/sounds` to ISO directory `/sounds`,
and `/home/me/pictures` to `/pictures`.
At program end, the ISO image gets produced and the contents of the
two directory trees gets copied into the ISO.

If you have experience with program `mkisofs`, you may also use its
emulation by xorriso:
```
  xorriso -as mkisofs \
          -o $HOME/result.iso \
          -graft-points \
          /sounds=/home/me/sounds \
          /pictures=/home/me/pictures
```

See [man xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
for xorriso native commands.

See [man xorrisofs](http://www.gnu.org/software/xorriso/man_1_xorrisofs.html)
for its mkisofs emulation.



----------------------------------------------------------------------------
### Burning
----------------------------------------------------------------------------

##### What is the difference between cdrskin and xorriso ? <A NAME="diff_cdrskin_xorriso">

[cdrskin](Cdrskin) is a dedicated emulator of program cdrecord, based on
libburn. It tries to be as similar to cdrecord as is possible under that
premise.

[xorriso](Xorriso) is an integrated tool which creates, loads, manipulates,
and writes ISO 9660 filesystem images with Rock Ridge extensions.
It is based on libburn, libisofs, and libisoburn. One of its features is
the emulation of the corresponding tasks as done by mkisofs and cdrecord.

##### What does that SCSI error message mean ? <A NAME="scsi_error">

Error messages labled as "SCSI" stem from the drive. They are codes of
three hexadecimal numbers, like `[3 0C 00]`. The first number gives an overall
classification of the problem. The other two numbers give the particular
error description.

libburn translates known error codes into text messages. They consist of
two statements: the overall classification and the error description.

E.g. `[3 0C 00] Medium error. Write error.`

The classification allows a guess where the problem cause might sit:

2 `Drive not ready` : This is a well normal drive state and should be handled
by libburn. If you see this outside of DEBUG messages then it happened
at an unexpected occasion. Either libburn did its job wrong, or the hardware
suffers from blackouts. Hardware can be: drive, cable, bus controller.

Workaround: Check cables. If possible, try the drive at a different
bus controller.

3 `Medium error` : This indicates a problem between drive and medium. libburn
cannot directly cause such an error by any mistake. If drive and medium
are balancing on the edge of defect, it is possible that optional settings
can cause or prevent such errors. But in many cases of drive-medium conflicts
it is mere incident whether a burn run succeeds or not.

Workaround: Try other media or another drive.

4 `Drive error` : The drive or the bus controller accuse themselves of
doing it wrong. As with "Medium error" this might be aggravated or eased by
optional settings.

Workaround: Check cables. If possible, try the drive at a different
bus controller.

5 `Illegal request` : The drive did not like a command sent by libburn.
This may be normal. But if you see this outside of DEBUG messages, then
either the drive does not comply to MMC or libburn does not do its job right.

Workaround: Submit an error report to
[GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso).

B `Command aborted` : Seems to be generated by some bus controllers or
operating system SCSI drivers. The newest outbreak is said to be due to USB 3
and drivers which do not prevent power saving.

Workaround: Plug USB drives to USB 2 sockets or have a recent operating
system kernel. If this does not help, contact
[https://lists.gnu.org/mailman/listinfo/bug-xorriso GNU xorriso mailing list]
and be ready for experiments.

##### Why is simultaneous burning with multiple drives so slow ? <A NAME="concurrent_burn">

It is a known regression of Linux since about 2010 that operating more than
one drive at the same time via SCSI commands shows severe throughput problems.
See [the wiki page about this problem](ConcurrentLinuxSr) which offers two
alternative workarounds in userspace, explanantions of the reason, 
and a link to a remedy proposal by courageous kernel modification.


----------------------------------------------------------------------------
### Imaging
----------------------------------------------------------------------------

##### Is there a way to edit files inside the ISO image ? <A NAME="edit_files">

File content cannot be altered. But files may be replaced by new copies from
the disk filesystem.

The main method of manipulating an existing ISO image is to append a session
with a new complete directory tree and the file content of the added or
overwritten files. Depending on the media type you get gaps between sessions
of up to 20 MB. So better try to do all foreseeable changes by one add-on
session.

##### For which architectures xorriso is able to create bootable images ? <A NAME="boot_arch">

Currently it supports systems with PC-BIOS for booting from CD, DVD, or BD
media, and from memory sticks or hard disks. The same feature range is
supported for systems with EFI firmware with x86 or ARM processor.

Further it supports machines with MIPS processor from SGI (Big Endian)
and DEC (Little Endian), and SUN SPARC machines.
(See [libisofs/doc/boot_sectors.txt](https://dev.lovelyhq.com/libburnia/libisofs/raw/HEAD/doc/boot_sectors.txt)
for technical details.)

Examples how to get an impression of the boot equipment of existing ISO 9660
images are on the wiki page about xorriso
[commands -report_system_area and -report_el_torito](Reportsystemarea).

##### How to enable booting from USB stick ? <A NAME="isohybrid">

In most cases, ISOs are prepared for PC-BIOS to boot the ISOLINUX boot loader.
This boot loader is normally started from CD, DVD or BD media via an El Torito
boot record. But if the ISO image resides on an USB stick or another
hard-disk-like device, then PC-BIOS ignores El Torito and rather expects a
Master Boot Record (MBR). Both boot record types can reside in the same ISO
image. Therefore it is possible to create an MBR that starts the boot image
file of ISOLINUX which is already target of the El Torito boot record.
This kind of MBR is called `isohybrid`. ISOLINUX provides
a program named `isohybrid` to patch existing images, but libisofs can create
an MBR already when producing the ISO image. See in
[manual page of xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html) 
option `-boot_image` with arguments `isolinux system_area=`,
and `-as mkisofs` option `-isohybrid-mbr`.

See [Wikipedia on MBR](http://en.wikipedia.org/wiki/Master_boot_record) for
general information about PC-DOS Master Boot Records, and
[ISOLINUX wiki](http://syslinux.zytor.com/wiki/index.php/ISOLINUX) for special
information about ISOLINUX. The wiki example with mkisofs can be performed
as well by help of xorriso option -as mkisofs.

A similar combination of El Torito and MBR is created by GRUB2 tool
grub-mkrescue. See [homepage of GNU GRUB 2](http://www.gnu.org/software/grub/)
for general information.

EFI firmware in its native mode boots by El Torito from CD, DVD or BD media,
and by partition table from USB stick or hard disk. Both, El Torito and
partition table, point to a FAT filesystem image, the EFI System Partition.
The partiton table may be either a DOS-style MBR partition table or a
[GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table).
The x86 program program in the MBR is ignored by EFI, which rather starts
a program from the FAT directory "\EFI\BOOT". The name of the program file
depends on the processor architecture: BOOTX64.EFI, BOOTIA32.EFI, BOOTARM.EFI,
BOOTAA64.EFI for x86 64 bit, x86 32 bit, ARM 32 bit, and ARM 64 bit,
respectively.

The boot equipment for other systems may well work from USB stick too.
But libburnia project has no tangible information about this.

##### What is partition offset feature all about? <A NAME="partition_offset">

If an MBR is present, then it contains a partition table with up to four
entries. The MBR is located at the very start of the ISO image. By
tradition the first partition should begin only after the range of MBR and
eventual supporting data blocks. On hard disk one often sees partition 1
starting at byte `63*512`. Further it is tradition that the payload filesystem
is mountable via one of the partitions.

The isohybrid MBR has its only partition start at byte 0. Thus it is mountable
but does not obey the tradition to begin only after the MBR.
The `grub-mkrescue` MBR on the other hand has partition 1 start at byte 512,i
which makes it unmountable. Only the unpartitioned base device can be mounted.
(On GNU/Linux
e.g. `/dev/sdb` is the base device whereas `/dev/sdb1` is its partition 1.)

The compromise offered by libisofs is to create a second superblock at
address `16*2048` and to let start partition 1 at this address. The second
superblock leads to a second directory tree which takes into account the
address difference between partition 1 and the base device. So the image
gets mountable via both devices and reserves 32 kB for boot manager software
where it may manipulate and augment the MBR.
(See [Partition Offset Wiki](PartitionOffset)
for examples.)

There are reports of machines which will not boot from USB stick if
partition offset is 0.

##### Partition offset bad on Apple ? <A NAME="partition_offset_apple">

Apple's "Snow Leopard" operating system refuses to mount Debian CD images
with non-zero partition offset.

The issue is not yet fully understood. For now one has to choose
between mountability on Apple "Snow Leopard" or bootability from USB stick
on Kontron CG2100 "carrier grade server".

----------------------------------------------------------------------------
### Developing
----------------------------------------------------------------------------

##### Where are the APIs of libburnia libraries described ? <A NAME="api_specs">

The decisive references are the inclusion headers of the libraries
`<libburn/libburn.h>`, `<libisofs/libisofs.h>`, `<libisoburn/libisoburn.h>`,
and `<libisoburn/xorriso.h>`.

Current git versions of these files: 
[libburn/libburn.h](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/libburn/libburn.h) ,
[libisofs/libisofs.h](https://dev.lovelyhq.com/libburnia/libisofs/raw/HEAD/libisofs/libisofs.h) ,
[libisoburn/libisoburn.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/libisoburn/libisoburn.h) ,
[libisoburn/xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/xorriso/xorriso.h)

##### I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? <A NAME="gui_advise">

Most appreciated would be a GUI for xorriso which allows to copy files from
a view of the hard disk filesystem to a view of the ISO filesystem, and vice
versa. The xorriso implementation is located inside libisoburn.

Each option that is described in
[man 1 xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
can be performed by a corresponding C function that is defined in
[xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/xorriso/xorriso.h)

Further there are calls for library startup and shutdown, for problem
handling, and for the interpreters of xorriso's command line interface.
The xorriso API encapsulates calls to libisofs, libburn, and libisoburn.

An alternative to the xorriso C API is xorriso dialog mode.
[See below](#xorriso_dialog_mode).
The script
[xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/xorriso-tcltk)
demonstrates this approach. It is part of the
libisoburn release tarball and of the GNU xorriso tarball.

The known existing GUIs
[Xfburn](http://goodies.xfce.org/projects/applications/xfburn),
[Brasero](http://projects.gnome.org/brasero/),
[FlBurn](http://flburn.sourceforge.net/)
rather use libisofs and libburn directly.
(Please submit an URI if you want your libburnia GUI application mentioned
here.)

----------------------------------------------------------------------------
### Miscellaneous
----------------------------------------------------------------------------

##### Where to see examples ? <A NAME="example_links">

[xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES) ,
[cdrskin examples](http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES) ,
[libburner.c a minimal but complete burn program](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/test/libburner.c).


##### What personalities are supported by xorriso ? <A NAME="xorriso_aliases">

The name by which xorriso is started may trigger certain features which
normally would need to be enabled by program options.

xorrisofs starts up in mkisofs emulation mode, which otherwise would have to
be entered by command `-as mkisofs`.

xorrecord starts up in cdrecord emulation mode, which is normally entered by
command `-as cdrecord`. This emulation is only able to write a single data
track as new session to blank or appendable media. No audio. No multiple
tracks in one session.

osirrox can copy files from ISO image to disk and to apply option -mount
to one or more of the existing ISO sessions. This is normally enabled by
option `-osirrox on:o_excl_off`.

##### What is xorriso dialog mode useful for ? <A NAME="xorriso_dialog_mode">

Dialog mode is initiated if `-dialog on` is among the program arguments.
It can be used to inspect and exploit existing ISO 9660 images or
to explore xorriso's behavior in order to develop the command sequence
for a batch run.

Frontend programmers may fork xorriso initiating a xorriso dialog session
(`-dialog on -use_readline off -pkt_output on -mark done`),
and interact with it from their own program via pipes connected to
xorriso's stdin and stdout. This is more efficient than forking xorriso
every now and then to perform various commands in order to complete
complex tasks like image size prediction.

The script
[xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/xorriso-tcltk)
demonstrates this approach. It is part of the
libisoburn release tarball and of the GNU xorriso tarball.

##### Why is every second release missing ? <A NAME="version_numbers">

Releases have an even third version number. Like 0.5.6 or 1.0.4.
During development the next higher odd number is used. E.g. 0.5.7 or 1.0.5.

The content of release tarballs does not get changed without changing
their name. The development tarballs of xorriso and cdrskin may change
their content without notice.

----------------------------------------------------------------------------
Site maintainer: Do not edit this wiki directly but rather the git version
of `libisoburn/doc/faq.wiki`. When done, paste it into the wiki editor.