diff --git a/doc/faq.wiki b/doc/faq.wiki new file mode 100644 index 00000000..be13f47d --- /dev/null +++ b/doc/faq.wiki @@ -0,0 +1,202 @@ + +'''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 ?] + +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 What is isohybrid MBR useful for ?] + + [#partition_offset What is partition offset feature all about?] + +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 ?] + +---------------------------------------------------------------------------- +'''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 as 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. + +---------------------------------------------------------------------------- +'''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. + +===== 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 +[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 eventually can manipulate and augment the MBR. +(See [http://libburnia-project.org/wiki/PartitionOffset Partition Offset Wiki] +for examples.) + +---------------------------------------------------------------------------- +'''Developing''' +---------------------------------------------------------------------------- + +===== Where are the APIs of libburnia libraries described ? ===== #api_specs + +The decisive references are the inclusion headers of the libraries +, , , +and . + +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. + +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". + +---------------------------------------------------------------------------- +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. +