Libburnia Frequently Asked Questions

Please post your questions to  GNU xorriso mailing list.


Content:

Google favorites:

xorriso not found

xorriso tutorial

xorriso create ISO image

Burning:

What is the difference between cdrskin and xorriso ?

What does that SCSI error message mean ?

Imaging:

Is there a way to edit files inside the ISO image ?

For which architectures xorriso is able to create bootable images ?

How to enable booting from USB stick ?

What is partition offset feature all about?

Partition offset bad on Apple ?

Development:

Where are the APIs of libburnia libraries described ?

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

Miscellaneous:

Where to see examples ?

What personalities are supported by xorriso ?

What is xorriso dialog mode useful for ?

Why is every second release missing ?


Google favorites


xorriso not found

This message is issued by programs which use 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 source tarball. For instructions read in its  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

There is not much more than the  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  xorriso-tcltk ( 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  man xorriso ready to learn what the particular commands mean.

xorriso create ISO image
  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 for xorriso native commands.

See  man xorriso for its mkisofs emulation.


Burning


What is the difference between cdrskin and xorriso ?

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 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 ?

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.

B "Command aborted" : Seems to be generated by some bus controllers or operating system SCSI drivers.

Workaround: Contact  GNU xorriso mailing list and be ready for experiments.


Imaging


Is there a way to edit files inside the ISO image ?

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 ?

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  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 ?

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  manual page of xorriso option -boot_image with arguments "isolinux" "system_area=", and -as mkisofs option -isohybrid-mbr.

See  Wikipedia on MBR for general information about PC-DOS Master Boot Records, and  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  homepage of GNU GRUB 2 for general information.

What is partition offset feature all about?

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 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 ?

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 ?

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: libburn/libburn.h ,  libisofs/libisofs.h , libisoburn/libisoburn.h , libisoburn/xorriso.h

Doxygen generated API descriptions at  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 ?

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 can be performed by a corresponding C function that is defined in 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. The script xorriso-tcltk demonstrates this approach. It is part of the libisoburn release tarball and of the GNU xorriso tarball.

The known existing GUIs  Xfburn,  Brasero,  FlBurn rather use libisofs and libburn directly. (Please submit an URI if you want your libburnia GUI application mentioned here.)


Miscellaneous


 xorriso examples ,  cdrskin examples , libburner.c a minimal but complete burn program (also illustrated at the end of  libburn API intro).

What personalities are supported by xorriso ?

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 ?

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 demonstrates this approach. It is part of the libisoburn release tarball and of the GNU xorriso tarball.

Why is every second release missing ?

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.