libisoburn/doc/faq.wiki

'''Libburnia Frequently Asked Questions'''

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

----------------------------------------------------------------------------
'''Content:'''

Google favorites:

 [#xorriso_not_found  xorriso not found]

 [#xorriso_tutorial  xorriso tutorial]

 [#xorriso_create_iso  xorriso create ISO image]

Burning:

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

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

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

Imaging:

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

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

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

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

 [#partition_offset_apple  Partition offset bad on Apple ?]

Development:

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

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

Miscellaneous:

 [#example_links  Where to see examples ?]

 [#xorriso_aliases  What personalities are supported by xorriso ?]

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

 [#version_numbers  Why is every second release missing ?]

----------------------------------------------------------------------------
'''Google favorites'''
----------------------------------------------------------------------------

===== xorriso not found ===== #xorriso_not_found

This message is issued by programs which use [wiki: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 [http://www.gnu.org/software/xorriso#download GNU xorriso]
source tarball. For instructions read in its
[http://www.gnu.org/software/xorriso/README_xorriso README file]
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 ===== #xorriso_tutorial

There is not much more than the
[http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES man xorriso 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 [http://svn.libburnia-project.org/libisoburn/trunk/frontend/README-tcltk xorriso-tcltk]
([http://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif screenshot])
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 [http://www.gnu.org/software/xorriso/man_1_xorriso.html man xorriso]
ready to learn what the particular commands mean.


===== xorriso create ISO image ===== #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 [http://www.gnu.org/software/xorriso/man_1_xorriso.html man xorriso]
for xorriso native commands.

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



----------------------------------------------------------------------------
'''Burning'''
----------------------------------------------------------------------------

===== What is the difference between cdrskin and xorriso ? ===== #diff_cdrskin_xorriso

[wiki: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.

[wiki: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 ? ===== #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
[https://lists.gnu.org/mailman/listinfo/bug-xorriso GNU xorriso mailing list].

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 ? ===== #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 [ConcurrentLinuxSr the wiki page about this problem] 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 ? ===== #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 ? ===== #boot_arch

Currently it supports systems with PC-BIOS via El Torito for booting from
CD, DVD, or BD media, and via MBR for booting from memory sticks or hard
disks. Further it supports machines with MIPS processor from SGI (Big Endian)
and DEC (Little Endian), and SUN SPARC machines.
(See [http://bazaar.launchpad.net/%7Elibburnia-team/libisofs/scdbackup/annotate/head%3A/doc/boot_sectors.txt libisofs/doc/boot_sectors.txt]
for technical details.)

Machines which support EFI may either boot via El Torito or use the files
of the ISO image directly. It is possible to append to the ISO image a
writeable FAT12 partition where files for EFI may be stored and changed.

===== How to enable booting from USB stick ? ===== #isohybrid

The ISOLINUX boot loader is normally started from CD, DVD or BD media
by a PC-BIOS 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
[http://www.gnu.org/software/xorriso/man_1_xorriso.html manual page of xorriso] 
option -boot_image with arguments "isolinux" "system_area=",
and -as mkisofs option -isohybrid-mbr.

See [http://en.wikipedia.org/wiki/Master_boot_record Wikipedia on MBR] for
general information about PC-DOS Master Boot Records, and
[http://syslinux.zytor.com/wiki/index.php/ISOLINUX ISOLINUX wiki] 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 [http://www.gnu.org/software/grub/ homepage of GNU GRUB 2]
for general information.

===== What is partition offset feature all about? ===== #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, 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 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 [http://libburnia-project.org/wiki/PartitionOffset Partition Offset Wiki]
for examples.)

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

===== Partition offset bad on Apple ? ===== #partition_offset_apple

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

The issue is still under investigation. But 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 ? ===== #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 SVN versions of these files: 
[http://libburnia-project.org/browser/libburn/trunk/libburn/libburn.h libburn/libburn.h] ,
[http://bazaar.launchpad.net/%7Elibburnia-team/libisofs/scdbackup/annotate/head%3A/libisofs/libisofs.h libisofs/libisofs.h] ,
[http://libburnia-project.org/browser/libisoburn/trunk/libisoburn/libisoburn.h libisoburn/libisoburn.h] ,
[http://libburnia-project.org/browser/libisoburn/trunk/xorriso/xorriso.h libisoburn/xorriso.h]

Doxygen generated API descriptions at
[http://api.libburnia-project.org api.libburnia-project.org]
might be slightly behind the latest developments.

===== I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? ===== #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
[http://www.gnu.org/software/xorriso/man_1_xorriso.html man 1 xorriso]
can be performed by a corresponding C function that is defined in
[http://libburnia-project.org/browser/libisoburn/trunk/xorriso/xorriso.h 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.
[#xorriso_dialog_mode See below.]
The script
[http://libburnia-project.org/browser/libisoburn/trunk/frontend/xorriso-tcltk xorriso-tcltk]
demonstrates this approach. It is part of the
libisoburn release tarball and of the GNU xorriso tarball.

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

----------------------------------------------------------------------------
'''Miscellaneous'''
----------------------------------------------------------------------------

===== Where to see examples ? ===== #example_links

[http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES xorriso examples] ,
[http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES cdrskin examples] ,
[http://libburnia-project.org/browser/libburn/trunk/test/libburner.c libburner.c a minimal but complete burn program]
(also illustrated at the end of [http://api.libburnia-project.org/libburn/ libburn API intro]).


===== What personalities are supported by xorriso ? ===== #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 allows to 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 ? ===== #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
[http://libburnia-project.org/browser/libisoburn/trunk/frontend/xorriso-tcltk 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 ? ===== #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 SVN version
of libisoburn/trunk/doc/faq.wiki. When done, paste it into the wiki editor.