session.
If set to "as_needed" then use "on" only if
"off" is predicted to fail with the given medium and its state.
Not all drives correctly recognize fast-blanked DVD-RW which need
"on". If there is well founded suspicion that a burn run failed
due to -close "off", then -close "as_needed" causes a
re-try with "on".
Note that emulation command -as "cdrecord" temporarily overrides
the current setting of -close by its own default -close "on" if
its option -multi is missing.
- -write_type
"auto"|"tao"|"sao/dao"
- Set the write type for the next burn run. "auto" will select SAO
with blank CD media, DAO with blank DVD-R[W] if -close is "on",
and elsewise CD TAO or the equivalent write type of the particular DVD/BD
media. Choosing TAO or SAO/DAO explicitly might cause the burn run to fail
if the desired write type is not possible with the given media state.
- -padding
number["k"|"m"]|"included"|"appended"
- Append the given number of extra bytes to the image stream. This is a
traditional remedy for a traditional bug in block device read drivers.
Needed only for CD recordings in TAO mode. Since one can hardly predict on
what media an image might end up, xorriso adds the traditional 300k
of padding by default to all images.
For images which will never get to a CD it is safe to use -padding 0 .
Normally padding is not written as part of the ISO image but appended after
the image end. This is -padding mode "appended".
Emulation command -as "mkisofs" and command -jigdo cause padding
to be written as part of the image. The same effect is achieved by
-padding mode "included".
- Bootable ISO images:
Contrary to published specifications many BIOSes will load an El
Torito record from the first session on media and not from the last one,
which gets mounted by default. This makes no problems with overwriteable
media, because they appear to inadverted readers as one single session.
But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that the
whole bootable system has to reside already in the first session and that
the last session still has to bear all files which the booted system expects
after mounting the ISO image.
If a boot image from ISOLINUX or GRUB is known to be present on media then it
is advised to patch it when a follow-up session gets written. But one should
not rely on the capability to influence the bootability of the existing
sessions, unless one can assume overwriteable media.
Normally the boot images are data files inside the ISO filesystem. By special
path "--interval:appended_partition_NNN:all::" it is possible to
refer to an appended partition. The number NNN gives the partition number as
used with the corresponding command -append_partition. E.g.:
-append_partition 2 0xef /tmp/efi.img
-boot_image any efi_path=--interval:appended_partition_2:all::
There are booting mechanisms which do not use an El Torito record but rather
start at the first bytes of the image: PC-BIOS MBR or EFI GPT for
hard-disk-like devices, APM partition entries for Macs which expect HFS+
boot images, MIPS Volume Header for old SGI computers, DEC Boot Block for
old MIPS DECstation, SUN Disk Label for SPARC machines, HP-PA boot sector
for HP PA-RISC machines, DEC Alpha SRM boot sector for old DEC Alpha
machines.
Several of the following commands expect disk paths as input but
also accept description strings for the libisofs interval reader, which is
able to cut out data from disk files or -indev and to zeroize parts of the
content: command -append_partition, boot specs system_area=, grub2_mbr=,
prep_boot_part=, efi_boot_part=.
The description string consists of the following components, separated by
colon ':'
"--interval:"Flags":"Interval":"Zeroizers":"Source
The component "--interval" states that this is not a plain disk path
but rather an interval reader description string. The component Flags
modifies the further interpretation:
"local_fs" demands to read from a file depicted by the path in
Source.
"imported_iso" demands to read from the -indev. This works only if
-outdev is not the same as -indev. The Source component is ignored.
"appended_partition_NNN" with a decimal number NNN works only for
-boot_image bootspecs which announce El Torito boot image paths: bin_path=,
efi_path=. The number gives the partition number as used with the
corresponding command -append_partition.
The component Interval consists of two byte address numbers separated by a
"-" character. E.g. "0-429" means to read bytes 0 to
429.
The component Zeroizers consists of zero or more comma separated strings. They
define which part of the read data to zeroize. Byte number 0 means the byte
read from the Interval start address. Each string may be one of:
"zero_mbrpt" demands to zeroize the MBR partition table if bytes 510
and 511 bear the MBR signature 0x55 0xaa.
"zero_gpt" demands to check for a GPT header in bytes 512 to 1023,
to zeroize it and its partition table blocks.
"zero_apm" demands to check for an APM block 0 and to zeroize its
partition table blocks.
Start_byte"-"End_byte demands to zeroize the read-in bytes beginning
with number Start_byte and ending after End_byte.
The component Source is the file path with flag "local_fs", and
ignored with flag "imported_iso".
Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning
multiplication by {1024, 1024k, 1024m, 1024g, 2048, 512}. A scaled value end
number depicts the last byte of the scaled range.
E.g. "0d-0d" is "0-511".
Examples:
"local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso"
"imported_iso:45056d-47103d::"
- -boot_image
"any"|"isolinux"|"grub"
-
"discard"|"keep"|"patch"|"replay"|"show_status"|
bootspec|"next"
Define the equipment of the emerging filesystem with boot entry points.
With systems which boot via BIOS or EFI this is a set of El Torito boot
images, possibly MBR boot code, and possibly partition tables of type MBR,
GPT, or APM. Such file sets get produced by boot loader systems like
ISOLINUX or GRUB.
Each -boot_image command has two parameters: type and setting.
More than one -boot_image command may be used to define the handling of
one or more boot images. Sequence matters.
Types isolinux and grub care for known peculiarities. Type
any makes no assumptions about the origin of the boot images.
When loading an ISO filesystem, system area and El Torito boot
images get loaded, too. The default behavior is not to write loaded El
Torito boot images and to write the loaded system area content without
alterations.
discard gives up the El Torito boot catalog and its boot images.
regardless whether loaded from an ISO filesystem or defined by commands.
Any BIOS or EFI related boot options get revoked. Nevertheless, loaded
system area data stay valid. If desired, they have to be erased by
-boot_image any system_area=/dev/zero
keep keeps or copies El Torito boot images unaltered and writes a
new catalog.
patch applies patching to existing El Torito boot images if they
seem to bear a boot info table.
A boot info table needs to be patched when the boot image gets newly
introduced into the ISO image or if an existing image gets relocated.
This is automatically done if type "isolinux" or
"grub" is given, but not with "any".
If patching is enabled, then boot images from previous sessions will be
checked whether they seem to bear a boot info table. If not, then they
stay unpatched. This check is not infallible. So if you do know that the
images need no patching, use "any" "keep".
"grub" "patch" will not patch EFI images
(platform_id=0xef).
replay is a more modern version of "patch", which not
only cares for existing El Torito boot equipment but also for the
recognizable boot provisions in the System Area. It discards any
existing -boot_image setting and executes the commands proposed by
command -report_el_torito "cmd".
This action will only succeed if the file objects mentioned in the output
of command -report_el_torito "cmd" are still available. Do not
remove or rename boot image files after -indev.
Drop unknown El Torito: -boot_image "any" "discard"
Maintain recognizable stuff: -boot_image "any"
"replay"
El Torito only for GRUB: -boot_image "grub" "patch"
El Torito only for ISOLINUX: -boot_image "isolinux"
"patch"
show_status will print what is known about the loaded boot images
and their designated fate.
A bootspec is a word of the form name=value. It is used
to describe the parameters of a boot feature. The names "dir",
"bin_path", "efi_path" lead to El Torito bootable
images. Name "system_area" activates a given file as MBR or
other disk header.
On all media types this is possible within the first session. In further
sessions an existing boot image can get replaced by a new one, but
depending on the media type this may have few effect at boot time. See
above.
El Torito boot images have to be added to the ISO image by normal means
(image loading, -map, -add, ...). In case of ISOLINUX the files should
reside either in ISO image directory /isolinux or in /boot/isolinux . In
that case it suffices to use as bootspec the text
"dir=/isolinux" or "dir=/boot/isolinux".
E.g.:
-boot_image isolinux dir=/boot/isolinux
which bundles these individual settings:
-boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
-boot_image isolinux cat_path=/boot/isolinux/boot.cat
-boot_image isolinux load_size=2048
-boot_image any boot_info_table=on
An El Torito boot catalog file gets inserted into the ISO image with
address cat_path= with the first -boot_image "any"
"next" or at -commit time. It is subject to normal -overwrite
and -reassure processing if there is already a file with the same name.
The catalog lists the boot images and is read by the boot facility to
choose one of the boot images. But it is not necessary that it appears
in the directory tree at all. One may hide it in all trees by
cat_hidden=on. Other possible values are "iso_rr",
"joliet", "hfsplus", and the default
"off". The timestamps of the boot catalog file are refreshed
at commit time. Command -volume_date "uuid" can be used to set
their value.
bin_path= depicts an El Torito boot image file, a binary program
which is to be started by the hardware boot facility (e.g. the BIOS) at
boot time.
efi_path= depicts an El Torito boot image file that is ready for
EFI booting. This is normally a FAT filesystem image not larger than
65535 blocks of 512 bytes (= 32 MiB - 512). Its load_size is determined
automatically, no boot info table gets written, no boot medium gets
emulated, platform_id is 0xef.
emul_type= can be one of "no_emulation",
"hard_disk", "diskette". It controls the boot medium
emulation code of a boot image. The default "no_emulation" is
suitable for ISOLINUX, GRUB, FreeBSD cdboot.
load_size= is a value which depends on the boot image. Default is
2048 which matches the expectations of most boot images. The special
value "full" means the full size of the boot image file
rounded up to a multiple of 2048 bytes. Maximum is 33,552,384 bytes.
boot_info_table=on causes address patching to bytes 8 to 63 of the
boot image which is given by "any" "bin_path=".
"boot_info_table=off" disables this patching.
grub2_boot_info=on causes address patching to byte 2548 of the boot
image which is given by "any" "bin_path=". The
address is written as 64 bit little-endian number. It is the 2KB block
address of the boot image content, multiplied by 4, and then incremented
by 5. "grub2_boot_info=off" disables this patching.
platform_id= defines by a hexadecimal or decimal number the
Platform ID of the boot image. "0x00" is 80x86 PC-BIOS,
"0x01" is PowerPC, "0x02" is Mac, "0xef"
is EFI (decimal "239").
id_string=text|56_hexdigits defines the ID string of the boot
catalog section where the boot image will be listed. If the value
consists of 56 characters [0-9A-Fa-f] then it is converted into 28
bytes, else the first 28 characters become the ID string. The ID string
of the first boot image becomes the overall catalog ID. It is limited to
24 characters. Other id_strings become section IDs.
sel_crit=hexdigits defines the Selection Criteria of the boot
image. Up to 20 bytes get read from the given characters [0-9A-Fa-f].
They get attributed to the boot image entry in the catalog.
next ends the definition of a boot image and starts a new one. Any
following -bootimage bootspecs will affect the new image. The first
"next" discards loaded boot images and their catalog.
system_area=disk_path copies at most 32768 bytes from the given
disk file to the very start of the ISO image. This System Area is
reserved for system dependent boot software, e.g. an MBR which can be
used to boot from USB stick or hard disk.
Other than an El Torito boot image, the file disk_path needs not to be
added to the ISO image.
-boot_image isolinux system_area= implies
"partition_table=on". In this case, the disk path should lead
to one of the SYSLINUX files isohdp[fp]x*.bin or to a file which was
derived from one of those files. E.g. to the first 512 bytes from an
ISOLINUX isohybrid ISO image.
In this case, El Torito boot images (dir=, bin_path=, efi_path=) may be
augmented by isolinux partition_entry=gpt_basdat or isolinux
partition_entry=gpt_hfsplus, and by isolinux
partition_entry=apm_hfsplus. The boot image will then be mentioned
in GPT as Basic Data or GPT HFS+ partition, and in APM as HFS+
partition. The first three GPT partitions will also be marked by MBR
partitions.
In multi-session situations the existing System Area is preserved by
default. In in this case, the special disk_path "." prevents
reading of a disk file but nevertheless causes adjustments in the loaded
system area data. Such adjustments may get ordered by -boot_image
commands.
-boot_image any gpt_disk_guid=value controls whether an emerging
GPT shall get a randomly generated disk GUID or whether the GUID is
supplied by the user. Value "random" is default. Value
"volume_date_uuid" produces a low quality GUID from the value
set by -volume_date "uuid".
A string of 32 hex digits, or a RFC 4122 compliant GUID string may be used
to set the disk GUID directly. UEFI prescribes the first three
components of a RFC 4122 GUID string to be byte-swapped in the binary
representation:
E.g. gpt_disk_guid=2303cd2a-73c7-424a-a298-25632da7f446 equals
gpt_disk_guid=2acd0323c7734a42a29825632da7f446
The partition GUIDs get generated by minimally varying the disk GUID.
-boot_image any part_like_isohybrid=on enables -boot_image isolinux
partition_entry= even if no -boot_image isolinux system_area= is given.
No MBR partition of type 0xee emerges, even if GPT gets produced. Gaps
between GPT and APM partitions will not be filled by more partitions.
Appended partitions get mentioned in APM if other APM partitions emerge.
-boot_image any iso_mbr_part_type=number sets the partition type of
the MBR partition which represents the ISO or at least protects it.
Number may be 0x00 to 0xff. The text "default" re-enables the
default types of the various occasions to create an ISO MBR partition.
This is without effect if no such partition emerges by other settings or
if the partition type is prescribed mandatorily like 0xee for GPT
protective MBR or 0x96 for CHRP.
If instead a type_guid is given by a 32-digit hex string like
a2a0d0ebe5b9334487c068b6b72699c7 or by a structured text like
EBD0A0A2-B9E5-4433-87C0-68B6B72699C7, then it will be used as partition
type if the ISO filesystem appears as partition in GPT. In MBR,
C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped to 0xef. Any other
GUID will be mapped to 0x83.
grub2_mbr=disk_path works like "any" system_area= with
additional patching for modern GRUB MBRs. The content start address of
the first boot image is converted to a count of 512 byte blocks, and an
offset of 4 is added. The result is written as 64 bit little-endian
number to byte address 0x1b0.
This feature can be revoked either by grub2_mbr= with empty disk path, or
by submitting a disk_path via system_area=.
partition_table=on causes a simple partition table to be written
into bytes 446 to 511 of the System Area.
With type "isolinux" it shows a partition that begins at byte 0
and it causes the LBA of the first boot image to be written into the
MBR. For the first session this works only if also
"system_area=" and "bin_path=" or "dir="
is given.
With types "any" and "grub" it shows a single
partition which starts at byte 512 and ends where the ISO image ends.
This works with or without system_area= or boot image.
Bootspecs chrp_boot_part=, prep_boot_part=, and efi_boot_part= overwrite
this entry in the MBR partition table.
If types "isolinux" or "grub" are set to
"patch", then "partition_table=on" is activated
without new boot image. In this case the existing System Area gets
checked whether it bears addresses and sizes as if it had been processed
by "partition_table=on". If so, then those parameters get
updated when the new System Area is written.
Special "system_area=/dev/zero" causes 32k of NUL-bytes. Use
this to discard an MBR which was loaded with the ISO image.
appended_part_as=gpt marks partitions from -append_partition in GPT
rather than in MBR. In this case the MBR shows a single partition of
type 0xee which covers the whole output data.
appended_part_as=mbr is the default. Appended partitions get marked
in GPT only if GPT is produced because of other settings. If given
explicitly, this clears setting "gpt" and "apm".
Nevertheless "apm" may be added to "mbr".
appended_part_as=apm marks partitions from -append_partition in APM
additionally to "mbr" or "gpt".
By default, appended partitions get marked in APM only if APM is produced
because of other options together with
part_like_isohybrid="on".
chrp_boot_part=on causes a single partition in MBR which covers the
whole ISO image and has type 0x96. This is not compatible with any other
feature that produces MBR partition entries. It makes GPT
unrecognizable.
prep_boot_part=disk_path inserts the content of a data file into
the image and marks it by an MBR partition of type 0x41. The parts of
the ISO image before and after this partition will be covered by further
MBR partitions. The data file is supposed to contain ELF executable
code.
efi_boot_part=disk_path inserts the content of a data file into the
image and marks it by a GPT partition. If not chrp_boot_part=on, then
the first partition in MBR will have type 0xee to announce the presence
of GPT. The data file is supposed to contain a FAT filesystem.
Instead of a disk_path, the word --efi-boot-image may be given. It exposes
in GPT the content of the first El Torito EFI boot image as EFI system
partition. EFI boot images are introduced by bootspec efi_path=. The
affected EFI boot image cannot show up in HFS+ because it is stored
outside the HFS+ partition.
partition_offset=2kb_block_adr causes a partition table with a
single partition that begins at the given block address. This is counted
in 2048 byte blocks, not in 512 byte blocks. If the block address is
non-zero then it must be at least 16. A non-zero partition offset causes
two superblocks to be generated and two sets of directory trees. The
image is then mountable from its absolute start as well as from the
partition start.
The offset value of an ISO image gets preserved when a new session is
added. So the value defined here is only in effect if a new ISO image
gets written.
partition_hd_cyl=number gives the number of heads per cylinder for
the partition table. 0 chooses a default value. Maximum is 255.
partition_sec_hd=number gives the number of sectors per head for
the partition table. 0 chooses a default value. Maximum is 63.
The product partition_sec_hd * partition_hd_cyl * 512 is the cylinder
size. It should be divisible by 2048 in order to make exact alignment
possible. With appended partitions and "appended_part_as=gpt"
there is no limit for the number of cylinders. Else there may be at most
1024 of them. If the cylinder size is too small to stay below the limit,
then appropriate values of partition_hd_cyl are chosen with
partition_sec_hd 32 or 63. If the image is larger than 8,422,686,720
bytes, then the cylinder size constraints cannot be fulfilled for MBR.
partition_cyl_align=mode controls image size alignment to an
integer number of cylinders. It is prescribed by isohybrid specs and it
seems to please program fdisk. Cylinder size must be divisible by 2048.
Images larger than 8,323,596,288 bytes cannot be aligned in MBR
partition table.
Mode "auto" is default. Alignment by padding happens only with
"isolinux" "partition_table=on".
Mode "on" causes alignment by padding with
"partition_table=on" for any type. Mode "all" is
like "on" but also pads up partitions from -append_partition
to an aligned size.
Mode "off" disables alignment for any type.
mbr_force_bootable=mode enforces an MBR partition with
"bootable/active" flag if options like partition_table= or
grub2_mbr= indicate production of a bootable MBR. These options normally
cause the flag to be set if there is an MBR partition of type other than
0xee or 0xef. If no such partition exists, then no bootflag is set,
unless mbr_force_bootable="on" forces creation of a dummy
partition of type 0x00 which covers only the first block of the ISO
image.
If no bootable MBR is indicated and a partition gets created by
-append_partition, then mbr_force_bootable="on" causes a
bootflag like it would do with a bootable MBR.
mips_path=iso_rr_path declares a data file in the image to be a
MIPS Big Endian boot file and causes production of a MIPS Big Endian
Volume Header. This is mutually exclusive with production of other boot
blocks like MBR. It will overwrite the first 512 bytes of any data
provided by system_area=. Up to 15 boot files can be declared by
mips_path=.
mipsel_path=iso_rr_path declares a data file in the image to be the
MIPS Little Endian boot file. This is mutually exclusive with other boot
blocks. It will overwrite the first 512 bytes of any data provided by
system_area=. Only a single boot file can be declared by mipsel_path=.
sparc_label=text causes the production of a SUN Disk Label with the
given text as ASCII label. Partitions 2 to 8 may be occupied by appended
images. Partition 1 will always be the ISO image. See command
-append_partition. The first 512 bytes of any data provided by
system_area= will be overwritten.
grub2_sparc_core=iso_rr_path causes the content address and size of
the given file to be written after the SUN Disk Label. Both numbers are
counted in bytes. The address is written as 64 bit big-endian number to
byte 0x228. The size is written as 32 bit big-endian number to byte
0x230.
hppa_cmdline=text sets the PALO command line for HP-PA. Up to 1023
characters are permitted by default. With hppa_hdrversion=4 the limit is
127.
Note that the first five hppa_ bootspecs are mandatory, if any of the
hppa_ bootspecs is used. Only hppa_hdrversion= is allowed to be missing.
hppa_bootloader=iso_rr_path designates the given path as HP-PA
bootloader file.
hppa_kernel_32=iso_rr_path designates the given path as HP-PA 32
bit kernel file.
hppa_kernel_64=iso_rr_path designates the given path as HP-PA 64
bit kernel file.
hppa_ramdisk=iso_rr_path designates the given path as HP-PA RAM
disk file.
hppa_hdrversion=number chooses between PALO header version 5
(default) and version 4. For the appropriate value see in PALO source
code: PALOHDRVERSION.
alpha_boot=iso_rr_path declares a data file in the image to be the
DEC Alpha SRM Secondary Bootstrap Loader and causes production of a boot
sector which points to it. This is mutually exclusive with production of
other boot blocks like MBR.
mips_discard, sparc_discard, hppa_discard,
alpha_discard revoke any boot file declarations made for
mips/mipsel, sparc, hppa, or alpha, respectively. This removes the ban
on production of other boot blocks.
hfsplus_serial=hexstring sets a string of 16 digits "0"
to "9" and letters "a" to "f", which will
be used as unique serial number of an emerging HFS+ filesystem.
hfsplus_block_size=number sets the allocation block size to be used
when producing HFS+ filesystems. Permissible are 512, 2048, or 0. The
latter lets the program decide.
apm_block_size=number sets the block size to be used when
describing partitions by an Apple Partition Map. Permissible are 512,
2048, or 0. The latter lets the program decide.
Note that size 512 is not compatible with production of GPT, and that size
2048 will not be mountable -t hfsplus at least by older Linux kernels.
- -append_partition partition_number type_code disk_path
- Cause a prepared filesystem image to be appended to the ISO image and to
be described by a partition table entry in a boot block at the start of
the emerging ISO image. The partition entry will bear the size of the
submitted file rounded up to the next multiple of 2048 bytes or to the
next multiple of the cylinder size.
Beware of subsequent multi-session runs. The appended partition will get
overwritten.
Partitions may be appended with boot block type MBR and with SUN Disk Label.
With MBR:
partition_number may be 1 to 4. Number 1 will put the whole ISO image into
the unclaimed space before partition 1. So together with most
xorriso MBR features, number 2 would be the most natural choice.
The type_code may be "FAT12", "FAT16",
"Linux", or a hexadecimal number between 0x00 and 0xff. Not all
those numbers will yield usable results. For a list of MBR partition type
codes search the Internet for "Partition Types" or run fdisk
command "L".
type_code may also be a type GUID as plain hex string like
a2a0d0ebe5b9334487c068b6b72699c7 or as structured text like
EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the partition is
mentioned in GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be
mapped to 0xef. Any other GUID will be mapped to 0x83.
If some other command causes the production of GPT, then the appended
partitions will be mentioned there too.
The disk_path must provide the necessary data bytes at commit time. An empty
disk_path disables this feature for the given partition number.
With SUN Disk Label (selected by -boot_image any sparc_label=):
partition_number may be 2 to 8. Number 1 will always be the ISO image.
Partition start addresses are aligned to 320 KiB. The type_code does not
matter. Submit 0x0.
Partition image name "." causes the partition to become a copy of
the next lower valid one.
- Jigdo Template Extraction:
From man genisoimage: "Jigdo is a tool to help in the
distribution of large files like CD and DVD images; see
http://atterer.net/jigdo/ for more details. Debian CDs and DVD ISO images
are published on the web in jigdo format to allow end users to download them
more efficiently."
xorriso can produce a .jigdo and a .template file together with a
single-session ISO image. The .jigdo file contains checksums and symbolic
file addresses. The .template file contains the compressed ISO image with
reference tags instead of the content bytes of the listed files.
Input for this process are the normal arguments for a xorriso session
on a blank -outdev, and a .md5 file which lists those data files which may
be listed in the .jigdo file and externally referenced in the .template
file. Each designated file is represented in the .md5 file by a single text
line:
MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks,
symbolic file address
The file address in an .md5 line has to bear the same basename as the
disk_path of the file which it shall match. The directory path of the file
address is decisive for To=From mapping, not for file recognition. After
To=From mapping, the file address gets written into the .jigdo file. Jigdo
restore tools will convert these addresses into really reachable data source
addresses from which they can read.
If the list of jigdo parameters is not empty, then xorriso will refuse
to write to non-blank targets, it will disable multi-session emulation, and
padding will be counted as part of the ISO image.
- -jigdo parameter_name value
- Clear Jigdo Template Extraction parameter list or add a parameter to that
list. The alias names are the corresponding genisoimage options. They are
accepted as parameter names as well. Especially they are recognized by the
-as mkisofs emulation command.
Parameter clear with any value empties the whole list. No .jigdo and
.template file will be produced.
template_path sets the disk_path for the .template file with the
holed and compressed ISO image copy.
Alias: -jigdo-template
jigdo_path sets the disk_path for the .jigdo file with the checksums
and download addresses for filling the holes in .template.
Alias: -jigdo-jigdo
md5_path sets the disk_path where to find the .md5 input file.
Alias: -md5-list
min_size sets the minimum size for a data file to be listed in the
.jigdo file and being a hole in the .template file.
Alias: -jigdo-min-file-size
exclude adds a regular expression pattern which will get compared
with the absolute disk_path of any data file. A match causes the file to
stay in .template in any case.
Alias: -jigdo-exclude
demand_md5 adds a regular expression pattern which will get compared
with the absolute disk_path of any data file that was not found in the
.md5 list. A match causes a MISHAP event.
Alias: -jigdo-force-md5
mapping adds a string pair of the form To=From to the parameter list.
If a data file gets listed in the .jigdo file, then it is referred by the
file address from its line in the .md5 file. This file address gets
checked whether it begins with the From string. If so, then this string
will be replaced by the To string and a ':' character, before it goes into
the .jigdo file. The From string should end by a '/' character.
Alias: -jigdo-map
compression chooses one of "bzip2" or "gzip" for
the compression of the template file. The jigdo file is put out
uncompressed.
Alias: -jigdo-template-compress
checksum_iso chooses one or more of "md5",
"sha1", "sha256", "sha512" for the auxiliary
"# Image Hex" checksums in the jigdo file. The value may e.g.
look like "md5,sha1,sha512". Value "all" chooses all
available algorithms. Note that MD5 stays always enabled.
Alias: -checksum_algorithm_iso
checksum_template is like checksum_iso but for "# Template
Hex".
Alias: -checksum_algorithm_template
- Character sets:
File names are strings of non-zero bytes with 8 bit each.
Unfortunately the same byte string may appear as different peculiar national
characters on differently nationalized terminals. The meanings of byte codes
are defined in character sets which have names. Shell command iconv
-l lists them.
The file names on hard disk are assumed to be encoded by the local
character set which is also used for the communication with the user.
Byte codes 32 to 126 of the local character set must match the US-ASCII
characters of the same code. ISO-8859 and UTF-8 fulfill this demand.
By default, xorriso uses the character set as told by shell command
"locale" with argument "charmap". This may be influenced
by environment variables LC_ALL, LC_CTYPE, or LANG and should match the
expectations of the terminal. In some situations it may be necessary to set
it by command -local_charset.
Local character sets should not matter as long as only english alphanumeric
characters are used for file names or as long as all writers and readers of
the media use the same local character set. Outside these constraints it may
be necessary to let xorriso convert byte codes from and to other
character sets.
The Rock Ridge file names in ISO filesystems are assumed to be encoded by the
input character set. The Rock Ridge file names which get written with
ISO filesystems will be encoded by the output character set.
The sets can be defined independently by commands -in_charset and
-out_charset. Normally one will have both identical, if ever. Other than the
local character set, these two character sets may deviate from US-ASCII.
The output character sets for Joliet and HFS+ are not influenced by these
commands. Joliet uses output character set UCS-2 or UTF-16. HFS+ uses
UTF-16.
The default output charset is the local character set of the terminal where
xorriso runs. So by default no conversion happens between local
filesystem names and emerging Rock Ridge names in the image. The situation
stays ambiguous and the reader has to riddle what character set was used.
By command -auto_charset it is possible to attribute the output charset name
to the image. This makes the situation unambiguous. But if your terminal
character set does not match the character set of the local file names, then
this attribute can become plainly wrong and cause problems at read time. To
prevent this it is necessary to check whether the terminal properly displays
all intended filenames. Check especially the exotic national characters.
To enforce recording of a particular character set name without any conversion
at image generation time, set -charset and -local_charset to the desired
name, and enable -backslash_codes to avoid evil character display on your
terminal.
- -charset character_set_name
- Set the character set from which to convert file names when loading an
image and to which to convert when writing an image.
- -local_charset character_set_name
- Override the system assumption of the local character set name. If this
appears necessary, one should consider to set -backslash_codes to
"on" in order to avoid dangerous binary codes being sent to the
terminal.
- Exception processing:
Since the tasks of xorriso are manifold and prone to
external influence, there may arise the need for xorriso to report
and handle problem events.
Those events get classified when they are detected by one of the software
modules and forwarded to reporting and evaluation modules which decide about
reactions. Event classes are sorted by severity:
"NEVER" The upper end of the severity spectrum.
"ABORT" The program is being aborted and on its way to end.
"FATAL" The main purpose of the run failed or an important resource
failed unexpectedly.
"FAILURE" An important part of the job could not be performed.
"MISHAP" A FAILURE which can be tolerated during ISO image
generation.
"SORRY" A less important part of the job could not be performed.
"WARNING" A situation is suspicious of being not intended by the
user.
"HINT" A proposal to the user how to achieve better results.
"NOTE" A harmless information about noteworthy circumstances.
"UPDATE" A pacifier message during long running operations.
"DEBUG" A message which would only interest the program developers.
"ALL" The lower end of the severity spectrum.
- -abort_on severity
- Set the severity threshold for events to abort the program.
Useful: "NEVER", "ABORT", "FATAL",
"FAILURE" , "MISHAP", "SORRY"
It may become necessary to abort the program anyway, despite the setting by
this command. Expect not many "ABORT" events to be ignorable.
A special property of this command is that it works preemptive if given as
program start argument. I.e. the first -abort_on setting among the start
arguments is in effect already when the first operations of xorriso
begin. Only "-abort_on" with dash "-" is recognized
that way.
- -return_with severity exit_value
- Set the threshold and exit_value to be returned at program end if no abort
has happened. This is to allow xorriso to go on after problems but
to get a failure indicating exit value from the program, nevertheless.
Useful is a value lower than the -abort_on threshold, down to
"WARNING".
exit_value may be either 0 (indicating success to the starter of the
program) or a number between 32 and 63. Some other exit_values are used by
xorriso if it decides to abort the program run:
1=abort due to external signal
2=no program arguments given
3=creation of xorriso main object failed
4=failure to start libburnia-project.org libraries
5=program abort during argument processing
6=program abort during dialog processing
- -report_about severity
- Set the threshold for events to be reported.
Useful: "SORRY", "WARNING", "HINT",
"NOTE", "UPDATE", "DEBUG", "ALL"
Regardless what is set by -report_about, messages get always reported if
they reach the severity threshold of -abort_on .
Event messages are sent to the info channel "I" which is usually
stderr but may be influenced by command -pkt_output. Info messages which
belong to no event get attributed severity "NOTE".
A special property of this command is that the first -report_about setting
among the start arguments is in effect already when the first operations
of xorriso begin. Only "-report_about" with dash
"-" is recognized that way.
- -signal_handling mode
- Control the installation of a signal handler which shall react on external
signals (e.g. from program "kill" or from keys Ctrl+C) or on
signals caused by severe program errors.
Mode "on" is the default. It uses the signal handler of libburn
which produces ugly messages but puts much effort in releasing optical
drives before xorriso ends.
Mode "off" as first -signal_handling among the start arguments
prevents all own signal precautions of xorriso. Inherited signal
handler settings stay as they are.
It works like "sig_dfl" if given after other signal handling was
already established at program start.
Mode "sig_dfl" uses the system provided default handling of
signals, which is normally a sudden abort of the program. To prevent stuck
drives, the libburn handler is used during burning, blanking, and
formatting on MMC drives.
Mode "sig_ign" tries to ignore as many signal types as possible.
This imposes the risk that xorriso refuses to end until externally
kill -9 if performed. kill -9 then imposes the risk that the drive is left
in unusable state and needs poweroff to be reset. So during burning,
blanking, and formatting wait for at least their normal run time before
killing externally.
A special property of this command is that the first -signal_handling
setting among the start arguments is in effect already when the first
operations of xorriso begin. Only "-signal_handling" with
dash "-" is recognized that way.
- -error_behavior occasion behavior
- Control the program behavior at problem event occasions. For now this
applies to occasions "image_loading" which is given while an
image tree is read from the input device, and to
"file_extraction" which is given with osirrox commands like
-extract.
With "image_loading" there are three behaviors available:
"best_effort" goes on with reading after events with severity
below FAILURE if the threshold of command -abort_on allows this.
"failure" aborts image tree reading on first event of at least
SORRY. It issues an own FAILURE event. This is the default.
"fatal" acts like "failure" but issues the own event as
FATAL.
With occasion "file_extraction" there are three behaviors:
"keep" maintains incompletely extracted files on disk. This is the
default.
"delete" removes files which encountered errors during content
extraction.
"best_effort" starts a revovery attempt by means of -extract_cut
if the file content stems from the loaded ISO image and is not
filtered.
- Dialog mode control:
- -dialog "on"|"off"|"single_line"
- Enable or disable to enter dialog mode after all program arguments are
processed. In dialog mode input lines get prompted via readline or from
stdin.
If no -abort_on severity was set when dialog starts, then "NEVER"
is set to avoid abort in most cases of wrong input or other problems.
Before dialog begins, the default is "FAILURE" which e.g. aborts
on unknown commands.
Mode "on" supports input of newline characters within quotation
marks and line continuation by trailing backslash outside quotation marks.
Mode "single_line" does not.
- -page length width
- Describe terminal to the text pager. See also above, paragraph Result
pager.
If parameter length is nonzero then the user gets prompted after that number
of terminal lines. Zero length disables paging.
Parameter width is the number of characters per terminal line. It is used to
compute the number of terminal lines which get occupied by an output line.
A usual terminal width is 80.
- -use_readline "on"|"off"
- If "on" then use readline for dialog. Else use plain stdin.
See also above, paragraph Dialog, Readline, Result pager.
- -reassure "on"|"tree"|"off"
- If "on" then ask the user for "y" or "n":
before deleting or overwriting any file in the ISO image,
before overwriting any disk file during restore operations,
before rolling back pending image changes,
before committing image changes to media,
before changing the input drive,
before blanking or formatting media,
before ending the program.
With setting "tree" the reassuring prompt will appear for an
eventual directory only once and not for each file in its whole subtree.
Setting "off" silently kills any kind of image file object and
performs above irrevocable actions.
To really produce user prompts, command -dialog needs to be set to
"on". Note that the prompt does not appear in situations where
file removal is forbidden by command -overwrite. -reassure only imposes an
additional curb for removing existing file objects.
Be aware that file objects get deleted from the ISO image immediately after
confirmation. They are gone even if the running command gets aborted and
its desired effect gets revoked. In case of severe mess-up, consider to
use -rollback to revoke the whole session.
- Drive and media related inquiry actions:
- -devices
- Show list of available MMC drives with the addresses of their libburn
standard device files.
This is only possible when no ISO image changes are pending. After this
command was executed, there is no drive current and no image loaded.
In order to be visible, a device has to offer rw-permissions with its
libburn standard device file. Thus it might be only the superuser
who is able to see all drives.
Drives which are occupied by other processes get not shown.
- -device_links
- Like -devices, but presenting the drives with addresses of symbolic links
which point to the actual device files.
Modern GNU/Linux systems may shuffle drive addresses from boot to boot. The
udev daemon is supposed to create links which always point to the same
drive, regardless of its system address. The command -device_links shows
the addresses of such links if they begin by "/dev/dvd" or
"/dev/cd". Precedence is: "dvdrw", "cdrw",
"dvd", "cdrom", "cd".
- -toc
-
Show media specific tables of content. This is the session history of the
medium, not the ISO image directory tree.
In case of overwriteable media holding a valid ISO image, it may happen that
only a single session gets shown. But if the first session on the
overwriteable media was written by xorriso then a complete session
history can be emulated.
A drive which is incapable of writing may show any media as CD-ROM or
DVD-ROM with only one or two sessions on it. The last of these sessions is
supposed to be the most recent real session then.
Some read-only drives and media show no usable session history at all.
Command -rom_toc_scan might help.
If input device and output device are both acquired and not the same, then
both tables-of-content get shown.
- -toc_of
"in"|"out"|"all"[":short"]
- Like command -toc but explicitly choosing which drive's table-of-content
to show. "in" shows -indev or -dev, "out" shows
-outdev or -dev, "all" shows the same as -toc.
If ":short" is appended to the drive choosing word, then only a
short summary of drive state and medium content is printed.
As further difference to -toc, this command does not emit FAILURE events if
the desired drive is not acquired.
- -mount_cmd drive entity id path
- Emit an appropriate command line for mounting the ISO session indicated by
drive, entity and id. The result will be different on GNU/Linux and on
FreeBSD or NetBSD.
drive can be "indev" or "outdev" to indicate already
acquired drives, or it can be the path of a not yet acquired drive. Prefix
"stdio:" for non-MMC drives is not mandatory.
For entity and id, see also command -load. They must be either
"sbsector" with the superblock sector address as id, or
"track" with a track number as id, or "session" with a
session number, or "volid" with a search pattern for the volume
id, or "auto" with which any text as id mounts the first track
of the last session.
path will be used as mount point and must already exist as a directory on
disk.
The command gets printed to the result channel. See command -mount for
direct execution of this command.
- -mount_opts option[:option...]
- Set options which influence -mount and -mount_cmd. Currently there is only
option "exclusive" which is default and its counterpart
"shared". The latter causes xorriso not to give up the
affected drive with command -mount. On GNU/Linux it adds mount option
"loop" which may enable mounting of several sessions of the same
block device at the same time. One should not write to a mounted optical
medium, of course. Take care to umount all sessions before ejecting.
- -session_string drive entity id format
- Print to the result channel a text which gets composed according to format
and the parameters of the addressed session.
Formats "linux:"path or "freebsd:"path produce the
output of -mount_cmd for the given operating systems.
In other texts xorriso will substitute the following parameter names.
An optional prefix "string:" will be removed.
"%device%" will be substituted by the mountable device path of the
drive address.
"%sbsector%" will be substituted by the session start sector.
"%track%", "%session%", "%volid%" will be
substituted by track number, session number, or volume id of the depicted
session.
- -print_size
- Print the foreseeable consumption of 2048 byte blocks by next -commit.
This can last a while as a -commit gets prepared and only in last moment
is revoked by this command. The result depends on several settings and
also on the kind of output device. If no -jidgo options are set and not
command -as "mkisofs" was used, then -padding (300 kB by
default) is not counted as part of the image size.
If an El Torito boot image file is already depicted, then command
-print_size automatically executes -boot_image "any"
"next". This means that the properties of that boot image cannot
be edited by subsequent commands.
- -tell_media_space
- Print available space on the output medium and the free space after
subtracting already foreseeable consumption by next -commit.
Note that the title of the prediction "After commit :" is
misleading. It is rather the space that may still be filled in this
session without making the next -commit fail from medium overflow.
The free space after the next -commit might be smaller by several MB. This
depends on medium type, number of recorded sessions, and drive
habits.
- -pvd_info
- Print various ID strings and timestamps which can be found in loaded ISO
images. Some of the IDs may be changed by commands like -volid or
-publisher. For these IDs -pvd_info reports what would be written with the
next -commit. The timestamps get not automatically propagated from loaded
image to newly written image. The ones for new images may be set by
command -volume_date. See there for the meaning of the particular
timestamps.
- -report_el_torito mode
-
With mode plain print a report about the information found in the El
Torito boot catalog of the loaded ISO image.
With mode help print a text which explains the meaning of the lines
put out by "plain".
Mode cmd tries to print the xorriso commands which are
necessary to produce the found boot equipment: disk identifiers, El Torito
boot images, and System Area. Disk identifiers are strings which the
booting operating system might use to find the ISO filesystem from where
it comes. Currently known is the use of volume id and modification date.
The intended use case is modification of the filesystem by having -indev and
-outdev pointing to different images or drives. The result might be
insufficient, if the found equipment cannot be produced by xorriso.
Various SORRY events may arise in this case, but it is not guaranteed that
xorriso recognizes all its insufficiencies.
Mode as_mkisofs tries to print the xorriso -as mkisofs
options, which are necessary to produce the found equipment. The intended
use case is to use the mounted filesystem as input tree together with the
printed options.
- -report_system_area mode
- With mode plain print a report about the information found in the
System Area of the loaded ISO image. The report consists of zero to many
lines with a header text, a colon, and information text.
With mode help print a text which explains the meaning of the lines
put out by "plain". You probably will have to look for more
documentation which explains the technical details of the mentioned boot
facilities.
Modes cmd and as_mkisofs work like with command
-report_el_torito. See above.
With mode gpt_disk_guid print the GPT disk GUID of the loaded ISO in
RFC 4122 text format to result channel. It is not considered an error if
no GPT is present. In this case nothing is printed to result channel.
With mode gpt_crc_of:disk_path read up to 32 KiB from the disk file
with the path given after the colon. Compute the GPT compliant CRC number
and print it to the result channel. The number is shown like
"0x690fd979". The special disk_path "-" causes reading
from standard input.
With mode make_guid print a pseudo-random GUID in RFC 4122 text
format to result channel.
- Navigation in ISO image and disk filesystem:
- -cd iso_rr_path
- Change the current working directory in the ISO image. This is prepended
to iso_rr_paths which do not begin with '/'.
It is possible to set the working directory to a path which does not exist
yet in the ISO image. The necessary parent directories will be created
when the first file object is inserted into that virtual directory. Use
-mkdir if you want to enforce the existence of the directory already at
first insertion.
- -cdx disk_path
- Change the current working directory in the local filesystem. To be
prepended to disk_paths which do not begin with '/'.
- -pwd
-
Tell the current working directory in the ISO image.
- -pwdx
-
Tell the current working directory in the local filesystem.
- -ls iso_rr_pattern [***]
- List files in the ISO image which match shell patterns (i.e. with
wildcards '*' '?' '[a-z]'). If a pattern does not begin with '/' then it
is compared with addresses relative to -cd.
Directories are listed by their content rather than as single file item.
Pattern expansion may be disabled by command -iso_rr_pattern.
- -lsd iso_rr_pattern [***]
- Like -ls but listing directories as themselves and not by their content.
This resembles shell command ls -d.
- -lsl iso_rr_pattern [***]
- Like -ls but also list some of the file attributes. The output format
resembles shell command ls -ln.
File type 'e' indicates the El Torito boot catalog.
If the file has non-trivial ACL, then a '+' is appended to the permission
info. If the file is hidden, then 'I' for "iso_rr", 'J' for
"joliet", 'A' for "hfsplus", 'H' for multiple hiding
gets appended. Together with ACL it is 'i', 'j', 'a', 'h'.
- -lsdl iso_rr_pattern [***]
- Like -lsd but also list some of the file attributes. The output format
resembles shell command ls -dln.
- -lsx disk_pattern [***]
- List files in the local filesystem which match shell patterns. Patterns
which do not begin with '/' are used relative to -cdx.
Directories are listed by their content rather than as single file item.
Pattern expansion may be disabled by command -disk_pattern.
- -lsdx disk_pattern [***]
- Like -lsx but listing directories as themselves and not by their content.
This resembles shell command ls -d.
- -lslx disk_pattern [***]
- Like -lsx but also listing some of the file attributes. Output format
resembles shell command ls -ln.
- -lsdlx disk_pattern [***]
- Like -lsdx but also listing some of the file attributes. Output format
resembles shell command ls -dln.
- -getfacl iso_rr_pattern [***]
- Print the access permissions of the given files in the ISO image using the
format of shell command getfacl. If a file has no ACL then it gets
fabricated from the -chmod settings. A file may have a real ACL if it was
introduced into the ISO image while command -acl was set to
"on".
- -getfacl_r iso_rr_pattern [***]
- Like -gefacl but listing recursively the whole file trees underneath
eventual directories.
- -getfattr iso_rr_pattern [***]
- Print the xattr of the given files in the ISO image. If a file has no such
xattr then noting is printed for it. The choice of namespaces depends on
the setting of command -xattr: "on" or "user"
restricts it to namespace "user", "any" only omits
namespace "isofs".
- -getfattr_r iso_rr_pattern [***]
- Like -gefattr but listing recursively the whole file trees underneath of
directories.
- -du iso_rr_pattern [***]
- Recursively list size of directories and files in the ISO image which
match one of the patterns. similar to shell command du -k.
- -dus iso_rr_pattern [***]
- List size of directories and files in the ISO image which match one of the
patterns. Similar to shell command du -sk.
- -dux disk_pattern [***]
- Recursively list size of directories and files in the local filesystem
which match one of the patterns. Similar to shell command du -k.
- -dusx disk_pattern [***]
- List size of directories and files in the local filesystem which match one
of the patterns. Similar to shell command du -sk.
- -findx disk_path [-name pattern] [-type t] [-exec action [params]]
--
- Like -find but operating on local filesystem and not on the ISO image.
This is subject to the settings of -follow.
-findx accepts the same -type parameters as -find. Additionally it
recognizes type "mountpoint" (or "m") which matches
subdirectories which reside on a different device than their parent. It
never matches the disk_path given as start address for -findx.
-findx accepts the -exec actions as does -find. But except the following few
actions it will always perform action "echo".
in_iso reports the path if its counterpart exists in the ISO image.
For this the disk_path of the -findx command gets replaced by the
iso_rr_path given as parameter.
E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd --
not_in_iso reports the path if its counterpart does not exist in the
ISO image. The report format is the same as with command -compare.
add_missing iso_rr_path_start adds the counterpart if it does not yet
exist in the ISO image and marks it for "rm_merge" as
non-removable.
E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd --
is_full_in_iso reports if the counterpart in the ISO image contains
files. To be used with -type "m" to report mount points.
empty_iso_dir deletes all files from the counterpart in the ISO
image. To be used with -type "m" to truncate mount points.
estimate_size prints a lower and an upper estimation of the number of
blocks which the found files together will occupy in the emerging ISO
image. This does not account for the superblock, for the directories in
the -findx path, or for image padding.
list_extattr mode prints a script to the result channel, which would
use FreeBSD command setextattr to set the file's xattr name-value pairs of
user namespace. See -find for a description of parameter mode.
E.g. -exec list_extattr e --
- -compare disk_path iso_rr_path
- Compare attributes and eventual data file content of a fileobject in the
local filesystem with a file object in the ISO image. The iso_rr_path may
well point to an image file object which is not yet committed, i.e. of
which the data content still resides in the local filesystem. Such data
content is prone to externally caused changes.
If iso_rr_path is empty then disk_path is used as path in the ISO image too.
Differing attributes are reported in detail, differing content is
summarized. Both to the result channel. In case of no differences no
result lines are emitted.
- -compare_r disk_path iso_rr_path
- Like -compare but working recursively. I.e. all file objects below both
addresses get compared whether they have counterparts below the other
address and whether both counterparts match.
- -compare_l disk_prefix iso_rr_prefix disk_path [***]
- Perform -compare_r with each of the disk_path parameters. iso_rr_path will
be composed from disk_path by replacing disk_prefix by iso_rr_prefix.
- -show_stream iso_rr_path [***]
- Display the content stream chain of data files in the ISO image. The chain
consists of the iso_rr_name and one or more streams, separated by "
< " marks. A stream description consists of one or more texts,
separated by ":" characters. The first text tells the stream
type, the following ones, if ever, describe its individual properties.
Frequently used types are:
disk:'disk_path' for local filesystem objects.
image:'iso_rr_path' for ISO image file objects.
cout:'disk_path offset count' for -cut_out files.
extf:'filter_name' for external filters.
Example:
'/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
- -show_stream_r iso_rr_path [***]
- Like -show_stream but working recursively.
- Evaluation of readability and recovery:
It is not uncommon that optical media produce read errors. The
reasons may be various and get obscured by error correction which is
performed by the drives and based on extra data on the media. If a drive
returns data then one can quite trust that they are valid. But at some
degree of read problems the correction will fail and the drive is supposed
to indicate error.
xorriso can scan a medium for readable data blocks, classify them
according to their read speed, save them to a file, and keep track of
successfully saved blocks for further tries on the same medium.
By command -md5 checksums may get recorded with data files and whole sessions.
These checksums are reachable only via indev and a loaded image. They work
independently of the media type and can detect transmission errors.
- -check_media [option [option ...]] --
- Try to read data blocks from the indev drive, optionally copy them to a
disk file, and finally report about the encountered quality. Several
options may be used to modify the default behavior.
The parameters given with this command override the default settings which
may have been changed by command -check_media_defaults. See there for a
description of available options.
The result list tells intervals of 2 KiB blocks with start address, number
of blocks and quality. Qualities which begin with "+" are
supposed to be valid readable data. Qualities with "-" are
unreadable or corrupted data. "0" indicates qualities which are
not covered by the check run or are regularly allowed to be unreadable
(e.g. gaps between tracks).
Alternatively it is possible to report damaged files rather than blocks.
If -md5 is "on" then the default mode what=tracks looks out for
libisofs checksum tags for the ISO session data and checks them against
the checksums computed from the data stream.
- -check_media_defaults [option [option ...]] --
- Preset options for runs of -check_media, -extract_cut and best_effort file
extraction. Options given with -check_media will override the preset
options. -extract_cut will override some options automatically.
An option consists of a keyword, a "=" character, and a value.
Options may override each other. So their sequence matters.
The default setting at program start is:
use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
time_limit=28800 item_limit=100000 data_to='' event=ALL
abort_file=/var/opt/xorriso/do_abort_check_media
sector_map='' map_with_volid=off patch_lba0=off report=blocks
bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0
Option "reset=now" restores these startup defaults.
Non-default options are:
report="files" lists the files which use damaged blocks
(not with use=outdev). The format is like with find -exec report_damage.
Note that a MD5 session mismatch marks all files of the session as
damaged. If finer distinction is desired, perform -md5 off before
-check_media.
report="blocks_files" first lists damaged blocks and then
affected files.
use="outdev" reads from the output drive instead of the
input drive. This avoids loading the ISO image tree from media.
use="sector_map" does not read any media but loads the file
given by option sector_map= and processes this virtual outcome.
what="disc" scans the payload range of a medium without
respecting track gaps.
what="image" similar to "disc", but restricts
scanning to the range of the ISO 9660 image, if present.
min_lba=limit omits all blocks with addresses lower than limit.
max_lba=limit switches to what=disc and omits all blocks above limit.
chunk_size=size sets the number of bytes to be read in one low-level
read operation. This gets rounded down to full blocks of 2048 bytes. 0
means automatic size.
retry="on" forces read retries with minimal senseful chunk
size when the normal read chunk produces a read error. This size is 1s
with CD and stdio files, 16s with DVD (1 ECC Block), and 32s with BD (1
Cluster). By default, retries are only enabled with CD media.
"retry=off" forbits retries for all media types.
abort_file=disk_path gives the path of the file which may abort a
scan run. Abort happens if the file exists and its mtime is not older than
the start time of the run. Use shell command "touch" to trigger
this. Other than an aborted program run, this will report the tested and
untested blocks and go on with running xorriso.
time_limit=seconds gives the number of seconds after which the scan
shall be aborted. This is useful for unattended scanning of media which
may else overwork the drive in its effort to squeeze out some readable
blocks. Abort may be delayed by the drive gnawing on the last single read
operation. Value -1 means unlimited time.
item_limit=number gives the number of report list items after which
to abort. Value -1 means unlimited item number.
data_to=disk_path copies the valid blocks to the given file.
event=severity sets the given severity for a problem event which
shall be issued at the end of a check run if data blocks were unreadable
or failed to match recorded MD5 checksums. Severity "ALL"
disables this event.
sector_map=disk_path tries to read the file given by disk_path as
sector bitmap and to store such a map file after the scan run. The bitmap
tells which blocks have been read successfully in previous runs. It is the
persistent memory for several scans on the same medium, even with
intermediate eject, in order to collect readable blocks whenever the drive
is lucky enough to produce them. The stored file contains a human readable
TOC of tracks and their start block addresses, followed by binary bitmap
data.
By default, untested blocks are not considered bad, but rather as
intentionally unread. If you expect time_limit= or item_limit= to abort
the run, then consider to use bad_limit="untested".
map_with_volid="on" examines tracks whether they are ISO
images and prints their volume IDs into the human readable TOC of
sector_map=.
patch_lba0="on" transfers within the data_to= file a copy
of the currently loaded session head to the start of that file and patches
it to be valid at that position. This makes the loaded session the last
valid session of the image file when it gets mounted or loaded as stdio:
drive. New sessions will be appended after this last session and will
overwrite any sessions which have followed it.
patch_lba0="force" performs patch_lba0="on" even
if xorriso believes that the copied data are not valid.
patch_lba0= may also bear a number. If it is 32 or higher it is taken as
start address of the session to be copied. In this case it is not
necessary to have an -indev and a loaded image. ":force" may be
appended after the number.
bad_limit=threshold sets the highest quality which shall be
considered as damage. Choose one of "good",
"md5_match", "slow", "partial",
"valid", "untested", "md5_mismatch",
"invalid", "tao_end", "off_track",
"unreadable".
"valid" and "invalid" are qualities imported from a
sector_map file. "tao_end" and "off_track" are
intentionally not readable, but not bad either. "partial" are
blocks retrieved from a partially readable chunk. They are supposed to be
ok but stem from a suspicious neighborhood.
"md5_match" and "md5_mismatch" regions overlap with
regions of other quality. The former is a strong confirmation for quality,
the latter only tells that one or more blocks of the region must be wrong.
By default bad_limit is set higher than md5_mismatch, so that mismatches are
classified as quality class "0" rather than "-". This
means that the sectors of a MD5 mismatch range are recorded in the
sector_map as successfully read, if the drive handed them out at all. Set
"bad_limit=md5_mismatch" to let the sector_map record the whole
mismatching range as yet not retrieved.
slow_limit=threshold sets the time threshold for a single read chunk
to be considered slow. This may be a fractional number like 0.1 or 1.5.
async_chunks=number enables asynchronous MD5 processing if number is
2 or larger. In this case the given number of read chunks is allocated as
fifo buffer. On very fast MMC drives try: chunk_size=64s
async_chunks=16.
- -check_md5 severity iso_rr_path [***]
- Compare the data content of the given files in the loaded image with their
recorded MD5 checksums, if there are any. In case of any mismatch an event
of the given severity is issued. It may then be handled by appropriate
settings of commands -abort_on or -return_with which both can cause
non-zero exit values of the program run. Severity ALL suppresses that
event.
This command reports match and mismatch of data files to the result channel.
Non-data files cause NOTE events. There will also be UPDATE events from
data reading.
If no iso_rr_path is given then the whole loaded session is compared with
its MD5 sum. Be aware that this covers only one session and not the whole
image if there are older sessions.
- -check_md5_r severity iso_rr_path [***]
- Like -check_md5 but checking all data files underneath the given paths.
Only mismatching data files will be reported.
- osirrox ISO-to-disk restore commands:
Normally xorriso only writes to disk files which were given
as stdio: pseudo-drives or as log files. But its alter ego osirrox is able
to extract file objects from ISO images and to create, overwrite, or delete
file objects on disk.
Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply. If disk file
objects already exist then the settings of -overwrite and -reassure apply.
But -overwrite "on" only triggers the behavior of -overwrite
"nondir". I.e. directories cannot be deleted.
Access permissions of files in the ISO image do not restrict restoring. The
directory permissions on disk have to allow rwx.
- -osirrox setting[:option:...]
- Setting "off" disables disk filesystem manipulations. This is
the default unless the program was started with leafname
"osirrox". Elsewise the capability to restore files can be
enabled explicitly by -osirrox "on". It can be irrevocably
disabled by -osirrox "banned".
The setting "blocked" is like "off". But it can only be
revoked by setting "unblock", which elsewise is like
"on". This can be used to curb command scripts which might use
"on" undesiredly.
To enable restoring of special files by "device_files" is
potentially dangerous. The meaning of the number st_rdev (see man 2 stat)
depends much on the operating system. Best is to restore device files only
to the same system from where they were copied. If not enabled, device
files in the ISO image are ignored during restore operations.
Due to a bug of previous versions, device files from previous sessions might
have been altered to major=0, minor=1. So this combination does not get
restored.
Option "concat_split_on" is default. It enables restoring of split
file directories as data files if the directory contains a complete
collection of -cut_out part files. With option
"concat_split_off" such directories are handled like any other
ISO image directory.
Option "auto_chmod_off" is default. If "auto_chmod_on"
is set then access restrictions for disk directories get circumvented if
those directories are owned by the effective user who runs xorriso.
This happens by temporarily granting rwx permission to the owner.
Option "sort_lba_on" may improve read performance with optical
drives. It can restore large numbers of hard links without exhausting
-temp_mem_limit. It does not preserve directory mtime and it needs
-osirrox option auto_chmod_on in order to extract directories which offer
no write permission. Default is "sort_lba_off".
Option "o_excl_on" is the default unless the program was started
with leafname "osirrox". On GNU/Linux it tries to avoid using
drives which are mounted or in use by other libburn programs. Option
"o_excl_off" on GNU/Linux enables access to such drives by the
equivalent of -drive_access "shared:readonly". I.e. drives which
get acquired while "o_excl_off" will refuse to get blanked,
formatted, written, or ejected. But be aware that even harmless inquiries
can spoil ongoing burns of CD-R[W] and DVD-R[W].
Option "strict_acl_off" is default. It tolerates on FreeBSD the
presence of directory "default" ACLs in the ISO image. With
"strict_acl_on" these GNU/Linux ACLs cause on FreeBSD a FAILURE
event during restore with -acl "on".
- -extract iso_rr_path disk_path
- Copy the file objects at and underneath iso_rr_path to their corresponding
addresses at and underneath disk_path. This is the inverse of -map or
-update_r.
If iso_rr_path is a directory and disk_path is an existing directory then
both trees will be merged. Directory attributes get extracted only if the
disk directory is newly created by the copy operation. Disk files get
removed only if they are to be replaced by file objects from the ISO
image.
As many attributes as possible are copied together with restored file
objects.
- -extract_single iso_rr_path disk_path
- Like -extract, but if iso_rr_path is a directory then its sub tree gets
not restored.
- -extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
- Perform -extract with each of the iso_rr_path parameters. disk_path will
be composed from iso_rr_path by replacing iso_rr_prefix by
disk_prefix.
- -extract_cut iso_rr_path byte_offset byte_count disk_path
- Copy a byte interval from a data file out of an ISO image into a newly
created disk file. The main purpose for this is to offer a way of handling
large files if they are not supported by mount -t iso9660 or if the target
disk filesystem cannot store large files.
If the data bytes of iso_rr_path are stored in the loaded ISO image, and no
filter is applied, and byte_offset is a multiple of 2048, then a special
run of -check_media is performed. It may be quicker and more rugged than
the general reading method.
- -cpx iso_rr_path [***] disk_path
- Copy single leaf file objects from the ISO image to the address given by
disk_path. If more then one iso_rr_path is given then disk_path must be a
directory or non-existent. In the latter case it gets created and the
extracted files get installed in it with the same leafnames.
Missing directory components in disk_path will get created, if possible.
Directories are allowed as iso_rr_path only with -osirrox
"concat_split_on" and only if they actually represent a complete
collection of -cut_out split file parts.
- -cpax iso_rr_path [***] disk_path
- Like -cpx but restoring mtime, atime as in ISO image and trying to set
ownership and group as in ISO image.
- -cp_rx iso_rr_path [***] disk_path
- Like -cpx but also extracting whole directory trees from the ISO image.
The resulting disk paths are determined as with shell command cp -r : If
disk_path is an existing directory then the trees will be inserted or
merged underneath this directory and will keep their leaf names. The ISO
directory "/" has no leaf name and thus gets mapped directly to
disk_path.
- -cp_rax iso_rr_path [***] disk_path
- Like -cp_rx but restoring mtime, atime as in ISO image and trying to set
ownership and group as in ISO image.
- -paste_in iso_rr_path disk_path byte_offset byte_count
- Read the content of a ISO data file and write it into a data file on disk
beginning at the byte_offset. Write at most byte_count bytes. This is the
inverse of command -cut_out.
- -concat mode [target | lim prog [args [...]] lim] iso_rr_path
[***]
- Copy the data content of one or more data files of the ISO image into a
disk file object, into a file descriptor, or start a program and copy the
data into its standard input. The latter is subject to the security
restrictions for external filters.
Modes overwrite and append write into the target which is
given by the second parameter. This may be the path to a disk file object,
or "-" which means standard output, or a text of the form
/dev/fd/number, where number is an open file descriptor (e.g. standard
error is /dev/fd/2). An existing target file is not removed before writing
begins. If it is not able to take content data, then this command fails.
Mode overwrite truncates regular data files to 0 size before writing into
them. Example:
-concat append /home/me/accumulated_text /my/iso/text --
Mode pipe expects as second parameter a delimiter word
which shall mark the end of the program argument list. The third
argument is the disk_path to the program. It must contain at least one
'/'. $PATH is not applied. Further parameters up to the announced
delimiter word are used as arguments with the program start. Example:
-iso_rr_pattern on \
-concat pipe + /usr/bin/wc + "/my/iso/files*" --
The further parameters in all modes are the iso_rr_paths of
data files. Their content gets concatenated in the copy.
- -mount drive entity id path
- Produce the same line as -mount_cmd and then execute it as external
program run after giving up the depicted drive. See also -mount_opts. This
demands -osirrox to be enabled and normally will succeed only for the
superuser. For safety reasons the mount program is only executed if it is
reachable as /bin/mount or /sbin/mount.
- Command compatibility emulations:
Writing of ISO 9660 on CD is traditionally done by program mkisofs
as ISO 9660 image producer and cdrecord as burn program. xorriso does
not strive for their comprehensive emulation. Nevertheless it is ready to
perform some of its core tasks under control of commands which in said
programs trigger comparable actions.
- -as personality option [options] --
-
Perform the variable length option list as sparse emulation of the program
depicted by the personality word.
Personality "mkisofs" accepts the options
listed with:
-as mkisofs -help --
Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mode, -file-mode,
-path-list, -m, -exclude-list, -f, -print-size, -pad, -no-pad, -V, -v,
-version, -graft-points, -z, -no-emul-boot, -b, -c, -boot-info-table,
-boot-load-size, -input-charset, -G, -output-charset, -U, -hide,
-hide-joliet, -hide-list, -hide-joliet-list, file paths and pathspecs. A
lot of options are not supported and lead to failure of the mkisofs
emulation. Some are ignored, but better do not rely on this tolerance.
The supported options are documented in detail in xorrisofs.info and in
man xorrisofs. The description here is focused on the effect of mkisofs
emulation in the context of a xorriso run.
Other than with the "cdrecord" personality there is no automatic
-commit at the end of a "mkisofs" option list. Verbosity
settings -v (= "UPDATE") and -quiet (= "SORRY")
persist. The output file persists until things happen like -commit,
-rollback, -dev, or end of xorriso.
Options which affect all file objects in the ISO image, like -r or
-dir-mode, will be applied only to files which are present in the ISO
image when the command -as ends. If you use several -as mkisofs commands
in the same run, then consider to put such options into the last -as
command.
If files are added to the image, then -pacifier gets set to
"mkisofs" and -stdio_sync is defaulted to "off" if
no such setting was made yet.
-graft-points is equivalent to -pathspecs on. Note that pathspecs without
"=" are interpreted differently than with xorriso
command -add. Directories get merged with the root directory of the ISO
image, other filetypes get mapped into that root directory.
If pathspecs are given and if no output file was chosen before or during
the "mkisofs" option list, then standard output (-outdev
"-") will get into effect. If -o points to a regular file,
then it will be truncated to 0 bytes when finally writing begins. This
truncation does not happen if the drive is chosen by xorriso
commands before -as mkisofs or after its list delimiter. Directories and
symbolic links are no valid -o targets.
Writing to stdout is possible only if -as "mkisofs" was among
the start arguments or if other start arguments pointed the output drive
to standard output.
-print-size inhibits automatic image production at program end. This ban
is lifted only if the pending image changes get discarded.
Padding is counted as part of the ISO image if not option --emul-toc is
given.
If no -iso-level is given, then level 1 is chosen when the first file or
directory is added to the image. At the same occasion directory names
get allowed to violate the standard by -compliance option
allow_dir_id_ext. This may be avoided by option -disallow_dir_id_ext.
Option -root is supported. Option -old-root is implemented by
xorriso commands -mkdir, -cp_clone, -find update_merge, and -find
rm_merge. -root and -old-root set command -disk_dev_ino to
"ino_only" and -md5 to "on", by default.
-disk_dev_ino can be set to "off" by --old-root-no-ino or to
"on" by --old-root-devno . -md5 can be set to "off"
by --old-root-no-md5 .
Not original mkisofs options are --quoted_path_list , --hardlinks , --acl
, --xattr , --md5 , --stdio_sync . They work like the xorriso
commands with the same name and hardcoded parameter "on", e.g.
-acl "on". Explicit parameters are expected by --stdio_sync
and --scdbackup_tag.
The capability to preserve multi-session history on overwriteable media
gets disabled by default. It can be enabled by using --emul-toc with the
first session. See -compliance no_emul_toc.
--sort-weight gets as parameters a number and an iso_rr_path. The number
becomes the LBA sorting weight of regular file iso_rr_path or of all
regular files underneath directory iso_rr_path. (See -find -exec
sort_weight).
Adopted from grub-mkisofs are --protective-msdos-label (see -boot_image
grub partition_table=on) and --modification-date=YYYYMMDDhhmmsscc (see
-volume_date uuid). For EFI bootable GRUB boot images use --efi-boot. It
performs -boot_image grub efi_path= surrounded by two -boot_image
"any" "next". Alternative option -e from Fedora
genisoimage sets bin_path and platform_id for EFI, but performs no
"next".
For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE, where FILE
is one of the Syslinux files mbr/isohdp[fp]x*.bin . Use this instead of
-G to apply the effect of -boot_image isolinux partition_table=on.
--boot-catalog-hide is -boot_image any cat_hidden=on.
-mips-boot is the same as -boot_image any mips_path= .
-mipsel-boot leads to mipsel_path= .
-partition_offset number is -boot_image any partition_offset=number.
Command -append_partition is supported.
-untranslated_name_len number is -compliance untranslated_name_len=number.
--old-empty is -compliance old_empty.
The options of genisoimage Jigdo Template Extraction are recognized and
performed via xorriso command -jigdo. See the "Alias:"
names there for the meaning of the genisoimage options.
Personalities "xorrisofs",
"genisoimage", and "genisofs" are
aliases for "mkisofs".
If xorriso is started with one of the leafnames
"xorrisofs", "genisofs", "mkisofs", or
"genisoimage", then it performs -read_mkisofsrc and prepends
-as "genisofs" to the program arguments. I.e. all arguments
will be interpreted mkisofs style until "--" is encountered.
From then on, arguments are interpreted as xorriso commands.
--no_rc as first argument of such a program start prevents interpretation
of startup files. See section FILES below.
Personality "cdrecord" accepts the options
listed with:
-as cdrecord -help --
Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=,
tsize=, -isosize, -multi, -msinfo, --grow_overwriteable_iso,
write_start_address=, track source file path or "-" for
standard input as track source.
It ignores most other options of cdrecord and cdrskin but refuses on
-audio, -scanbus, and on blanking modes unknown to xorriso.
The scope is only a single data track per session to be written to blank,
overwriteable, or appendable media. The medium gets closed if closing is
applicable and not option -multi is present.
If an input drive was acquired, then it is given up. This is only allowed
if no image changes are pending.
dev= must be given as xorriso device address. Addresses like 0,0,0
or ATA:1,1,0 are not supported.
If a track source is given, then an automatic -commit happens at the end
of the "cdrecord" option list.
--grow_overwriteable_iso enables emulation of multi-session on
overwriteable media. To enable emulation of a TOC, the first session
needs -C 0,32 with -as mkisofs (but no -M) and --grow_overwriteable_iso
write_start_address=32s with -as cdrecord.
A much more elaborate libburn based cdrecord emulator is the program
cdrskin.
Personalites "xorrecord", "wodim", and
"cdrskin" are aliases for "cdrecord".
If xorriso is started with one of the leafnames
"xorrecord", "cdrskin", "cdrecord", or
"wodim", then it automatically prepends -as
"cdrskin" to the program arguments. I.e. all arguments will be
interpreted cdrecord style until "--" is encountered. From
then on, arguments are interpreted as xorriso commands.
--no_rc as first argument of such a program start prevents interpretation
of xorriso startup files. See section FILES below.
- -read_mkisofsrc
- Try one by one to open for reading:
./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc , $(dirname $0)/.mkisofsrc
On success interpret the file content as of man mkisofs CONFIGURATION, and
end this command. Do not try further files. The last address is used only
if start argument 0 has a non-trivial dirname.
The reader currently interprets the following NAME=VALUE pairs: APPI
(-application_id) , PUBL (-publisher) , SYSI (-system_id) , VOLI (-volid)
, VOLS (-volset_id)
Any other lines will be silently ignored.
- -pacifier behavior_code
- Control behavior of UPDATE pacifiers during write operations. The
following behavior codes are defined:
"xorriso" is the default format:
Writing: sector XXXXX of YYYYYY [fifo active, nn% fill]
"cdrecord" looks like:
X of Y MB written (fifo nn%) [buf mmm%]
"mkisofs"
nn% done, estimate finish Tue Jul 15 20:13:28 2008
The frequency of the messages can be adjusted by
"interval=number"
where number gives the seconds between two messages. Permissible settings
are 0.1 to 60.0.
- -scdbackup_tag list_path record_name
- Set the parameter "name" for a scdbackup checksum record. It
will be appended in an scdbackup checksum tag to the -md5 session tag if
the image starts at LBA 0. This is the case if it gets written as first
session onto a sequential medium, or piped into a program, named pipe or
character device.
If list_path is not empty then the record will also be appended to the data
file given by this path.
Program scdbackup_verify will recognize and verify tag and file record.
An empty record_name disables this feature.
- Scripting, dialog and program control features:
- -no_rc
-
Only if used as first program argument this command prevents reading and
interpretation of startup files. See section FILES below.
- -options_from_file fileaddress
- Read quoted input from fileaddress and execute it like dialog lines. Empty
lines and lines which begin by # are ignored. Normally one line should
hold one xorriso command and all its parameters. Nevertheless lines
may be concatenated by a trailing backslash.
See also section "Command processing", paragraph "Quoted
input".
- -help
-
Print helptext.
- -version
- Print program name and version, component versions, license.
- -list_extras code
- Tell whether certain extra features were enabled at compile time. Code
"all" lists all features and a headline. Other codes pick a
single feature. Code "codes" lists them. They share names with
related commands (see also there):
"acl" tells whether xorriso has an adapter for local filesystems
ACLs.
"xattr" tells whether xorriso has an adapter for local filesystems
EA.
"jigdo" tells whether production of Jigdo files is possible.
"zisofs" tells whether zisofs and built-in gzip filters are
enabled.
"external_filter" tells whether external filter processes are
allowed and whether they are allowed if real user id and effective user id
differ.
"dvd_obs" tells whether 64 kB output to DVD media is default.
"use_readline" tells whether readline may be enabled in dialog
mode.
- -history textline
- Copy textline into libreadline history.
- -status mode|filter
- Print the current settings of xorriso. Modes:
short... print only important or altered settings
long ... print all settings including defaults
long_history like long plus history lines
Filters begin with '-' and are compared literally against the output lines
of -status:long_history. A line is put out only if its start matches the
filter text. No wildcards.
- -status_history_max number
- Set maximum number of history lines to be reported with -status
"long_history".
- -list_delimiter word
- Set the list delimiter to be used instead of "--". It has to be
a single word, must not be empty, not longer than 80 characters, and must
not contain quotation marks.
For brevity the list delimiter is referred as "--" throughout this
text.
- -sh_style_result "on"|"off"
- Make the result output of some filesystem inspection commands look more
like the output of equivalent shell commands. The most important effect is
to prevent the wrapping of file addresses into quotation marks with
commands
-pwd -pwdx -ls -lsd -lsl -lsdl -lsx -lsdx -lslx -lsdlx
-du -dus -dux -dusx -findx -find
This will make ambiguous the representation of file names which contain
newline characters. On the other hand it should facilitate integration of
xorriso into shell scripts which already use the corresponding shell
commands.
- -backslash_codes "on"|"off"|mode[:mode]
- Enable or disable the interpretation of symbolic representations of
special characters with quoted input, or with program arguments, or with
program text output. If enabled the following translations apply:
\a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
\n=linefeed(012) \r=carriage_return(015) \t=tab(011)
\v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code
\x[0-9a-f][0-9a-f]=hex_code \cC=control-C
Translations can occur with quoted input in 3 modes:
"in_double_quotes" translates only inside " quotation.
"in_quotes" translates inside " and ' quotation.
"with_quoted_input" translates inside and outside quotes.
With the start program arguments there is mode:
"with_program_arguments" translates program arguments.
Mode "encode_output" encodes output characters. It combines
"encode_results" with "encode_infos". Inside single or
double quotation marks encoding applies to 8-bit characters octal 001 to
037 , 177 to 377 and to backslash(134).
Mode "off" is default and disables any translation. Mode
"on" is
"with_quoted_input:with_program_arguments:encode_output".
- -temp_mem_limit number["k"|"m"]
- Set the maximum size of temporary memory to be used for image dependent
buffering. Currently this applies to pattern expansion, LBA sorting,
restoring of hard links.
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB.
- -print text
- Print a text line to the result channel which is by default stdout.
- -print_info text
- Print a text line to the info channel which is by default stderr.
- -print_mark text
- Print a text line to the mark channel which is by default directed to
both, result and info channel. An empty text will cause no output at
all.
- -prompt text
- Show text at beginning of output line and wait for the user to hit the
Enter key or to send a line via stdin.
- -sleep seconds
- Wait for the given number of seconds before performing the next command.
Expect coarse granularity no better than 1/100 seconds.
- -errfile_log mode path|channel
-
If problem events are related to input files from the filesystem, then their
disk_paths can be logged to a file or to output channels R or I.
Mode can either be "plain" or "marked". The latter
causes marker lines which give the time of log start, burn session start,
burn session end, log end or program end. In mode "plain", only
the file paths are logged.
If path is "-" or "-R" then the log is directed to the
result channel. Path "-I" directs it to the info message
channel. Any text that does not begin with "-" is used as path
for a file to append the log lines.
Problematic files can be recorded multiple times during one program run. If
the program run aborts then the list might not be complete because some
input files might not have been processed at all.
The errfile paths are transported as messages of very low severity
"ERRFILE". This transport becomes visible with -report_about
"ALL".
- -session_log path
- If path is not empty it gives the address of a plain text file where a log
record gets appended after each session. This log can be used to determine
the start_lba of a session for mount options -o sbsector= (on GNU/Linux)
or -s (on FreeBSD) from date or volume ID.
Record format is: timestamp start_lba size volume-id
The first three items are single words, the rest of the line is the volume
ID.
- -scsi_log "on"|"off"
- Mode "on" enables very verbose logging of SCSI commands and
drive replies. Logging messages get printed to stderr, not to any of the
xorriso output channels.
A special property of this command is that the first -scsi_log setting among
the start arguments is in effect already when the first operations of
xorriso begin. Only "-scsi_log" with dash "-"
is recognized that way.
- -end
-
End program after writing pending changes.
- -rollback_end
- Discard pending changes. End program immediately.
- # any text
- Only in dialog or file execution mode, and only as first non-whitespace in
line: Do not execute the line but store it in readline history.
- Support for frontend programs via stdin and stdout:
- -pkt_output "on"|"off"
- Consolidate text output on stdout and classify each line by a channel
indicator:
'R:' for result lines,
'I:' for notes and error messages,
'M:' for -mark texts.
Next is a decimal number of which only bit 0 has a meaning for now. 0 means
no newline at end of payload, 1 means that the newline character at the
end of the output line belongs to the payload. After another colon and a
blank follows the payload text.
Example:
I:1: enter option and parameters :
- -logfile channel fileaddress
- Copy output of a channel to the given file. Channel may be one of:
"." for all channels, "I" for info messages,
"R" for result lines, "M" for -mark texts.
- -mark text
- If text is not empty it will get put out on "M" channel each
time xorriso is ready for the next dialog line or before
xorriso performs a command that was entered to the pager
prompt.
- -msg_op opcode parameter_text
- This command shall facilitate extraction of particular information from
the message output of other commands. It gives access to the C API
function Xorriso_parse_line() and to the message sieve that is provided by
the C API. Please refer to their descriptions in file xorriso.h. Further
it helps to interpret the severity codes of info messages.
Intended users are frontend programs which operate xorriso in dialog mode.
The result output of this command is not caught by the message sieve.
The following opcodes are defined:
start_sieve
Install the message sieve as of Xorriso_sieve_big() and start watching
program messages. The parameter_text has no meaning.
show_sieve
Show a list of filter rule names. The parameter_text has no meaning. The
list begins by a line with the return value of Xorriso_sieve_get_result()
with flag bit3. If this value is larger than 0, then the next line tells
the number of names. The following lines show one name each.
read_sieve
Use the parameter_text as name of a filter rule and inquire its next
recorded result. See Xorriso_sieve_big() for a list of names and reply
strings.
The recorded strings are put out on result channel. They get wrapped into
lines which tell their structure. The first line tells the return value of
Xorriso_sieve_get_result(). The next line tells the number of strings.
Each string begins by a line that tells the number of lines of the string.
Then follow these lines. They are to be concatenated with a newline
character between each of them. Finally the number of still available
recorded results of the given name is put out.
clear_sieve
Dispose all recorded strings and continue watching program messages. The
parameter_text has no meaning.
end_sieve
Dispose the sieve with its filter rules and stop watching program messages.
The parameter_text has no meaning.
parse
Read a text from dialog input and submit it to Xorriso_parse_line(). The
parameter_text word shall consist of several words separated by blanks. It
will be necessary to use both kinds of quotation marks.
E.g. "'ISO session :' '' 0 0 1"
The five parameter words are: prefix, separators, max_words, flag,
number_of_input_lines. The former four are handed over to
Xorriso_parse_line(). The number of input lines minus one tells xorriso
how many newline characters are part of the input text.
The announced number of text lines will be read from dialog input,
concatenated with a newline character between each of them, and submitted
to Xorriso_parse_line() as parameter line. Note that newlines outside of
quotation marks are interpreted as separators if the separators parameter
is empty.
The parsed strings are put out on result channel. They get wrapped into
lines which tell their structure. The first line tells the return value of
Xorriso_parse_line(). The next line tells the number of strings. Each
string begins by a line that tells the number of lines of the string. Then
follow these lines. They are to be concatenated with a newline character
between each of them.
If -backslash_codes "encode_output" is enabled, then the strings
undergo encoding as if they were enclosed in quotes. Escpecially each
string will be put out as a single result line.
parse_bulk
Like "parse", but with the fifth parameter word being
number_of_input_texts rather than number_of_input_lines. Each input text
has to be preceded by a line that tells number_of_input_lines as with
"parse". Then come the announced number of text lines.
All input texts will be read before printing of result lines begins. This
consumes memory in xorriso. So the number_of_input_texts should not be
extremely high. On the other hand, large transactions of command, input
texts, and results are desirable if connection latency is an issue.
parse_silently
Like "parse" but not issuing a prompting message. Confusing to
humans.
parse_bulk_silently
Like "parse_bulk" but not issuing a prompting message. Confusing
to humans.
compare_sev
The parameter_text should contain two comma separated severity texts as
issued by this program. Like "SORRY,UPDATE". See also paragraph
"Exception processing".
These two severity texts get compared and a number gets printed to the
result channel. This number is 0 if both severities are equal. It is -1 if
the first severity is lower than the second one. It is 1 is the first
severity is higher than the second one.
Above example "SORRY,UPDATE" will yield 1.
list_sev
Print to the result channel a blank separated list of all severity names.
Sorted from low to high severity.
- -named_pipe_loop mode[:mode] disk_path_stdin disk_path_stdout
disk_path_stderr
- Temporarily replace standard input, standard output and standard error by
named pipes. Enter dialog mode without readline.
Defined modes are:
"cleanup" removes the submitted pipe files when the loop ends.
"keep" does not delete them. This is the default.
"buffered" reads all lines from the input pipe until EOF before it
opens the output pipes and processes the input lines.
"direct" opens the output pipes after the first input line was
read. Each line is executed directly after it is read. This is the
default.
The other three parameters must either be disk paths to existing named
pipes, or be "-" to leave the according standard i/o channel
unreplaced.
xorriso will open the stdin pipe, read and execute dialog lines from it
until the sender closes the pipe. The output pipes get opened depending on
mode "buffered" or "direct". After all lines are
executed, xorriso will close its side of the pipes and enter a new cycle
of opening, reading and executing.
If an input line consists only of the word "end_named_pipe_loop"
then -named_pipe_loop will end and further xorriso commands may be
executed from other sources.
- -launch_frontend program [arguments ...] --
- Start the program that is given as first parameter. Submit the other
parameters as program arguments. Enable xorriso dialog mode.
Two nameless pipe objects are created. xorriso standard input gets connected
to the standard output of the started program. xorriso standard output and
standard error get connected to the standard input of that program.
xorriso will abort when the started program ends or if it cannot be started
at all. In both cases it will return a non-zero exit value. The exit value
will be zero if the frontend sends -end or -rollback_end before ending
itself.
This command may be totaly banned at compile time. It is banned by default
if xorriso runs under setuid permissions.
The program name will not be searched in the $PATH directories. To make this
clear, it must contain at least one /-character. Best is an absolute path.
Example:
xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio --
The frontend program should first send via its standard output:
-mark 0 -pkt_output on -msg_op start_sieve - -reassure off
It should be ready to decode -pkt_output and to react on -mark messages.
Best is to increment the -mark number after each sent command sequence and
then to wait for the new number to show up in a mark message:
...some...commands... -mark <incremented_number>
Further are advised:
-report_about UPDATE -abort_on NEVER
-iso_rr_pattern off -disk_pattern off
A check of the xorriso version should be done, in order to make sure that
all desired features are present.
Command -launch_frontend will only work once per xorriso run. If no command
parameters are submitted or if program is an empty text, then no program
will be started but nevertheless -launch_frontend will be irrevocably
disabled.
- -prog text
- Use text as name of this program in subsequent messages
- -prog_help text
- Use text as name of this program and perform -help.