Updated libisoburn doc/*.wiki files by current publicly shown files

This commit is contained in:
Thomas Schmitt 2017-09-06 14:42:21 +02:00
parent 047b8db7ac
commit 650c015c5b
3 changed files with 596 additions and 585 deletions

View File

@ -1,407 +1,424 @@
'''Libburnia Frequently Asked Questions''' ### Libburnia Frequently Asked Questions
Please post your questions to Please post your questions to
[https://lists.gnu.org/mailman/listinfo/bug-xorriso GNU xorriso mailing list]. [GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso).
---------------------------------------------------------------------------- ----------------------------------------------------------------------------
'''Content:''' ### Content:
Google favorites: Google favorites:
[#xorriso_not_found xorriso not found] [xorriso not found](#xorriso_not_found)
[#xorriso_tutorial xorriso tutorial] [xorriso tutorial](#xorriso_tutorial)
[#xorriso_create_iso xorriso create ISO image] [xorriso create ISO image](#xorriso_create_iso)
Burning: Burning:
[#diff_cdrskin_xorriso What is the difference between cdrskin and xorriso ?] [What is the difference between cdrskin and xorriso ?](#diff_cdrskin_xorriso)
[#scsi_error What does that SCSI error message mean ?] [What does that SCSI error message mean ?](#scsi_error)
[#concurrent_burn Why is simultaneous burning with multiple drives so slow ?] [Why is simultaneous burning with multiple drives so slow ?](#concurrent_burn)
Imaging: Imaging:
[#edit_files Is there a way to edit files inside the ISO image ?] [Is there a way to edit files inside the ISO image ?](#edit_files)
[#boot_arch For which architectures xorriso is able to create bootable images ?] [For which architectures xorriso is able to create bootable images ?](#boot_arch)
[#isohybrid How to enable booting from USB stick ?] [How to enable booting from USB stick ?](#isohybrid)
[#partition_offset What is partition offset feature all about?] [What is partition offset feature all about?](#partition_offset)
[#partition_offset_apple Partition offset bad on Apple ?] [Partition offset bad on Apple ?](#partition_offset_apple)
Development: Development:
[#api_specs Where are the APIs of libburnia libraries described ?] [Where are the APIs of libburnia libraries described ?](#api_specs)
[#gui_advise I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?] [I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?](#gui_advise)
Miscellaneous: Miscellaneous:
[#example_links Where to see examples ?] [Where to see examples ?](#example_links)
[#xorriso_aliases What personalities are supported by xorriso ?] [What personalities are supported by xorriso ?](#xorriso_aliases)
[#xorriso_dialog_mode What is xorriso dialog mode useful for ?] [What is xorriso dialog mode useful for ?](#xorriso_dialog_mode)
[#version_numbers Why is every second release missing ?] [Why is every second release missing ?](#version_numbers)
----------------------------------------------------------------------------
'''Google favorites''' ------------------------------------------------------------------------
---------------------------------------------------------------------------- ### Google favorites
------------------------------------------------------------------------
===== xorriso not found ===== #xorriso_not_found
##### xorriso not found <A NAME="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. This message is issued by programs which use [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". 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] If your operating system does not offer such a package, then consider
source tarball. For instructions read in its to get the [GNU xorriso](http://www.gnu.org/software/xorriso#download)
[http://www.gnu.org/software/xorriso/README_xorriso README file] source tarball. For instructions read in its
the paragraph "Compilation, First Glimpse, Installation". [README file](http://www.gnu.org/software/xorriso/README_xorriso)
With grub-mkrescue it is possible to use the resulting binary without further the paragraph "Compilation, First Glimpse, Installation".
installation. Just submit its absolute path with option --xorriso=. E.g.: 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 ```
}}} grub-mkrescue --xorriso=$HOME/xorriso-1.3.8/xorriso/xorriso -o output.iso
```
===== xorriso tutorial ===== #xorriso_tutorial
##### xorriso tutorial <A NAME="xorriso_tutorial">
There is not much more than the
[http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES man xorriso examples]. There is not much more than the
[man xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#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 Volunteers are wanted who make a collection of use cases, ask at bug-xorriso
user-readable manner. 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]) Up to then, the GUI demo [xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/README-tcltk)
may serve as interactive exploration tool. It needs xorriso >= 1.2.6, Tcl, [(screenshot)](http://www.gnu.org/software/xorriso/xorriso-tcltk-screen.gif)
Tk >= 8.4, optionally Tcl / Tk package "BWidget". 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 - ```
}}} 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 starts the GUI and will log the essential xorriso commands in the start
is triggered by xorriso command "-devices". 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. Click the rightmost mouse button while being over any of the GUI elements
Have [http://www.gnu.org/software/xorriso/man_1_xorriso.html man xorriso] in order to get the particular help text for that element.
ready to learn what the particular commands mean. Have [man xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
ready to learn what the particular commands mean.
===== xorriso create ISO image ===== #xorriso_create_iso
##### xorriso create ISO image <A NAME="xorriso_create_iso">
{{{
xorriso -outdev $HOME/result.iso \ ```
-map /home/me/sounds /sounds \ xorriso -outdev $HOME/result.iso \
-map /home/me/pictures /pictures -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, This points the output to file `$HOME/result.iso`, which should not yet exist.
and /home/me/pictures to /pictures. Then it maps disk directory `/home/me/sounds` to ISO directory `/sounds`,
At program end, the ISO image gets produced and the contents of the and `/home/me/pictures` to `/pictures`.
two directory trees gets copied into the ISO. 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: If you have experience with program `mkisofs`, you may also use its
{{{ emulation by xorriso:
xorriso -as mkisofs \ ```
-o $HOME/result.iso \ xorriso -as mkisofs \
-graft-points \ -o $HOME/result.iso \
/sounds=/home/me/sounds \ -graft-points \
/pictures=/home/me/pictures /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 [man xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
for xorriso native commands.
See [http://www.gnu.org/software/xorriso/man_1_xorrisofs.html man xorriso]
for its mkisofs emulation. See [man xorrisofs](http://www.gnu.org/software/xorriso/man_1_xorrisofs.html)
for its mkisofs emulation.
----------------------------------------------------------------------------
'''Burning''' ----------------------------------------------------------------------------
---------------------------------------------------------------------------- ### Burning
----------------------------------------------------------------------------
===== What is the difference between cdrskin and xorriso ? ===== #diff_cdrskin_xorriso
##### What is the difference between cdrskin and xorriso ? <A NAME="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 [cdrskin](Cdrskin) is a dedicated emulator of program cdrecord, based on
premise. 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. [xorriso](Xorriso) is an integrated tool which creates, loads, manipulates,
It is based on libburn, libisofs, and libisoburn. One of its features is and writes ISO 9660 filesystem images with Rock Ridge extensions.
the emulation of the corresponding tasks as done by mkisofs and cdrecord. 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
##### What does that SCSI error message mean ? <A NAME="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 Error messages labled as "SCSI" stem from the drive. They are codes of
classification of the problem. The other two numbers give the particular three hexadecimal numbers, like `[3 0C 00]`. The first number gives an overall
error description. 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. 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.
E.g. `[3 0C 00] Medium error. Write error.`
The classification allows a guess where the problem cause might sit:
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 2 `Drive not ready` : This is a well normal drive state and should be handled
at an unexpected occasion. Either libburn did its job wrong, or the hardware by libburn. If you see this outside of DEBUG messages then it happened
suffers from blackouts. Hardware can be: drive, cable, bus controller. 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. 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 3 `Medium error` : This indicates a problem between drive and medium. libburn
are balancing on the edge of defect, it is possible that optional settings cannot directly cause such an error by any mistake. If drive and medium
can cause or prevent such errors. But in many cases of drive-medium conflicts are balancing on the edge of defect, it is possible that optional settings
it is mere incident whether a burn run succeeds or not. 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.
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 4 `Drive error` : The drive or the bus controller accuse themselves of
optional settings. 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. 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 5 `Illegal request` : The drive did not like a command sent by libburn.
either the drive does not comply to MMC or libburn does not do its job right. 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]. Workaround: Submit an error report to
[GNU xorriso mailing list](https://lists.gnu.org/mailman/listinfo/bug-xorriso).
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 B `Command aborted` : Seems to be generated by some bus controllers or
and drivers which do not prevent power saving. 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 Workaround: Plug USB drives to USB 2 sockets or have a recent operating
[https://lists.gnu.org/mailman/listinfo/bug-xorriso GNU xorriso mailing list] system kernel. If this does not help, contact
and be ready for experiments. [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
##### Why is simultaneous burning with multiple drives so slow ? <A NAME="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. It is a known regression of Linux since about 2010 that operating more than
See [ConcurrentLinuxSr the wiki page about this problem] which offers two one drive at the same time via SCSI commands shows severe throughput problems.
alternative workarounds in userspace, explanantions of the reason, See [the wiki page about this problem](ConcurrentLinuxSr) which offers two
and a link to a remedy proposal by courageous kernel modification. alternative workarounds in userspace, explanantions of the reason,
and a link to a remedy proposal by courageous kernel modification.
----------------------------------------------------------------------------
'''Imaging'''
---------------------------------------------------------------------------- ----------------------------------------------------------------------------
### 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 ##### Is there a way to edit files inside the ISO image ? <A NAME="edit_files">
the disk filesystem.
File content cannot be altered. But files may be replaced by new copies from
The main method of manipulating an existing ISO image is to append a session the disk filesystem.
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 The main method of manipulating an existing ISO image is to append a session
of up to 20 MB. So better try to do all foreseeable changes by one add-on with a new complete directory tree and the file content of the added or
session. 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 session.
Currently it supports systems with PC-BIOS via El Torito for booting from ##### For which architectures xorriso is able to create bootable images ? <A NAME="boot_arch">
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) Currently it supports systems with PC-BIOS for booting from CD, DVD, or BD
and DEC (Little Endian), and SUN SPARC machines. media, and from memory sticks or hard disks. The same feature range is
(See [http://bazaar.launchpad.net/%7Elibburnia-team/libisofs/scdbackup/annotate/head%3A/doc/boot_sectors.txt libisofs/doc/boot_sectors.txt] supported for systems with EFI firmware with x86 or ARM processor.
for technical details.)
Further it supports machines with MIPS processor from SGI (Big Endian)
Machines which support EFI may either boot via El Torito or use the files and DEC (Little Endian), and SUN SPARC machines.
of the ISO image directly. It is possible to append to the ISO image a (See [libisofs/doc/boot_sectors.txt](https://dev.lovelyhq.com/libburnia/libisofs/raw/HEAD/doc/boot_sectors.txt)
writeable FAT12 partition where files for EFI may be stored and changed. for technical details.)
===== How to enable booting from USB stick ? ===== #isohybrid Examples how to get an impression of the boot equipment of existing ISO 9660
images are on the wiki page about xorriso
The ISOLINUX boot loader is normally started from CD, DVD or BD media [commands -report_system_area and -report_el_torito](Reportsystemarea).
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 ##### How to enable booting from USB stick ? <A NAME="isohybrid">
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 In most cases, ISOs are prepared for PC-BIOS to boot the ISOLINUX boot loader.
starts the boot image file of ISOLINUX which is already target of the El Torito This boot loader is normally started from CD, DVD or BD media via an El Torito
boot record. This kind of MBR is called "isohybrid". ISOLINUX provides boot record. But if the ISO image resides on an USB stick or another
a program named isohybrid to patch existing images, but libisofs can create an hard-disk-like device, then PC-BIOS ignores El Torito and rather expects a
MBR already when producing the ISO image. See in Master Boot Record (MBR). Both boot record types can reside in the same ISO
[http://www.gnu.org/software/xorriso/man_1_xorriso.html manual page of xorriso] image. Therefore it is possible to create an MBR that starts the boot image
option -boot_image with arguments "isolinux" "system_area=", file of ISOLINUX which is already target of the El Torito boot record.
and -as mkisofs option -isohybrid-mbr. This kind of MBR is called `isohybrid`. ISOLINUX provides
a program named `isohybrid` to patch existing images, but libisofs can create
See [http://en.wikipedia.org/wiki/Master_boot_record Wikipedia on MBR] for an MBR already when producing the ISO image. See in
general information about PC-DOS Master Boot Records, and [manual page of xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
[http://syslinux.zytor.com/wiki/index.php/ISOLINUX ISOLINUX wiki] for special option `-boot_image` with arguments `isolinux system_area=`,
information about ISOLINUX. The wiki example with mkisofs can be performed and `-as mkisofs` option `-isohybrid-mbr`.
as well by help of xorriso option -as mkisofs.
See [Wikipedia on MBR](http://en.wikipedia.org/wiki/Master_boot_record) for
A similar combination of El Torito and MBR is created by GRUB2 tool general information about PC-DOS Master Boot Records, and
grub-mkrescue. See [http://www.gnu.org/software/grub/ homepage of GNU GRUB 2] [ISOLINUX wiki](http://syslinux.zytor.com/wiki/index.php/ISOLINUX) for special
for general information. information about ISOLINUX. The wiki example with mkisofs can be performed
as well by help of xorriso option -as mkisofs.
===== What is partition offset feature all about? ===== #partition_offset
A similar combination of El Torito and MBR is created by GRUB2 tool
If an MBR is present, then it contains a partition table with up to four grub-mkrescue. See [homepage of GNU GRUB 2](http://www.gnu.org/software/grub/)
entries. The MBR is located at the very start of the ISO image. By for general information.
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 EFI firmware in its native mode boots by El Torito from CD, DVD or BD media,
starting at byte 63*512. Further it is tradition that the payload filesystem and by partition table from USB stick or hard disk. Both, El Torito and
is mountable via one of the partitions. partition table, point to a FAT filesystem image, the EFI System Partition.
The partiton table may be either a DOS-style MBR partition table or a
The isohybrid MBR has its only partition start at byte 0. Thus it is mountable [GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table).
but does not obey the tradition to begin only after the MBR. The grub-mkrescue The x86 program program in the MBR is ignored by EFI, which rather starts
MBR on the other hand has partition 1 start at byte 512, which makes it a program from the FAT directory "\EFI\BOOT". The name of the program file
unmountable. Only the unpartitioned base device can be mounted. (On GNU/Linux depends on the processor architecture: BOOTX64.EFI, BOOTIA32.EFI, BOOTARM.EFI,
e.g. /dev/sdb is the base device whereas /dev/sdb1 is partition 1.) BOOTAA64.EFI for x86 64 bit, x86 32 bit, ARM 32 bit, and ARM 64 bit,
respectively.
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 The boot equipment for other systems may well work from USB stick too.
superblock leads to a second directory tree which takes into account the But libburnia project has no tangible information about this.
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 ##### What is partition offset feature all about? <A NAME="partition_offset">
where it may manipulate and augment the MBR.
(See [http://libburnia-project.org/wiki/PartitionOffset Partition Offset Wiki] If an MBR is present, then it contains a partition table with up to four
for examples.) 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
There are reports of machines which will not boot from USB stick if eventual supporting data blocks. On hard disk one often sees partition 1
partition offset is 0. starting at byte `63*512`. Further it is tradition that the payload filesystem
is mountable via one of the partitions.
===== Partition offset bad on Apple ? ===== #partition_offset_apple
The isohybrid MBR has its only partition start at byte 0. Thus it is mountable
Apple's "Snow Leopard" operating system refuses to mount Debian CD images but does not obey the tradition to begin only after the MBR.
with non-zero partition offset. The `grub-mkrescue` MBR on the other hand has partition 1 start at byte 512,i
which makes it unmountable. Only the unpartitioned base device can be mounted.
The issue is still under investigation. But for now one has to choose (On GNU/Linux
between mountability on Apple "Snow Leopard" or bootability from USB stick e.g. `/dev/sdb` is the base device whereas `/dev/sdb1` is its partition 1.)
on Kontron CG2100 "carrier grade server".
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
'''Developing''' 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 are the APIs of libburnia libraries described ? ===== #api_specs where it may manipulate and augment the MBR.
(See [Partition Offset Wiki](PartitionOffset)
The decisive references are the inclusion headers of the libraries for examples.)
<libburn/libburn.h>, <libisofs/libisofs.h>, <libisoburn/libisoburn.h>,
and <libisoburn/xorriso.h>. There are reports of machines which will not boot from USB stick if
partition offset is 0.
Current SVN versions of these files:
[http://libburnia-project.org/browser/libburn/trunk/libburn/libburn.h libburn/libburn.h] , ##### Partition offset bad on Apple ? <A NAME="partition_offset_apple">
[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] , Apple's "Snow Leopard" operating system refuses to mount Debian CD images
[http://libburnia-project.org/browser/libisoburn/trunk/xorriso/xorriso.h libisoburn/xorriso.h] with non-zero partition offset.
Doxygen generated API descriptions at The issue is not yet fully understood. For now one has to choose
[http://api.libburnia-project.org api.libburnia-project.org] between mountability on Apple "Snow Leopard" or bootability from USB stick
might be slightly behind the latest developments. on Kontron CG2100 "carrier grade server".
===== I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? ===== #gui_advise ----------------------------------------------------------------------------
### Developing
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. ##### Where are the APIs of libburnia libraries described ? <A NAME="api_specs">
Each option that is described in The decisive references are the inclusion headers of the libraries
[http://www.gnu.org/software/xorriso/man_1_xorriso.html man 1 xorriso] `<libburn/libburn.h>`, `<libisofs/libisofs.h>`, `<libisoburn/libisoburn.h>`,
can be performed by a corresponding C function that is defined in and `<libisoburn/xorriso.h>`.
[http://libburnia-project.org/browser/libisoburn/trunk/xorriso/xorriso.h xorriso.h].
Further there are calls for library startup and shutdown, for problem Current git versions of these files:
handling, and for the interpreters of xorriso's command line interface. [libburn/libburn.h](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/libburn/libburn.h) ,
The xorriso API encapsulates calls to libisofs, libburn, and libisoburn. [libisofs/libisofs.h](https://dev.lovelyhq.com/libburnia/libisofs/raw/HEAD/libisofs/libisofs.h) ,
[libisoburn/libisoburn.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/libisoburn/libisoburn.h) ,
An alternative to the xorriso C API is xorriso dialog mode. [libisoburn/xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/xorriso/xorriso.h)
[#xorriso_dialog_mode See below.]
The script ##### I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? <A NAME="gui_advise">
[http://libburnia-project.org/browser/libisoburn/trunk/frontend/xorriso-tcltk xorriso-tcltk]
demonstrates this approach. It is part of the Most appreciated would be a GUI for xorriso which allows to copy files from
libisoburn release tarball and of the GNU xorriso tarball. a view of the hard disk filesystem to a view of the ISO filesystem, and vice
versa. The xorriso implementation is located inside libisoburn.
The known existing GUIs [http://www.xfce.org/projects/xfburn/ Xfburn],
[http://projects.gnome.org/brasero/ Brasero], Each option that is described in
[http://flburn.sourceforge.net/ FlBurn] [man 1 xorriso](http://www.gnu.org/software/xorriso/man_1_xorriso.html)
rather use libisofs and libburn directly. can be performed by a corresponding C function that is defined in
(Please submit an URI if you want your libburnia GUI application mentioned [xorriso.h](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/xorriso/xorriso.h)
here.)
Further there are calls for library startup and shutdown, for problem
---------------------------------------------------------------------------- handling, and for the interpreters of xorriso's command line interface.
'''Miscellaneous''' The xorriso API encapsulates calls to libisofs, libburn, and libisoburn.
----------------------------------------------------------------------------
An alternative to the xorriso C API is xorriso dialog mode.
===== Where to see examples ? ===== #example_links [See below](#xorriso_dialog_mode).
The script
[http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES xorriso examples] , [xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/xorriso-tcltk)
[http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES cdrskin examples] , demonstrates this approach. It is part of the
[http://libburnia-project.org/browser/libburn/trunk/test/libburner.c libburner.c a minimal but complete burn program] libisoburn release tarball and of the GNU xorriso tarball.
(also illustrated at the end of [http://api.libburnia-project.org/libburn/ libburn API intro]).
The known existing GUIs
[Xfburn](http://goodies.xfce.org/projects/applications/xfburn),
===== What personalities are supported by xorriso ? ===== #xorriso_aliases [Brasero](http://projects.gnome.org/brasero/),
[FlBurn](http://flburn.sourceforge.net/)
The name by which xorriso is started may trigger certain features which rather use libisofs and libburn directly.
normally would need to be enabled by program options. (Please submit an URI if you want your libburnia GUI application mentioned
here.)
xorrisofs starts up in mkisofs emulation mode, which otherwise would have to
be entered by command -as "mkisofs". ----------------------------------------------------------------------------
### Miscellaneous
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 ##### Where to see examples ? <A NAME="example_links">
tracks in one session.
[xorriso examples](http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES) ,
osirrox allows to copy files from ISO image to disk and to apply option -mount [cdrskin examples](http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES) ,
to one or more of the existing ISO sessions. This is normally enabled by [libburner.c a minimal but complete burn program](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/test/libburner.c).
option -osirrox "on:o_excl_off".
===== What is xorriso dialog mode useful for ? ===== #xorriso_dialog_mode ##### What personalities are supported by xorriso ? <A NAME="xorriso_aliases">
Dialog mode is initiated if -dialog "on" is among the program arguments. The name by which xorriso is started may trigger certain features which
It can be used to inspect and exploit existing ISO 9660 images or normally would need to be enabled by program options.
to explore xorriso's behavior in order to develop the command sequence
for a batch run. xorrisofs starts up in mkisofs emulation mode, which otherwise would have to
be entered by command `-as mkisofs`.
Frontend programmers may fork xorriso initiating a xorriso dialog session
(-dialog "on" -use_readline "off" -pkt_output "on" -mark "done"), xorrecord starts up in cdrecord emulation mode, which is normally entered by
and interact with it from their own program via pipes connected to command `-as cdrecord`. This emulation is only able to write a single data
xorriso's stdin and stdout. This is more efficient than forking xorriso track as new session to blank or appendable media. No audio. No multiple
every now and then to perform various commands in order to complete tracks in one session.
complex tasks like image size prediction.
osirrox can copy files from ISO image to disk and to apply option -mount
The script to one or more of the existing ISO sessions. This is normally enabled by
[http://libburnia-project.org/browser/libisoburn/trunk/frontend/xorriso-tcltk xorriso-tcltk] option `-osirrox on:o_excl_off`.
demonstrates this approach. It is part of the
libisoburn release tarball and of the GNU xorriso tarball. ##### What is xorriso dialog mode useful for ? <A NAME="xorriso_dialog_mode">
===== Why is every second release missing ? ===== #version_numbers 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
Releases have an even third version number. Like 0.5.6 or 1.0.4. to explore xorriso's behavior in order to develop the command sequence
During development the next higher odd number is used. E.g. 0.5.7 or 1.0.5. for a batch run.
The content of release tarballs does not get changed without changing Frontend programmers may fork xorriso initiating a xorriso dialog session
their name. The development tarballs of xorriso and cdrskin may change (`-dialog on -use_readline off -pkt_output on -mark done`),
their content without notice. 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
Site maintainer: Do not edit this wiki directly but rather the SVN version complex tasks like image size prediction.
of libisoburn/trunk/doc/faq.wiki. When done, paste it into the wiki editor.
The script
[xorriso-tcltk](https://dev.lovelyhq.com/libburnia/libisoburn/raw/HEAD/frontend/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 ? <A NAME="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 git version
of `libisoburn/doc/faq.wiki`. When done, paste it into the wiki editor.

View File

@ -6,7 +6,7 @@ Thus it marks a small part of the device as unclaimed by partitions and
available for storing boot loader code. available for storing boot loader code.
Nevertheless the USB stick is mountable via its overall device file as well as Nevertheless the USB stick is mountable via its overall device file as well as
via the partition device file. E.g. on GNU/Linux: /dev/sdb and /dev/sdb1. via the partition device file. E.g. on GNU/Linux: `/dev/sdb` and `/dev/sdb1`.
This is achieved by two distinct sets of meta-data which refer to the same This is achieved by two distinct sets of meta-data which refer to the same
file content. file content.
@ -19,21 +19,15 @@ extend the unclaimed area into vital blocks of the ISO image.
-------------------------------------------------------------------------- --------------------------------------------------------------------------
Meanwhile Debian
[http://cdimage.debian.org/cdimage/daily-builds/daily/current/ daily]
and [http://cdimage.debian.org/cdimage/weekly-builds/ weekly] builds make
use of this feature with their bootable ISO images for i386. E.g.
[http://cdimage.debian.org/cdimage/daily-builds/daily/current/i386/iso-cd/debian-testing-i386-netinst.iso debian-testing-i386-netinst.iso].
According to a According to a
[http://syslinux.zytor.com/archives/2011-March/016201.html thread of march 2011] [thread of march 2011](http://www.syslinux.org/archives/2011-March/016527.html)
on Syslinux mailing list this enabled booting of a Kontron CG2100 server on Syslinux mailing list this enabled booting of a Kontron CG2100 server
from USB stick, which otherwise failed. from USB stick, which otherwise failed.
Regrettably the feature seems to prevent mounting of ISO 9660 images on Regrettably the feature seems to prevent mounting of ISO 9660 images on
Apple "Snow Leopard" systems. Apple "Snow Leopard" systems.
At least this is the outcome of a At least this is the outcome of a
[http://lists.debian.org/debian-cd/2011/04/msg00029.html debian-cd thread of april 2011]. [debian-cd thread of april 2011](http://lists.debian.org/debian-cd/2011/04/msg00029.html).
-------------------------------------------------------------------------- --------------------------------------------------------------------------
@ -46,33 +40,33 @@ Overview:
The test image was derived from one year old RIPLinux-9.3-non-X.iso which The test image was derived from one year old RIPLinux-9.3-non-X.iso which
has an isohybrid MBR. Syslinux version seems to be 3.82. That MBR and the file has an isohybrid MBR. Syslinux version seems to be 3.82. That MBR and the file
tree from the mounted RIPLinux image was used to build a new ISO image tree from the mounted RIPLinux image was used to build a new ISO image
with 16 * 2kB partition offset. Isohybrid MBR patching was done by xorriso. with 16 \* 2kB partition offset. Isohybrid MBR patching was done by xorriso.
Details: Details:
The first 32 kB of an ISO 9660 image are called System Area and may host any The first 32 kB of an ISO 9660 image are called System Area and may host any
byte pattern. The first 512 bytes of RIPLinux-9.3-non-X.iso contain the byte pattern. The first 512 bytes of RIPLinux-9.3-non-X.iso contain the
isohybrid capable MBR, which will be re-used in this example. isohybrid capable MBR, which will be re-used in this example.
{{{ ```
dd if=RIPLinux-9.3-non-X.iso bs=512 count=1 of=RIPLinux-9.3-non-X.mbr dd if=RIPLinux-9.3-non-X.iso bs=512 count=1 of=RIPLinux-9.3-non-X.mbr
}}} ```
Normally the isohybrid MBR is provided by the Syslinux Normally the isohybrid MBR is provided by the Syslinux
installation under the name isohdp[fp]x*.bin . installation under the name `isohdp[fp]x*.bin` .
E.g. /usr/lib/syslinux/isohdpfx.bin E.g. `/usr/lib/syslinux/isohdpfx.bin`
The files of the image are made accessible for reading The files of the image are made accessible for reading
{{{ ```
mount -o loop RIPLinux-9.3-non-X.iso /mnt mount -o loop RIPLinux-9.3-non-X.iso /mnt
}}} ```
A new ISO image gets composed. The first three lines of arguments are taken A new ISO image gets composed. The first three lines of arguments are taken
from the prescriptions of ISOLINUX wiki and adapted to the names used in from the prescriptions of ISOLINUX wiki and adapted to the names used in
RIPLinux-9.3-non-X.iso. RIPLinux-9.3-non-X.iso.
Option -isohybrid-mbr imports the copied MBR and patches it Option `-isohybrid-mbr` imports the copied MBR and patches it
according to rules published by hpa on Syslinux mailing list. according to rules published by hpa on Syslinux mailing list.
Option -partition_offset 16 causes the first partition to start at 2 kB block Option `-partition_offset 16` causes the first partition to start at 2 kB block
number 16. It also prepares the image to be mountable by this partition, too. number 16. It also prepares the image to be mountable by this partition, too.
{{{ ```
xorriso -as mkisofs \ xorriso -as mkisofs \
-o new_image.iso \ -o new_image.iso \
-b boot/isolinux/isolinux.bin -c boot/boot.cat \ -b boot/isolinux/isolinux.bin -c boot/boot.cat \
@ -80,80 +74,80 @@ number 16. It also prepares the image to be mountable by this partition, too.
-isohybrid-mbr RIPLinux-9.3-non-X.mbr \ -isohybrid-mbr RIPLinux-9.3-non-X.mbr \
-partition_offset 16 \ -partition_offset 16 \
/mnt /mnt
}}} ```
The image was copied onto a USB stick The image was copied onto a USB stick
{{{ ```
dd if=new_image.iso of=/dev/sdc dd if=new_image.iso of=/dev/sdc
}}} ```
and plugged into a Debian system. and plugged into a Debian system.
{{{ ```
fdisk -lu /dev/sdb fdisk -lu /dev/sdb
}}} ```
yields yields
{{{ ```
Device Boot Start End Blocks Id System Device Boot Start End Blocks Id System
/dev/sdb1 * 64 120831 60384 17 Hidden HPFS/NTFS /dev/sdb1 * 64 120831 60384 17 Hidden HPFS/NTFS
}}} ```
I can mount /dev/sdb and /dev/sdb1 alike: I can mount `/dev/sdb` and `/dev/sdb1` alike:
{{{ ```
mount /dev/sdb1 /mnt1 mount /dev/sdb1 /mnt1
mount -o loop /dev/sdb /mnt mount -o loop /dev/sdb /mnt
}}} ```
-o loop avoids failure with "mount: /dev/sdb already mounted or /mnt busy". `-o loop` avoids failure with "mount: /dev/sdb already mounted or /mnt busy".
A comparison by A comparison by
{{{ ```
diff -r /mnt /mnt1 diff -r /mnt /mnt1
}}} ```
reports no difference. reports no difference.
Human readable files look ok. Human readable files look ok.
Test-reading all content by Test-reading all content by
{{{ ```
tar cf - /mnt | wc tar cf - /mnt | wc
}}} ```
yields a reasonable byte count of 60743680 and no errors. yields a reasonable byte count of 60743680 and no errors.
The machine boots RIPLinux from this USB stick with no visible problems. The machine boots RIPLinux from this USB stick with no visible problems.
It can then mount /dev/sdb as well as /dev/sdb1. It can then mount `/dev/sdb` as well as `/dev/sdb1`.
The ISO image boots from CD too. The ISO image boots from CD too.
Mounting the partition can be simulated with an image file on hard disk by Mounting the partition can be simulated with an image file on hard disk by
cutting off the first partition_offset blocks of 2 KB: cutting off the first partition_offset blocks of 2 KB:
{{{ ```
dd if=new_image.iso of=partition_image.iso bs=2048 skip=16 dd if=new_image.iso of=partition_image.iso bs=2048 skip=16
mount -o loop partition_image.iso /mnt1 mount -o loop partition_image.iso /mnt1
}}} ```
-------------------------------------------------------------------------- --------------------------------------------------------------------------
Another test was made with GRUB 2 by downloading Another test was made with GRUB 2 by downloading
{{{ ```
bzr branch http://bzr.savannah.gnu.org/r/grub/trunk/grub bzr branch http://bzr.savannah.gnu.org/r/grub/trunk/grub
}}} ```
Before building GRUB 2, the file Before building GRUB 2, the file
{{{ ```
util/grub-mkrescue.in util/grub-mkrescue.in
}}} ```
was edited to replace in the options of the xorriso command: was edited to replace in the options of the xorriso command:
{{{ ```
--protective-msdos-label --protective-msdos-label
}}} ```
by by
{{{ ```
-partition_offset 16 -no-pad -partition_offset 16 -no-pad
}}} ```
Then GRUB 2 was built and installed. Then GRUB 2 was built and installed.
The resulting image from The resulting image from
{{{ ```
./grub-mkrescue -o image.iso ./grub-mkrescue -o image.iso
}}} ```
was put onto USB stick. It passed the same tests on Debian was put onto USB stick. It passed the same tests on Debian
as above RIPLinux example. It boots to a GRUB prompt. as above RIPLinux example. It boots to a GRUB prompt.
Due to option -no-pad the image is about 250 kB smaller than Due to option `-no-pad` the image is about 250 kB smaller than
the image produced by original grub-mkrescue. Else it would have grown by the image produced by original `grub-mkrescue`. Else it would have grown by
about 50 kB. about 50 kB.
Unpadded ISO images are safe except for burning on CD in TAO mode. Unpadded ISO images are safe except for burning on CD in TAO mode.
@ -163,11 +157,11 @@ require padding by 300 kB.
Burning on DVD or BD needs no such caution. Neither does copying Burning on DVD or BD needs no such caution. Neither does copying
on USB stick or hard disk. on USB stick or hard disk.
Program fdisk will complain about "different physical/logical" addresses. Program `fdisk` will complain about "different physical/logical" addresses.
This can be silenced by adding option This can be silenced by adding option
{{{ ```
-partition_cyl_align on -partition_cyl_align on
}}} ```
at the cost of image padding up to the next full MB. at the cost of image padding up to the next full MB.
E.g. by 402 kB to 2 MB. E.g. by 402 kB to 2 MB.
@ -187,7 +181,7 @@ preparations.
Application: Application:
The partition offset feature can be controlled by libisofs API calls The partition offset feature can be controlled by libisofs API calls
{{{ ```
int iso_write_opts_set_part_offset(IsoWriteOpts *opts, int iso_write_opts_set_part_offset(IsoWriteOpts *opts,
uint32_t block_offset_2k, uint32_t block_offset_2k,
int secs_512_per_head, int secs_512_per_head,
@ -195,9 +189,9 @@ int iso_write_opts_set_part_offset(IsoWriteOpts *opts,
int iso_write_opts_set_system_area(IsoWriteOpts *opts, char data[32768], int iso_write_opts_set_system_area(IsoWriteOpts *opts, char data[32768],
int options, int flag); int options, int flag);
}}} ```
or by libisoburn calls or by libisoburn calls
{{{ ```
int isoburn_igopt_set_part_offset(struct isoburn_imgen_opts *opts, int isoburn_igopt_set_part_offset(struct isoburn_imgen_opts *opts,
uint32_t block_offset_2k, uint32_t block_offset_2k,
int secs_512_per_head, int heads_per_cyl); int secs_512_per_head, int heads_per_cyl);
@ -211,9 +205,9 @@ int isoburn_igopt_set_system_area(struct isoburn_imgen_opts *o,
int isoburn_igopt_get_system_area(struct isoburn_imgen_opts *o, int isoburn_igopt_get_system_area(struct isoburn_imgen_opts *o,
char data[32768], int *options); char data[32768], int *options);
}}} ```
or by xorriso options or by xorriso options
{{{ ```
-boot_image any partition_offset=(2kb_block_adr) -boot_image any partition_offset=(2kb_block_adr)
-boot_image any partition_sec_hd=(number) -boot_image any partition_sec_hd=(number)
-boot_image any partition_hd_cyl=(number) -boot_image any partition_hd_cyl=(number)
@ -223,7 +217,7 @@ or by xorriso options
-partition_hd_cyl (number) \ -partition_hd_cyl (number) \
-partition_sec_hd (number) \ -partition_sec_hd (number) \
-partition_cyl_align (on|auto|off) ... -partition_cyl_align (on|auto|off) ...
}}} ```
As stated above, an offset larger than 16 would expose vital parts of the As stated above, an offset larger than 16 would expose vital parts of the
ISO image as unclaimed space. Values smaller than 16 are not accepted. ISO image as unclaimed space. Values smaller than 16 are not accepted.

View File

@ -7,12 +7,12 @@ The options follow proposals of Paolo Bonzini on qemu-devel mailing list.
My compliments for his patient guidance. My compliments for his patient guidance.
Basic knowledge about Debian and qemu was learned from Basic knowledge about Debian and qemu was learned from
[http://www.gnu.org/s/hurd/hurd/running/qemu.html GNU Hurd qemu page]. [GNU Hurd qemu page](http://www.gnu.org/s/hurd/hurd/running/qemu.html GNU Hurd qemu page).
---------------------------------------------------------------------- ----------------------------------------------------------------------
This start command works with qemu-1.0-rc3: This start command works with `qemu-1.0-rc3`:
{{{ ```
$ qemu \ $ qemu \
-enable-kvm \ -enable-kvm \
-nographic \ -nographic \
@ -23,11 +23,11 @@ This start command works with qemu-1.0-rc3:
-drive file=/dev/sr0,if=none,id=scsicd,format=raw \ -drive file=/dev/sr0,if=none,id=scsicd,format=raw \
-device virtio-blk-pci,drive=scsicd,logical_block_size=2048,physical_block_size=2048 \ -device virtio-blk-pci,drive=scsicd,logical_block_size=2048,physical_block_size=2048 \
-cdrom .../some_image.iso -cdrom .../some_image.iso
}}} ```
This start command works with qemu-2.1.2: This start command works with `qemu-2.1.2`:
{{{ ```
$ qemu \ $ qemu \
-enable-kvm \ -enable-kvm \
-nographic \ -nographic \
@ -37,23 +37,23 @@ This start command works with qemu-2.1.2:
-hda /dvdbuffer/i386-install.qemu \ -hda /dvdbuffer/i386-install.qemu \
-cdrom .../some_image.iso \ -cdrom .../some_image.iso \
-drive file=/dev/sr0,index=2,if=virtio -drive file=/dev/sr0,index=2,if=virtio
}}} ```
With these setups of -drive and -device it is necessary to have a With these setups of `-drive` and `-device` it is necessary to have a
medium in the drive, when qemu gets started. Else it will refuse. medium in the drive, when qemu gets started. Else it will refuse.
The guest system is accessible via ssh and scp at port 5557 of the The guest system is accessible via ssh and scp at port 5557 of the
host system. host system.
'''/dev/sr0''' is the address of the DVD drive which is handed over to the `/dev/sr0` is the address of the DVD drive which is handed over to the
guest system. guest system.
'''.../some_image.iso''' may be any readable file which shall serve as `.../some_image.iso` may be any readable file which shall serve as
virtual DVD-ROM. qemu is not happy without such a thing. virtual DVD-ROM. qemu is not happy without such a thing.
'''/dvdbuffer/i386-install.qemu''' is the disk image, where the guest operating `/dvdbuffer/i386-install.qemu` is the disk image, where the guest operating
system was installed by: system was installed by:
{{{ ```
$ qemu-img create /dvdbuffer/i386-install.qemu 8G $ qemu-img create /dvdbuffer/i386-install.qemu 8G
$ qemu \ $ qemu \
-enable-kvm \ -enable-kvm \
@ -62,92 +62,92 @@ system was installed by:
-hda /dvdbuffer/i386-install.qemu \ -hda /dvdbuffer/i386-install.qemu \
-cdrom debian-6.0.3-i386-netinst.iso \ -cdrom debian-6.0.3-i386-netinst.iso \
-boot d -boot d
}}} ```
Host system of my qemu-1.0-rc3 test is Debian GNU/Linux 6.0.2 amd64. Host system of my `qemu-1.0-rc3` test is Debian GNU/Linux 6.0.2 amd64.
With qemu-2.1.2 it is Debian 8.1 amd64. With `qemu-2.1.2` it is Debian 8.1 amd64.
Both had access to the Internet when the guest was installed. Both had access to the Internet when the guest was installed.
---------------------------------------------------------------------- ----------------------------------------------------------------------
Preparations on guest system Debian GNU/Linux 6.0.3 i386 Preparations on guest system Debian GNU/Linux 6.0.3 i386
There appears no /dev/sr for the passthrough drive. Thus libburn will not There appears no `/dev/sr` for the passthrough drive. Thus libburn will not
list it by its drive search function. One may use it nevertheless. But list it by its drive search function. One may use it nevertheless. But
xorriso will only do so if prefix "mmc:" is used with the address: xorriso will only do so if prefix "mmc:" is used with the address:
{{{ ```
-dev mmc:/dev/vda -dev mmc:/dev/vda
}}} ```
The drive will be listed by libburn if there is a symbolic link /dev/sr* The drive will be listed by libburn if there is a symbolic link `/dev/sr*`
pointing to it. On Debian 6, this link persists only if it is created pointing to it. On Debian 6, this link persists only if it is created
by an udev rule. by an udev rule.
In /lib/udev/rules.d/50-udev-default.rules: In `/lib/udev/rules.d/50-udev-default.rules`:
{{{ ```
KERNEL=="vda", SYMLINK+="sr1" KERNEL=="vda", SYMLINK+="sr1"
}}} ```
libburn on Linux needs rw-permission for the drive's device node. libburn on Linux needs rw-permission for the drive's device node.
The virtual device /dev/vda is in group "disk". Usual for CD drives is The virtual device `/dev/vda` is in group "disk". Usual for CD drives is
group "cdrom", to which i (or the Debian installer ?) have added my group "cdrom", to which i (or the Debian installer ?) have added my
normal user when i installed the guest system. normal user when i installed the guest system.
Like with the symbolic link, such a change persists on Debian 6 only as Like with the symbolic link, such a change persists on Debian 6 only as
udev rule. udev rule.
In /lib/udev/rules.d/91-permissions.rules: In `/lib/udev/rules.d/91-permissions.rules`:
{{{ ```
KERNEL=="vda", GROUP="cdrom" KERNEL=="vda", GROUP="cdrom"
}}} ```
This should yield This should yield
{{{ ```
lrwxrwxrwx 1 root root 3 Nov 8 11:19 /dev/sr1 -> vda lrwxrwxrwx 1 root root 3 Nov 8 11:19 /dev/sr1 -> vda
brw-rw---- 1 root cdrom 254, 0 Nov 8 11:19 /dev/vda brw-rw---- 1 root cdrom 254, 0 Nov 8 11:19 /dev/vda
}}} ```
xorriso version must be >= 1.1.8 xorriso version must be >= 1.1.8
{{{ ```
$ xorriso -version $ xorriso -version
}}} ```
tells the versions of its components on stdout: tells the versions of its components on stdout:
{{{ ```
... ...
xorriso version : 1.1.8 xorriso version : 1.1.8
... ...
}}} ```
If your distro's xorriso is too old, consider to get and build GNU xorriso. If your distro's xorriso is too old, consider to get and build GNU xorriso.
{{{ ```
http://ftpmirror.gnu.org/xorriso/xorriso-1.1.8.tar.gz http://ftpmirror.gnu.org/xorriso/xorriso-1.1.8.tar.gz
}}} ```
Do Do
{{{ ```
$ tar xzf xorriso-1.1.8.tar.gz $ tar xzf xorriso-1.1.8.tar.gz
$ cd xorriso-1.1.8 $ cd xorriso-1.1.8
$ ./configure && make $ ./configure && make
}}} ```
Either do as superuser Either do as superuser
{{{ ```
# make install # make install
}}} ```
or execute it where it was built as or execute it where it was built as
{{{ ```
$ ./xorriso/xorriso ...arguments... $ ./xorriso/xorriso ...arguments...
}}} ```
After compilation, this binary does not depend on files in the build After compilation, this binary does not depend on files in the build
directory. You may move it to any other location. directory. You may move it to any other location.
For details about the following xorriso commands, read For details about the following xorriso commands, read
{{{ ```
man xorriso man xorriso
man ./xorriso/xorriso.1 man ./xorriso/xorriso.1
}}} ```
or with the same content or with the same content
{{{ ```
info xorriso info xorriso
info ./xorriso/xorriso.info info ./xorriso/xorriso.info
}}} ```
Or read the [http://scdbackup.sourceforge.net/man_1_xorriso_devel.html online man page of xorriso]. Or read the [online man page of xorriso](http://scdbackup.sourceforge.net/man_1_xorriso_devel.html).
Note that the sequence of xorriso arguments matters. They are commands Note that the sequence of xorriso arguments matters. They are commands
@ -158,20 +158,20 @@ sequence.
Writing happens automatically if ISO filetree changes are pending Writing happens automatically if ISO filetree changes are pending
at the end of the program run. This is like with other burn tools. at the end of the program run. This is like with other burn tools.
(There is a command -commit for intermediate writing e.g. in dialog (There is a command `-commit` for intermediate writing e.g. in dialog
mode.) mode.)
---------------------------------------------------------------------- ----------------------------------------------------------------------
Listing accessible drives: Listing accessible drives:
{{{ ```
$ xorriso -devices $ xorriso -devices
}}} ```
shows on stdout: shows on stdout:
{{{ ```
0 -dev '/dev/sr0' rwrw-- : 'QEMU ' 'QEMU DVD-ROM' 0 -dev '/dev/sr0' rwrw-- : 'QEMU ' 'QEMU DVD-ROM'
1 -dev '/dev/sr1' rwrw-- : 'Optiarc ' 'BD RW BD-5300S' 1 -dev '/dev/sr1' rwrw-- : 'Optiarc ' 'BD RW BD-5300S'
}}} ```
---------------------------------------------------------------------- ----------------------------------------------------------------------
@ -182,11 +182,11 @@ See "Other applicable media types:" further below.
---------------------------------------------------------------------- ----------------------------------------------------------------------
Inspecting drive and medium: Inspecting drive and medium:
{{{ ```
$ xorriso -outdev /dev/sr1 -toc $ xorriso -outdev /dev/sr1 -toc
}}} ```
should show on stdout something like should show on stdout something like
{{{ ```
Drive current: -dev '/dev/sr1' Drive current: -dev '/dev/sr1'
Drive type : vendor 'Optiarc' product 'BD RW BD-5300S' revision '1.04' Drive type : vendor 'Optiarc' product 'BD RW BD-5300S' revision '1.04'
Media current: DVD-RW sequential recording Media current: DVD-RW sequential recording
@ -198,7 +198,7 @@ should show on stdout something like
ISO session : 2 , 135536 , 108385s , ISOIMAGE ISO session : 2 , 135536 , 108385s , ISOIMAGE
ISO session : 3 , 250240 , 56202s , ISOIMAGE ISO session : 3 , 250240 , 56202s , ISOIMAGE
Media summary: 3 sessions, 271744 data blocks, 531m data, 0 free Media summary: 3 sessions, 271744 data blocks, 531m data, 0 free
}}} ```
---------------------------------------------------------------------- ----------------------------------------------------------------------
@ -207,11 +207,11 @@ Blanking to single session capability:
This medium has to be blanked before further writing. For the DAO This medium has to be blanked before further writing. For the DAO
test, one can save time by fast blanking, which xorriso normally test, one can save time by fast blanking, which xorriso normally
dislikes because the result is not capable of multi-session: dislikes because the result is not capable of multi-session:
{{{ ```
$ xorriso -outdev /dev/sr1 -blank deformat_quickest $ xorriso -outdev /dev/sr1 -blank deformat_quickest
}}} ```
should report on stderr should report on stderr
{{{ ```
... ...
xorriso : UPDATE : Blanking ( 1.0% done in 2 seconds ) xorriso : UPDATE : Blanking ( 1.0% done in 2 seconds )
... ...
@ -221,7 +221,7 @@ should report on stderr
Media current: DVD-RW sequential recording Media current: DVD-RW sequential recording
Media status : is blank Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 4489m free Media summary: 0 sessions, 0 data blocks, 0 data, 4489m free
}}} ```
Do not worry if the pacifier messages show no neat percentage progress. Do not worry if the pacifier messages show no neat percentage progress.
Some drives report "1.0%" until they are done. Some report "1.0%" Some drives report "1.0%" until they are done. Some report "1.0%"
after "99%". after "99%".
@ -230,14 +230,14 @@ after "99%".
Writing a DAO session: Writing a DAO session:
Use one or more moderately sized directories as input. Here: /usr/bin. Use one or more moderately sized directories as input. Here: `/usr/bin`.
Terminate the list of -add arguments by argument "--". Terminate the list of `-add` arguments by argument `--`.
It is important to have command -close "on" among the arguments. It is important to have command `-close on` among the arguments.
{{{ ```
$ xorriso -md5 on -outdev /dev/sr1 -close on -add /usr/bin -- $ xorriso -md5 on -outdev /dev/sr1 -close on -add /usr/bin --
}}} ```
should report on stderr should report on stderr
{{{ ```
... ...
xorriso : UPDATE : 594 files added in 1 seconds xorriso : UPDATE : 594 files added in 1 seconds
... ...
@ -252,7 +252,7 @@ should report on stderr
ISO image produced: 52735 sectors ISO image produced: 52735 sectors
Written to media : 52885 sectors at LBA 0 Written to media : 52885 sectors at LBA 0
Writing to '/dev/sr1' completed successfully. Writing to '/dev/sr1' completed successfully.
}}} ```
Do not worry if there is no progress to see for a few dozen seconds Do not worry if there is no progress to see for a few dozen seconds
at the beginning. at the beginning.
The run will last at least as long as writing of 1 GB would need. The run will last at least as long as writing of 1 GB would need.
@ -262,14 +262,14 @@ messages at the end of writing.
---------------------------------------------------------------------- ----------------------------------------------------------------------
Checkreading the result: Checkreading the result:
{{{ ```
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / -- $ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
}}} ```
The word "sorry" sets the severity class of the event message, which is The word "sorry" sets the severity class of the event message, which is
emitted in case of MD5 mismatch. (See man xorriso, "Exception processing".) emitted in case of MD5 mismatch. (See man xorriso, "Exception processing".)
This should report on stderr This should report on stderr
{{{ ```
... ...
Drive current: -indev '/dev/sr1' Drive current: -indev '/dev/sr1'
Media current: DVD-RW sequential recording Media current: DVD-RW sequential recording
@ -281,11 +281,11 @@ This should report on stderr
... ...
xorriso : UPDATE : 103.7m content bytes read in 35 seconds xorriso : UPDATE : 103.7m content bytes read in 35 seconds
File contents and their MD5 checksums match. File contents and their MD5 checksums match.
}}} ```
and the exit value should be 0, if no mismatch was reported. and the exit value should be 0, if no mismatch was reported.
A mismatch message would look like A mismatch message would look like
{{{ ```
... ...
MD5 MISMATCH: '/usr/bin/ncursesw5-config' MD5 MISMATCH: '/usr/bin/ncursesw5-config'
... ...
@ -293,22 +293,22 @@ A mismatch message would look like
xorriso : SORRY : Event triggered by MD5 comparison mismatch xorriso : SORRY : Event triggered by MD5 comparison mismatch
xorriso : NOTE : Tolerated problem event of severity 'SORRY' xorriso : NOTE : Tolerated problem event of severity 'SORRY'
xorriso : NOTE : -return_with SORRY 32 triggered by problem severity SORRY xorriso : NOTE : -return_with SORRY 32 triggered by problem severity SORRY
}}} ```
and the exit value would be non-zero. and the exit value would be non-zero.
---------------------------------------------------------------------- ----------------------------------------------------------------------
Blanking to multi-session capability: Blanking to multi-session capability:
{{{ ```
$ xorriso -outdev /dev/sr1 -blank as_needed $ xorriso -outdev /dev/sr1 -blank as_needed
}}} ```
This will need as long as writing the DVD-RW up to its end. This will need as long as writing the DVD-RW up to its end.
Blanking option "as_needed" lets xorriso decide what to do in order Blanking option `as_needed` lets xorriso decide what to do in order
to make the medium writable from scratch. With DVD-RW it will decide for to make the medium writable from scratch. With DVD-RW it will decide for
-blank "all". `-blank all`.
The report on stderr should end by The report on stderr should end by
{{{ ```
... ...
xorriso : UPDATE : Blanking ( 98.9% done in 902 seconds ) xorriso : UPDATE : Blanking ( 98.9% done in 902 seconds )
xorriso : UPDATE : Blanking ( 99.0% done in 903 seconds ) xorriso : UPDATE : Blanking ( 99.0% done in 903 seconds )
@ -319,15 +319,15 @@ The report on stderr should end by
Media current: DVD-RW sequential recording Media current: DVD-RW sequential recording
Media status : is blank Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 4489m free Media summary: 0 sessions, 0 data blocks, 0 data, 4489m free
}}} ```
---------------------------------------------------------------------- ----------------------------------------------------------------------
Writing multiple sessions (DVD-RW write type Incremental): Writing multiple sessions (DVD-RW write type Incremental):
This time do not perform command -close "on", so that the medium This time do not perform command `-close on`, so that the medium
stays writable: stays writable:
{{{ ```
$ xorriso -md5 on -dev /dev/sr1 -add /usr/lib -- $ xorriso -md5 on -dev /dev/sr1 -add /usr/lib --
... ...
xorriso : UPDATE : Writing: 105280s 98.6% fifo 0% buf 77% 3.5xD xorriso : UPDATE : Writing: 105280s 98.6% fifo 0% buf 77% 3.5xD
@ -338,40 +338,40 @@ stays writable:
ISO image produced: 106646 sectors ISO image produced: 106646 sectors
Written to media : 106800 sectors at LBA 0 Written to media : 106800 sectors at LBA 0
Writing to '/dev/sr1' completed successfully. Writing to '/dev/sr1' completed successfully.
}}} ```
Checkread like after the DAO test: Checkread like after the DAO test:
{{{ ```
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / -- $ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
... ...
xorriso : UPDATE : 204.0m content bytes read in 63 seconds xorriso : UPDATE : 204.0m content bytes read in 63 seconds
File contents and their MD5 checksums match. File contents and their MD5 checksums match.
}}} ```
Writing the second session looks like the first one. Just use another Writing the second session looks like the first one. Just use another
set of input files to get a visible change in the ISO 9660 file tree: set of input files to get a visible change in the ISO 9660 file tree:
{{{ ```
$ xorriso -md5 on -dev /dev/sr1 -add /usr/bin -- $ xorriso -md5 on -dev /dev/sr1 -add /usr/bin --
... ...
Written to media : 53408 sectors at LBA 135488 Written to media : 53408 sectors at LBA 135488
Writing to '/dev/sr1' completed successfully. Writing to '/dev/sr1' completed successfully.
}}} ```
And checkread the whole tree of files (i.e. both sessions): And checkread the whole tree of files (i.e. both sessions):
{{{ ```
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / -- $ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
... ...
xorriso : UPDATE : 307.8m content bytes read in 89 seconds xorriso : UPDATE : 307.8m content bytes read in 89 seconds
File contents and their MD5 checksums match. File contents and their MD5 checksums match.
}}} ```
At the end of writing a final session, the medium can be closed. At the end of writing a final session, the medium can be closed.
It will not take more writing unless it gets blanked or formatted. It will not take more writing unless it gets blanked or formatted.
So use command -close "on" to demand closing after writing. So use command `-close on` to demand closing after writing.
{{{ ```
$ xorriso -md5 on -dev /dev/sr1 -close on -add /usr/sbin -- $ xorriso -md5 on -dev /dev/sr1 -close on -add /usr/sbin --
... ...
Written to media : 16160 sectors at LBA 195056 Written to media : 16160 sectors at LBA 195056
Writing to '/dev/sr1' completed successfully. Writing to '/dev/sr1' completed successfully.
}}} ```
Checkread Checkread
{{{ ```
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / -- $ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
... ...
Media current: DVD-RW sequential recording Media current: DVD-RW sequential recording
@ -380,25 +380,25 @@ Checkread
... ...
xorriso : UPDATE : 337.7m content bytes read in 97 seconds xorriso : UPDATE : 337.7m content bytes read in 97 seconds
File contents and their MD5 checksums match. File contents and their MD5 checksums match.
}}} ```
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
If the drive tray can move by itself, you may now eject the medium: If the drive tray can move by itself, you may now eject the medium:
{{{ ```
$ xorriso -outdev /dev/sr1 -eject all $ xorriso -outdev /dev/sr1 -eject all
}}} ```
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
Other applicable media types: Other applicable media types:
These test runs for sequential DVD-RW may be performed on CD-RW with the These test runs for sequential DVD-RW may be performed on CD-RW with the
same xorriso arguments. Be aware that /usr/lib will hardly fit on a CD. same xorriso arguments. Be aware that `/usr/lib` will hardly fit on a CD.
So choose smaller directories for CD. So choose smaller directories for CD.
-blank "deformat_quickest" addresses a peculiarity of DVD-RW. `-blank deformat_quickest` addresses a peculiarity of DVD-RW.
It will work on other media like -blank "fast". It will work on other media like `-blank fast`.
Except the blanking runs, the tests may also be performed on BD-R, DVD-R, Except the blanking runs, the tests may also be performed on BD-R, DVD-R,
DVD+R, and CD-R. But you would waste two media by this. DVD+R, and CD-R. But you would waste two media by this.
@ -407,7 +407,7 @@ The first session on CD will always be written with write type SAO,
further sessions will be written with TAO. further sessions will be written with TAO.
CD-R and DVD-R have a simulation mode. It can be enabled by xorriso CD-R and DVD-R have a simulation mode. It can be enabled by xorriso
command -dummy "on", but of course it will not produce readable results. command `-dummy on`, but of course it will not produce readable results.
So this simulation is usable only for first sessions on blank media. So this simulation is usable only for first sessions on blank media.
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
@ -416,7 +416,7 @@ Now for formatted overwritable media:
All blank, write and check runs of above tests "Writing multiple sessions" All blank, write and check runs of above tests "Writing multiple sessions"
may also be performed with DVD+RW, DVD-RAM, formatted DVD-RW, and BD-RE. may also be performed with DVD+RW, DVD-RAM, formatted DVD-RW, and BD-RE.
There is no way to close formatted media. The command -close "on" There is no way to close formatted media. The command `-close on`
gets silently ignored. gets silently ignored.
The write methods and states of formatted media differ from those of The write methods and states of formatted media differ from those of
@ -438,20 +438,20 @@ automatically. Just start a normal write run. DVD-RAM are sold formatted.
xorriso treats overwritable media with a valid ISO 9660 filesystem as xorriso treats overwritable media with a valid ISO 9660 filesystem as
appendable media. To make then writable from scratch, apply appendable media. To make then writable from scratch, apply
-blank "as_needed", which will actually write a few bytes into the PVD `-blank as_needed`, which will actually write a few bytes into the PVD
(superblock) of the ISO filesystem to invalidate it. (superblock) of the ISO filesystem to invalidate it.
De-formatting is only possible with DVD-RW. E.g. by -blank "deformat". De-formatting is only possible with DVD-RW. E.g. by `-blank deformat`.
----------------------------------------------------------------------------- -----------------------------------------------------------------------------
Format DVD-RW for overwriting without intermediate blanking, Format DVD-RW for overwriting without intermediate blanking,
or format BD-R for Defect Management: or format BD-R for Defect Management:
{{{ ```
$ xorriso -outdev /dev/sr1 -format as_needed $ xorriso -outdev /dev/sr1 -format as_needed
}}} ```
should report on stderr should report on stderr
{{{ ```
... ...
xorriso : UPDATE : Formatting ( 99.0% done in 912 seconds ) xorriso : UPDATE : Formatting ( 99.0% done in 912 seconds )
Formatting done Formatting done
@ -460,15 +460,15 @@ should report on stderr
Media current: DVD-RW restricted overwrite Media current: DVD-RW restricted overwrite
Media status : is blank Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 4488m free Media summary: 0 sessions, 0 data blocks, 0 data, 4488m free
}}} ```
As with blanking, one should not worry if the progress messages show As with blanking, one should not worry if the progress messages show
unplausible percentages. Some drives are more equal than others. unplausible percentages. Some drives are more equal than others.
Formatting is said to be much stress to the medium. -format option Formatting is said to be much stress to the medium. `-format` option
"as_needed" applies it only to yet unformatted media. `as_needed` applies it only to yet unformatted media.
When performing above write tests, take care to use -blank "as_needed" When performing above write tests, take care to use `-blank as_needed`
rather than -blank "deformat_quickest". Else you will get a sequential rather than `-blank deformat_quickest`. Else you will get a sequential
unformatted DVD-RW rather than a formatted DVD-RW which xorriso is unformatted DVD-RW rather than a formatted DVD-RW which xorriso is
willing to write from scratch. willing to write from scratch.
There is no use in a separate "DAO" test on overwritable media anyway. There is no use in a separate "DAO" test on overwritable media anyway.
@ -478,12 +478,12 @@ There is no use in a separate "DAO" test on overwritable media anyway.
Change the formatted size of a BD-RE: Change the formatted size of a BD-RE:
First learn about formatted size and proposals of other sizes. First learn about formatted size and proposals of other sizes.
(One can issue own wishes, too. See in man xorriso, command -format.) (One can issue own wishes, too. See in man xorriso, command `-format`.)
{{{ ```
$ xorriso -outdev /dev/sr1 -list_formats $ xorriso -outdev /dev/sr1 -list_formats
}}} ```
should tell on stdout should tell on stdout
{{{ ```
... ...
Format status: formatted, with 23610.0 MiB Format status: formatted, with 23610.0 MiB
BD Spare Area: 0 blocks consumed, 131072 blocks available BD Spare Area: 0 blocks consumed, 131072 blocks available
@ -493,26 +493,26 @@ should tell on stdout
Format idx 3 : 30h , 11564032s , 22586.0 MiB Format idx 3 : 30h , 11564032s , 22586.0 MiB
Format idx 4 : 30h , 12088320s , 23610.0 MiB Format idx 4 : 30h , 12088320s , 23610.0 MiB
Format idx 5 : 31h , 12219392s , 23866.0 MiB Format idx 5 : 31h , 12219392s , 23866.0 MiB
}}} ```
So lets go back from 23610.0 MiB to the default size of 23098.0 MiB So lets go back from 23610.0 MiB to the default size of 23098.0 MiB
{{{ ```
$ xorriso -outdev /dev/sr1 -format by_index_2 -blank as_needed $ xorriso -outdev /dev/sr1 -format by_index_2 -blank as_needed
... ...
Media summary: 2 sessions, 105470 data blocks, 206m data, 22.4g free Media summary: 2 sessions, 105470 data blocks, 206m data, 22.4g free
}}} ```
Although the heads of the old sessions might remain readable after Although the heads of the old sessions might remain readable after
-format, better do not rely on this and a append -blank "as_needed" to `-format`, better do not rely on this and a append `-blank as_needed` to
avoid any data corruption. avoid any data corruption.
If you want to keep the data, then make at least a checkread run. If you want to keep the data, then make at least a checkread run.
Check whether the size has changed: Check whether the size has changed:
{{{ ```
$ xorriso -outdev /dev/sr1 -list_formats $ xorriso -outdev /dev/sr1 -list_formats
}}} ```
should tell on stdout should tell on stdout
{{{ ```
... ...
Format status: formatted, with 23098.0 MiB Format status: formatted, with 23098.0 MiB
BD Spare Area: 0 blocks consumed, 393216 blocks available BD Spare Area: 0 blocks consumed, 393216 blocks available
... ...
}}} ```