309 lines
14 KiB
Plaintext
309 lines
14 KiB
Plaintext
|
|
'''Libburnia Frequently Asked Questions'''
|
|
|
|
Please post your questions to
|
|
[http://mailman-mail1.webfaction.com/listinfo/libburn-hackers/ libburn-hackers mailing list].
|
|
|
|
----------------------------------------------------------------------------
|
|
'''Content:'''
|
|
|
|
Burning:
|
|
|
|
[#diff_cdrskin_xorriso What is the difference between cdrskin and xorriso ?]
|
|
|
|
[#scsi_error What does that SCSI error message mean ?]
|
|
|
|
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 ?]
|
|
|
|
----------------------------------------------------------------------------
|
|
'''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
|
|
[http://mailman-mail1.webfaction.com/listinfo/libburn-hackers/ libburn-hackers mailing list].
|
|
|
|
B "Command aborted" : Seems to be generated by some bus controllers or
|
|
operating system SCSI drivers.
|
|
|
|
Workaround: Contact
|
|
[http://mailman-mail1.webfaction.com/listinfo/libburn-hackers/ libburn-hackers mailing list]
|
|
and be ready for experiments.
|
|
|
|
|
|
----------------------------------------------------------------------------
|
|
'''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.
|
|
|