Took source file of into SVN

This commit is contained in:
Thomas Schmitt 2010-12-23 14:02:01 +00:00
parent 3ef177f1c9
commit 86fb1eb0cf

doc/ Normal file
View File

@ -0,0 +1,202 @@
'''Libburnia Frequently Asked Questions'''
Please post your questions to
[ libburn-hackers mailing list].
[#diff_cdrskin_xorriso What is the difference between cdrskin and xorriso ?]
[#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 What is isohybrid MBR useful for ?]
[#partition_offset What is partition offset feature all about?]
[#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 ?]
[#example_links Where to see examples ?]
[#xorriso_aliases What personalities are supported by xorriso ?]
===== 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 as cdrecord as is possible under that
[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.
===== 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
===== 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 [ 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.
===== What is isohybrid MBR useful for ? ===== #isohybrid
The ISOLINUX boot manager system 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? ===== #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 eventually can manipulate and augment the MBR.
(See [ Partition Offset Wiki]
for examples.)
===== 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:
[ libburn/libburn.h] ,
[ libisofs/libisofs.h] ,
[ libisoburn/libisoburn.h] ,
[ libisoburn/xorriso.h]
Doxygen generated API descriptions at
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
[ 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.
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
===== Where to see examples ? ===== #example_links
[ 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 ? ===== #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".
Site maintainer: Do not edit this wiki directly but rather the SVN version
of libisoburn/trunk/doc/ When done, paste it into the wiki editor.