libburnia/legacy
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Branching for libisoburn release 1.2.2

Browse Source
This commit is contained in:
Thomas Schmitt
2012-04-02 12:14:07 +00:00
parent bda8d18505
commit 9fe7dde29f
128 changed files with 103117 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

85
libisoburn/branches/1.2.2/doc/comments Normal file
View File

@ -0,0 +1,85 @@
/**
@author Mario Danic, Vreixo Formoso, Thomas Schmitt
@mainpage Libisoburn Documentation Index
@section intro Introduction
Libburnia is an open-source project for reading, mastering and writing
optical discs. This page is about its capability to read, manipulate, and
write ISO 9660 filesystems with Rock Ridge extensions. Media can be optical
media or filesystem objects.
Our scope is currently Linux 2.4 and 2.6, or FreeBSD, or OpenSolaris.
libisoburn is an add-on to libburn and libisofs which coordinates both and
also allows to grow ISO-9660 filesystem images on multi-session media as well
as on overwriteable media via the same API.
All media peculiarities are handled automatically.
xorriso is an application of all three libraries which creates, loads,
manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions.
Manipulation is not only adding or overwriting of files but also deletion,
renaming, and attribute changing. An incremental backup feature is provided.
The xorriso features are accessible via built-in command interpreters and
via a C language API.
SONAME:
libisoburn.so.1 (since 0.1.0, February 2008).
@section using Using the libraries
Our build system is based on autotools.
User experience tells us that you will need at least autotools version 1.7.
To build libisoburn go into its toplevel directory and execute:
- ./bootstrap (needed if you downloaded from SVN)
- ./configure
- make
To make the library and the xorriso application accessible for running resp.
software development:
- make install
For direct use as command line tool use the xorriso binary which among many
other features provides a mkisofs emulation via command "-as mkisofs".
See man page xorriso/xorriso.1 or GNU info document xorriso/xorriso.info.
If you want to link an own application with libisoburn, you have
two alternative APIs for choice:
- libisoburn, together with libburn and libisofs.
- xorriso, a complete representation of xorriso command line options.
It encapsulates the three lower level libraries.
Calls of both API families shall not be mixed.
For a description of the lbisoburn API read libisoburn/libisoburn.h
See file README for download and installation of a release tarball.
You will also have to install and understand the two libraries of the
Libburnia project which provide fundamental services:
libburn is the library by which preformatted data get onto optical media.
See libburn/libburn.h for its API description.
libisofs is the library to handle ISO 9660 filesystems with Rock Ridge
extensions. Its API is described in libisofs/libisofs.h .
For xorriso features see its man page xorriso/xorriso.1 or
its GNU info document xorriso/xorriso.info.
For the corresponding C language API see libisoburn/xorriso.h (resp.
xorriso/xorriso.h in the build directory).
The implementation this API is part of libisoburn.
The xorriso command line tool gets installed as dynamically linked
binary together with libisoburn.
There is also a statically linked release named GNU xorriso.
See xorriso/README_gnu_xorriso for its download and installation.
*/

1294
libisoburn/branches/1.2.2/doc/doxygen.conf.in Normal file
View File

File diff suppressed because it is too large Load Diff

246
libisoburn/branches/1.2.2/doc/faq.wiki Normal file
View File

@ -0,0 +1,246 @@
'''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 How to enable booting from USB stick ?]
[#partition_offset What is partition offset feature all about?]
[#partition_offset_apple Partition offset bad on Apple ?]
Development:
[#api_specs Where are the APIs of libburnia libraries described ?]
[#gui_advise I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ?]
Miscellaneous:
[#example_links Where to see examples ?]
[#xorriso_aliases What personalities are supported by xorriso ?]
[#xorriso_dialog_mode What is xorriso dialog mode useful for ?]
[#version_numbers Why is every second release missing ?]
----------------------------------------------------------------------------
'''Burning'''
----------------------------------------------------------------------------
===== What is the difference between cdrskin and xorriso ? ===== #diff_cdrskin_xorriso
[wiki:Cdrskin cdrskin] is a dedicated emulator of program cdrecord, based on
libburn. It tries to be as similar to cdrecord as is possible under that
premise.
[wiki:Xorriso xorriso] is an integrated tool which creates, loads, manipulates,
and writes ISO 9660 filesystem images with Rock Ridge extensions.
It is based on libburn, libisofs, and libisoburn. One of its features is
the emulation of the corresponding tasks as done by mkisofs and cdrecord.
----------------------------------------------------------------------------
'''Imaging'''
----------------------------------------------------------------------------
===== Is there a way to edit files inside the ISO image ? ===== #edit_files
File content cannot be altered. But files may be replaced by new copies from
the disk filesystem.
The main method of manipulating an existing ISO image is to append a session
with a new complete directory tree and the file content of the added or
overwritten files. Depending on the media type you get gaps between sessions
of up to 20 MB. So better try to do all foreseeable changes by one add-on
session.
===== For which architectures xorriso is able to create bootable images ? ===== #boot_arch
Currently it supports systems with PC-BIOS via El Torito for booting from
CD, DVD, or BD media, and via MBR for booting from memory sticks or hard
disks. Further it supports machines with MIPS processor from SGI (Big Endian)
and DEC (Little Endian), and SUN SPARC machines.
(See [http://bazaar.launchpad.net/%7Elibburnia-team/libisofs/scdbackup/annotate/head%3A/doc/boot_sectors.txt libisofs/doc/boot_sectors.txt]
for technical details.)
Machines which support EFI may either boot via El Torito or use the files
of the ISO image directly. It is possible to append to the ISO image a
writeable FAT12 partition where files for EFI may be stored and changed.
===== How to enable booting from USB stick ? ===== #isohybrid
The ISOLINUX boot loader is normally started from CD, DVD or BD media
by a PC-BIOS via an El Torito boot record. But if the ISO image resides on an
USB stick or another hard-disk-like device, then PC-BIOS ignores El Torito
and rather expects a Master Boot Record (MBR). Both boot record types can
reside in the same ISO image. Therefore it is possible to create an MBR that
starts the boot image file of ISOLINUX which is already target of the El Torito
boot record. This kind of MBR is called "isohybrid". ISOLINUX provides
a program named isohybrid to patch existing images, but libisofs can create an
MBR already when producing the ISO image. See in
[http://www.gnu.org/software/xorriso/man_1_xorriso.html manual page of xorriso]
option -boot_image with arguments "isolinux" "system_area=",
and -as mkisofs option -isohybrid-mbr.
See [http://en.wikipedia.org/wiki/Master_boot_record Wikipedia on MBR] for
general information about PC-DOS Master Boot Records, and
[http://syslinux.zytor.com/wiki/index.php/ISOLINUX ISOLINUX wiki] for special
information about ISOLINUX. The wiki example with mkisofs can be performed
as well by help of xorriso option -as mkisofs.
A similar combination of El Torito and MBR is created by GRUB2 tool
grub-mkrescue. See [http://www.gnu.org/software/grub/ homepage of GNU GRUB 2]
for general information.
===== What is partition offset feature all about? ===== #partition_offset
If an MBR is present, then it contains a partition table with up to four
entries. The MBR is located at the very start of the ISO image. By
tradition the first partition should begin only after the range of MBR and
eventual supporting data blocks. On hard disk one often sees partition 1
starting at byte 63*512. Further it is tradition that the payload filesystem
is mountable via one of the partitions.
The isohybrid MBR has its only partition start at byte 0. Thus it is mountable
but does not obey the tradition to begin only after the MBR. The grub-mkrescue
MBR on the other hand has partition 1 start at byte 512, which makes it
unmountable. Only the unpartitioned base device can be mounted. (On GNU/Linux
e.g. /dev/sdb is the base device whereas /dev/sdb1 is partition 1.)
The compromise offered by libisofs is to create a second superblock at
address 16*2048 and to let start partition 1 at this address. The second
superblock leads to a second directory tree which takes into account the
address difference between partition 1 and the base device. So the image
gets mountable via both devices and reserves 32 kB for boot manager software
where it may manipulate and augment the MBR.
(See [http://libburnia-project.org/wiki/PartitionOffset Partition Offset Wiki]
for examples.)
There are reports of machines which will not boot from USB stick if
partition offset is 0.
===== Partition offset bad on Apple ? ===== #partition_offset_apple
Apple's "Snow Leopard" operating system refuses to mount Debian CD images
with non-zero partition offset.
The issue is still under investigation. But for now one has to choose
between mountability on Apple "Snow Leopard" or bootability from USB stick
on Kontron CG2100 "carrier grade server".
----------------------------------------------------------------------------
'''Developing'''
----------------------------------------------------------------------------
===== Where are the APIs of libburnia libraries described ? ===== #api_specs
The decisive references are the inclusion headers of the libraries
<libburn/libburn.h>, <libisofs/libisofs.h>, <libisoburn/libisoburn.h>,
and <libisoburn/xorriso.h>.
Current SVN versions of these files:
[http://libburnia-project.org/browser/libburn/trunk/libburn/libburn.h libburn/libburn.h] ,
[http://bazaar.launchpad.net/%7Elibburnia-team/libisofs/scdbackup/annotate/head%3A/libisofs/libisofs.h libisofs/libisofs.h] ,
[http://libburnia-project.org/browser/libisoburn/trunk/libisoburn/libisoburn.h libisoburn/libisoburn.h] ,
[http://libburnia-project.org/browser/libisoburn/trunk/xorriso/xorriso.h libisoburn/xorriso.h]
Doxygen generated API descriptions at
[http://api.libburnia-project.org api.libburnia-project.org]
might be slightly behind the latest developments.
===== I want to write a GUI on the top of libburnia libraries. Any pointers or recommendations ? ===== #gui_advise
Most appreciated would be a GUI for xorriso which allows to copy files from
a view of the hard disk filesystem to a view of the ISO filesystem, and vice
versa. The xorriso implementation is located inside libisoburn.
Each option that is described in
[http://www.gnu.org/software/xorriso/man_1_xorriso.html man 1 xorriso]
can be performed by a corresponding C function that is defined in
[http://libburnia-project.org/browser/libisoburn/trunk/xorriso/xorriso.h xorriso.h].
Further there are calls for library startup and shutdown, for problem
handling, and for the interpreters of xorriso's command line interface.
The xorriso API encapsulates calls to libisofs, libburn, and libisoburn.
An alternative to the xorriso C API is xorriso dialog mode.
[#xorriso_dialog_mode See below.]
The known existing GUIs [http://www.xfce.org/projects/xfburn/ Xfburn],
[http://projects.gnome.org/brasero/ Brasero],
[http://flburn.sourceforge.net/ FlBurn]
rather use libisofs and libburn directly.
(Please submit an URI if you want your libburnia GUI application mentioned
here.)
----------------------------------------------------------------------------
'''Miscellaneous'''
----------------------------------------------------------------------------
===== Where to see examples ? ===== #example_links
[http://www.gnu.org/software/xorriso/man_1_xorriso.html#EXAMPLES xorriso examples] ,
[http://scdbackup.sourceforge.net/man_1_cdrskin_devel.html#EXAMPLES cdrskin examples] ,
[http://libburnia-project.org/browser/libburn/trunk/test/libburner.c libburner.c a minimal but complete burn program]
(also illustrated at the end of [http://api.libburnia-project.org/libburn/ libburn API intro]).
===== What personalities are supported by xorriso ? ===== #xorriso_aliases
The name by which xorriso is started may trigger certain features which
normally would need to be enabled by program options.
xorrisofs starts up in mkisofs emulation mode, which otherwise would have to
be entered by command -as "mkisofs".
xorrecord starts up in cdrecord emulation mode, which is normally entered by
command -as "cdrecord". This emulation is only able to write a single data
track as new session to blank or appendable media. No audio. No multiple
tracks in one session.
osirrox allows to copy files from ISO image to disk and to apply option -mount
to one or more of the existing ISO sessions. This is normally enabled by
option -osirrox "on:o_excl_off".
===== What is xorriso dialog mode useful for ? ===== #xorriso_dialog_mode
Dialog mode is initiated if -dialog "on" is among the program arguments.
It can be used to inspect and exploit existing ISO 9660 images or
to explore xorriso's behavior in order to develop the command sequence
for a batch run.
Frontend programmers may fork xorriso initiating a xorriso dialog session
(-dialog "on" -use_readline "off" -pkt_output "on" -mark "done"),
and interact with it from their own program via pipes connected to
xorriso's stdin and stdout. This is more efficient than forking xorriso
every now and then to perform various commands in order to complete
complex tasks like image size prediction.
===== Why is every second release missing ? ===== #version_numbers
Releases have an even third version number. Like 0.5.6 or 1.0.4.
During development the next higher odd number is used. E.g. 0.5.7 or 1.0.5.
The content of release tarballs does not get changed without changing
their name. The development tarballs of xorriso and cdrskin may change
their content without notice.
----------------------------------------------------------------------------
Site maintainer: Do not edit this wiki directly but rather the SVN version
of libisoburn/trunk/doc/faq.wiki. When done, paste it into the wiki editor.

232
libisoburn/branches/1.2.2/doc/partition_offset.wiki Normal file
View File

@ -0,0 +1,232 @@
The partition offset feature of libisofs can produce ISO 9660 images which bear
a quite conventional partition table if copied onto a USB stick. The first
partition marks the size of the ISO image but starts at a non-zero address.
Thus it marks a small part of the device as unclaimed by partitions and
available for storing boot loader code.
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.
This is achieved by two distinct sets of meta-data which refer to the same
file content.
The dual-mount feature supports Rock Ridge and Joliet too.
It is capable of multi-session.
Currently only offset 32 kB seems to make sense. Smaller offsets are prohibited
by fundamental assumptions of libisofs and libisoburn. Larger offsets would
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 and amd64. E.g.
[http://cdimage.debian.org/cdimage/daily-builds/daily/current/i386/iso-cd/debian-testing-i386-businesscard.iso debian-testing-i386-businesscard.iso].
According to a
[http://syslinux.zytor.com/archives/2011-March/016201.html thread of march 2011]
on Syslinux mailing list this enabled booting of a Kontron CG2100 server
from USB stick, which otherwise failed.
Regrettably the feature seems to prevent mounting of ISO 9660 images on
Apple "Snow Leopard" systems.
At least this is the outcome of a
[http://lists.debian.org/debian-cd/2011/04/msg00029.html debian-cd thread of april 2011].
--------------------------------------------------------------------------
Example:
Testing mountability and ISOLINUX bootability from USB stick and CD.
Overview:
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
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.
Details:
The first 32 kB of an ISO 9660 image are called System Area and may host any
byte pattern. In the case of RIPLinux-9.3-non-X.iso only the first 512 bytes
are non-zero. But to avoid any assumptions, all 32 kB get copied here.
{{{
dd if=RIPLinux-9.3-non-X.iso bs=1K count=32 of=RIPLinux-9.3-non-X.sysarea
}}}
Normally the System Area file with its MBR is provided by the Syslinux
installation under the name isohdp[fp]x*.bin .
E.g. /usr/lib/syslinux/isohdpfx.bin
The files of the image are made accessible for reading
{{{
mount -o loop RIPLinux-9.3-non-X.iso /mnt
}}}
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
RIPLinux-9.3-non-X.iso.
Option -isohybrid-mbr imports the copied System Area and patches the MBR
according to rules published by hpa on Syslinux mailing list.
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.
{{{
xorriso -as mkisofs \
-o new_image.iso \
-b boot/isolinux/isolinux.bin -c boot/boot.cat \
-no-emul-boot -boot-load-size 4 -boot-info-table \
-isohybrid-mbr RIPLinux-9.3-non-X.sysarea \
-partition_offset 16 \
/mnt
}}}
The image was copied onto a USB stick
{{{
dd if=new_image.iso of=/dev/sdc
}}}
and plugged into a Debian system.
{{{
fdisk -lu /dev/sdb
}}}
yields
{{{
Device Boot Start End Blocks Id System
/dev/sdb1 * 64 120831 60384 17 Hidden HPFS/NTFS
}}}
I can mount /dev/sdb and /dev/sdb1 alike:
{{{
mount /dev/sdb1 /mnt1
mount -o loop /dev/sdb /mnt
}}}
-o loop avoids failure with "mount: /dev/sdb already mounted or /mnt busy".
A comparison by
{{{
diff -r /mnt /mnt1
}}}
reports no difference.
Human readable files look ok.
Test-reading all content by
{{{
tar cf - /mnt | wc
}}}
yields a reasonable byte count of 60743680 and no errors.
The machine boots RIPLinux from this USB stick with no visible problems.
It can then mount /dev/sdb as well as /dev/sdb1.
The ISO image boots from CD too.
Mounting the partition can be simulated with an image file on hard disk by
cutting off the first partition_offset blocks of 2 KB:
{{{
dd if=new_image.iso of=partition_image.iso bs=2048 skip=16
mount -o loop partition_image.iso /mnt1
}}}
--------------------------------------------------------------------------
Another test was made with GRUB 2 by downloading
{{{
bzr branch http://bzr.savannah.gnu.org/r/grub/trunk/grub
}}}
Before building GRUB 2, the file
{{{
util/grub-mkrescue.in
}}}
was edited to replace in the options of the xorriso command:
{{{
--protective-msdos-label
}}}
by
{{{
-partition_offset 16 -no-pad
}}}
Then GRUB 2 was built and installed.
The resulting image from
{{{
./grub-mkrescue -o image.iso
}}}
was put onto USB stick. It passed the same tests on Debian
as above RIPLinux example. It boots to a GRUB prompt.
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
about 50 kB.
Unpadded ISO images are safe except for burning on CD in TAO mode.
In this case problems may occur with reading the last few data blocks.
So when burning onto CD make sure to require SAO mode and/or to
require padding by 300 kB.
Burning on DVD or BD needs no such caution. Neither does copying
on USB stick or hard disk.
Program fdisk will complain about "different physical/logical" addresses.
This can be silenced by adding option
{{{
-partition_cyl_align on
}}}
at the cost of image padding up to the next full MB.
E.g. by 402 kB to 2 MB.
--------------------------------------------------------------------------
Open questions:
- Shall the partition of an isohybrid image be marked bootable ?
Currently xorriso keeps the 0x80 mark of an imported MBR
resp. the 0x80 mark which xorriso sets by its own MBR
preparations.
- If not to be marked bootable:
What equipment would the partition need to justify having the mark ?
------------------------------------------------------------------------
Application:
The partition offset feature can be controlled by libisofs API calls
{{{
int iso_write_opts_set_part_offset(IsoWriteOpts *opts,
uint32_t block_offset_2k,
int secs_512_per_head,
int heads_per_cyl);
int iso_write_opts_set_system_area(IsoWriteOpts *opts, char data[32768],
int options, int flag);
}}}
resp. by libisoburn calls
{{{
int isoburn_igopt_set_part_offset(struct isoburn_imgen_opts *opts,
uint32_t block_offset_2k,
int secs_512_per_head, int heads_per_cyl);
int isoburn_igopt_get_part_offset(struct isoburn_imgen_opts *opts,
uint32_t *block_offset_2k,
int *secs_512_per_head, int *heads_per_cyl);
int isoburn_igopt_set_system_area(struct isoburn_imgen_opts *o,
char data[32768], int options);
int isoburn_igopt_get_system_area(struct isoburn_imgen_opts *o,
char data[32768], int *options);
}}}
resp. by xorriso options
{{{
-boot_image any partition_offset=(2kb_block_adr)
-boot_image any partition_sec_hd=(number)
-boot_image any partition_hd_cyl=(number)
-boot_image any partition_cyl_align(on|auto|off)
-as mkisofs ... -partition_offset (2kb_block_adr) \
-partition_hd_cyl (number) \
-partition_sec_hd (number) \
-partition_cyl_align (on|auto|off) ...
}}}
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.
So use either an offset of 16 blocks or keep the feature disabled by
offset 0.

503
libisoburn/branches/1.2.2/doc/qemu_xorriso.wiki Normal file
View File

@ -0,0 +1,503 @@
This text describes how to set up a qemu virtual machine so that xorriso
on its guest GNU/Linux can operate a CD, DVD or BD recorder of the host
system.
The options follow proposals of Paolo Bonzini on qemu-devel mailing list.
My compliments for his patient guidance.
Basic knowledge about Debian and qemu was learned from
[http://www.gnu.org/s/hurd/hurd/running/qemu.html GNU Hurd qemu page].
----------------------------------------------------------------------
This start command works with with qemu-1.0-rc3:
{{{
$ qemu \
-enable-kvm \
-nographic \
-m 512 \
-net nic,model=ne2k_pci \
-net user,hostfwd=tcp::5557-:22 \
-hda /dvdbuffer/i386-install.qemu \
-drive file=/dev/sr2,if=none,id=scsicd,format=raw \
-device virtio-blk-pci,drive=scsicd,logical_block_size=2048,physical_block_size=2048 \
-cdrom .../some_image.iso
}}}
With this setup of -drive and -device it is necessary to have a
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
host system.
'''/dev/sr2''' is the address of the DVD drive which is handed over to the
guest system.
'''.../some_image.iso''' may be any readable file which shall serve as
virtual DVD-ROM. qemu is not happy without such a thing.
'''/dvdbuffer/i386-install.qemu''' is the disk image, where the guest operating
system was installed by:
{{{
$ qemu-img create /dvdbuffer/i386-install.qemu 8G
$ qemu \
-enable-kvm \
-m 512 \
-net nic,model=ne2k_pci \
-hda /dvdbuffer/i386-install.qemu \
-cdrom debian-6.0.3-i386-netinst.iso \
-boot d
}}}
Host system of my test is Debian GNU/Linux 6.0.2 amd64,
which had access to the Internet when the guest was installed.
----------------------------------------------------------------------
Preparations on guest system Debian GNU/Linux 6.0.3 i386
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
xorriso will only do so if prefix "mmc:" is used with the address:
{{{
-dev mmc:/dev/vda
}}}
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
by an udev rule.
In /lib/udev/rules.d/50-udev-default.rules:
{{{
KERNEL=="vda", SYMLINK+="sr1"
}}}
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
group "cdrom", to which i (or the Debian installer ?) have added my
normal user when i installed the guest system.
Like with the symbolic link, such a change persists on Debian 6 only as
udev rule.
In /lib/udev/rules.d/91-permissions.rules:
{{{
KERNEL=="vda", GROUP="cdrom"
}}}
This should yield
{{{
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
}}}
xorriso version must be >= 1.1.8
{{{
$ xorriso -version
}}}
tells the versions of its components on stdout:
{{{
...
xorriso version : 1.1.8
...
}}}
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
}}}
Do
{{{
$ tar xzf xorriso-1.1.8.tar.gz
$ cd xorriso-1.1.8
$ ./configure && make
}}}
Either do as superuser
{{{
# make install
}}}
or execute it where it was built as
{{{
$ ./xorriso/xorriso ...arguments...
}}}
After compilation, this binary does not depend on files in the build
directory. You may move it to any other location.
For details about the following xorriso commands, read
{{{
man xorriso
man ./xorriso/xorriso.1
}}}
or with the same content
{{{
info xorriso
info ./xorriso/xorriso.info
}}}
Or read the [http://scdbackup.sourceforge.net/man_1_xorriso_devel.html online man page of xorriso].
Note that the sequence of xorriso arguments matters. They are commands
which get performed one after the other.
This differs from the behavior of mkisofs, cdrecord, et.al.,
which parse all arguments and then perform actions in a hardcoded
sequence.
Writing happens automatically if ISO filetree changes are pending
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
mode.)
----------------------------------------------------------------------
Listing accessible drives:
{{{
$ xorriso -devices
}}}
shows on stdout:
{{{
0 -dev '/dev/sr0' rwrw-- : 'QEMU ' 'QEMU DVD-ROM'
1 -dev '/dev/sr1' rwrw-- : 'Optiarc ' 'BD RW BD-5300S'
}}}
----------------------------------------------------------------------
The burn tests are presented here for unformatted DVD-RW media.
The xorriso commands apply also to other types of optical media.
See "Other applicable media types:" further below.
----------------------------------------------------------------------
Inspecting drive and medium:
{{{
$ xorriso -outdev /dev/sr1 -toc
}}}
should show on stdout something like
{{{
Drive current: -dev '/dev/sr1'
Drive type : vendor 'Optiarc' product 'BD RW BD-5300S' revision '1.04'
Media current: DVD-RW sequential recording
Media product: RITEKW04 , Ritek Corp
Media status : is written , is closed
Media blocks : 306592 readable , 0 writable , 2298496 overall
TOC layout : Idx , sbsector , Size , Volume Id
ISO session : 1 , 0 , 106696s , ISOIMAGE
ISO session : 2 , 135536 , 108385s , ISOIMAGE
ISO session : 3 , 250240 , 56202s , ISOIMAGE
Media summary: 3 sessions, 271744 data blocks, 531m data, 0 free
}}}
----------------------------------------------------------------------
Blanking to single session capability:
This medium has to be blanked before further writing. For the DAO
test, one can save time by fast blanking, which xorriso normally
dislikes because the result is not capable of multi-session:
{{{
$ xorriso -outdev /dev/sr1 -blank deformat_quickest
}}}
should report on stderr
{{{
...
xorriso : UPDATE : Blanking ( 1.0% done in 2 seconds )
...
xorriso : UPDATE : Blanking ( 95.4% done in 36 seconds )
xorriso : UPDATE : Blanking ( 99.0% done in 37 seconds )
...
Media current: DVD-RW sequential recording
Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 4489m free
}}}
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%"
after "99%".
----------------------------------------------------------------------
Writing a DAO session:
Use one or more moderately sized directories as input. Here: /usr/bin.
Terminate the list of -add arguments by argument "--".
It is important to have command -close "on" among the arguments.
{{{
$ xorriso -md5 on -outdev /dev/sr1 -close on -add /usr/bin --
}}}
should report on stderr
{{{
...
xorriso : UPDATE : 594 files added in 1 seconds
...
xorriso : UPDATE : Thank you for being patient. Working since 2 seconds.
xorriso : UPDATE : Writing: 32s 0.1% fifo 100% buf 0% 0.1xD
...
xorriso : UPDATE : Writing: 2704s 5.1% fifo 11% buf 0% 3.9xD
...
xorriso : UPDATE : Writing: 20208s 38.2% fifo 52% buf 99% 4.0xD
...
xorriso : UPDATE : Writing: 52885s 100.0% fifo 0% buf 99% 0.0xD
ISO image produced: 52735 sectors
Written to media : 52885 sectors at LBA 0
Writing to '/dev/sr1' completed successfully.
}}}
Do not worry if there is no progress to see for a few dozen seconds
at the beginning.
The run will last at least as long as writing of 1 GB would need.
If you write less data, then there will be a lot of zero progress
messages at the end of writing.
----------------------------------------------------------------------
Checkreading the result:
{{{
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
}}}
The word "sorry" sets the severity class of the event message, which is
emitted in case of MD5 mismatch. (See man xorriso, "Exception processing".)
This should report on stderr
{{{
...
Drive current: -indev '/dev/sr1'
Media current: DVD-RW sequential recording
Media status : is written , is closed
Media summary: 1 session, 52885 data blocks, 103m data, 0 free
Volume id : 'ISOIMAGE'
xorriso : UPDATE : 568079 content bytes read in 5 seconds
xorriso : UPDATE : 17074k content bytes read in 10 seconds
...
xorriso : UPDATE : 103.7m content bytes read in 35 seconds
File contents and their MD5 checksums match.
}}}
and the exit value should be 0, if no mismatch was reported.
A mismatch message would look like
{{{
...
MD5 MISMATCH: '/usr/bin/ncursesw5-config'
...
Mismatch detected between file contents and MD5 checksums.
xorriso : SORRY : Event triggered by MD5 comparison mismatch
xorriso : NOTE : Tolerated problem event of severity 'SORRY'
xorriso : NOTE : -return_with SORRY 32 triggered by problem severity SORRY
}}}
and the exit value would be non-zero.
----------------------------------------------------------------------
Blanking to multi-session capability:
{{{
$ xorriso -outdev /dev/sr1 -blank as_needed
}}}
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
to make the medium writable from scratch. With DVD-RW it will decide for
-blank "all".
The report on stderr should end by
{{{
...
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 904 seconds )
Blanking done
xorriso : NOTE : Re-assessing -outdev '/dev/sr1'
Drive current: -outdev '/dev/sr1'
Media current: DVD-RW sequential recording
Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 4489m free
}}}
----------------------------------------------------------------------
Writing multiple sessions (DVD-RW write type Incremental):
This time do not perform command -close "on", so that the medium
stays writable:
{{{
$ xorriso -md5 on -dev /dev/sr1 -add /usr/lib --
...
xorriso : UPDATE : Writing: 105280s 98.6% fifo 0% buf 77% 3.5xD
xorriso : UPDATE : Writing: 106796s 100.0% fifo 0% buf 62% 2.2xD
xorriso : UPDATE : Closing track/session. Working since 44 seconds
...
xorriso : UPDATE : Closing track/session. Working since 77 seconds
ISO image produced: 106646 sectors
Written to media : 106800 sectors at LBA 0
Writing to '/dev/sr1' completed successfully.
}}}
Checkread like after the DAO test:
{{{
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
...
xorriso : UPDATE : 204.0m content bytes read in 63 seconds
File contents and their MD5 checksums match.
}}}
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:
{{{
$ xorriso -md5 on -dev /dev/sr1 -add /usr/bin --
...
Written to media : 53408 sectors at LBA 135488
Writing to '/dev/sr1' completed successfully.
}}}
And checkread the whole tree of files (i.e. both sessions):
{{{
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
...
xorriso : UPDATE : 307.8m content bytes read in 89 seconds
File contents and their MD5 checksums match.
}}}
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.
So use command -close "on" to demand closing after writing.
{{{
$ xorriso -md5 on -dev /dev/sr1 -close on -add /usr/sbin --
...
Written to media : 16160 sectors at LBA 195056
Writing to '/dev/sr1' completed successfully.
}}}
Checkread
{{{
$ xorriso -md5 on -indev /dev/sr1 -check_md5_r sorry / --
...
Media current: DVD-RW sequential recording
Media status : is written , is closed
Media summary: 3 sessions, 176368 data blocks, 344m data, 4064m free
...
xorriso : UPDATE : 337.7m content bytes read in 97 seconds
File contents and their MD5 checksums match.
}}}
-----------------------------------------------------------------------------
If the drive tray can move by itself, you may now eject the medium:
{{{
$ xorriso -outdev /dev/sr1 -eject all
}}}
-----------------------------------------------------------------------------
Other applicable media types:
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.
So choose smaller directories for CD.
-blank "deformat_quickest" addresses a peculiarity of DVD-RW.
It will work on other media like -blank "fast".
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.
The first session on CD will always be written with write type SAO,
further sessions will be written with TAO.
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.
So this simulation is usable only for first sessions on blank media.
-----------------------------------------------------------------------------
Now for formatted overwritable media:
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.
There is no way to close formatted media. The command -close "on"
gets silently ignored.
The write methods and states of formatted media differ from those of
sequential media. But xorriso presents to the user a unified
multi-session usage model, under the assumption that all emulated
sessions contain ISO 9660 filesystem images, which successively
build on each other.
So from the view of xorriso commands, the only task which makes
them differ from sequential media, is to apply optional formatting
or re-formatting.
A special case are BD-R, which xorriso may format but will not bring
into (pseudo-) overwritable state. Formatted BD-R perform Defect
Management by default, which checkreads during writing and replaces
bad block.
The mandatory formatting of unused DVD+RW and BD-RE is done by xorriso
automatically. Just start a normal write run. DVD-RAM are sold formatted.
xorriso treats overwritable media with a valid ISO 9660 filesystem as
appendable media. To make then writable from scratch, apply
-blank "as_needed", which will actually write a few bytes into the PVD
(superblock) of the ISO filesystem to invalidate it.
De-formatting is only possible with DVD-RW. E.g. by -blank "deformat".
-----------------------------------------------------------------------------
Format DVD-RW for overwriting without intermediate blanking,
or format BD-R for Defect Management:
{{{
$ xorriso -outdev /dev/sr1 -format as_needed
}}}
should report on stderr
{{{
...
xorriso : UPDATE : Formatting ( 99.0% done in 912 seconds )
Formatting done
xorriso : NOTE : Re-assessing -outdev '/dev/sr1'
Drive current: -outdev '/dev/sr1'
Media current: DVD-RW restricted overwrite
Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 4488m free
}}}
As with blanking, one should not worry if the progress messages show
unplausible percentages. Some drives are more equal than others.
Formatting is said to be much stress to the medium. -format option
"as_needed" applies it only to yet unformatted media.
When performing above write tests, take care to use -blank "as_needed"
rather than -blank "deformat_quickest". Else you will get a sequential
unformatted DVD-RW rather than a formatted DVD-RW which xorriso is
willing to write from scratch.
There is no use in a separate "DAO" test on overwritable media anyway.
-----------------------------------------------------------------------------
Change the formatted size of a BD-RE:
First learn about formatted size and proposals of other sizes.
(One can issue own wishes, too. See in man xorriso, command -format.)
{{{
$ xorriso -outdev /dev/sr1 -list_formats
}}}
should tell on stdout
{{{
...
Format status: formatted, with 23610.0 MiB
BD Spare Area: 0 blocks consumed, 131072 blocks available
Format idx 0 : 00h , 11826176s , 23098.0 MiB
Format idx 1 : 01h , 11564032s , 22586.0 MiB
Format idx 2 : 30h , 11826176s , 23098.0 MiB
Format idx 3 : 30h , 11564032s , 22586.0 MiB
Format idx 4 : 30h , 12088320s , 23610.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
{{{
$ xorriso -outdev /dev/sr1 -format by_index_2 -blank as_needed
...
Media summary: 2 sessions, 105470 data blocks, 206m data, 22.4g free
}}}
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
avoid any data corruption.
If you want to keep the data, then make at least a checkread run.
Check whether the size has changed:
{{{
$ xorriso -outdev /dev/sr1 -list_formats
}}}
should tell on stdout
{{{
...
Format status: formatted, with 23098.0 MiB
BD Spare Area: 0 blocks consumed, 393216 blocks available
...
}}}

22
libisoburn/branches/1.2.2/doc/startup_file.txt Normal file
View File

@ -0,0 +1,22 @@
# This is an example for a xorriso startup file.
# If found at one of the following addresses then its text lines will get
# executed by xorriso as commands before any of its program arguments:
# /etc/default/xorriso
# /etc/opt/xorriso/rc
# /etc/xorriso/xorriso.conf
# $HOME/.xorrisorc
# Note: Command -no_rc as first program argument prevents this execution.
# Disallow the use of hard disk /dev/sda and its partitions as
# pseudo-drive (e.g. as output target of an ISO image).
-drive_class banned /dev/sda*
# Allow the use of /dev/sdb, /dev/sdc, and /dev/sdd as pseudo-drives
# without the prefix "stdio:" which is usually required for device addresses
# which begin by "/dev/" but represent no CD drives.
-drive_class harmless /dev/sd[bcd]