"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "xorriso/xorriso.1" between
xorriso-1.5.2.tar.gz and xorriso-1.5.4.tar.gz

About: GNU xorriso creates, loads, manipulates and writes ISO 9660 filesystem images with Rock Ridge extensions. It is suitable for incremental data backup and for production of bootable ISO 9660 images. GNU xorriso is a statical compilation of the libraries libburn, libisofs, libisoburn, and libjte.

xorriso.1  (xorriso-1.5.2):xorriso.1  (xorriso-1.5.4)
skipping to change at line 34 skipping to change at line 34
Changes file properties in the ISO image. Changes file properties in the ISO image.
Updates ISO subtrees incrementally to match given disk subtrees. Updates ISO subtrees incrementally to match given disk subtrees.
Writes result either as completely new image or as add-on session to opti cal media or filesystem objects. Writes result either as completely new image or as add-on session to opti cal media or filesystem objects.
Can activate ISOLINUX and GRUB boot images via El Torito and MBR. Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
Can perform multi-session tasks as emulation of mkisofs and cdrecord. Can perform multi-session tasks as emulation of mkisofs and cdrecord.
Can record and restore hard links and ACL. Can record and restore hard links and ACL.
Content may get zisofs compressed or filtered by external processes. Content may get zisofs compressed or filtered by external processes.
Can issue commands to mount older sessions on GNU/Linux or FreeBSD. Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
Can check media for damages and copy readable blocks to disk. Can check media for damages and copy readable blocks to disk.
Can attach MD5 checksums to each data file and the whole session. Can attach MD5 checksums to each data file and the whole session.
Scans for optical drives, blanks re-useable optical media. Scans for optical drives, blanks re-usable optical media.
Reads its instructions from command line arguments, dialog, and files. Reads its instructions from command line arguments, dialog, and files.
Provides navigation commands for interactive ISO image manipulation. Provides navigation commands for interactive ISO image manipulation.
Adjustable thresholds for abort, exit value, and problem reporting. Adjustable thresholds for abort, exit value, and problem reporting.
Note that xorriso does not write audio CDs and that it does not produce UDF filesystems which are Note that xorriso does not write audio CDs and that it does not produce UDF filesystems which are
specified for official video DVD or BD. specified for official video DVD or BD.
General information paragraphs: General information paragraphs:
Session model Session model
Media types and states Media types and states
skipping to change at line 73 skipping to change at line 73
This session usage model has been extended on CD media by the conc ept of multi-session , which adds This session usage model has been extended on CD media by the conc ept of multi-session , which adds
information to the CD and gives the mount programs of the operating syste ms the addresses of the entry information to the CD and gives the mount programs of the operating syste ms the addresses of the entry
points of each session. The mount programs recognize block devices whi ch represent CD media and will by points of each session. The mount programs recognize block devices whi ch represent CD media and will by
default mount the image in the last session. default mount the image in the last session.
This session usually contains an updated directory tree for the whole medium which governs the data This session usually contains an updated directory tree for the whole medium which governs the data
contents in all recorded sessions. So in the view of the mount pro gram all sessions of a particular contents in all recorded sessions. So in the view of the mount pro gram all sessions of a particular
medium together form a single filesystem image. medium together form a single filesystem image.
Adding a session to an existing ISO image is in this text referred as gro wing. Adding a session to an existing ISO image is in this text referred as gro wing.
The multi-session model of the MMC standard does not apply to all media t ypes. But program growisofs by The multi-session model of the MMC standard does not apply to all media t ypes. But program growisofs by
Andy Polyakov showed how to extend this functionality to overwriteabl e media or disk files which carry Andy Polyakov showed how to extend this functionality to overwritabl e media or disk files which carry
valid ISO 9660 filesystems. valid ISO 9660 filesystems.
xorriso provides growing as well as an own method named modifying which produces a completely new ISO xorriso provides growing as well as an own method named modifying which produces a completely new ISO
image from the old one and the modifications. See paragraph Creating, Growing, Modifying, Blind Growing image from the old one and the modifications. See paragraph Creating, Growing, Modifying, Blind Growing
below. below.
xorriso adopts the concept of multi-session by loading an image directory tree if present, by offering to xorriso adopts the concept of multi-session by loading an image directory tree if present, by offering to
manipulate it by several actions, and by writing the new image to the tar get medium. manipulate it by several actions, and by writing the new image to the tar get medium.
The first session of a xorriso run begins by the definition of the inp ut drive with the ISO image or by The first session of a xorriso run begins by the definition of the inp ut drive with the ISO image or by
the definition of an output drive. The session ends by command -commit w hich triggers writing. A -commit the definition of an output drive. The session ends by command -commit w hich triggers writing. A -commit
skipping to change at line 102 skipping to change at line 102
done in a single session. But in principle it is possible to store in termediate states and to continue done in a single session. But in principle it is possible to store in termediate states and to continue
with image manipulations. with image manipulations.
Media types and states: Media types and states:
There are two families of media in the MMC standard: There are two families of media in the MMC standard:
Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and u nformatted DVD-RW. These media Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and u nformatted DVD-RW. These media
provide a table of content which describes their existing sessions. See c ommand -toc. provide a table of content which describes their existing sessions. See c ommand -toc.
Similar to multi-session media are DVD-R DL and minimally blanked D VD-RW. They record only a single Similar to multi-session media are DVD-R DL and minimally blanked D VD-RW. They record only a single
session of which the size must be known in advance. xorriso will write o nto them only if command -close session of which the size must be known in advance. xorriso will write o nto them only if command -close
is set to "on". is set to "on".
Overwriteable media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. T hey offer random write access but Overwritable media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. T hey offer random write access but
do not provide information about their session history. If they contain o ne or more ISO 9660 sessions and do not provide information about their session history. If they contain o ne or more ISO 9660 sessions and
if the first session was written by xorriso, then a table of content ca n be emulated. Else only a single if the first session was written by xorriso, then a table of content ca n be emulated. Else only a single
overall session will be visible. overall session will be visible.
DVD-RW media can be formatted by -format "full". They can be made unform atted by -blank "deformat". DVD-RW media can be formatted by -format "full". They can be made unform atted by -blank "deformat".
Regular files and block devices are handled as overwriteable media. Pipe s and other writeable file types Regular files and block devices are handled as overwritable media. Pipes and other writeable file types
are handled as blank multi-session media. are handled as blank multi-session media.
These media can assume several states in which they offer different capab ilities. These media can assume several states in which they offer different capab ilities.
Blank media can be written from scratch. They contain no ISO image suitab le for xorriso. Blank media can be written from scratch. They contain no ISO image suitab le for xorriso.
Blank is the state of newly purchased optical media. With used CD-RW and DVD-RW it can be achieved by Blank is the state of newly purchased optical media. With used CD-RW and DVD-RW it can be achieved by
action -blank "as_needed". Overwriteable media are considered blank if t action -blank "as_needed". Overwritable media are considered blank if th
hey are new or if they have been ey are new or if they have been
marked as blank by xorriso. Action -blank "as_needed" can be used to marked as blank by xorriso. Action -blank "as_needed" can be used t
do this marking on overwriteable o do this marking on overwritable
media, or to apply mandatory formatting to new media if necessary. media, or to apply mandatory formatting to new media if necessary.
Appendable media accept further sessions. Either they are MMC multi-sessi on media in appendable state, or Appendable media accept further sessions. Either they are MMC multi-sessi on media in appendable state, or
they are overwriteable media which contain an ISO image suitable for xorr iso. they are overwritable media which contain an ISO image suitable for xorri so.
Appendable is the state after writing a session with command -close off. Appendable is the state after writing a session with command -close off.
Closed media cannot be written. They may contain an ISO image suitable fo r xorriso. Closed media cannot be written. They may contain an ISO image suitable fo r xorriso.
Closed is the state of DVD-ROM media and of multi-session media which wer e written with command -close on. Closed is the state of DVD-ROM media and of multi-session media which wer e written with command -close on.
If the drive is read-only hardware then it will probably show any media a s closed CD-ROM or DVD-ROM. If the drive is read-only hardware then it will probably show any media a s closed CD-ROM or DVD-ROM.
Overwriteable media assume this state in such read-only drives or if they contain unrecognizable data in Overwritable media assume this state in such read-only drives or if they contain unrecognizable data in
the first 32 data blocks. the first 32 data blocks.
Read-only drives may or may not show session histories of multi-sessio n media. Often only the first and Read-only drives may or may not show session histories of multi-sessio n media. Often only the first and
the last session are visible. Sometimes not even that. Command -rom_toc_s can might or might not help in the last session are visible. Sometimes not even that. Command -rom_toc_s can might or might not help in
such cases. such cases.
Creating, Growing, Modifying, Blind Growing: Creating, Growing, Modifying, Blind Growing:
A new empty ISO image gets created if there is no input drive with a va lid ISO 9660 image when the first A new empty ISO image gets created if there is no input drive with a va lid ISO 9660 image when the first
time an output drive is defined. This is achieved by command -dev on blan k media or by command -outdev on time an output drive is defined. This is achieved by command -dev on blan k media or by command -outdev on
media in any state. media in any state.
The new empty image can be populated with directories and files. Before it can be written, the medium in The new empty image can be populated with directories and files. Before it can be written, the medium in
skipping to change at line 172 skipping to change at line 172
-load sbsector $msc1 -grow_blindly $msc2 -load sbsector $msc1 -grow_blindly $msc2
Libburn drives: Libburn drives:
Input drive, i.e. source of an existing or empty ISO image, can be a ny random access readable libburn Input drive, i.e. source of an existing or empty ISO image, can be a ny random access readable libburn
drive: optical media with readable data, blank optical media, regular fil es, block devices. drive: optical media with readable data, blank optical media, regular fil es, block devices.
Output drive, i.e. target for writing, can be any libburn drive. Some dr ive types do not support the Output drive, i.e. target for writing, can be any libburn drive. Some dr ive types do not support the
method of growing but only the methods of modifying and blind growing . They all are suitable for newly method of growing but only the methods of modifying and blind growing . They all are suitable for newly
created images. created images.
All drive file objects have to offer rw-permission to the user of xorriso . Even those which will not be All drive file objects have to offer rw-permission to the user of xorriso . Even those which will not be
useable for reading an ISO image. usable for reading an ISO image.
With any type of drive object, the data are considered to be organized i n blocks of 2 KiB. Access happens With any type of drive object, the data are considered to be organized i n blocks of 2 KiB. Access happens
in terms of Logical Block Address (LBA) which gives the number of a parti cular data block. in terms of Logical Block Address (LBA) which gives the number of a parti cular data block.
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by the path of their block device MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by the path of their block device
or of their generic character device. E.g. or of their generic character device. E.g.
-dev /dev/sr0 -dev /dev/sr0
-dev /dev/hdc -dev /dev/hdc
-dev /dev/sg2 -dev /dev/sg2
By default xorriso will try to map the given address to /dev/h d* and /dev/sr*. The command By default xorriso will try to map the given address to /dev/h d* and /dev/sr*. The command
-scsi_dev_family can redirect the mapping from sr to scd or sg. The lat ter does not suffer from the -scsi_dev_family can redirect the mapping from sr to scd or sg. The lat ter does not suffer from the
skipping to change at line 246 skipping to change at line 246
up to 1024 characters. Rock Ridge fulfills this demand. up to 1024 characters. Rock Ridge fulfills this demand.
An El Torito boot record points the BIOS bootstrapping facility to one or more boot images, which are An El Torito boot record points the BIOS bootstrapping facility to one or more boot images, which are
binary program files stored in the ISO image. The content of the boot i mage files is not in the scope of binary program files stored in the ISO image. The content of the boot i mage files is not in the scope of
El Torito. El Torito.
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot image s. xorriso is able to create or Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot image s. xorriso is able to create or
maintain an El Torito object which makes such an image bootable. For deta ils see command -boot_image. maintain an El Torito object which makes such an image bootable. For deta ils see command -boot_image.
It is possible to make ISO images bootable from USB stick or other hard -disk-like media. Several options It is possible to make ISO images bootable from USB stick or other hard -disk-like media. Several options
install a MBR (Master Boot Record), It may get adjusted according to th e needs of the intended boot install a MBR (Master Boot Record), It may get adjusted according to th e needs of the intended boot
firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. A MBR c ontains boot code and a partition firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. A MBR c ontains boot code and a partition
table. The new MBR of a follow-up session can get in effect only on over writeable media. table. The new MBR of a follow-up session can get in effect only on over writable media.
MBR is read by PC-BIOS when booting from USB stick or hard disk, and by P owerPC CHRP or PReP when booting. MBR is read by PC-BIOS when booting from USB stick or hard disk, and by P owerPC CHRP or PReP when booting.
An MBR partition with type 0xee indicates the presence of GPT. An MBR partition with type 0xee indicates the presence of GPT.
Emulation -as mkisofs supports the example options out of the ISOLIN UX wiki, the options used in GRUB Emulation -as mkisofs supports the example options out of the ISOLIN UX wiki, the options used in GRUB
script grub-mkrescue, and the example in the FreeBSD AvgLiveCD wiki. script grub-mkrescue, and the example in the FreeBSD AvgLiveCD wiki.
A GPT (GUID Partition Table) marks partitions in a more modern way. It i s read by EFI when booting from A GPT (GUID Partition Table) marks partitions in a more modern way. It i s read by EFI when booting from
USB stick or hard disk, and may be used for finding and mounting a HFS+ p artition inside the ISO image. USB stick or hard disk, and may be used for finding and mounting a HFS+ p artition inside the ISO image.
An APM (Apple Partition Map) marks the HFS+ partition. It is read by Mac s for booting and for mounting. An APM (Apple Partition Map) marks the HFS+ partition. It is read by Mac s for booting and for mounting.
MBR, GPT and APM are combinable. APM occupies the first 8 bytes of MBR b oot code. All three do not hamper MBR, GPT and APM are combinable. APM occupies the first 8 bytes of MBR b oot code. All three do not hamper
El Torito booting from CDROM. El Torito booting from CDROM.
There is support for further facilities: MIPS Big Endian (SGI), MIPS Li ttle Endian (DEC), SUN SPARC, There is support for further facilities: MIPS Big Endian (SGI), MIPS Li ttle Endian (DEC), SUN SPARC,
skipping to change at line 499 skipping to change at line 499
"d" for DVD, "b" for BD, "x" is optional. "d" for DVD, "b" for BD, "x" is optional.
Example speeds: Example speeds:
706k = 706kB/s = 4c = 4xCD 706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD 5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then the mediu m in the -indev will decide. If there is no hint about the speed unit attached, then the mediu m in the -indev will decide.
Default unit is CD = 176.4k. Default unit is CD = 176.4k.
Depending on the drive, the reported read speeds can be deceivi ngly low or high. Therefore "min" Depending on the drive, the reported read speeds can be deceivi ngly low or high. Therefore "min"
cannot become higher than 1x speed of the involved medium type. R ead speed "max" cannot become cannot become higher than 1x speed of the involved medium type. R ead speed "max" cannot become
lower than 52xCD, 24xDVD, or 20xBD, depending on the medium type. lower than 52xCD, 24xDVD, or 20xBD, depending on the medium type.
MMC drives usually activate their own idea of speed and take the speed value given by the burn MMC drives usually activate their own idea of speed and take the speed value given by the burn
program only as hint for their own decision. program only as hint for their own decision. Friendly drives adjus
t their constant angular velocity
so that the desired speed is reached at the outer rim of the me
dium. But often there is only the
choice between very slow and very loud.
Sometimes no speed setting is obeyed at all, but speed is adjusted
to the demand frequency of the
reading program. So xorriso offers to set an additional s
oftware enforced limit by prefix
"soft_force:". The program will take care not to read faster than
the soft_force speed. This may
be combined with setting the drive speed to a higher value. Set
ting "soft_force:0" disables this
feature.
"soft_force:" tries to correct in subsequent waiting periods lost
or surplus time of up to 0.25
seconds. This smoothens the overall data stream but also enabl
es short times of higher speed to
compensate short times of low speed. Prefix "soft_corr:" sets thi
s hindsight span by giving a
number of microseconds. Not more than 1 billion = 1000 seconds.
Very short times can cause speed
deviations, because systematic inaccuracies of the waiting functio
n cannot be compensated.
Examples (combinable):
-read_speed 6xBD
-read_speed soft_force:4xBD -read_speed soft_corr:100000
-load entity id -load entity id
Load a particular (possibly outdated) ISO session from -dev or -indev. Usually all available Load a particular (possibly outdated) ISO session from -dev or -indev. Usually all available
sessions are shown with command -toc. sessions are shown with command -toc.
entity depicts the kind of addressing. id depicts the particula r address. The following entities entity depicts the kind of addressing. id depicts the particula r address. The following entities
are defined: are defined:
"auto" with any id addresses the last session in -toc. This is the default. "auto" with any id addresses the last session in -toc. This is the default.
"session" with id being a number as of a line "ISO session", colum n "Idx". "session" with id being a number as of a line "ISO session", colum n "Idx".
"track" with id being a number as of a line "ISO track", column "I dx". "track" with id being a number as of a line "ISO track", column "I dx".
"lba" or "sbsector" with a number as of a line "ISO ...", column " sbsector". "lba" or "sbsector" with a number as of a line "ISO ...", column " sbsector".
skipping to change at line 612 skipping to change at line 627
not possible to set them via xorriso xattr manipulation commands. not possible to set them via xorriso xattr manipulation commands.
-md5 "on"|"all"|"off"|"load_check_off" -md5 "on"|"all"|"off"|"load_check_off"
Enable or disable processing of MD5 checksums for the overall session and for each single data Enable or disable processing of MD5 checksums for the overall session and for each single data
file. If enabled then images with checksum tags get loaded only i f the tags of superblock and file. If enabled then images with checksum tags get loaded only i f the tags of superblock and
directory tree match properly. The MD5 checksums of data files and whole session get loaded from directory tree match properly. The MD5 checksums of data files and whole session get loaded from
the image if there are any. the image if there are any.
With commands -compare and -update the recorded MD5 of a file will be used to avoid content reading With commands -compare and -update the recorded MD5 of a file will be used to avoid content reading
from the image. Only the disk file content will be read and comp ared with that MD5. This can save from the image. Only the disk file content will be read and comp ared with that MD5. This can save
much time if -disk_dev_ino "on" is not suitable. much time if -disk_dev_ino "on" is not suitable.
At image generation time they are computed for each file which get Commands which copy whole data files from ISO to hard disk will ve
s its data written into the new rify the copied data stream by
session. The checksums of files which have their data in older the recorded MD5, if -osirrox "check_md5_on" is set.
sessions get copied into the new At image generation time they are computed for each file which g
ets its data written into the new
session. The checksums of files which have their data in older ses
sions get copied into the new
session. Superblock, tree and whole session get a checksum tag eac h. session. Superblock, tree and whole session get a checksum tag eac h.
Mode "all" will additionally check during image generation whether Mode "all" will additionally check during image generation wh
the checksum of a data file ether the checksum of a data file
changed between the time when its reading began and the time wh changed between the time when its reading began and the time when
en it ended. This implies reading it ended. This implies reading
every file twice. every file twice.
Mode "load_check_off" together with "on" or "all" will load record Mode "load_check_off" together with "on" or "all" will load r
ed MD5 sums but not test the ecorded MD5 sums but not test the
recorded checksum tags of superblock and directory tree. This i recorded checksum tags of superblock and directory tree. This is
s necessary if growisofs was used necessary if growisofs was used
as burn program, because it does not overwrite the superblock chec as burn program, because it does not overwrite the superblock c
ksum tag of the first session. hecksum tag of the first session.
Therefore load_check_off is in effect when xorriso -as mkisofs opt ion -M is performed. Therefore load_check_off is in effect when xorriso -as mkisofs opt ion -M is performed.
The test can be re-enabled by mode "load_check_on". The test can be re-enabled by mode "load_check_on".
Checksums can be exploited via commands -check_md5, -check_ md5_r, via find actions get_md5, Checksums can be exploited via commands -check_md5, -check_md5 _r, via find actions get_md5,
check_md5, and via -check_media. check_md5, and via -check_media.
-for_backup -for_backup
Enable all extra features which help to produce or to restore back ups with highest fidelity of file Enable all extra features which help to produce or to restore back ups with highest fidelity of file
properties. Currently this is a shortcut for: properties. Currently this is a shortcut for:
-hardlinks on -acl on -xattr any -md5 on -hardlinks on -acl on -xattr any -md5 on
If you restore a backup with xattr from non-user namespace s, then make sure that the target If you restore a backup with xattr from non-user namespaces, th en make sure that the target
operating system and filesystem know what these attributes mean. Possibly you will need operating system and filesystem know what these attributes mean. Possibly you will need
administrator privileges to record or restore such attributes. At administrator privileges to record or restore such attributes. At
recording time, xorriso will try recording time, xorriso will try
to tolerate missing privileges and just record what is readable. to tolerate missing privileges and just record what is readab
But at restore time, missing le. But at restore time, missing
privileges will cause failure events. privileges will cause failure events.
Command -xattr "user" after command -for_backup excludes non-user attributes from being recorded or Command -xattr "user" after command -for_backup excludes non-user attributes from being recorded or
restored. restored.
-ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase" -ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase"
Choose the conversion of file names from the loaded session if nei Choose the conversion of file names when a session gets loaded,
ther a Rock Ridge name nor a if they stem neither from a Rock
Joliet name was read from the session. Ridge name nor from a Joliet name.
Mode "stripped" is the default. It shows the names as found in the ISO but removes trailing ";1" or Mode "stripped" is the default. It shows the names as found in the ISO but removes trailing ";1" or
".;1" if present. ".;1" if present.
Mode "unmapped" shows names as found without removing characters. Mode "unmapped" shows names as found without removing characters.
Warning: Multi-session converts
"xyz;1" to "xyz_1" and maybe adds new ";1".
Mode "lowercase" is like "stripped" but also maps uppercase letter s to lowercase letters. This is Mode "lowercase" is like "stripped" but also maps uppercase letter s to lowercase letters. This is
compatible to default GNU/Linux mount behavior. compatible to default GNU/Linux mount behavior.
Mode "uppercase" is like "stripped" but maps lowercase letters t o uppercase, if any occur despite Mode "uppercase" is like "stripped" but maps lowercase letters t o uppercase, if any occur despite
the prescriptions of ECMA-119. the prescriptions of ECMA-119.
-joliet_map "stripped"|"unmapped"
Choose the conversion of file names when a session gets loaded fro
m a Joliet tree.
Mode "stripped" is the default. It removes trailing ";1" or ".;1"
if present.
Mode "unmapped" shows names as found without removing characters.
Warning: Multi-session converts
"xyz;1" to "xyz_1" and maybe adds new ";1".
-iso_nowtime "dynamic"|timestring -iso_nowtime "dynamic"|timestring
Choose whether to use the current time ("dynamic") or a fixed time point for timestamps of ISO 9660 Choose whether to use the current time ("dynamic") or a fixed time point for timestamps of ISO 9660
nodes without a disk source file and as default for superblock tim estamps. nodes without a disk source file and as default for superblock tim estamps.
If a timestring is given, then it is used for such timestamps. F or the formats of timestrings see If a timestring is given, then it is used for such timestamps. For the formats of timestrings see
command -alter_date. command -alter_date.
-disk_dev_ino "on"|"ino_only"|"off" -disk_dev_ino "on"|"ino_only"|"off"
Enable or disable processing of recorded file identification numbe Enable or disable processing of recorded file identification numb
rs (dev_t and ino_t). If enabled ers (dev_t and ino_t). If enabled
they are stored as xattr and can substantially accelerate file they are stored as xattr and can substantially accelerate file com
comparison. The root node gets a parison. The root node gets a
global start timestamp. If during comparison a file with younger t global start timestamp. If during comparison a file with young
imestamps is found in the ISO er timestamps is found in the ISO
image, then it is suspected to have inconsistent content. image, then it is suspected to have inconsistent content.
If device numbers and inode numbers of the disk filesystems a If device numbers and inode numbers of the disk filesystems are p
re persistent and if no irregular ersistent and if no irregular
alterations of timestamps or system clock happen, then potential c alterations of timestamps or system clock happen, then potentia
ontent changes can be detected l content changes can be detected
without reading that content. File content change is assumed if a ny of mtime, ctime, device number without reading that content. File content change is assumed if a ny of mtime, ctime, device number
or inode number have changed. or inode number have changed.
Mode "ino_only" replaces the precondition that device numbers are stable by the precondition that Mode "ino_only" replaces the precondition that device numbers ar e stable by the precondition that
mount points in the compared tree always lead to the same filesyst ems. Use this if mode "on" always mount points in the compared tree always lead to the same filesyst ems. Use this if mode "on" always
sees all files changed. sees all files changed.
The speed advantage appears only if the loaded session was produce d with -disk_dev_ino "on" too. The speed advantage appears only if the loaded session was produce d with -disk_dev_ino "on" too.
Note that -disk_dev_ino "off" is totally in effect only if -hardli nks is "off", too. Note that -disk_dev_ino "off" is totally in effect only if -hardli nks is "off", too.
-file_name_limit [+]number -file_name_limit [+]number
Set the maximum permissible length for file names in the range of 64 to 255. Path components which Set the maximum permissible length for file names in the range of 64 to 255. Path components which
are longer than the given number will get truncated and have the are longer than the given number will get truncated and have their
ir last 33 bytes overwritten by a last 33 bytes overwritten by a
colon ':' and the hex representation of the MD5 of the first 4095 colon ':' and the hex representation of the MD5 of the first
bytes of the whole oversized 4095 bytes of the whole oversized
name. Potential incomplete UTF-8 characters will get their leading bytes replaced by '_'. name. Potential incomplete UTF-8 characters will get their leading bytes replaced by '_'.
iso_rr_paths with the long components will still be able to acc ess the file paths with truncated iso_rr_paths with the long components will still be able to access the file paths with truncated
components. components.
If -file_name_limit is executed while an ISO tree is present, the If -file_name_limit is executed while an ISO tree is present, t
file names in the ISO tree get he file names in the ISO tree get
checked for existing truncated file names of the current limi checked for existing truncated file names of the current limit an
t and for name collisions between d for name collisions between
newly truncated files and existing files. In both cases, the sett newly truncated files and existing files. In both cases, the set
ing will be refused with a SORRY ting will be refused with a SORRY
event. event.
One may lift this ban by prepending the character "+" to One may lift this ban by prepending the character "+" to the
the argument of -file_name_limit. argument of -file_name_limit.
Truncated filenames may then get truncated again, invalidating the Truncated filenames may then get truncated again, invalidating th
ir MD5 part. Colliding truncated eir MD5 part. Colliding truncated
names are made unique, consuming at least 9 more bytes of the rema ining name part. names are made unique, consuming at least 9 more bytes of the rema ining name part.
If writing of xattr is enabled, then the length will be stored in "isofs.nt" of the root directory. If writing of xattr is enabled, then the length will be stored in "isofs.nt" of the root directory.
If reading of xattr is enabled and "isofs.nt" is found, then the f ound length will get into effect If reading of xattr is enabled and "isofs.nt" is found, then the found length will get into effect
if it is smaller than the current setting of -file_name_limit. if it is smaller than the current setting of -file_name_limit.
File name patterns will only work if they match the truncated name . This might change in future. File name patterns will only work if they match the truncated name . This might change in future.
Files with truncated names get deleted and re-added unconditiona lly during -update and -update_r. Files with truncated names get deleted and re-added unconditionall y during -update and -update_r.
This might change in future. This might change in future.
Linux kernels up to at least 4.1 misrepresent names of length 254 Linux kernels up to at least 4.1 misrepresent names of length
and 255. If you expect such 254 and 255. If you expect such
names in or under disk_paths and plan to mount the ISO by su names in or under disk_paths and plan to mount the ISO by such L
ch Linux kernels, consider to set inux kernels, consider to set
-file_name_limit 253. Else just avoid names longer than 253 chara cters. -file_name_limit 253. Else just avoid names longer than 253 chara cters.
-rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"] -rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"]
Read-only drives do not tell the actual media type but show any me dia as ROM (e.g. as DVD-ROM). The Read-only drives do not tell the actual media type but show any me dia as ROM (e.g. as DVD-ROM). The
session history of MMC multi-session media might be truncated to session history of MMC multi-session media might be truncated to f
first and last session or even be irst and last session or even be
completely false. (The emulated history of overwriteable media is completely false. (The emulated history of overwritable media is
not affected by this.) not affected by this.)
To have in case of failure a chance of getting the session history To have in case of failure a chance of getting the session hist
and especially the address of ory and especially the address of
the last session, there is a scan for ISO 9660 filesystem header the last session, there is a scan for ISO 9660 filesystem headers
s which might help but also might which might help but also might
yield worse results than the drive's table of content. At its end yield worse results than the drive's table of content. At its
it can cause read attempts to end it can cause read attempts to
invalid addresses and thus ugly drive behavior. Setting " invalid addresses and thus ugly drive behavior. Setting "on"
on" enables that scan for alleged enables that scan for alleged
read-only media. read-only media.
Some operating systems are not able to mount the most recent sessi on of multi-session DVD or BD. If Some operating systems are not able to mount the most recent sessi on of multi-session DVD or BD. If
on such a system xorriso has no own MMC capabilities then it m ay still find that session from a on such a system xorriso has no own MMC capabilities then it may s till find that session from a
scanned table of content. Setting "force" handles any media like a ROM medium with setting "on". scanned table of content. Setting "force" handles any media like a ROM medium with setting "on".
On the other hand the emulation of session history on overwriteabl On the other hand the emulation of session history on overwri
e media can hamper reading of table media can hamper reading of
partly damaged media. Setting "off:emul_off" disables the else partly damaged media. Setting "off:emul_off" disables the elsewi
wise trustworthy table-of-content se trustworthy table-of-content
scan for those media. scan for those media.
The table-of-content scan on overwriteable media normally searches The table-of-content scan on overwritable media normally searches
only up to the end of the only up to the end of the session
session that is pointed to by the superblock at block 0. Set that is pointed to by the superblock at block 0. Setting "on:emul
ting "on:emul_wide" lets the scan _wide" lets the scan continue up
continue up to the end of the medium. This may be useful after co to the end of the medium. This may be useful after cop
pying a medium with -check_media ying a medium with -check_media
patch_lba0=on when not the last session was loaded. patch_lba0=on when not the last session was loaded.
-calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
Reduce drive noise until it is actually used again. Some drive Reduce drive noise until it is actually used again. Some drives st
s stay alert for substantial time ay alert for substantial time
after they have been used for reading. This reduces the startup ti after they have been used for reading. This reduces the startup
me for the next drive operation time for the next drive operation
but can be loud and waste energy if no i/o with the drive is expec ted to happen soon. but can be loud and waste energy if no i/o with the drive is expec ted to happen soon.
Modes "in", "out", "all" immediately calm down -indev, -out dev, or both, respectively. Mode Modes "in", "out", "all" immediately calm down -indev, -outdev, or both, respectively. Mode
"revoke" immediately alerts both. Mode "on" causes -calm_drive to be performed automatically after "revoke" immediately alerts both. Mode "on" causes -calm_drive to be performed automatically after
each -dev, -indev, and -outdev. Mode "off" disables this. each -dev, -indev, and -outdev. Mode "off" disables this.
-ban_stdio_write -ban_stdio_write
Allow for writing only the usage of MMC optical drives. Disallow to write the result into files of Allow for writing only the usage of MMC optical drives. Disallow t o write the result into files of
nearly arbitrary type. Once set, this command cannot be revoked. nearly arbitrary type. Once set, this command cannot be revoked.
-early_stdio_test "on"|"appendable_wo"|"off" -early_stdio_test "on"|"appendable_wo"|"off"
If enabled by "on" then regular files and block devices ge If enabled by "on" then regular files and block devices
t tested for effective access get tested for effective access
permissions. This implies to try opening those files for writing, permissions. This implies to try opening those files for writing,
which otherwise will happen only which otherwise will happen only
later and only if actual writing is desired. later and only if actual writing is desired.
The test result is used for classifying the pseudo drives as overw The test result is used for classifying the pseudo drives as ove
riteable, read-only, write-only, rwritable, read-only, write-only,
or uselessly empty. This may lead to earlier detection of severe or uselessly empty. This may lead to earlier detection of severe p
problems, and may avoid some less roblems, and may avoid some less
severe error events. severe error events.
Mode "appendable_wo" is like "on" with the additional property tha t non-empty write-only files are Mode "appendable_wo" is like "on" with the additional property th at non-empty write-only files are
regarded as appendable rather than blank. regarded as appendable rather than blank.
-data_cache_size number_of_tiles blocks_per_tile -data_cache_size number_of_tiles blocks_per_tile
Set the size and granularity of the data cache which is used wh Set the size and granularity of the data cache which is used when
en ISO images are loaded and when ISO images are loaded and when
file content is read from ISO images. The cache consists of severa file content is read from ISO images. The cache consists of seve
l tiles, which each consists of ral tiles, which each consists of
several blocks. A larger cache reduces the need for tiles being several blocks. A larger cache reduces the need for tiles being re
read multiple times. Larger tiles ad multiple times. Larger tiles
might additionally improve the data throughput from the drive, but might additionally improve the data throughput from the drive, bu
can be wasteful if the data are t can be wasteful if the data are
scattered over the medium. scattered over the medium.
Larger cache sizes help best with image loading from MMC drives. They are an inferior alternative Larger cache sizes help best with image loading from MMC drives. T hey are an inferior alternative
to -osirrox option "sort_lba_on". to -osirrox option "sort_lba_on".
blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The over blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The ove
all cache size must not exceed 1 rall cache size must not exceed 1
GiB. The default values can be restored by parameter "defau GiB. The default values can be restored by parameter "default" in
lt" instead of one or both of the stead of one or both of the
numbers. Currently the default is 32 tiles of 32 blocks = 2 MiB. numbers. Currently the default is 32 tiles of 32 blocks = 2 MiB.
Inserting files into ISO image: Inserting files into ISO image:
The following commands expect file addresses of two kinds: The following commands expect file addresses of two kinds:
disk_path is a path to an object in the local filesystem tree. disk_path is a path to an object in the local filesystem tree.
iso_rr_path is the Rock Ridge name of a file object in the ISO image. If iso_rr_path is the Rock Ridge name of a file object in the ISO image.
no Rock Ridge information is If no Rock Ridge information is
recorded in the loaded ISO image, then you will see ISO 9660 name recorded in the loaded ISO image, then you will see ISO 9660 names whi
s which are of limited length and ch are of limited length and
character set. If no Rock Ridge information shall be stored in an emergi character set. If no Rock Ridge information shall be stored in an eme
ng ISO image, then their names rging ISO image, then their names
will get mapped to such restricted ISO 9660 (aka ECMA-119) names. will get mapped to such restricted ISO 9660 (aka ECMA-119) names.
Note that in the ISO image you are as powerful as the superuser. Access Note that in the ISO image you are as powerful as the superuser. Access p
permissions of the existing files ermissions of the existing files
in the image do not apply to your write operations. They are intended to in the image do not apply to your write operations. They are intended t
be in effect with the read-only o be in effect with the read-only
mounted image. mounted image.
If the iso_rr_path of a newly inserted file leads to an existing file object in the ISO image, then the If the iso_rr_path of a newly inserted file leads to an existing file obj ect in the ISO image, then the
following collision handling happens: following collision handling happens:
If both objects are directories then they get merged by recursively inserting the subobjects from If both objects are directories then they get merged by recursiv ely inserting the subobjects from
filesystem into ISO image. If other file types collide then the setting of command -overwrite decides. filesystem into ISO image. If other file types collide then the setting of command -overwrite decides.
Renaming of files has similar collision handling, but directories can o Renaming of files has similar collision handling, but directories can onl
nly be replaced, not merged. Note y be replaced, not merged. Note
that if the target directory exists, then -mv inserts the source objects that if the target directory exists, then -mv inserts the source object
into this directory rather than s into this directory rather than
attempting to replace it. Command -move, on the other hand, would attempt to replace it. attempting to replace it. Command -move, on the other hand, would attempt to replace it.
The commands in this section alter the ISO image and not the local filesy stem. The commands in this section alter the ISO image and not the local filesy stem.
-disk_pattern "on"|"ls"|"off" -disk_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the disk_path parameters of se veral commands which support this Set the pattern expansion mode for the disk_path parameters of sev eral commands which support this
feature. feature.
Setting "off" disables this feature for all commands which are marked in this man page by Setting "off" disables this feature for all commands which are marked in this man page by
"disk_path [***]" or "disk_pattern [***]". "disk_path [***]" or "disk_pattern [***]".
Setting "on" enables it for all those commands. Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked by "disk_p attern [***]". Setting "ls" enables it only for those which are marked by "disk_p attern [***]".
Default is "ls". Default is "ls".
-add pathspec [...] | disk_path [***] -add pathspec [...] | disk_path [***]
Insert the given files or directory trees from filesystem into the ISO image. Insert the given files or directory trees from filesystem into the ISO image.
If -pathspecs is set to "on" or "as_mkisofs" then pattern expansion is always disabled and If -pathspecs is set to "on" or "as_mkisofs" then pattern exp ansion is always disabled and
character '=' has a special meaning. It separates the ISO image pa th from the disk path: character '=' has a special meaning. It separates the ISO image pa th from the disk path:
iso_rr_path=disk_path iso_rr_path=disk_path
Character '=' in the iso_rr_path must be escaped by '\' (i.e. as " \="). Character '=' in the iso_rr_path must be escaped by '\' (i.e. as " \=").
With -pathspecs "on", the character '\' must not be escaped. The c haracter '=' in the disk_path With -pathspecs "on", the character '\' must not be escaped. T he character '=' in the disk_path
must not be escaped. must not be escaped.
With -pathspecs "as_mkisofs", all characters '\' must be e scaped in both, iso_rr_path and With -pathspecs "as_mkisofs", all characters '\' must be esc aped in both, iso_rr_path and
disk_path. The character '=' may or may not be escaped in the disk _path. disk_path. The character '=' may or may not be escaped in the disk _path.
If iso_rr_path does not begin with '/' then -cd is prepended. If disk_path does not begin with '/' If iso_rr_path does not begin with '/' then -cd is prepended. If disk_path does not begin with '/'
then -cdx is prepended. then -cdx is prepended.
If no '=' is given then the word is used as both, iso_rr_path an If no '=' is given then the word is used as both, iso_rr_path and
d disk path. If in this case the disk path. If in this case the
word does not begin with '/' then -cdx is prepended to the disk_pa word does not begin with '/' then -cdx is prepended to the disk
th and -cd is prepended to the _path and -cd is prepended to the
iso_rr_path. iso_rr_path.
If -pathspecs is set to "off" then -disk_pattern expansion ap plies, if enabled. The resulting If -pathspecs is set to "off" then -disk_pattern expansion applie s, if enabled. The resulting
words are used as both, iso_rr_path and disk path. Relative path w ords get prepended the setting of words are used as both, iso_rr_path and disk path. Relative path w ords get prepended the setting of
-cdx to disk_path and the setting of -cd to iso_rr_path. -cdx to disk_path and the setting of -cd to iso_rr_path.
-add_plainly mode -add_plainly mode
If set to mode "unknown" then any command word that does not beg in with "-" and is not recognized If set to mode "unknown" then any command word that does not begin with "-" and is not recognized
as known command will be subject to a virtual -add command. I.e. it will be used as pathspec or as as known command will be subject to a virtual -add command. I.e. it will be used as pathspec or as
disk_path and added to the image. If enabled, -disk_pattern expan sion applies to disk_paths. disk_path and added to the image. If enabled, -disk_pattern expan sion applies to disk_paths.
Mode "dashed" is similar to "unknown" but also adds unrecognized command words even if they begin Mode "dashed" is similar to "unknown" but also adds unrecognized c ommand words even if they begin
with "-". with "-".
Mode "any" announces that all further words are to be added as pat hspecs or disk_paths. This does Mode "any" announces that all further words are to be added as p athspecs or disk_paths. This does
not work in dialog mode. not work in dialog mode.
Mode "none" is the default. It prevents any words from being un derstood as files to add, if they Mode "none" is the default. It prevents any words from being under stood as files to add, if they
are not parameters to appropriate commands. are not parameters to appropriate commands.
-path_list disk_path -path_list disk_path
Like -add but read the parameter words from file disk_path or stan dard input if disk_path is "-". Like -add but read the parameter words from file disk_path or st andard input if disk_path is "-".
The list must contain exactly one pathspec or disk_path pattern pe r line. The list must contain exactly one pathspec or disk_path pattern pe r line.
-quoted_path_list disk_path -quoted_path_list disk_path
Like -path_list but with quoted input reading rules. Lines get spl it into parameter words for -add. Like -path_list but with quoted input reading rules. Lines get spl it into parameter words for -add.
Whitespace outside quotes is discarded. Whitespace outside quotes is discarded.
-map disk_path iso_rr_path -map disk_path iso_rr_path
Insert file object disk_path into the ISO image as iso_rr_path. If disk_path is a directory then Insert file object disk_path into the ISO image as iso_rr_path. If disk_path is a directory then
its whole sub tree is inserted into the ISO image. its whole sub tree is inserted into the ISO image.
-map_single disk_path iso_rr_path -map_single disk_path iso_rr_path
Like -map, but if disk_path is a directory then its sub tree is no t inserted. Like -map, but if disk_path is a directory then its sub tree is no t inserted.
-map_l disk_prefix iso_rr_prefix disk_path [***] -map_l disk_prefix iso_rr_prefix disk_path [***]
Perform -map with each of the disk_path parameters. iso_rr_path w ill be composed from disk_path by Perform -map with each of the disk_path parameters. iso_rr_path wi ll be composed from disk_path by
replacing disk_prefix by iso_rr_prefix. replacing disk_prefix by iso_rr_prefix.
-update disk_path iso_rr_path -update disk_path iso_rr_path
Compare file object disk_path with file object iso_rr_path. If the Compare file object disk_path with file object iso_rr_path. If th
y do not match, then perform the ey do not match, then perform the
necessary image manipulations to make iso_rr_path a matching c necessary image manipulations to make iso_rr_path a matching copy
opy of disk_path. By default this of disk_path. By default this
comparison will imply lengthy content reading before a decision is comparison will imply lengthy content reading before a decision i
made. Commands -disk_dev_ino or s made. Commands -disk_dev_ino or
-md5 may accelerate comparison if they were already in effect when the loaded session was recorded. -md5 may accelerate comparison if they were already in effect when the loaded session was recorded.
If disk_path is a directory and iso_rr_path does not exist ye t, then the whole subtree will be If disk_path is a directory and iso_rr_path does not exist yet, th en the whole subtree will be
inserted. Else only directory attributes will be updated. inserted. Else only directory attributes will be updated.
-update_r disk_path iso_rr_path -update_r disk_path iso_rr_path
Like -update but working recursively. I.e. all file objects belo Like -update but working recursively. I.e. all file objects
w both addresses get compared below both addresses get compared
whether they have counterparts below the other address and wh whether they have counterparts below the other address and whethe
ether both counterparts match. If r both counterparts match. If
there is a mismatch then the necessary update manipulation is done . there is a mismatch then the necessary update manipulation is done .
Note that the comparison result may depend on command -follow. Its setting should always be the Note that the comparison result may depend on command -follow. Its setting should always be the
same as with the first adding of disk_path as iso_rr_path. same as with the first adding of disk_path as iso_rr_path.
If iso_rr_path does not exist yet, then it gets added. I f disk_path does not exist, then If iso_rr_path does not exist yet, then it gets added. If d isk_path does not exist, then
iso_rr_path gets deleted. iso_rr_path gets deleted.
-update_l disk_prefix iso_rr_prefix disk_path [***] -update_l disk_prefix iso_rr_prefix disk_path [***]
Perform -update_r with each of the disk_path parameters. iso_ rr_path will be composed from Perform -update_r with each of the disk_path parameters. i so_rr_path will be composed from
disk_path by replacing disk_prefix by iso_rr_prefix. disk_path by replacing disk_prefix by iso_rr_prefix.
-update_li iso_rr_prefix disk_prefix iso_rr_path [***] -update_li iso_rr_prefix disk_prefix iso_rr_path [***]
Perform -update_r with each of the iso_rr_path parameters. disk_path will be composed from Perform -update_r with each of the iso_rr_path parameters. di sk_path will be composed from
iso_rr_path by replacing iso_rr_prefix by disk_prefix. iso_rr_path by replacing iso_rr_prefix by disk_prefix.
-update_lxi disk_prefix iso_rr_prefix disk_path [***] -update_lxi disk_prefix iso_rr_prefix disk_path [***]
Perform -update_r with each of the disk_path parameters and with i so_rr_paths in the ISO filesystem Perform -update_r with each of the disk_path parameters and with i so_rr_paths in the ISO filesystem
which are derived from the disk_path parameters after exchanging which are derived from the disk_path parameters after exchanging d
disk_prefix by iso_rr_prefix. So, isk_prefix by iso_rr_prefix. So,
other than -update_l, this detects missing matches of disk_path other than -update_l, this detects missing matches of disk_p
and deletes the corresponding ath and deletes the corresponding
iso_rr_path. iso_rr_path.
Note that relative disk_paths and disk_path patterns are interp Note that relative disk_paths and disk_path patterns are interpret
reted as sub paths of the current ed as sub paths of the current
disk working directory -cdx. The corresponding iso_rr_paths are de disk working directory -cdx. The corresponding iso_rr_paths are
rived by exchanging disk_prefix derived by exchanging disk_prefix
by iso_rr_prefix before pattern expansion happens. The current -cd i directory has no influence. by iso_rr_prefix before pattern expansion happens. The current -cd i directory has no influence.
-cut_out disk_path byte_offset byte_count iso_rr_path -cut_out disk_path byte_offset byte_count iso_rr_path
Map a byte interval of a regular disk file into a regular fi Map a byte interval of a regular disk file into a regular file in
le in the ISO image. This may be the ISO image. This may be
necessary if the disk file is larger than a single medium, or if i necessary if the disk file is larger than a single medium, or if
t exceeds the traditional limit it exceeds the traditional limit
of 2 GiB - 1 for old operating systems, or the limit of 4 GiB - of 2 GiB - 1 for old operating systems, or the limit of 4 GiB - 1
1 for newer ones. Only the newest for newer ones. Only the newest
Linux kernels seem to read properly files >= 4 GiB - 1. Linux kernels seem to read properly files >= 4 GiB - 1.
A clumsy remedy for this limit is to backup file pieces and to con A clumsy remedy for this limit is to backup file pieces and to co
catenate them at restore time. A ncatenate them at restore time. A
well tested chopping size is 2047m. It is permissible to well tested chopping size is 2047m. It is permissible to req
request a higher byte_count than uest a higher byte_count than
available. The resulting file will be truncated to the correct siz e of a final piece. To request a available. The resulting file will be truncated to the correct siz e of a final piece. To request a
byte_offset higher than available yields no file in the ISO image but a SORRY event. E.g: byte_offset higher than available yields no file in the ISO image but a SORRY event. E.g:
-cut_out /my/disk/file 0 2047m \ -cut_out /my/disk/file 0 2047m \
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \ /file/part_1_of_3_at_0_with_2047m_of_5753194821 \
-cut_out /my/disk/file 2047m 2047m \ -cut_out /my/disk/file 2047m 2047m \
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \ /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
-cut_out /my/disk/file 4094m 2047m \ -cut_out /my/disk/file 4094m 2047m \
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821 /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
While command -split_size is set larger than 0, and if all pieces While command -split_size is set larger than 0, and if all pieces
of a file reside in the same ISO of a file reside in the same ISO
directory with no other files, and if the names look like above, t directory with no other files, and if the names look like above,
hen their ISO directory will be then their ISO directory will be
recognized and handled like a regular file. This affects recognized and handled like a regular file. This affects com
commands -compare*, -update*, and mands -compare*, -update*, and
overwrite situations. See command -split_size for details. overwrite situations. See command -split_size for details.
-cpr disk_path [***] iso_rr_path -cpr disk_path [***] iso_rr_path
Insert the given files or directory trees from filesystem into the ISO image. Insert the given files or directory trees from filesystem into the ISO image.
The rules for generating the ISO addresses are similar as with she The rules for generating the ISO addresses are similar as with s
ll command cp -r. Nevertheless, hell command cp -r. Nevertheless,
directories of the iso_rr_path are created if necessary. Especial directories of the iso_rr_path are created if necessary. Especiall
ly a not yet existing iso_rr_path y a not yet existing iso_rr_path
will be handled as directory if multiple disk_paths are present. will be handled as directory if multiple disk_paths are presen
The leafnames of the multiple t. The leafnames of the multiple
disk_paths will be grafted under that directory as would be done w ith an existing directory. disk_paths will be grafted under that directory as would be done w ith an existing directory.
If a single disk_path is present then a non-existing iso_rr_p ath will get the same type as the If a single disk_path is present then a non-existing iso_rr_path w ill get the same type as the
disk_path. disk_path.
If a disk_path does not begin with '/' then -cdx is prepended. If the iso_rr_path does not begin If a disk_path does not begin with '/' then -cdx is prepended. If the iso_rr_path does not begin
with '/' then -cd is prepended. with '/' then -cd is prepended.
-mkdir iso_rr_path [...] -mkdir iso_rr_path [...]
Create empty directories if they do not exist yet. Existence as directory generates a WARNING Create empty directories if they do not exist yet. Existence as directory generates a WARNING
event, existence as other file causes a FAILURE event. event, existence as other file causes a FAILURE event.
-lns target_text iso_rr_path -lns target_text iso_rr_path
Create a symbolic link with address iso_rr_path which points to ta rget_text. iso_rr_path may not Create a symbolic link with address iso_rr_path which points to target_text. iso_rr_path may not
exist yet. exist yet.
Hint: Command -clone produces the ISO equivalent of a hard link. Hint: Command -clone produces the ISO equivalent of a hard link.
-clone iso_rr_path_original iso_rr_path_copy -clone iso_rr_path_original iso_rr_path_copy
Create a copy of the ISO file object iso_rr_path_original with the new address iso_rr_path_copy. If Create a copy of the ISO file object iso_rr_path_original with the new address iso_rr_path_copy. If
the original is a directory then copy all files and directories un derneath. If iso_rr_path_original the original is a directory then copy all files and directories un derneath. If iso_rr_path_original
is a boot catalog file, then it gets not copied but is silently ig nored. is a boot catalog file, then it gets not copied but is silently ig nored.
The copied ISO file objects have the same attributes. Copied dat a files refer to the same content The copied ISO file objects have the same attributes. Copied data files refer to the same content
source as their originals. The copies may then be manipulated ind ependendly of their originals. source as their originals. The copies may then be manipulated ind ependendly of their originals.
This command will refuse execution if the address iso_rr_path_copy already exists in the ISO tree. This command will refuse execution if the address iso_rr_path_copy already exists in the ISO tree.
-cp_clone iso_rr_path_original [***] iso_rr_path_dest -cp_clone iso_rr_path_original [***] iso_rr_path_dest
Create copies of one or more ISO file objects as with command -clo ne. In case of collision merge Create copies of one or more ISO file objects as with command -c lone. In case of collision merge
directories with existing ones, but do not overwrite existing ISO file objects. directories with existing ones, but do not overwrite existing ISO file objects.
The rules for generating the copy addresses are the same as with The rules for generating the copy addresses are the same as with c
command -cpr (see above) or shell ommand -cpr (see above) or shell
command cp -r. Other than with -cpr, relative iso_rr_path_original command cp -r. Other than with -cpr, relative iso_rr_path_origina
will get prepended the -cd path l will get prepended the -cd path
and not the -cdx path. Consider to -mkdir iso_rr_path_dest bef and not the -cdx path. Consider to -mkdir iso_rr_path_dest before
ore -cp_clone so the copy address -cp_clone so the copy address
does not depend on the number of iso_rr_path_original parameters. does not depend on the number of iso_rr_path_original parameters.
cp_clone so the copy address
Settings for file insertion: Settings for file insertion:
-file_size_limit value [value [...]] -- -file_size_limit value [value [...]] --
Set the maximum permissible size for a single data file. The value s get summed up for the actual Set the maximum permissible size for a single data file. The va lues get summed up for the actual
limit. If the only value is "off" then the file size is not limite d by xorriso. Default is a limit limit. If the only value is "off" then the file size is not limite d by xorriso. Default is a limit
of 100 extents, 4g -2k each: of 100 extents, 4g -2k each:
-file_size_limit 400g -200k -- -file_size_limit 400g -200k --
When mounting ISO 9660 filesystems, old operating systems can hand When mounting ISO 9660 filesystems, old operating systems can
le only files up to 2g -1 --. handle only files up to 2g -1 --.
Newer ones are good up to 4g -1 --. You need quite a new Linux k Newer ones are good up to 4g -1 --. You need quite a new Linux ke
ernel to read correctly the final rnel to read correctly the final
bytes of a file >= 4g if its size is not aligned to 2048 byte bloc ks. bytes of a file >= 4g if its size is not aligned to 2048 byte bloc ks.
xorriso's own data read capabilities are not affected by operating system size limits. Such limits xorriso's own data read capabilities are not affected by operatin g system size limits. Such limits
apply to mounting only. Nevertheless, the target filesystem of an -extract must be able to take the apply to mounting only. Nevertheless, the target filesystem of an -extract must be able to take the
file size. file size.
-not_mgt code[:code[...]] -not_mgt code[:code[...]]
Control the behavior of the exclusion lists. Control the behavior of the exclusion lists.
Exclusion processing happens before disk_paths get mapped to the I Exclusion processing happens before disk_paths get mapped to th
SO image and before disk files e ISO image and before disk files
get compared with image files. The absolute disk path of get compared with image files. The absolute disk path of the
the source is matched against the source is matched against the
-not_paths list. The leafname of the disk path is matched against -not_paths list. The leafname of the disk path is matched agai
the patterns in the -not_leaf nst the patterns in the -not_leaf
list. If a match is detected then the disk path will not be regard ed as an existing file and not be list. If a match is detected then the disk path will not be regard ed as an existing file and not be
added to the ISO image. added to the ISO image.
Several codes are defined. The _on/_off settings persist until th ey are revoked by their_off/_on Several codes are defined. The _on/_off settings persist until they are revoked by their_off/_on
counterparts. counterparts.
"erase" empties the lists which were accumulated by -not_paths and -not_leaf. "erase" empties the lists which were accumulated by -not_paths and -not_leaf.
"reset" is like "erase" but also re-installs default behavior. "reset" is like "erase" but also re-installs default behavior.
"off" disables exclusion processing temporarily without invalidati ng the lists and settings. "off" disables exclusion processing temporarily without invalidati ng the lists and settings.
"on" re-enables exclusion processing. "on" re-enables exclusion processing.
"param_off" applies exclusion processing only to paths below disk _path parameter of commands. I.e. "param_off" applies exclusion processing only to paths below disk_ path parameter of commands. I.e.
explicitly given disk_paths are exempted from exclusion processing . explicitly given disk_paths are exempted from exclusion processing .
"param_on" applies exclusion processing to command parameters as well as to files below such "param_on" applies exclusion processing to command parameter s as well as to files below such
parameters. parameters.
"subtree_off" with "param_on" excludes parameter paths only if they match a -not_paths item "subtree_off" with "param_on" excludes parameter paths only if they match a -not_paths item
exactly. exactly.
"subtree_on" additionally excludes parameter paths which lead to a file address below any "subtree_on" additionally excludes parameter paths which lea d to a file address below any
-not_paths item. -not_paths item.
"ignore_off" treats excluded disk files as if they were mis sing. I.e. they get reported with "ignore_off" treats excluded disk files as if they were missing. I.e. they get reported with
-compare and deleted from the image with -update. -compare and deleted from the image with -update.
"ignore_on" keeps excluded files out of -compare or -update activi ties. "ignore_on" keeps excluded files out of -compare or -update activi ties.
-not_paths disk_path [***] -not_paths disk_path [***]
Add the given paths to the list of excluded absolute disk paths. I Add the given paths to the list of excluded absolute disk paths.
f a given path is relative, then If a given path is relative, then
the current -cdx is prepended to form an absolute path. Pattern the current -cdx is prepended to form an absolute path. Pattern m
matching, if enabled, happens at atching, if enabled, happens at
definition time and not when exclusion checks are made. definition time and not when exclusion checks are made.
(Do not forget to end the list of disk_paths by "--") (Do not forget to end the list of disk_paths by "--")
-not_leaf pattern -not_leaf pattern
Add a single shell parser style pattern to the list of exclusi ons for disk leafnames. These Add a single shell parser style pattern to the list of exc lusions for disk leafnames. These
patterns are evaluated when the exclusion checks are made. patterns are evaluated when the exclusion checks are made.
-not_list disk_path -not_list disk_path
Read lines from disk_path and use each of them either as -not_pat hs parameter, if they contain a / Read lines from disk_path and use each of them either as -not_path s parameter, if they contain a /
character, or as -not_leaf pattern. character, or as -not_leaf pattern.
-quoted_not_list disk_path -quoted_not_list disk_path
Like -not_list but with quoted input reading rules. Each word is handled as one parameter for Like -not_list but with quoted input reading rules. Each wor d is handled as one parameter for
-not_paths or -not_leaf. -not_paths or -not_leaf.
-follow occasion[:occasion[...]] -follow occasion[:occasion[...]]
Enable or disable resolution of symbolic links and mountpoints under disk_paths. This applies to Enable or disable resolution of symbolic links and mountpoints und er disk_paths. This applies to
actions -add, -du*x, -ls*x, -findx, -concat, and to -disk_pattern expansion. actions -add, -du*x, -ls*x, -findx, -concat, and to -disk_pattern expansion.
There are three kinds of follow decisison to be made: There are three kinds of follow decisison to be made:
link is the hop from a symbolic link to its target file object for the purpose of reading. I.e. not link is the hop from a symbolic link to its target file object for the purpose of reading. I.e. not
for command -concat. If enabled then symbolic links are handled a s their target file objects, else for command -concat. If enabled then symbolic links are handled a s their target file objects, else
symbolic links are handled as themselves. symbolic links are handled as themselves.
mount is the hop from one filesystem to another subordinate filesy stem. If enabled then mountpoint mount is the hop from one filesystem to another subordinate filesy stem. If enabled then mountpoint
directories are handled as any other directory, else mountpoints are handled as empty directories directories are handled as any other directory, else mountpoints a re handled as empty directories
if they are encountered in directory tree traversals. if they are encountered in directory tree traversals.
concat is the hop from a symbolic link to its target file object f or the purpose of writing. I.e. concat is the hop from a symbolic link to its target file object for the purpose of writing. I.e.
for command -concat. This is a security risk ! for command -concat. This is a security risk !
Less general than above occasions: Less general than above occasions:
pattern is mount and link hopping, but only during -disk_pattern e xpansion. pattern is mount and link hopping, but only during -disk_pattern e xpansion.
param is link hopping for parameter words (after eventual pat param is link hopping for parameter words (after eventual pattern
tern expansion). If enabled then expansion). If enabled then
-ls*x will show the link targets rather than the links themselves. -ls*x will show the link targets rather than the links themsel
-du*x, -findx, and -add will ves. -du*x, -findx, and -add will
process the link targets but not follow links in an eventual process the link targets but not follow links in an eventual dir
directory tree below the targets ectory tree below the targets
(unless "link" is enabled). (unless "link" is enabled).
Occasions can be combined in a colon separated list. All occasions mentioned in the list will then Occasions can be combined in a colon separated list. All occasion s mentioned in the list will then
lead to a positive follow decision. lead to a positive follow decision.
off prevents any positive follow decision. Use it if no other occa sion applies. off prevents any positive follow decision. Use it if no other occa sion applies.
Shortcuts: Shortcuts:
default is equivalent to "pattern:mount:limit=100". default is equivalent to "pattern:mount:limit=100".
on always decides positive. Equivalent to "link:mount:concat". on always decides positive. Equivalent to "link:mount:concat".
Not an occasion but an optional setting is: Not an occasion but an optional setting is:
limit=<number> which sets the maximum number of link hops. A l ink hop consists of a sequence of limit=<number> which sets the maximum number of link hops. A link hop consists of a sequence of
symbolic links and a final target of different type. Nevertheless those hops can loop. Example: symbolic links and a final target of different type. Nevertheless those hops can loop. Example:
$ ln -s .. uploop $ ln -s .. uploop
Link hopping has a built-in loop detection which stops hopping at Link hopping has a built-in loop detection which stops hopping
the first repetition of a link at the first repetition of a link
target. Then the repeated link is handled as itself and not as target. Then the repeated link is handled as itself and not as its
its target. Regrettably one can target. Regrettably one can
construct link networks which cause exponential workload before t construct link networks which cause exponential workload befo
heir loops get detected. The re their loops get detected. The
number given with "limit=" can curb this workload at the risk of t runcating an intentional sequence number given with "limit=" can curb this workload at the risk of t runcating an intentional sequence
of link hops. of link hops.
-pathspecs "on"|"off"|"as_mkisofs" -pathspecs "on"|"off"|"as_mkisofs"
Control parameter interpretation with xorriso actions -add and -pa th_list. Control parameter interpretation with xorriso actions -add and -pa th_list.
Mode "as_mkisofs" enables pathspecs of the form Mode "as_mkisofs" enables pathspecs of the form
iso_rr_path=disk_path iso_rr_path=disk_path
like with program mkisofs -graft-points. like with program mkisofs -graft-points.
All characters '\' must be escaped in both, iso_rr_path and disk_p All characters '\' must be escaped in both, iso_rr_path and disk
ath. The character '=' must be _path. The character '=' must be
escaped in the iso_rr_path and may or may not be escaped in the escaped in the iso_rr_path and may or may not be escaped in the di
disk_path. This mode temporarily sk_path. This mode temporarily
disables -disk_pattern expansion for command -add. disables -disk_pattern expansion for command -add.
Mode "on" does nearly the same. But '=' must only be escaped in th e iso_rr_path and '\' must not be Mode "on" does nearly the same. But '=' must only be escaped in th e iso_rr_path and '\' must not be
escaped at all. This has the disadvantage that one cannot express an iso_rr_path which ends by '\'. escaped at all. This has the disadvantage that one cannot express an iso_rr_path which ends by '\'.
Mode "off" disables pathspecs of the form target=source and re-ena bles -disk_pattern expansion. Mode "off" disables pathspecs of the form target=source and re-ena bles -disk_pattern expansion.
-overwrite "on"|"nondir"|"off" -overwrite "on"|"nondir"|"off"
Allow or disallow overwriting of existing files in the ISO image b y files with the same name. Allow or disallow overwriting of existing files in the ISO image b y files with the same name.
With setting "off", name collisions with at least one non-dir ectory file cause FAILURE events. With setting "off", name collisions with at least one non-directo ry file cause FAILURE events.
Collisions of two directories lead to merging of their file lists. Collisions of two directories lead to merging of their file lists.
With setting "nondir", only directories are protected by such even ts, other existing file types get With setting "nondir", only directories are protected by such even ts, other existing file types get
treated with -rm before the new file gets added. Setting "on " enables automatic -rm_r. I.e. a treated with -rm before the new file gets added. Setting "on" en ables automatic -rm_r. I.e. a
non-directory can replace an existing directory and all its subord inates. non-directory can replace an existing directory and all its subord inates.
If restoring of files is enabled, then the overwrite rule applies to the target file objects on If restoring of files is enabled, then the overwrite rule appl ies to the target file objects on
disk as well, but "on" is downgraded to "nondir". disk as well, but "on" is downgraded to "nondir".
-split_size number["k"|"m"] -split_size number["k"|"m"]
Set the threshold for automatic splitting of regular files. Such splitting maps a large disk file Set the threshold for automatic splitting of regular files. Such s plitting maps a large disk file
onto a ISO directory with several part files in it. This is neces sary if the size of the disk file onto a ISO directory with several part files in it. This is neces sary if the size of the disk file
exceeds -file_size_limit. Older operating systems can handle file s in mounted ISO 9660 filesystems exceeds -file_size_limit. Older operating systems can handle file s in mounted ISO 9660 filesystems
only if they are smaller than 2 GiB or in other cases 4 GiB. only if they are smaller than 2 GiB or in other cases 4 GiB.
Default is 0 which will exclude files larger than -file_size_limit by a FAILURE event. A well Default is 0 which will exclude files larger than -file_size_ limit by a FAILURE event. A well
tested -split_size is 2047m. Sizes above -file_size_limit are not permissible. tested -split_size is 2047m. Sizes above -file_size_limit are not permissible.
While command -split_size is set larger than 0 such a directo While command -split_size is set larger than 0 such a directory wi
ry with split file pieces will be th split file pieces will be
recognized and handled like a regular file by commands -compare* recognized and handled like a regular file by commands -comp
, -update*, and in overwrite are* , -update*, and in overwrite
situations. There are -osirrox parameters "concat_split_on" and situations. There are -osirrox parameters "concat_split_on" and "
"concat_split_off" which control concat_split_off" which control
the handling when files get restored to disk. the handling when files get restored to disk.
In order to be recognizable, the names of the part files have to describe the splitting by 5 In order to be recognizable, the names of the part files ha ve to describe the splitting by 5
numbers: numbers:
part_number,total_parts,byte_offset,byte_count,disk_file_size part_number,total_parts,byte_offset,byte_count,disk_file_size
which are embedded in the following text form: which are embedded in the following text form:
part_#_of_#_at_#_with_#_of_# part_#_of_#_at_#_with_#_of_#
Scaling characters like "m" or "k" are taken into respect. All d igits are interpreted as decimal, Scaling characters like "m" or "k" are taken into respect. All di gits are interpreted as decimal,
even if leading zeros are present. even if leading zeros are present.
E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
No other files are allowed in the directory. All parts have to be present and their numbers have to No other files are allowed in the directory. All parts have to be present and their numbers have to
be plausible. E.g. byte_count must be valid as -cut_out par ameter and their contents may not be plausible. E.g. byte_count must be valid as -cut_out paramete r and their contents may not
overlap. overlap.
File manipulations: File manipulations:
The following commands manipulate files in the ISO image, regardless whet her they stem from the loaded The following commands manipulate files in the ISO image, regardless whether they stem from the loaded
image or were newly inserted. image or were newly inserted.
-iso_rr_pattern "on"|"ls"|"off" -iso_rr_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the iso_rr_path parameters of several commands which support Set the pattern expansion mode for the iso_rr_path parameters of several commands which support
this feature. this feature.
Setting "off" disables pattern expansion for all commands which ar e marked in this man page by Setting "off" disables pattern expansion for all commands whi ch are marked in this man page by
"iso_rr_path [***]" or "iso_rr_pattern [***]". "iso_rr_path [***]" or "iso_rr_pattern [***]".
Setting "on" enables it for all those commands. Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked by "iso_rr _pattern [***]". Setting "ls" enables it only for those which are marked by "iso_rr _pattern [***]".
Default is "on". Default is "on".
-rm iso_rr_path [***] -rm iso_rr_path [***]
Delete the given files from the ISO image. Delete the given files from the ISO image.
Note: This does not free any space on the -indev medium, even if the deletion is committed to that Note: This does not free any space on the -indev medium, even if t he deletion is committed to that
same medium. same medium.
The image size will shrink if the image is written to a different medium in modification mode. The image size will shrink if the image is written to a different medium in modification mode.
-rm_r iso_rr_path [***] -rm_r iso_rr_path [***]
Delete the given files or directory trees from the ISO image. See also the note with command -rm. Delete the given files or directory trees from the ISO image. See also the note with command -rm.
-rmdir iso_rr_path [***] -rmdir iso_rr_path [***]
Delete empty directories. Delete empty directories.
-move iso_rr_path iso_rr_path -move iso_rr_path iso_rr_path
Rename the file given by the first (origin) iso_rr_path to the se Rename the file given by the first (origin) iso_rr_path to the
cond (destination) iso_rr_path. second (destination) iso_rr_path.
Deviate from rules of shell command mv by not moving the o Deviate from rules of shell command mv by not moving the origi
rigin file underneath an existing n file underneath an existing
destination directory. The origin file will rather replace such a destination directory. The origin file will rather replace such a
directory, if this is allowed by directory, if this is allowed by
command -overwrite. command -overwrite.
-mv iso_rr_path [***] iso_rr_path -mv iso_rr_path [***] iso_rr_path
Rename the given file objects in the ISO tree to the last paramete r in the list. Use the same rules Rename the given file objects in the ISO tree to the last paramete r in the list. Use the same rules
as with shell command mv. as with shell command mv.
If pattern expansion is enabled and if the last parameter contains wildcard characters then it must If pattern expansion is enabled and if the last parameter contains wildcard characters then it must
match exactly one existing file address, or else the command fails with a FAILURE event. match exactly one existing file address, or else the command fails with a FAILURE event.
-chown uid iso_rr_path [***] -chown uid iso_rr_path [***]
Set ownership of file objects in the ISO image. uid may either be a decimal number or the name of a Set ownership of file objects in the ISO image. uid may either be a decimal number or the name of a
user known to the operating system. user known to the operating system.
-chown_r uid iso_rr_path [***] -chown_r uid iso_rr_path [***]
Like -chown but affecting all files below eventual directories. Like -chown but affecting all files below eventual directories.
-chgrp gid iso_rr_path [***] -chgrp gid iso_rr_path [***]
Set group attribute of file objects in the ISO image. gid may eit her be a decimal number or the Set group attribute of file objects in the ISO image. gid may either be a decimal number or the
name of a group known to the operating system. name of a group known to the operating system.
-chgrp_r gid iso_rr_path [***] -chgrp_r gid iso_rr_path [***]
Like -chgrp but affecting all files below eventual directories. Like -chgrp but affecting all files below eventual directories.
-chmod mode iso_rr_path [***] -chmod mode iso_rr_path [***]
Equivalent to shell command chmod in the ISO image. mode is eith er an octal number beginning with Equivalent to shell command chmod in the ISO image. mode is eithe r an octal number beginning with
"0" or a comma separated list of statements of the form [ugoa]*[+- =][rwxst]* . "0" or a comma separated list of statements of the form [ugoa]*[+- =][rwxst]* .
Like: go-rwx,u+rwx . Like: go-rwx,u+rwx .
Personalities: u=user, g=group, o=others, a=all Personalities: u=user, g=group, o=others, a=all
Operators: + adds given permissions, - revokes given permissions, = revokes all old permissions and Operators: + adds given permissions, - revokes given permissions, = revokes all old permissions and
then adds the given ones. then adds the given ones.
Permissions: r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit Permissions: r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit
For octal numbers see man 2 stat. For octal numbers see man 2 stat.
-chmod_r mode iso_rr_path [***] -chmod_r mode iso_rr_path [***]
Like -chmod but affecting all files below eventual directories. Like -chmod but affecting all files below eventual directories.
-setfacl acl_text iso_rr_path [***] -setfacl acl_text iso_rr_path [***]
Attach the given ACL to the given iso_rr_paths. If the files already have ACLs, then those get Attach the given ACL to the given iso_rr_paths. If the files alrea dy have ACLs, then those get
deleted before the new ones get into effect. If acl_text is empty , or contains the text "clear" or deleted before the new ones get into effect. If acl_text is empty , or contains the text "clear" or
the text "--remove-all", then the existing ACLs will be removed the text "--remove-all", then the existing ACLs will be removed an
and no new ones will be attached. d no new ones will be attached.
Any other content of acl_text will be interpreted as a list of ACL Any other content of acl_text will be interpreted as a list of A
entries. It may be in the long CL entries. It may be in the long
multi-line format as put out by -getfacl but may also be abbreviat ed as follows: multi-line format as put out by -getfacl but may also be abbreviat ed as follows:
ACL entries are separated by comma or newline. If an entry is empt y text or begins with "#" then it ACL entries are separated by comma or newline. If an entry is empt y text or begins with "#" then it
will be ignored. A valid entry has to begin by a letter out of {ug om} for "user", "group", "other", will be ignored. A valid entry has to begin by a letter out of {ug om} for "user", "group", "other",
"mask". It has to contain two colons ":". A non-empty text bet "mask". It has to contain two colons ":". A non-empty text between
ween those ":" gives a user id or those ":" gives a user id or
group id. After the second ":" there may be letters out of {rwx- # group id. After the second ":" there may be letters out of {rwx
}. The first three give read, - #}. The first three give read,
write, or execute permission. Letters "-", " " and TAB are ig write, or execute permission. Letters "-", " " and TAB are ignore
nored. "#" causes the rest of the d. "#" causes the rest of the
entry to be ignored. Letter "X" or any other letters are not suppo rted. Examples: entry to be ignored. Letter "X" or any other letters are not suppo rted. Examples:
g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw- group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
A valid entry may be prefixed by "d", some following characters an d ":". This indicates that the A valid entry may be prefixed by "d", some following characters and ":". This indicates that the
entry goes to the "default" ACL rather than to the "access" ACL. E xample: entry goes to the "default" ACL rather than to the "access" ACL. E xample:
u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
-setfacl_r acl_text iso_rr_path [***] -setfacl_r acl_text iso_rr_path [***]
Like -setfacl but affecting all files below eventual directories. Like -setfacl but affecting all files below eventual directories.
-setfacl_list disk_path -setfacl_list disk_path
Read the output of -getfacl_r or shell command getfacl -R and appl y it to the iso_rr_paths as given Read the output of -getfacl_r or shell command getfacl -R and appl y it to the iso_rr_paths as given
in lines beginning with "# file:". This will change ownership, gro in lines beginning with "# file:". This will change ownership,
up and ACL of the given files. group and ACL of the given files.
If disk_path is "-" then lines are read from standard input. Lin If disk_path is "-" then lines are read from standard input. Line
e "@" ends the list, "@@@" aborts "@" ends the list, "@@@" aborts
without changing the pending iso_rr_path. without changing the pending iso_rr_path.
Since -getfacl and getfacl -R strip leading "/" from file paths, t he setting of -cd does always Since -getfacl and getfacl -R strip leading "/" from file path s, the setting of -cd does always
matter. matter.
-setfattr [-]name value iso_rr_path [***] -setfattr [-]name value iso_rr_path [***]
Attach the given xattr pair of name and value to the given is Attach the given xattr pair of name and value to the given iso_rr_
o_rr_paths. If the given name is paths. If the given name is
prefixed by "-", then the pair with that name gets removed from prefixed by "-", then the pair with that name gets remove
the xattr list. If name is d from the xattr list. If name is
"--remove-all" then all user namespace xattr of the given iso "--remove-all" then all user namespace xattr of the given iso_rr_p
_rr_paths get deleted. In case of aths get deleted. In case of
deletion, value must be an empty text. deletion, value must be an empty text.
Which names are permissible depends on the setting of command -xat tr. "on" or "user" restricts Which names are permissible depends on the setting of command -xattr. "on" or "user" restricts
them to namespace "user". I.e. a name has to look like "user.x" or "user.whatever". them to namespace "user". I.e. a name has to look like "user.x" or "user.whatever".
-xattr setting "any" enables names from all namespaces except "iso fs". -xattr setting "any" enables names from all namespaces except "iso fs".
Values and names undergo the normal input processing Values and names undergo the normal input processing of
of xorriso. See also command xorriso. See also command
-backslash_codes. Other than with command -setfattr_list, the byte -backslash_codes. Other than with command -setfattr_list, the byt
value 0 cannot be expressed via e value 0 cannot be expressed via
-setfattr. -setfattr.
-setfattr_r [-]name value iso_rr_path [***] -setfattr_r [-]name value iso_rr_path [***]
Like -setfattr but affecting all files below eventual directories. Like -setfattr but affecting all files below eventual directories.
-setfattr_list disk_path -setfattr_list disk_path
Read the output format of -getfattr_r or shell command ge Read the output format of -getfattr_r or shell command getfa
tfattr -Rd and apply it to the ttr -Rd and apply it to the
iso_rr_paths as given in lines beginning with "# file:". All pre iso_rr_paths as given in lines beginning with "# file:". All
viously existing xattr of the previously existing xattr of the
acceptable namespaces will be deleted before the new xattr ge acceptable namespaces will be deleted before the new xattr get at
t attached. The set of acceptable tached. The set of acceptable
names depends on the setting of command -xattr. names depends on the setting of command -xattr.
If disk_path is "-" then lines are read from standard input. If disk_path is "-" then lines are read from standard input.
Since -getfattr and getfattr -Rd strip leading "/" from file paths , the setting of -cd does always Since -getfattr and getfattr -Rd strip leading "/" from file path s, the setting of -cd does always
matter. matter.
Empty input lines and lines which begin by "#" will be ignored Empty input lines and lines which begin by "#" will be ignored (ex
(except "# file:"). Line "@" ends cept "# file:"). Line "@" ends
the list, "@@@" aborts without changing the pending iso_rr_path. O the list, "@@@" aborts without changing the pending iso_rr_path
ther input lines must have the . Other input lines must have the
form form
name="value" name="value"
The separator "=" is not allowed in names. Value may contain The separator "=" is not allowed in names. Value may contain any
any kind of bytes. It must be in kind of bytes. It must be in
quotes. Trailing whitespace after the end quote will be ignored. N quotes. Trailing whitespace after the end quote will be ignored
on-printables bytes and quotes . Non-printables bytes and quotes
must be represented as \XYZ by their octal 8-bit code XYZ. Use co de \000 for 0-bytes. must be represented as \XYZ by their octal 8-bit code XYZ. Use co de \000 for 0-bytes.
-alter_date type timestring iso_rr_path [***] -alter_date type timestring iso_rr_path [***]
Alter the date entries of files in the ISO image. type may be one of the following: Alter the date entries of files in the ISO image. type may be one of the following:
"a" sets access time, updates ctime. "a" sets access time, updates ctime.
"m" sets modification time, updates ctime. "m" sets modification time, updates ctime.
"b" sets access time and modification time, updates ctime. "b" sets access time and modification time, updates ctime.
"a-c", "m-c", and "b-c" set the times without updating ctime. "a-c", "m-c", and "b-c" set the times without updating ctime.
"c" sets the ctime. "c" sets the ctime.
timestring may be in the following formats (see also section EXAMP LES): timestring may be in the following formats (see also section EXAMP LES):
As expected by program date: As expected by program date:
MMDDhhmm[[CC]YY][.ss]] MMDDhhmm[[CC]YY][.ss]]
As produced by program date: As produced by program date:
[Day] MMM DD hh:mm:ss [TZON] YYYY [Day] MMM DD hh:mm:ss [TZON] YYYY
Relative times counted from current clock time: Relative times counted from current clock time:
+|-Number["s"|"h"|"d"|"w"|"m"|"y"] +|-Number["s"|"h"|"d"|"w"|"m"|"y"]
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"= 30d, "y"=365.25d plus 1d added to where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, "y"=365.25d plus 1d added to
multiplication result. multiplication result.
Absolute seconds counted from Jan 1 1970: Absolute seconds counted from Jan 1 1970:
=Number =Number
xorriso's own timestamps: xorriso's own timestamps:
YYYY.MM.DD[.hh[mm[ss]]] YYYY.MM.DD[.hh[mm[ss]]]
scdbackup timestamps: scdbackup timestamps:
YYMMDD[.hhmm[ss]] YYMMDD[.hhmm[ss]]
where "A0" is year 2000, "B0" is 2010, etc. where "A0" is year 2000, "B0" is 2010, etc.
ECMA-119 volume timestamps: ECMA-119 volume timestamps:
YYYYMMDDhhmmsscc YYYYMMDDhhmmsscc
These are normally given as GMT. The suffix "LOC" causes l These are normally given as GMT. The suffix "LOC" causes
ocal timezone conversion. E.g. local timezone conversion. E.g.
2013010720574700, 2013010720574700LOC. The last two digits cc (c 2013010720574700, 2013010720574700LOC. The last two digits cc (ce
entiseconds) will be ignored, but ntiseconds) will be ignored, but
must be present in order to make the format recognizable. must be present in order to make the format recognizable.
Example: Example:
-alter_date m-c 2013.11.27.103951 /file1 /file2 -- -alter_date m-c 2013.11.27.103951 /file1 /file2 --
This command does not persistently apply to the boot catalog, w hich gets fresh timestamps at This command does not persistently apply to the boot catalo g, which gets fresh timestamps at
-commit time. Command -volume_date "uuid" can set this time value. -commit time. Command -volume_date "uuid" can set this time value.
-alter_date_r type timestring iso_rr_path [***] -alter_date_r type timestring iso_rr_path [***]
Like -alter_date but affecting all files below eventual directorie s. Like -alter_date but affecting all files below eventual directorie s.
-hide hide_state iso_rr_path [***] -hide hide_state iso_rr_path [***]
Prevent the names of the given files from showing up in the d Prevent the names of the given files from showing up in the direct
irectory trees of ISO 9660 and/or ory trees of ISO 9660 and/or
Joliet and/or HFS+ when the image gets written. The data content Joliet and/or HFS+ when the image gets written. The data con
of such hidden files will be tent of such hidden files will be
included in the resulting image, even if they do not show up in included in the resulting image, even if they do not show up in an
any directory. But you will need y directory. But you will need
own means to find nameless data in the image. own means to find nameless data in the image.
Warning: Data which are hidden from the ISO 9660 tree will not be copied by the write method of Warning: Data which are hidden from the ISO 9660 tree will not be copied by the write method of
modifying. modifying.
Possible values of hide_state are: "iso_rr" for hiding from I SO 9660 tree, "joliet" for Joliet Possible values of hide_state are: "iso_rr" for hiding from ISO 9 660 tree, "joliet" for Joliet
tree, "hfsplus" for HFS+, "on" for them all. "off" means visibili ty in all directory trees. tree, "hfsplus" for HFS+, "on" for them all. "off" means visibili ty in all directory trees.
These values may be combined. E.g.: joliet:hfsplus These values may be combined. E.g.: joliet:hfsplus
This command does not apply to the boot catalog. Rather use: -boo t_image "any" "cat_hidden=on" This command does not apply to the boot catalog. Rather use: -boo t_image "any" "cat_hidden=on"
Tree traversal command -find: Tree traversal command -find:
-find iso_rr_path [test [op] [test ...]] [-exec action [params]] -- -find iso_rr_path [test [op] [test ...]] [-exec action [params]] --
A restricted substitute for shell command find in the ISO image. It performs an action on matching A restricted substitute for shell command find in the ISO image. It performs an action on matching
file objects at or below iso_rr_path. file objects at or below iso_rr_path.
If not used as last command in the line then the parameter list ne eds to get terminated by "--". If not used as last command in the line then the parameter list ne eds to get terminated by "--".
Tests are optional. If they are omitted then action is applied Tests are optional. If they are omitted then action is applied to
to all file objects. If tests are all file objects. If tests are
given then they form together an expression. The action is applie given then they form together an expression. The action is appli
d only if the expression matches ed only if the expression matches
the file object. Default expression operator between tests is the file object. Default expression operator between tests is -and
-and, i.e. the expression matches , i.e. the expression matches
only if all its tests match. only if all its tests match.
Available tests are: Available tests are:
-name pattern : Matches if pattern matches the file leaf name. If the pattern does not contain any -name pattern : Matches if pattern matches the file leaf name. If the pattern does not contain any
of the characters "*?[", then it will be truncated according to -f ile_name_limit and thus match the of the characters "*?[", then it will be truncated according to -f ile_name_limit and thus match the
truncated name in the ISO filesystem. truncated name in the ISO filesystem.
-wholename pattern : Matches if pattern matches the file path as i t would be printed by action -wholename pattern : Matches if pattern matches the file path as it would be printed by action
"echo". Character '/' can be matched by wildcards. If pattern piec es between '/' do not contain any "echo". Character '/' can be matched by wildcards. If pattern piec es between '/' do not contain any
of the characters "*?[", they will be truncated according to -file _name_limit. of the characters "*?[", they will be truncated according to -file _name_limit.
-disk_name pattern : Like -name but testing the leaf name of the f -disk_name pattern : Like -name but testing the leaf name of th
ile source on disk. Can match e file source on disk. Can match
only data files which do not stem from the loaded image, or for d only data files which do not stem from the loaded image, or for di
irectories above such data files. rectories above such data files.
With directories the result can change between -find runs if thei With directories the result can change between -find runs if
r content stems from multiple their content stems from multiple
sources. sources.
-disk_path disk_path : Matches if the given disk_path is equal to the path of the file source on -disk_path disk_path : Matches if the given disk_path is equal to the path of the file source on
disk. The same restrictions apply as with -disk_name. disk. The same restrictions apply as with -disk_name.
-type type_letter : Matches files of the given type: "block", "char", "dir", "pipe", "file", -type type_letter : Matches files of the given type: "block ", "char", "dir", "pipe", "file",
"link", "socket", "eltorito", and "Xotic" which matches what is no t matched by the other types. "link", "socket", "eltorito", and "Xotic" which matches what is no t matched by the other types.
Only the first letter is interpreted. E.g.: -find / -type d Only the first letter is interpreted. E.g.: -find / -type d
-maxdepth number : Matches only files which are at most at the -maxdepth number : Matches only files which are at most at the giv
given depth level relative to the en depth level relative to the
iso_rr_path where -find starts. That path itself is at depth 0, it iso_rr_path where -find starts. That path itself is at depth 0,
s directory children are at 1, its directory children are at 1,
their directory children at 2, and so on. their directory children at 2, and so on.
-mindepth number : Matches only files which are at least at the gi ven depth level. -mindepth number : Matches only files which are at least at the gi ven depth level.
-damaged : Matches files which use data blocks marked as damaged b y a previous run of -check_media. -damaged : Matches files which use data blocks marked as damaged b y a previous run of -check_media.
The damage info vanishes when a new ISO image gets loaded. The damage info vanishes when a new ISO image gets loaded.
Note that a MD5 session mismatch marks all files of the session as damaged. If finer distinction 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. is desired, perform -md5 off before -check_media.
-pending_data : Matches files which get their content from outside the loaded ISO image. -pending_data : Matches files which get their content from outside the loaded ISO image.
-lba_range start_lba block_count : Matches files which use data blocks within the range of -lba_range start_lba block_count : Matches files which use dat a blocks within the range of
start_lba and start_lba+block_count-1. start_lba and start_lba+block_count-1.
-has_acl : Matches files which have a non-trivial ACL. -has_acl : Matches files which have a non-trivial ACL.
-has_xattr : Matches files which have xattr name-value pairs from user namespace. -has_xattr : Matches files which have xattr name-value pairs from user namespace.
-has_aaip : Matches files which have ACL or any xattr. -has_aaip : Matches files which have ACL or any xattr.
-has_any_xattr : Matches files which have any xattr other than ACL . -has_any_xattr : Matches files which have any xattr other than ACL .
-has_md5 : Matches data files which have MD5 checksums. -has_md5 : Matches data files which have MD5 checksums.
-has_hfs_crtp creator type : Matches files which have the given HF -has_hfs_crtp creator type : Matches files which have the give
S+ creator and type attached. n HFS+ creator and type attached.
These are codes of 4 characters which get stored if -hfsplus is These are codes of 4 characters which get stored if -hfsplus is en
enabled. Use a single dash '-' as abled. Use a single dash '-' as
wildcard that matches any such code. E.g:. wildcard that matches any such code. E.g:.
-has_hfs_crtp YYDN TEXT -has_hfs_crtp YYDN TEXT
-has_hfs_crtp - - -has_hfs_crtp - -
-has_hfs_bless blessing : Matches files which bear the given HFS+ -has_hfs_bless blessing : Matches files which bear the given
blessing. It may be one of : HFS+ blessing. It may be one of :
"ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "os "ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx
x_folder", "any". See also action _folder", "any". See also action
set_hfs_bless. set_hfs_bless.
-has_filter : Matches files which are filtered by -set_filter. -has_filter : Matches files which are filtered by -set_filter.
-hidden hide_state : Matches files which are hidden in "iso_rr " tree, in "joliet" tree, in -hidden hide_state : Matches files which are hidden in "i so_rr" tree, in "joliet" tree, in
"hfsplus" tree, in all trees ("on"), or not hidden in any tree ("o ff"). "hfsplus" tree, in all trees ("on"), or not hidden in any tree ("o ff").
Those which are hidden in some tree match -not -hidden "off". Those which are hidden in some tree match -not -hidden "off".
-bad_outname namespace : Matches files with names which cha -bad_outname namespace : Matches files with names which change
nge when converted forth and back when converted forth and back
between the local character set and one of the namespaces "r between the local character set and one of the namespaces
ockridge", "joliet", "ecma119", "rockridge", "joliet", "ecma119",
"hfsplus". "hfsplus".
All applicable -compliance rules are taken into respect. Rule All applicable -compliance rules are taken into respect. Rule "om
"omit_version" is always enabled, it_version" is always enabled,
because else namespaces "joliet" and "ecma119" would cause changes because else namespaces "joliet" and "ecma119" would cause chang
with every non-directory name. es with every non-directory name.
Consider to also enable rules "no_force_dots" and "no_j_force_dots ". Consider to also enable rules "no_force_dots" and "no_j_force_dots ".
The namespaces use different character sets and apply furt The namespaces use different character sets and apply further
her restrictions to name length, restrictions to name length,
permissible characters, and mandatory name components. "rockridge permissible characters, and mandatory name components. "rockridg
" uses the character set defined e" uses the character set defined
by -out_charset, "joliet" uses UCS-2BE, "ecma119" uses ASCII, "hfs plus" uses UTF-16BE. by -out_charset, "joliet" uses UCS-2BE, "ecma119" uses ASCII, "hfs plus" uses UTF-16BE.
-name_limit_blocker length : Matches file names which would prev ent command -file_name_limit with -name_limit_blocker length : Matches file names which would preven t command -file_name_limit with
the given length. The command itself reports only the first proble m file. the given length. The command itself reports only the first proble m file.
-prune : If this test is reached and the tested file is a director y then -find will not dive into -prune : If this test is reached and the tested file is a direct ory then -find will not dive into
that directory. This test itself does always match. that directory. This test itself does always match.
-use_pattern "on"|"off" : This pseudo test controls the inter -use_pattern "on"|"off" : This pseudo test controls the interpret
pretation of wildcards with tests ation of wildcards with tests
-name, -wholename, and -disk_name. Default is "on". If interpretat -name, -wholename, and -disk_name. Default is "on". If interpre
ion is disabled by "off", then tation is disabled by "off", then
the parameters of -name, -wholename, and -disk_name have to matc the parameters of -name, -wholename, and -disk_name have to match
h literally rather than as search literally rather than as search
pattern. This test itself does always match. pattern. This test itself does always match.
-or_use_pattern "on"|"off" : Like -use_pattern, but automatically -or_use_pattern "on"|"off" : Like -use_pattern, but automatically
appending the test by -or rather appending the test by -or rather
than by -and. Further the test itself does never match. So a s than by -and. Further the test itself does never match. So a subse
ubsequent test -or will cause its quent test -or will cause its
other operand to be performed. other operand to be performed.
-decision "yes"|"no" : If this test is reached then the evaluation ends immediately and action is -decision "yes"|"no" : If this test is reached then the evaluati on ends immediately and action is
performed if the decision is "yes" or "true". See operator -if. performed if the decision is "yes" or "true". See operator -if.
-true and -false : Always match or match not, respectively. Evalua tion goes on. -true and -false : Always match or match not, respectively. Evalua tion goes on.
-sort_lba : Always match. This causes -find to perform its actio -sort_lba : Always match. This causes -find to perform its action
n in a sequence sorted by the ISO in a sequence sorted by the ISO
image block addresses of the files. It may improve throughput with image block addresses of the files. It may improve throughput
actions which read data from with actions which read data from
optical drives. Action will always get the absolute path as parame ter. optical drives. Action will always get the absolute path as parame ter.
Available operators are: Available operators are:
-not : Matches if the next test or sub expression does not match. Several tests do this -not : Matches if the next test or sub expression does not match. Several tests do this
specifically: specifically:
-undamaged, -lba_range with negative start_lba, -has_no_acl, -has_no_xattr, -has_no_aaip, -undamaged, -lba_range with negative start_lba, -has_no_ac l, -has_no_xattr, -has_no_aaip,
-has_no_filter . -has_no_filter .
-and : Matches if both neighboring tests or expressions match. -and : Matches if both neighboring tests or expressions match.
-or : Matches if at least one of both neighboring tests or express ions matches. -or : Matches if at least one of both neighboring tests or express ions matches.
-sub ... -subend or ( ... ) : Enclose a sub expression which gets evaluated first before it is -sub ... -subend or ( ... ) : Enclose a sub expression which gets evaluated first before it is
processed by neighboring operators. Normal precedence is: -not, - or , -and. processed by neighboring operators. Normal precedence is: -not, - or , -and.
-if ... -then ... -elseif ... -then ... -else ... -endif : Enclos e one or more sub expressions. If -if ... -then ... -elseif ... -then ... -else ... -endif : Enclos e one or more sub expressions. If
the -if expression matches, then the -then expression is eva luated as the result of the whole the -if expression matches, then the -then expression is evaluated as the result of the whole
expression up to -endif. Else the next -elseif expression is evalu ated and if it matches, its -then expression up to -endif. Else the next -elseif expression is evalu ated and if it matches, its -then
expression. Finally in case of no match, the -else expression is e valuated. There may be more than expression. Finally in case of no match, the -else expression is e valuated. There may be more than
one -elseif. Neither -else nor -elseif are mandatory. If -else is missing and would be hit, then one -elseif. Neither -else nor -elseif are mandatory. If -else is missing and would be hit, then
the result is a non-match. the result is a non-match.
-if-expressions are the main use case for above test -decision. -if-expressions are the main use case for above test -decision.
Default action is echo, i.e. to print the address of the foun Default action is echo, i.e. to print the address of the found fi
d file. Other actions are certain le. Other actions are certain
xorriso commands which get performed on the found files. The xorriso commands which get performed on the found files.
se commands may have specific These commands may have specific
parameters. See also their particular descriptions. parameters. See also their particular descriptions.
chown and chown_r change the ownership and get the user id as pa rameter. E.g.: -exec chown thomas chown and chown_r change the ownership and get the user id as para meter. E.g.: -exec chown thomas
-- --
chgrp and chgrp_r change the group attribute and get the group id as parameter. E.g.: -exec chgrp_r chgrp and chgrp_r change the group attribute and get the group id as parameter. E.g.: -exec chgrp_r
staff -- staff --
chmod and chmod_r change access permissions and get a mode string as parameter. E.g.: -exec chmod chmod and chmod_r change access permissions and get a mode string as parameter. E.g.: -exec chmod
a-w,a+r -- a-w,a+r --
alter_date and alter_date_r change the timestamps. They get a type character and a timestring as alter_date and alter_date_r change the timestamps. They get a t ype character and a timestring as
parameters. parameters.
E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" -- E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" --
set_to_mtime sets the ctime and atime to the value found in mtime. set_to_mtime sets the ctime and atime to the value found in mtime.
lsdl prints file information like shell command ls -dl. lsdl prints file information like shell command ls -dl.
compare performs command -compare with the found file address as compare performs command -compare with the found file address as i
iso_rr_path and the corresponding so_rr_path and the corresponding
file address below its parameter disk_path_start. For this the iso file address below its parameter disk_path_start. For this the
_rr_path of the -find command iso_rr_path of the -find command
gets replaced by the disk_path_start. gets replaced by the disk_path_start.
E.g.: -find /thomas -exec compare /home/thomas -- E.g.: -find /thomas -exec compare /home/thomas --
update performs command -update with the found file address as is o_rr_path. The corresponding file update performs command -update with the found file address as iso _rr_path. The corresponding file
address is determined like with above action "compare". address is determined like with above action "compare".
update_merge is like update but does not delete the found file if it is missing on disk. It may be update_merge is like update but does not delete the found file if it is missing on disk. It may be
run several times and records with all visited files whether thei run several times and records with all visited files whether their
r counterpart on disk has already counterpart on disk has already
been seen by one of the update_merge runs. Finally, a -find run w been seen by one of the update_merge runs. Finally, a -find run
ith action "rm_merge" may remove with action "rm_merge" may remove
all files that saw no counterpart on disk. all files that saw no counterpart on disk.
Up to the next "rm_merge" or "clear_merge" all newly inserted files will get marked as having a Up to the next "rm_merge" or "clear_merge" all newly inserted file s will get marked as having a
disk counterpart. disk counterpart.
rm removes the found iso_rr_path from the image if it is not a dir ectory with files in it. I.e. rm removes the found iso_rr_path from the image if it is not a directory with files in it. I.e.
this "rm" includes "rmdir". this "rm" includes "rmdir".
rm_r removes the found iso_rr_path from the image, including whole directory trees. rm_r removes the found iso_rr_path from the image, including whole directory trees.
rm_merge removes the found iso_rr_path if it was visited rm_merge removes the found iso_rr_path if it was visited by
by one or more previous actions one or more previous actions
"update_merge" and saw no counterpart on disk in any of them. The "update_merge" and saw no counterpart on disk in any of them. Th
marking from the update actions e marking from the update actions
is removed in any case. is removed in any case.
clear_merge removes an eventual marking from action "update_merge" . clear_merge removes an eventual marking from action "update_merge" .
report_damage classifies files whether they hit a data block that report_damage classifies files whether they hit a data block that
is marked as damaged. The result is marked as damaged. The result
is printed together with the address of the first damaged byte, th is printed together with the address of the first damaged byte,
e maximum span of damages, file the maximum span of damages, file
size, and the path of the file. size, and the path of the file.
report_lba prints files which are associated to image data bl report_lba prints files which are associated to image data blocks.
ocks. It tells the logical block It tells the logical block
address, the block number, the byte size, and the path of each fil address, the block number, the byte size, and the path of each
e. There may be reported more file. There may be reported more
than one line per file if the file has more than one secti than one line per file if the file has more than one section. I
on. In this case each line has a n this case each line has a
different extent number in column "xt". different extent number in column "xt".
report_sections like report_lba but telling the byte sizes of the particular sections rather than report_sections like report_lba but telling the byte sizes of th e particular sections rather than
the overall byte size of the file. the overall byte size of the file.
getfacl prints access permissions in ACL text form to the result c hannel. getfacl prints access permissions in ACL text form to the result c hannel.
setfacl attaches ACLs after removing existing ones. The new ACL is given in text form as defined setfacl attaches ACLs after removing existing ones. The new ACL is given in text form as defined
with command -setfacl. with command -setfacl.
E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw -- E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
getfattr prints xattr name-value pairs to the result channel. The getfattr prints xattr name-value pairs to the result channel. Th
choice of namespaces depends on e choice of namespaces depends on
the setting of command -xattr: "on" or "user" restricts it to the setting of command -xattr: "on" or "user" restricts it to the
the namespace "user", "any" only namespace "user", "any" only
omits namespace "isofs". omits namespace "isofs".
get_any_xattr prints xattr name-value pairs from any namespace exc ept ACL to the result channel. get_any_xattr prints xattr name-value pairs from any namespace except ACL to the result channel.
This is mostly for debugging of namespace "isofs". This is mostly for debugging of namespace "isofs".
list_extattr mode prints a script to the result channel, which wou ld use FreeBSD command setextattr list_extattr mode prints a script to the result channel, which wou ld use FreeBSD command setextattr
to set the file's xattr name-value pairs of user namespace. Param to set the file's xattr name-value pairs of user namespace. Pa
eter mode controls the form of rameter mode controls the form of
the output of names and values. Default mode "e" prints harml the output of names and values. Default mode "e" prints harmless
ess characters in shell quotation characters in shell quotation
marks, but represents texts with octal 001 to 037 and 0177 to 0377 marks, but represents texts with octal 001 to 037 and 0177 to 037
by an embedded echo -e command. 7 by an embedded echo -e command.
Mode "q" prints any characters in shell quotation marks. This migh t not be terminal-safe but should Mode "q" prints any characters in shell quotation marks. This migh t not be terminal-safe but should
work in script files. Mode "r" uses no quotation marks. Not saf e. Mode "b" prints backslash work in script files. Mode "r" uses no quotation marks. Not safe. Mode "b" prints backslash
encoding. Not suitable for shell parsing. encoding. Not suitable for shell parsing.
E.g. -exec list_extattr e -- E.g. -exec list_extattr e --
Command -backslash_codes does not affect the output. Command -backslash_codes does not affect the output.
get_md5 prints the MD5 sum, if recorded, together with file path. get_md5 prints the MD5 sum, if recorded, together with file path.
check_md5 compares the MD5 sum, if recorded, with the file content and reports if mismatch. check_md5 compares the MD5 sum, if recorded, with the file content and reports if mismatch.
E.g.: -find / -not -pending_data -exec check_md5 FAILURE -- E.g.: -find / -not -pending_data -exec check_md5 FAILURE --
make_md5 equips a data file with an MD5 sum of its content. U seful to upgrade the files in the make_md5 equips a data file with an MD5 sum of its content. Useful to upgrade the files in the
loaded image to full MD5 coverage by the next commit with -md5 "on ". loaded image to full MD5 coverage by the next commit with -md5 "on ".
E.g.: -find / -type f -not -has_md5 -exec make_md5 -- E.g.: -find / -type f -not -has_md5 -exec make_md5 --
setfattr sets or deletes xattr name value pairs. setfattr sets or deletes xattr name value pairs.
E.g.: -find / -has_xattr -exec setfattr --remove-all '' -- E.g.: -find / -has_xattr -exec setfattr --remove-all '' --
set_hfs_crtp adds, changes, or removes HFS+ creator and type attri butes. set_hfs_crtp adds, changes, or removes HFS+ creator and type attri butes.
E.g.: -exec set_hfs_crtp YYDN TEXT E.g.: -exec set_hfs_crtp YYDN TEXT
E.g.: -find /my/dir -prune -exec set_hfs_crtp --delete - E.g.: -find /my/dir -prune -exec set_hfs_crtp --delete -
get_hfs_crtp prints the HFS+ creator and type attributes together with the iso_rr_path, if the file get_hfs_crtp prints the HFS+ creator and type attributes together with the iso_rr_path, if the file
has such attributes at all. has such attributes at all.
E.g.: -exec get_hfs_crtp E.g.: -exec get_hfs_crtp
set_hfs_bless applies or removes HFS+ blessings. They are roles which can be attributed to up to set_hfs_bless applies or removes HFS+ blessings. They are roles wh ich can be attributed to up to
four directories and a data file: four directories and a data file:
"ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx _folder". "ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx _folder".
They may be abbreviated as "p", "i", "s", "9", and "x". They may be abbreviated as "p", "i", "s", "9", and "x".
Each such role can be attributed to at most one file object. "inte l_bootfile" is the one that would Each such role can be attributed to at most one file object. "inte l_bootfile" is the one that would
apply to a data file. All others apply to directories. The -find run will end as soon as the first apply to a data file. All others apply to directories. The -find run will end as soon as the first
blessing is issued. The previous bearer of the blessing will lose it then. No file object can bear blessing is issued. The previous bearer of the blessing will lose it then. No file object can bear
more than one blessing. more than one blessing.
E.g.: -find /my/blessed/directory -exec set_hfs_bless p E.g.: -find /my/blessed/directory -exec set_hfs_bless p
Further there is blessing "none" or "n" which revokes any blessing from the found files. This -find Further there is blessing "none" or "n" which revokes any blessing from the found files. This -find
run will not stop when the first match is reached. run will not stop when the first match is reached.
E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none
get_hfs_bless prints the HFS+ blessing role and the iso_rr_path, i f the file is blessed at all. get_hfs_bless prints the HFS+ blessing role and the iso_rr_path, i f the file is blessed at all.
E.g.: -exec get_hfs_bless E.g.: -exec get_hfs_bless
set_filter applies or removes filters. set_filter applies or removes filters.
E.g.: -exec set_filter --zisofs -- E.g.: -exec set_filter --zisofs --
mkisofs_r applies the rules of mkisofs -r to the file object: mkisofs_r applies the rules of mkisofs -r to the file object:
user id and group id become 0, all r-permissions get granted, all w denied. If there is any user id and group id become 0, all r-permissions get grante d, all w denied. If there is any
x-permission, then all three x get granted. s- and t-bits get rem oved. x-permission, then all three x get granted. s- and t-bits get rem oved.
sort_weight attributes a LBA weight number to regular files. sort_weight attributes a LBA weight number to regular files.
The number may range from -2147483648 to 2147483647. The higher i The number may range from -2147483648 to 2147483647. The higher it
t is, the lower will be the block is, the lower will be the block
address of the file data in the emerging ISO image. Currently the address of the file data in the emerging ISO image. Currently
boot catalog has a hardcoded the boot catalog has a hardcoded
weight of 1 billion. Normally it should occupy the block with the lowest possible address. weight of 1 billion. Normally it should occupy the block with the lowest possible address.
Data files which are loaded by -indev or -dev get a weight betw Data files which are loaded by -indev or -dev get a weight between
een 1 and 2 exp 28 = 268,435,456, 1 and 2 exp 28 = 268,435,456,
depending on their block address. This shall keep them roughly in depending on their block address. This shall keep them rough
the same order if the write ly in the same order if the write
method of modifying is applied. method of modifying is applied.
Data files which are added by other commands get an initial weig ht of 0. Boot image files have a Data files which are added by other commands get an initial weight of 0. Boot image files have a
default weight of 2. default weight of 2.
E.g.: -exec sort_weight 3 -- E.g.: -exec sort_weight 3 --
show_stream shows the content stream chain of a data file. show_stream shows the content stream chain of a data file.
show_stream_id is like show_stream, but also prints between stream type and first ":" in square show_stream_id is like show_stream, but also prints between st ream type and first ":" in square
brackets libisofs id numbers: [fs_id,dev_id,ino_id]. brackets libisofs id numbers: [fs_id,dev_id,ino_id].
hide brings the file into one of the hide states "on", "iso_rr", "joliet", "hfsplus", "off". They hide brings the file into one of the hide states "on", "iso_rr", " joliet", "hfsplus", "off". They
may be combined. E.g.: joliet:hfsplus may be combined. E.g.: joliet:hfsplus
E.g.: E.g.:
-find / -disk_name *_secret -exec hide on -find / -disk_name *_secret -exec hide on
print_outname prints in the first line the filename as registered by the program model, and in the print_outname prints in the first line the filename as registered by the program model, and in the
second line the filename after conversion forth and back between l ocal character set and one of the second line the filename after conversion forth and back between l ocal character set and one of the
namespaces "rockridge", "joliet", "ecma119", or "hfsplus". The thi rd output line is "--" . namespaces "rockridge", "joliet", "ecma119", or "hfsplus". The thi rd output line is "--" .
The name conversion does not take into respect the possibility of The name conversion does not take into respect the possibility
name collisions in the target of name collisions in the target
namespace. Such collisions are most likely in "joliet" and "ecm namespace. Such collisions are most likely in "joliet" and "ecma11
a119", where they get resolved by 9", where they get resolved by
automatic file name changes. automatic file name changes.
E.g.: E.g.:
-find / -bad_outname joliet -exec print_outname joliet -find / -bad_outname joliet -exec print_outname joliet
estimate_size prints a lower and an upper estimation of the number estimate_size prints a lower and an upper estimation of the numbe
of blocks which the found files r of blocks which the found files
together will occupy in the emerging ISO image. This does not ac together will occupy in the emerging ISO image. This does not acc
count for the superblock, for the ount for the superblock, for the
directories in the -find path, or for image padding. directories in the -find path, or for image padding.
find performs another run of -find on the matching file address. It accepts the same params as find performs another run of -find on the matching file addres s. It accepts the same params as
-find, except iso_rr_path. -find, except iso_rr_path.
E.g.: E.g.:
-find / -name '???' -type d -exec find -name '[abc]*' -exec chmo d a-w,a+r -- -find / -name '???' -type d -exec find -name '[abc]*' -exec chmo d a-w,a+r --
Filters for data file content: Filters for data file content:
Filters may be installed between data files in the ISO image and their content source outside the image. Filters may be installed between data files in the ISO image and their co ntent source outside the image.
They may also be used vice versa between data content in the image and ta rget files on disk. They may also be used vice versa between data content in the image and ta rget files on disk.
Built-in filters are "--zisofs" and "--zisofs-decode". The former is to b Built-in filters are "--zisofs" and "--zisofs-decode". The former is t
e applied via -set_filter, the o be applied via -set_filter, the
latter is automatically applied if zisofs compressed content is detected latter is automatically applied if zisofs compressed content is detected
with a file when loading the ISO with a file when loading the ISO
image. image.
Another built-in filter pair is "--gzip" and "--gunzip" with suffix " Another built-in filter pair is "--gzip" and "--gunzip" with suff
.gz". They behave about like ix ".gz". They behave about like
external gzip and gunzip but avoid forking a process for each single external gzip and gunzip but avoid forking a process for each single file
file. So they are much faster if . So they are much faster if
there are many small files. there are many small files.
-external_filter name option[:option] program_path [arguments] -- -external_filter name option[:option] program_path [arguments] --
Register a content filter by associating a name with a program pat Register a content filter by associating a name with a program
h, program arguments, and some path, program arguments, and some
behavioral options. Once registered it can be applied to mult behavioral options. Once registered it can be applied to multiple
iple data files in the ISO image, data files in the ISO image,
regardless whether their content resides in the loaded ISO image regardless whether their content resides in the loaded ISO
or in the local filesystem. image or in the local filesystem.
External filter processes may produce synthetic file content by External filter processes may produce synthetic file content by re
reading the original content from ading the original content from
stdin and writing to stdout whatever they want. They must deliver stdin and writing to stdout whatever they want. They must de
the same output on the same liver the same output on the same
input in repeated runs. input in repeated runs.
Options are: Options are:
"default" means that no other option is intended. "default" means that no other option is intended.
"suffix=..." sets a file name suffix. If it is not empty then it will be appended to the file name "suffix=..." sets a file name suffix. If it is not empty then it will be appended to the file name
or removed from it. or removed from it.
"remove_suffix" will remove a file name suffix rather than append ing it. "remove_suffix" will remove a file name suffix rather than append ing it.
"if_nonempty" will leave 0-sized files unfiltered. "if_nonempty" will leave 0-sized files unfiltered.
"if_reduction" will try filtering and revoke it if the content si ze does not shrink. "if_reduction" will try filtering and revoke it if the content si ze does not shrink.
"if_block_reduction" will revoke if the number of 2 kB blocks doe s not shrink. "if_block_reduction" will revoke if the number of 2 kB blocks doe s not shrink.
"used=..." is ignored. Command -status shows it with the number o f files which currently have the "used=..." is ignored. Command -status shows it with the number of files which currently have the
filter applied. filter applied.
Examples: Examples:
-external_filter bzip2 suffix=.bz2:if_block_reduction \ -external_filter bzip2 suffix=.bz2:if_block_reduction \
/usr/bin/bzip2 -- /usr/bin/bzip2 --
-external_filter bunzip2 suffix=.bz2:remove_suffix \ -external_filter bunzip2 suffix=.bz2:remove_suffix \
/usr/bin/bunzip2 -- /usr/bin/bunzip2 --
-unregister_filter name -unregister_filter name
Remove an -external_filter registration. This is only possible if the filter is not applied to any Remove an -external_filter registration. This is only possible if the filter is not applied to any
file in the ISO image. file in the ISO image.
-close_filter_list -close_filter_list
Irrevocably ban commands -concat "pipe", -external_filter, a nd -unregister_filter, but not Irrevocably ban commands -concat "pipe", -external_filter, a nd -unregister_filter, but not
-set_filter. Use this to prevent external filtering in general -set_filter. Use this to prevent external filtering in general or
or when all intended filters are when all intended filters are
registered and -concat mode "pipe" shall be disallowed. Externa registered and -concat mode "pipe" shall be disallowed. Ex
l filters may also be banned ternal filters may also be banned
totally at compile time of xorriso. By default they are ba totally at compile time of xorriso. By default they are banned
nned if xorriso runs under setuid if xorriso runs under setuid
permission. permission.
-set_filter name iso_rr_path [***] -set_filter name iso_rr_path [***]
Apply an -external_filter or a built-in filter to the given data f Apply an -external_filter or a built-in filter to the given dat
iles in the ISO image. If the a files in the ISO image. If the
filter suffix is not empty , then it will be applied to the fil filter suffix is not empty , then it will be applied to the file n
e name. Renaming only happens if ame. Renaming only happens if
the filter really gets attached and is not revoked by its options. the filter really gets attached and is not revoked by its options
By default files which already . By default files which already
bear the suffix will not get filtered. The others will get the su bear the suffix will not get filtered. The others will get the suf
ffix appended to their names. If fix appended to their names. If
the filter has option "remove_suffix", then the filter will only the filter has option "remove_suffix", then the filter will
be applied if the suffix is only be applied if the suffix is
present and can be removed. Name oversize or collision cau present and can be removed. Name oversize or collision caused
sed by suffix change will prevent by suffix change will prevent
filtering. filtering.
With most filter types this command will immediately run the filte With most filter types this command will immediately run the filt
r once for each file in order to er once for each file in order to
determine the output size. Content reading operations like determine the output size. Content reading operations like
-extract , -compare and image -extract , -compare and image
generation will perform further filter runs and deliver filtered c ontent. generation will perform further filter runs and deliver filtered c ontent.
extract , -compare and image
At image generation time the filter output must still be the same as the output from the first run. At image generation time the filter output must still be the same as the output from the first run.
Filtering for image generation does not happen with files from the loaded ISO image if the write Filtering for image generation does not happen with files from the loaded ISO image if the write
method of growing is in effect (i.e -indev and -outdev are identic al). method of growing is in effect (i.e -indev and -outdev are identic al).
The reserved filter name "--remove-all-filters" revokes filte ring. This will revoke suffix The reserved filter name "--remove-all-filters" revokes filt ering. This will revoke suffix
renamings as well. Use "--remove-all-filters+" to prevent any suf fix renaming. renamings as well. Use "--remove-all-filters+" to prevent any suf fix renaming.
Attaching or detaching filters will not alter the state of Attaching or detaching filters will not alter the state of -c
-changes_pending. If the filter hanges_pending. If the filter
manipulations shall be the only changes in a write run, then expl manipulations shall be the only changes in a write run, then ex
icitly execute -changes_pending plicitly execute -changes_pending
"yes". "yes".
-set_filter_r name iso_rr_path [***] -set_filter_r name iso_rr_path [***]
Like -set_filter but affecting all data files below eventual direc tories. Like -set_filter but affecting all data files below eventual direc tories.
Writing the result, drive control: Writing the result, drive control:
(see also paragraph about settings below) (see also paragraph about settings below)
-rollback -rollback
Discard the manipulated ISO image and reload it from -indev. (Use -rollback_end if immediate Discard the manipulated ISO image and reload it from -indev. ( Use -rollback_end if immediate
program end is desired.) program end is desired.)
-changes_pending "no"|"yes"|"mkisofs_printed"|"show_status" -changes_pending "no"|"yes"|"mkisofs_printed"|"show_status"
Write runs are performed only if a change of the image has been ma Write runs are performed only if a change of the image has been m
de since the image was loaded or ade since the image was loaded or
created blank. Vice versa the program will start a write run created blank. Vice versa the program will start a write run for
for pending changes when it ends pending changes when it ends
normally (i.e. not by abort and not by command -rollback_end). normally (i.e. not by abort and not by command -rollback_end).
The command -changes_pending can be used to override the automatic The command -changes_pending can be used to override the automa
ally determined state. This is tically determined state. This is
mainly useful for setting state "yes" despite no real ch mainly useful for setting state "yes" despite no real cha
anges were made. The sequence nges were made. The sequence
-changes_pending "no" -end is equivalent to the command -rollback_ -changes_pending "no" -end is equivalent to the command -rollbac
end. State "mkisofs_printed" is k_end. State "mkisofs_printed" is
caused by emulation command -as mkisofs if option -print-size is p resent. caused by emulation command -as mkisofs if option -print-size is p resent.
The pseudo-state "show_status" can be used to print the current st ate to result channel. The pseudo-state "show_status" can be used to print the current st ate to result channel.
Image loading or manipulations which happen after this command wi ll again update automatically the Image loading or manipulations which happen after this command wil l again update automatically the
change status of the image. change status of the image.
-commit -commit
Perform the write operation. Afterwards, if -outdev is readable, m Perform the write operation. Afterwards, if -outdev is readable,
ake it the new -dev and load the make it the new -dev and load the
image from there. Switch to growing mode. (A subsequent -outde image from there. Switch to growing mode. (A subsequent -outdev
v will activate modification mode will activate modification mode
or blind growing.) -commit is performed automatically at end of p or blind growing.) -commit is performed automatically at end of
rogram if there are uncommitted program if there are uncommitted
manipulations pending. manipulations pending.
So, to perform a final write operation with no new -dev and no new loading of image, rather execute So, to perform a final write operation with no new -dev and no new loading of image, rather execute
command -end. If you want to go on without image loading, execute -commit_eject "none". To eject command -end. If you want to go on without image loading, execut e -commit_eject "none". To eject
after write without image loading, use -commit_eject "all". after write without image loading, use -commit_eject "all".
To suppress a final write, execute -rollback_end. To suppress a final write, execute -rollback_end.
Writing can last quite a while. It is not unnormal with severa Writing can last quite a while. It is not unnormal with several ty
l types of media that there is no pes of media that there is no
progress visible for the first few minutes or that the drive gnaws progress visible for the first few minutes or that the drive gnaw
on the medium for a few minutes s on the medium for a few minutes
after all data have been transmitted. xorriso and the drives are after all data have been transmitted. xorriso and the drives are
in a client-server relationship. in a client-server relationship.
The drives have much freedom about what to do with the media. So The drives have much freedom about what to do with the media.
me combinations of drives and Some combinations of drives and
media simply do not work, despite the promises by their vendors. media simply do not work, despite the promises by their vendors.
If writing fails then try other If writing fails then try other
media or another drive. The reason for such failure is hardly ever media or another drive. The reason for such failure is hardly eve
in the code of the various burn r in the code of the various burn
programs but you may well try some of those listed below under SEE ALSO. programs but you may well try some of those listed below under SEE ALSO.
-eject "in"|"out"|"all" -eject "in"|"out"|"all"
Eject the medium in -indev, -outdev, or both drives, respectively. Note: It is not possible yet to Eject the medium in -indev, -outdev, or both drives, respectively. Note: It is not possible yet to
effectively eject disk files. effectively eject disk files.
-commit_eject "in"|"out"|"all"|"none" -commit_eject "in"|"out"|"all"|"none"
Combined -commit and -eject. When writing has finished do not make -outdev the new -dev, and load Combined -commit and -eject. When writing has finished do not ma ke -outdev the new -dev, and load
no ISO image. Rather eject -indev and/or -outdev. Give up any non- ejected drive. no ISO image. Rather eject -indev and/or -outdev. Give up any non- ejected drive.
-blank mode -blank mode
Make media ready for writing from scratch (if not -dummy is activa ted). Make media ready for writing from scratch (if not -dummy is activa ted).
This affects only the -outdev not the -indev. If both drives are the same and if the ISO image was This affects only the -outdev not the -indev. If both drives are the same and if the ISO image was
altered then this command leads to a FAILURE event. Defined modes are: altered then this command leads to a FAILURE event. Defined modes are:
as_needed, fast, all, deformat, deformat_quickest as_needed, fast, all, deformat, deformat_quickest
"as_needed" cares for used CD-RW, DVD-RW and for used overwrite "as_needed" cares for used CD-RW, DVD-RW and for used overwritable
able media by applying -blank media by applying -blank "fast".
"fast". It applies -format "full" to yet unformatted DVD-RAM and It applies -format "full" to yet unformatted DVD-RAM and BD-RE. O
BD-RE. Other media in blank state ther media in blank state are
are gracefully ignored. Media which cannot be made ready for writ gracefully ignored. Media which cannot be made ready for wri
ing from scratch cause a FAILURE ting from scratch cause a FAILURE
event. event.
"fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidate s overwriteable ISO images. "all" "fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidate s overwritable ISO images. "all"
might work more thoroughly and need more time. might work more thoroughly and need more time.
"deformat" converts overwriteable DVD-RW into unformatted ones. "deformat" converts overwritable DVD-RW into unformatted ones.
"deformat_quickest" is a faster way to deformat or blank DVD-RW bu "deformat_quickest" is a faster way to deformat or blank DVD-RW
t produces media which are only but produces media which are only
suitable for a single session. Some drives announce this state suitable for a single session. Some drives announce this state by
by not offering feature 21h, but not offering feature 21h, but
some drives offer it anyway. If feature 21h is missing, then xor some drives offer it anyway. If feature 21h is missing, the
riso will refuse to write on n xorriso will refuse to write on
DVD-RW if not command -close is set to "on". DVD-RW if not command -close is set to "on".
The progress reports issued by some drives while blanking are q The progress reports issued by some drives while blanking are quit
uite unrealistic. Do not conclude e unrealistic. Do not conclude
success or failure from the reported percentages. Blanking was suc success or failure from the reported percentages. Blanking wa
cessful if no SORRY event or s successful if no SORRY event or
worse occurred. worse occurred.
Mode may be prepended by "force:" in order to override the Mode may be prepended by "force:" in order to override the evalu
evaluation of the medium state by ation of the medium state by
libburn. E.g. "force:fast". Blanking will nevertheless only succe libburn. E.g. "force:fast". Blanking will nevertheless only succ
ed if the drive is willing to do eed if the drive is willing to do
it. it.
-format mode -format mode
Convert unformatted DVD-RW into overwriteable ones, "de-ice" DVD Convert unformatted DVD-RW into overwritable ones, "de-ice" DVD+RW
+RW, format newly purchased BD-RE , format newly purchased BD-RE or
or BD-R, re-format DVD-RAM or BD-RE. BD-R, re-format DVD-RAM or BD-RE.
Defined modes are: Defined modes are:
as_needed, full, fast, by_index_<num>, fast_by_index_<num>, as_needed, full, fast, by_index_<num>, fast_by_index_<num>,
by_size_<num>, fast_by_size_<num>, without_spare by_size_<num>, fast_by_size_<num>, without_spare
"as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or bla nk unformatted BD-R. Other media "as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or bl ank unformatted BD-R. Other media
are left untouched. are left untouched.
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank unfor matted BD-R. "full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank unfor matted BD-R.
"fast" does the same as "full" but tries to be quicker. "fast" does the same as "full" but tries to be quicker.
"by_index_" selects a format out of the descriptor list issued by command -list_formats. The index "by_index_" selects a format out of the descriptor list issued by command -list_formats. The index
number from that list is to be appended to the mode word. E.g: "by _index_3". number from that list is to be appended to the mode word. E.g: "by _index_3".
"fast_by_index_" does the same as "by_index_" but tries to be quic ker. "fast_by_index_" does the same as "by_index_" but tries to be quic ker.
"by_size_" selects a format out of the descriptor list which provi des at least the given size. That "by_size_" selects a format out of the descriptor list which provi des at least the given size. That
size is to be appended to the mode word. E.g: "by_size_4100m". This applies to media with Defect size is to be appended to the mode word. E.g: "by_size_4100m". Th is applies to media with Defect
Management. On BD-RE it will not choose format 0x31, which offers no Defect Management. Management. On BD-RE it will not choose format 0x31, which offers no Defect Management.
"fast_by_size_" does the same as "by_size_" but tries to be quicke r. "fast_by_size_" does the same as "by_size_" but tries to be quicke r.
"without_spare" selects the largest format out of the descriptor l ist which provides no Spare Area "without_spare" selects the largest format out of the descriptor list which provides no Spare Area
for Defect Management. On BD-RE this will be format 0x31. for Defect Management. On BD-RE this will be format 0x31.
The formatting action has no effect on media if -dummy is activate d. The formatting action has no effect on media if -dummy is activate d.
Formatting is normally needed only once during the lifetime of a medium, if ever. But it is a Formatting is normally needed only once during the lifetime of a m edium, if ever. But it is a
reason for re-formatting if: reason for re-formatting if:
DVD-RW was deformatted by -blank, DVD-RW was deformatted by -blank,
DVD+RW has read failures (re-format before next write), DVD+RW has read failures (re-format before next write),
DVD-RAM or BD-RE shall change their amount of defect reserve. DVD-RAM or BD-RE shall change their amount of defect reserve.
BD-R may be written unformatted or may be formatted before first u BD-R may be written unformatted or may be formatted before first
se. Formatting activates Defect use. Formatting activates Defect
Management which tries to catch and repair bad spots on medi Management which tries to catch and repair bad spots on media dur
a during the write process at the ing the write process at the
expense of half speed even with flawless media. expense of half speed even with flawless media.
The progress reports issued by some drives while formatting are qu The progress reports issued by some drives while formatting are q
ite unrealistic. Do not conclude uite unrealistic. Do not conclude
success or failure from the reported percentages. Formatting wa success or failure from the reported percentages. Formatting was s
s successful if no SORRY event or uccessful if no SORRY event or
worse occurred. Be patient with apparently frozen progress. worse occurred. Be patient with apparently frozen progress.
-list_formats -list_formats
Put out a list of format descriptors as reported by the output dri Put out a list of format descriptors as reported by the output
ve for the current medium. The drive for the current medium. The
list gives the index number after "Format idx", a MMC format c list gives the index number after "Format idx", a MMC format code,
ode, the announced size in blocks the announced size in blocks
(like "2236704s") and the same size in MiB. (like "2236704s") and the same size in MiB.
MMC format codes are manifold. Most important are: "00h" gener MMC format codes are manifold. Most important are: "00h" ge
al formatting, "01h" increases neral formatting, "01h" increases
reserve space for DVD-RAM, "26h" for DVD+RW, "30h" for BD-RE wi reserve space for DVD-RAM, "26h" for DVD+RW, "30h" for BD-RE with
th reserve space, "31h" for BD-RE reserve space, "31h" for BD-RE
without reserve space, "32h" for BD-R. without reserve space, "32h" for BD-R.
Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserv e space. Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserv e space.
-list_speeds -list_speeds
Put out a list of speed values as reported by the drives with the loaded media. The list tells read Put out a list of speed values as reported by the drives with the loaded media. The list tells read
speeds of the input drive and of the output drive. Further it tells write speeds of the output speeds of the input drive and of the output drive. Further it tell s write speeds of the output
drive. drive.
The list of write speeds does not necessarily mean that the medium is writable or that these speeds The list of write speeds does not necessarily mean that the medium is writable or that these speeds
are actually achievable. Especially the lists reported with empty drive or with ROM media obviously are actually achievable. Especially the lists reported with empty drive or with ROM media obviously
advertise speeds for other media. advertise speeds for other media.
It is not mandatory to use speed values out of the listed range. The drive is supposed to choose a It is not mandatory to use speed values out of the listed range. The drive is supposed to choose a
safe speed that is as near to the desired speed as possible. safe speed that is as near to the desired speed as possible.
At the end of the list, "Write speed L" and "Write speed H" a At the end of the list, "Write speed L" and "Write speed H" are th
re the best guesses for lower and e best guesses for lower and
upper write speed limit. "Write speed l" and "Write speed h" upper write speed limit. "Write speed l" and "Write spee
may appear only with CD and d h" may appear only with CD and
eventually override the list of other speed offers. eventually override the list of other speed offers.
Only if the drive reports contradicting speed information there w ill appear "Write speed 0", which Only if the drive reports contradicting speed information there wi ll appear "Write speed 0", which
tells the outcome of speed selection by command -speed 0, if it de viates from "Write speed H". tells the outcome of speed selection by command -speed 0, if it de viates from "Write speed H".
"Read speed L" and "Read speed H" tell the minimum and maximum rea "Read speed L" and "Read speed H" tell the minimum and maximu
d speeds, as reported by the m read speeds, as reported by the
drive. They would be chosen by -read_speed "min" or "max" if they drive. They would be chosen by -read_speed "min" or "max" if they
undercut or surpass the built-in undercut or surpass the built-in
limits. These are "1x", "52xCD", "24xDVD", "20xBD". limits. These are "1x", "52xCD", "24xDVD", "20xBD".
-list_profiles "in"|"out"|"all"
Put out a list of media types supported by -indev, -outdev, or b
oth, respectively. The currently
recognized type is marked by text "(current)".
-truncate_overwritable entity id adjust
On overwritable medium copy the volume descriptors of an ex
isting session to the overall
descriptors at LBA 0 ff. This makes all sessions inaccessible whi
ch are younger than the activated
one. A reason to do this would be read errors in the younger sess
ions and the wish to re-write or
skip them.
This operation is only allowed if no changes to the loaded filesy
stem are pending. If an -indev is
acquired then it is released before the write operation begins and
re-acquired only in case of
success.
The parameters "entity" and "id" have the same meaning as wit
h command -load. They choose the
existing ISO session which shall become the youngest accessible se
ssion. Available entity names are
"session", "track", "lba", "sbsector", "volid". "auto" makes fe
w sense. id is a number or search
text as appropriate for the given entity.
Parameter "adjust" controls the claimed size of the activated sess
ion. Text "new" means the size of
the newly activated session as it was before this command. I.e. t
he space of the then inaccessible
younger sessions will be re-used when appending more sessions.
"old" means the size up to the end of the previously youngest sess
ion. I.e. "old" will not free
the space of the then inaccessible younger sessions for re-use.
A number preceded by "+" gives the number of bytes to be adde
d to "new". A number without "+"
gives the overall number of bytes. In any case the result may not
be smaller than "new". Numbers
may have a unit suffix: "d"=512, "k"=1024, "s"=2048, "m"=1024k, "g
"=1024m.
Examples:
Activate session 4 and enable overwriting of the blocks of younger
sessions:
-truncate_overwritable session 4 new
Activate session 4 and claim the blocks of younger sessions as use
less part of session 4:
-truncate_overwritable session 4 old
Let session 4 claim additional 500 MiB as useless data:
-truncate_overwritable session 4 +500m
-close_damaged "as_needed"|"force" -close_damaged "as_needed"|"force"
Try to close the upcoming track and session if the drive reported Try to close the upcoming track and session if the drive reporte
the medium as damaged. This may d the medium as damaged. This may
apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL, or BD-R medi
media. It is indicated by warning a. It is indicated by warning
messages when the drive gets acquired, and by a remark "but next t messages when the drive gets acquired, and by a remark "but nex
rack is damaged" with the line t track is damaged" with the line
"Media status :" of command -toc. "Media status :" of command -toc.
The setting of command -close determines whether the medium stays appendable. The setting of command -close determines whether the medium stays appendable.
Mode "as_needed" gracefully refuses on media which are not reported as damaged. Mode "force" Mode "as_needed" gracefully refuses on media which are not repo rted as damaged. Mode "force"
attempts the close operation even with media which appear undamage d. attempts the close operation even with media which appear undamage d.
No image changes are allowed to be pending before this command is performed. After closing was No image changes are allowed to be pending before this command is performed. After closing was
attempted, both drives are given up. attempted, both drives are given up.
-list_profiles "in"|"out"|"all"
Put out a list of media types supported by -indev, -outdev, or b
oth, respectively. The currently
recognized type is marked by text "(current)".
Settings for result writing: Settings for result writing:
Rock Ridge info will be generated by default. ACLs will be written accor ding to the setting of command Rock Ridge info will be generated by default. ACLs will be written accor ding to the setting of command
-acl. -acl.
-joliet "on"|"off" -joliet "on"|"off"
If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge tree. If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge tree.
-hfsplus "on"|"off" -hfsplus "on"|"off"
If enabled by "on", generate a HFS+ filesystem inside the IS O 9660 image and mark it by Apple If enabled by "on", generate a HFS+ filesystem inside the IS O 9660 image and mark it by Apple
skipping to change at line 1695 skipping to change at line 1747
loaded from the input image and checked for information about HF S creator, filetype, or blessing. loaded from the input image and checked for information about HF S creator, filetype, or blessing.
If found, then they get enabled as settings for the next image production. Therefore it is If found, then they get enabled as settings for the next image production. Therefore it is
advisable to perform -hfsplus "on" before -indev or -dev. advisable to perform -hfsplus "on" before -indev or -dev.
Information about HFS creator, type, and blessings gets stored by xorriso if -hfsplus is enabled at Information about HFS creator, type, and blessings gets stored by xorriso if -hfsplus is enabled at
-commit time. It is stored as copy outside the HFS+ partition, but rather along with the Rock Ridge -commit time. It is stored as copy outside the HFS+ partition, but rather along with the Rock Ridge
information. xorriso does not read any information from the HFS+ meta data. information. xorriso does not read any information from the HFS+ meta data.
Be aware that HFS+ is case-insensitive although it can reco rd file names with upper-case and Be aware that HFS+ is case-insensitive although it can reco rd file names with upper-case and
lower-case letters. Therefore, file names from the iso_rr name tre e may collide in the HFS+ name lower-case letters. Therefore, file names from the iso_rr name tre e may collide in the HFS+ name
tree. In this case they get changed by adding underscore charact ers and counting numbers. In case tree. In this case they get changed by adding underscore charact ers and counting numbers. In case
of very long names, it might be necessary to map them to "MANGLED_ ...". of very long names, it might be necessary to map them to "MANGLED_ ...".
WARNING:
The HFS+ implementation in libisofs has a limit of 125,829,120 byt
es for the size of the overall
directory tree. This suffices for about 300,000 files of norm
al name length. If the limit gets
exceeded, a FAILURE event will be issued and the ISO production wi
ll not happen.
-rockridge "on"|"off" -rockridge "on"|"off"
Mode "off" disables production of Rock Ridge information for th e ISO 9660 file objects. The Mode "off" disables production of Rock Ridge information for th e ISO 9660 file objects. The
multi-session capabilities of xorriso depend much on the naming fidelity of Rock Ridge. So it is multi-session capabilities of xorriso depend much on the naming fidelity of Rock Ridge. So it is
strongly discouraged to deviate from default setting "on". strongly discouraged to deviate from default setting "on".
-compliance rule[:rule...] -compliance rule[:rule...]
Adjust the compliance to specifications of ISO 9660/ECMA-119 and i ts contemporary extensions. In Adjust the compliance to specifications of ISO 9660/ECMA-119 and i ts contemporary extensions. In
some cases it is worth to deviate a bit in order to circumvent b ugs of the intended reader system some cases it is worth to deviate a bit in order to circumvent b ugs of the intended reader system
or to get unofficial extra features. or to get unofficial extra features.
skipping to change at line 1752 skipping to change at line 1808
"rec_mtime" records with non-RockRidge directory entries the disk file's mtime and not the creation "rec_mtime" records with non-RockRidge directory entries the disk file's mtime and not the creation
time of the image. This applies to the ECMA-119 tree (plain ISO 9660), to Joliet, and to ISO time of the image. This applies to the ECMA-119 tree (plain ISO 9660), to Joliet, and to ISO
9660:1999. "rec_time" is default. If disabled, it gets automa tically re-enabled by -as mkisofs 9660:1999. "rec_time" is default. If disabled, it gets automa tically re-enabled by -as mkisofs
emulation when a pathspec is encountered. emulation when a pathspec is encountered.
"new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux but not for older FreeBSD or for "new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux but not for older FreeBSD or for
Solaris). This implies "aaip_susp_1_10_off" which may be changed b y subsequent "aaip_susp_1_10". Solaris). This implies "aaip_susp_1_10_off" which may be changed b y subsequent "aaip_susp_1_10".
Default is "old_rr" which uses Rock Ridge version 1.10. This im plies also "aaip_susp_1_10" which Default is "old_rr" which uses Rock Ridge version 1.10. This im plies also "aaip_susp_1_10" which
may be changed by subsequent "aaip_susp_1_10_off". may be changed by subsequent "aaip_susp_1_10_off".
"aaip_susp_1_10" allows AAIP to be written as unofficial extension of RRIP rather than as official "aaip_susp_1_10" allows AAIP to be written as unofficial extension of RRIP rather than as official
extension under SUSP-1.12. extension under SUSP-1.12.
"no_emul_toc" saves 64 kB with the first session on overwr iteable media but makes the image "no_emul_toc" saves 64 kB with the first session on overw ritable media but makes the image
incapable of displaying its session history. incapable of displaying its session history.
"iso_9660_1999" causes the production of an additional directory t ree compliant to ISO 9660:1999. "iso_9660_1999" causes the production of an additional directory t ree compliant to ISO 9660:1999.
It can record long filenames for readers which do not understand R ock Ridge. It can record long filenames for readers which do not understand R ock Ridge.
"old_empty" uses the old way of of giving block addresses in the range of [0,31] to files with no "old_empty" uses the old way of of giving block addresses in the range of [0,31] to files with no
own data content. The new way is to have a dedicated block to whic h all such files will point. own data content. The new way is to have a dedicated block to whic h all such files will point.
Default setting is Default setting is
"clear:only_iso_version:deep_paths:long_paths:no_j_force_dots: "clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
always_gmt:old_rr". always_gmt:old_rr".
Note: The term "ECMA-119 name" means the plain ISO 9660 names and attributes which get visible if Note: The term "ECMA-119 name" means the plain ISO 9660 names and attributes which get visible if
the reader ignores Rock Ridge. the reader ignores Rock Ridge.
skipping to change at line 1857 skipping to change at line 1913
-abstract_file text -abstract_file text
Set the abstract file name to be written with the next -commit. Th is should be the ISO 9660 path of Set the abstract file name to be written with the next -commit. Th is should be the ISO 9660 path of
a file in the image which contains an abstract statement about th e image content. Permissible are a file in the image which contains an abstract statement about th e image content. Permissible are
up to 37 characters. This setting gets overridden by image loading . up to 37 characters. This setting gets overridden by image loading .
-biblio_file text -biblio_file text
Set the biblio file name to be written with the next -commit. This should be the ISO 9660 path of a Set the biblio file name to be written with the next -commit. This should be the ISO 9660 path of a
file in the image which contains bibliographic records. Permissi ble are up to 37 characters. This file in the image which contains bibliographic records. Permissi ble are up to 37 characters. This
setting gets overridden by image loading. setting gets overridden by image loading.
-preparer_id -preparer_id text
Set the preparer ID string to be written with the next -commit. Th is may identify the person or Set the preparer ID string to be written with the next -commit. Th is may identify the person or
other entity which controls the preparation of the data which shall be recorded. Normally this other entity which controls the preparation of the data which shall be recorded. Normally this
should be the ID of xorriso and not of the person or program which operates xorriso. Please avoid should be the ID of xorriso and not of the person or program which operates xorriso. Please avoid
to change it. Permissible are up to 128 characters. to change it. Permissible are up to 128 characters.
The special text "@xorriso@" gets converted to the ID string of xo rriso which is default at program The special text "@xorriso@" gets converted to the ID string of xo rriso which is default at program
startup. startup.
Unlike other ID strings, this setting is not influenced by image l oading. Unlike other ID strings, this setting is not influenced by image l oading.
-application_use character|0xXY|disk_path -application_use character|0xXY|disk_path
Specify the content of the Application Use field which can take at most 512 bytes. Specify the content of the Application Use field which can take at most 512 bytes.
skipping to change at line 1887 skipping to change at line 1943
Set the character set to which file names get converted when wr iting an image. See paragraph Set the character set to which file names get converted when wr iting an image. See paragraph
"Character sets" for more explanations. When loading the writte n image after -commit the setting "Character sets" for more explanations. When loading the writte n image after -commit the setting
of -out_charset will be copied to -in_charset. of -out_charset will be copied to -in_charset.
-uid uid -uid uid
User id to be used for all files when the new ISO tree gets writte n to media. User id to be used for all files when the new ISO tree gets writte n to media.
-gid gid -gid gid
Group id to be used for all files when the new ISO tree gets writt en to media. Group id to be used for all files when the new ISO tree gets writt en to media.
-zisofs option[:options] -zisofs parameter[:parameters]
Set global parameters for zisofs compression. This data format i s recognized and transparently Set global parameters for zisofs compression. This data format i s recognized and transparently
uncompressed by some Linux kernels. It is to be applied via command -set_filter with built-in uncompressed by some Linux kernels. It is to be applied via command -set_filter with built-in
filter "--zisofs". Parameters are: filter "--zisofs".
Note: This command is only permitted while no --zisofs filters are
applied to any files.
Parameters are:
"level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
"block_size="32k|64k|128k size of compression blocks "block_size="32k|64k|128k sets the size of version 1 compression blocks.
"by_magic=on" enables an expensive test at image generation time which checks files from disk "by_magic=on" enables an expensive test at image generation time which checks files from disk
whether they already are zisofs compressed, e.g. by program mkzftr whether they already are zisofs compressed, e.g. by progra
ee. m mkzftree. "by_magic=v2" enables
"default" same as "level=6:block_size=32k:by_magic=off" processing of already zisofs2 compressed files additionally t
o those of zisofs version 1.
"by_magic=off" disables both.
"version_2="off|as_needed|on controls compression by experimental
version zisofs2 which can encode
files of size 4 GiB or larger. The Linux kernel (as of 5.9) does n
ot yet know this format and will
complain like
isofs: Unknown ZF compression algorithm: PZ
The files will then appear in their compressed form with zisofs
2 header, block pointer list, and
compressed data.
zisofs2 is recognized by xorriso in files from loaded images and g
ets equipped with --zisofs-decode
filters, unless restrictions on the number of block pointers preve
nt this.
Mode "off" restricts compression to files smaller than 4 GiB unc
ompressed size. Mode "as_needed"
uses zisofs2 for larger files. Mode "on" uses zisofs2 for all ziso
fs compressed files.
"susp_z2="off|on controls production of SUSP entries "Z2" instead
of "ZF" with zisofs2 compressed
files. Unaware Linux kernels are supposed to silently ignore "Z2"
entries.
"block_size_v2="32k|64k|128k|256k|512k|1m sets the size of compre
ssion blocks for zisofs2.
"bpt_target="-1|>0 sets a number of block pointers per file,
which is considered low enough to
justify a reduction of block size. If this number is larger than 0
, then block sizes smaller than
the settings of block_size= or block_size_v2= are tried whether t
hey yield not more block pointers
than the given number. If so, the smallest suitable block size is
applied.
The inavoidable final block pointer counts. E.g. a file of 55 KiB
has 3 block pointers if block
size is 32k, and 2 block pointers with block size 64k.
bpt_target=-1 disables this automatic block size adjustment.
"max_bpt="1k...128g sets the limit for the overall allocated blo
ck pointer memory. Block pointers
occupy virtual memory while a file gets uncompressed and while a f
ile, which shall be compressed,
waits for ISO filesystem creation.
One pointer occupies 8 bytes of memory and governs block_size or
block_size_v2 uncompressed bytes.
I.e. with block size 128k, 1m of block pointer memory suffices for
at most 16g of uncompressed file
size. Each file consumes one end block pointer, independently o
f the file size. Partially filled
end blocks may further reduce the effective payload.
In case of overflow of the max_bpt limit while adding compression
filters the program tries to go
on by discarding all buffered block pointers of previously added -
-zisofs filters. From then on all
newly added filters will discard their block pointers immediately
after being added. Discarded
block pointers cause an additional read and compression run of the
input file during the production
of the ISO filesystem.
"max_bpt_f="1k...128g sets the limit for the memory size of the b
lock pointer list of a single
file. max_bpt_f is never larger than max_bpt. If either is se
t to violate this rule, the other
gets set to the same value. If both values are the same before a
change by max_bpt= or max_bpt_f=,
then both limits stick together unless the limit is decreased by m
ax_bpt_f=.
"bpt_free_ratio="-1|0.0...1.0 sets a threshold for switching t
o block pointer discarding during
compression. If less than the given fraction of the max_bpt_f= mem
ory is free, then block pointers
of compression filters get discarded immediately after being added
. Value -1 disables this feature.
"default" is the same as "lev
el=6:block_size=32k:by_magic=off:
version_2=off:block_size_v2=128k:susp_z2=off:max_bpt=256m:max_bpt_
f=256m: bpt_free_ratio=-1".
-speed code|number[k|m|c|d|b] -speed code|number[k|m|c|d|b]
Set the burn speed. Default is "max" (or "0") = maximum speed as announced by the drive. Further Set the burn speed. Default is "max" (or "0") = maximum speed as a nnounced by the drive. Further
special speed codes are: special speed codes are:
"min" (or "-1") selects minimum speed as announced by the drive. "min" (or "-1") selects minimum speed as announced by the drive.
"none" avoids to send a speed setting command to the drive before burning begins. "none" avoids to send a speed setting command to the drive before burning begins.
Speed can be given in media dependent numbers or as a desired Speed can be given in media dependent numbers or as a des
throughput per second in MMC ired throughput per second in MMC
compliant kB (= 1000) or MB (= 1000 kB). Media x-speed factor can compliant kB (= 1000) or MB (= 1000 kB). Media x-speed factor can
be set explicitly by "c" for CD, be set explicitly by "c" for CD,
"d" for DVD, "b" for BD, "x" is optional. "d" for DVD, "b" for BD, "x" is optional.
Example speeds: Example speeds:
706k = 706kB/s = 4c = 4xCD 706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD 5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then the medium in the -outdev will decide. If there is no hint about the speed unit attached, then the m edium in the -outdev will decide.
Default unit is CD = 176.4k. Default unit is CD = 176.4k.
MMC drives usually activate their own idea of speed and take the speed value given by the burn MMC drives usually activate their own idea of speed and take the s peed value given by the burn
program only as upper limit for their own decision. program only as upper limit for their own decision.
-stream_recording "on"|"off"|"full"|"data"|number -stream_recording "on"|"off"|"full"|"data"|number
Setting "on" tries to circumvent the management of defects on DV D-RAM, BD-RE, or BD-R. Defect Setting "on" tries to circumvent the management of defects o n DVD-RAM, BD-RE, or BD-R. Defect
management keeps partly damaged media usable. But it reduces write speed to half nominal speed even management keeps partly damaged media usable. But it reduces write speed to half nominal speed even
if the medium is in perfect shape. For the case of flawless media , one may use -stream_recording if the medium is in perfect shape. For the case of flawless med ia, one may use -stream_recording
"on" to get full speed. "on" to get full speed.
"full" tries full speed with all write operations, whereas "on" does this only above byte address "full" tries full speed with all write operations, whereas "on" do es this only above byte address
32s. One may give a number of at least 16s in order to set an own address limit. 32s. One may give a number of at least 16s in order to set an own address limit.
"data" causes full speed to start when superblock and directory en tries are written and writing of "data" causes full speed to start when superblock and directory e ntries are written and writing of
file content blocks begins. file content blocks begins.
-dvd_obs "default"|"32k"|"64k" -dvd_obs "default"|"32k"|"64k"
GNU/Linux specific: Set the number of bytes to be transmitted wi GNU/Linux specific: Set the number of bytes to be transmitted with
th each write operation to DVD or each write operation to DVD or
BD media. A number of 64 KB may improve throughput with bus system BD media. A number of 64 KB may improve throughput with bus sys
s which show latency problems. tems which show latency problems.
The default depends on media type, on command -stream_recording , and on compile time options. The default depends on media type, on command -stream_recording , and on compile time options.
-modesty_on_drive parameter[:parameters] -modesty_on_drive parameter[:parameters]
Control whether the drive buffer shall be kept from getting compl etely filled. Parameter "on" (or Control whether the drive buffer shall be kept from getting comple tely filled. Parameter "on" (or
"1") keeps the program from trying to write to the burner drive wh ile its buffer is in danger to be "1") keeps the program from trying to write to the burner drive wh ile its buffer is in danger to be
filled over a given limit. If this limit is exceeded then the pr ogram will wait until the filling filled over a given limit. If this limit is exceeded then the pro gram will wait until the filling
reaches a given low percentage value. reaches a given low percentage value.
This can ease the load on operating system and drive controller an d thus help with achieving better This can ease the load on operating system and drive controller an d thus help with achieving better
input bandwidth if disk and burner are not on independent contr input bandwidth if disk and burner are not on independent controll
ollers (like hda and hdb). It may ers (like hda and hdb). It may
also help with throughput problems of simultaneous burns on differ also help with throughput problems of simultaneous burns on dif
ent burners with Linux kernels ferent burners with Linux kernels
like 3.16, if one has reason not to fix the problem by -scsi_dev_f amily "sg". On the other hand it like 3.16, if one has reason not to fix the problem by -scsi_dev_f amily "sg". On the other hand it
increases the risk of buffer underflow and thus reduced write spee d. increases the risk of buffer underflow and thus reduced write spee d.
Some burners are not suitable because they report buffer fill with granularity too coarse in size Some burners are not suitable because they report buffer fill wi th granularity too coarse in size
or time, or expect their buffer to be filled to the top before the y go to full speed. or time, or expect their buffer to be filled to the top before the y go to full speed.
Parameters "off" or "0" disable this feature. Parameters "off" or "0" disable this feature.
The threshold for beginning to wait is given by parameter "max_per cent=". Parameter "min_percent=" The threshold for beginning to wait is given by parameter "max_per cent=". Parameter "min_percent="
defines the threshold for resuming transmission. Percentages are permissible in the range of 25 to defines the threshold for resuming transmission. Percentages are permissible in the range of 25 to
100. Numbers in this range without a prepended name are interprete d as "on:min_percent=". 100. Numbers in this range without a prepended name are interprete d as "on:min_percent=".
E.g.: -modesty_on_drive 75 E.g.: -modesty_on_drive 75
The optimal values depend on the buffer behavior of the drive. The optimal values depend on the buffer behavior of the drive.
Parameter "timeout_sec=" defines after which time of unsucces sful waiting the modesty shall be Parameter "timeout_sec=" defines after which time of unsuccessful waiting the modesty shall be
disabled because it does not work. disabled because it does not work.
Parameter "min_usec=" defines the initial sleeping period in micro Parameter "min_usec=" defines the initial sleeping period in m
seconds. If the drive buffer icroseconds. If the drive buffer
appears to be too full for sending more data, the program will wa appears to be too full for sending more data, the program will wai
it the given time and inquire the t the given time and inquire the
buffer fill state again. If repeated inquiry shows not enough fre buffer fill state again. If repeated inquiry shows not enoug
e space, the sleep time will h free space, the sleep time will
slowly be increased to what parameter "max_usec=" defines. slowly be increased to what parameter "max_usec=" defines.
Parameters, which are not mentioned with a -modesty_on_drive comma nd, stay unchanged. Default is: Parameters, which are not mentioned with a -modesty_on_drive comma nd, stay unchanged. Default is:
-modesty_on_drive off:min_percent=90:max_percent=95: -modesty_on_drive off:min_percent=90:max_percent=95:
timeout_sec=120:min_usec=5000:max_usec=25000 timeout_sec=120:min_usec=5000:max_usec=25000
-use_immed_bit "on"|"off"|"default" -use_immed_bit "on"|"off"|"default"
Control whether several long lasting SCSI commands shall be e Control whether several long lasting SCSI commands shall be execut
xecuted with the Immed bit, which ed with the Immed bit, which
makes the commands end early while the drive operation is still go makes the commands end early while the drive operation is stil
ing on. xorriso then inquires l going on. xorriso then inquires
progress indication until the drive reports to be ready again. If progress indication until the drive reports to be ready again. If
this feature is turned off, then this feature is turned off, then
blanking and formatting will show no progress indication. blanking and formatting will show no progress indication.
It may depend on the operating system whether -use_immed_bit is se It may depend on the operating system whether -use_immed_bit is
t to "off" by default. Command set to "off" by default. Command
-status will tell by appending "/on" or "/off" if a driv -status will tell by appending "/on" or "/off" if a drive
e has already been acquired and has already been acquired and
-use_immed_bit is currently set to "default". Command -use_immed_ -use_immed_bit is currently set to "default". Command -use_imm
bit tolerates and ignores such ed_bit tolerates and ignores such
appended text. appended text.
-stdio_sync "on"|"off"|"end"|number -stdio_sync "on"|"off"|"end"|number
Set the number of bytes after which to force output to stdio: p Set the number of bytes after which to force output to stdio: pseu
seudo drives. This forcing keeps do drives. This forcing keeps
the memory from being clogged with lots of pending data for slow d the memory from being clogged with lots of pending data for slow
evices. Default "on" is the same devices. Default "on" is the same
as "16m". Forced output can be disabled by "off", or be de as "16m". Forced output can be disabled by "off", or be delayed
layed by "end" until all data are by "end" until all data are
produced. If a number is chosen, then it must be at least 64k. produced. If a number is chosen, then it must be at least 64k.
-dummy "on"|"off" -dummy "on"|"off"
If "on" then simulate burning or refuse with FAILURE event if no s imulation is possible, do neither If "on" then simulate burning or refuse with FAILURE event if no s imulation is possible, do neither
blank nor format. blank nor format.
-fs number["k"|"m"] -fs number["k"|"m"]
Set the size of the fifo buffer which smoothens the data stream f rom ISO image generation to media Set the size of the fifo buffer which smoothens the data stream fr om ISO image generation to media
burning. Default is 4 MiB, minimum 64 kiB, maximum 1 GiB. The num ber may be followed by letter "k" burning. Default is 4 MiB, minimum 64 kiB, maximum 1 GiB. The num ber may be followed by letter "k"
or "m" which means unit is kiB (= 1024) or MiB (= 1024 kiB). or "m" which means unit is kiB (= 1024) or MiB (= 1024 kiB).
-close "on"|"off"|"as_needed" -close "on"|"off"|"as_needed"
If -close is set to "on" then mark the written medium as not appen dable any more. This will have no If -close is set to "on" then mark the written medium as not appen dable any more. This will have no
effect on overwritable media types. Setting "on" is the contrary of cdrecord option -multi, and is effect on overwritable media types. Setting "on" is the contrary of cdrecord option -multi, and is
one aspect of growisofs option -dvd-compat. one aspect of growisofs option -dvd-compat.
If set to "off" then keep the medium writable for an appended sess ion. If set to "off" then keep the medium writable for an appended sess ion.
If set to "as_needed" then use "on" only if "off" is predicted to fail with the given medium and If set to "as_needed" then use "on" only if "off" is predicted to fail with the given medium and
its state. its state.
Not all drives correctly recognize fast-blanked DVD-RW which need Not all drives correctly recognize fast-blanked DVD-RW which nee
"on". If there is well founded d "on". If there is well founded
suspicion that a burn run failed due to -close "off", then -close suspicion that a burn run failed due to -close "off", then -close
"as_needed" causes a re-try with "as_needed" causes a re-try with
"on". "on".
Note that emulation command -as "cdrecord" temporarily overrides t he current setting of -close by 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. its own default -close "on" if its option -multi is missing.
-write_type "auto"|"tao"|"sao/dao" -write_type "auto"|"tao"|"sao/dao"
Set the write type for the next burn run. "auto" will select Set the write type for the next burn run. "auto" will select SAO w
SAO with blank CD media, DAO with ith blank CD media, DAO with
blank DVD-R[W] if -close is "on", and elsewise CD TAO or the blank DVD-R[W] if -close is "on", and elsewise CD TAO or
equivalent write type of the the equivalent write type of the
particular DVD/BD media. Choosing TAO or SAO/DAO explicitly mi particular DVD/BD media. Choosing TAO or SAO/DAO explicitly might
ght cause the burn run to fail if cause the burn run to fail if
the desired write type is not possible with the given media state. the desired write type is not possible with the given media state.
-padding number["k"|"m"]|"included"|"appended" -padding number["k"|"m"]|"included"|"appended"
Append the given number of extra bytes to the image stream. This is a traditional remedy for a Append the given number of extra bytes to the image stream. T his is a traditional remedy for a
traditional bug in block device read drivers. Needed only for CD r ecordings in TAO mode. Since one traditional bug in block device read drivers. Needed only for CD r ecordings in TAO mode. Since one
can hardly predict on what media an image might end up, xorriso adds the traditional 300k of can hardly predict on what media an image might end up, xor riso adds the traditional 300k of
padding by default to all images. padding by default to all images.
For images which will never get to a CD it is safe to use -padding 0 . 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 appe nded after the image end. This is Normally padding is not written as part of the ISO image but appen ded after the image end. This is
-padding mode "appended". -padding mode "appended".
Emulation command -as "mkisofs" and command -jigdo cause padding t o be written as part of the Emulation command -as "mkisofs" and command -jigdo cause pad ding to be written as part of the
image. The same effect is achieved by -padding mode "included". image. The same effect is achieved by -padding mode "included".
Bootable ISO images: Bootable ISO images:
Contrary to published specifications many BIOSes will load an El Torito Contrary to published specifications many BIOSes will load an El Torito r
record from the first session on ecord from the first session on
media and not from the last one, which gets mounted by default. This make media and not from the last one, which gets mounted by default. This ma
s no problems with overwriteable kes no problems with overwritable
media, because they appear to inadverted readers as one single session. 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 But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that th e whole bootable system has to
reside already in the first session and that the last session still has t o bear all files which the booted reside already in the first session and that the last session still has t o bear all files which the booted
system expects after mounting the ISO image. system expects after mounting the ISO image.
If a boot image from ISOLINUX or GRUB is known to be present on media th If a boot image from ISOLINUX or GRUB is known to be present on media the
en it is advised to patch it when n it is advised to patch it when
a follow-up session gets written. But one should not rely on the capabili a follow-up session gets written. But one should not rely on the capabi
ty to influence the bootability lity to influence the bootability
of the existing sessions, unless one can assume overwriteable media. of the existing sessions, unless one can assume overwritable media.
Normally the boot images are data files inside the ISO Normally the boot images are data files inside the ISO
filesystem. By special path filesystem. By special path
"--interval:appended_partition_NNN:all::" it is possible to refer to an a ppended partition. The number NNN "--interval:appended_partition_NNN:all::" it is possible to refer to an a ppended partition. The number NNN
gives the partition number as used with the corresponding command -append _partition. E.g.: gives the partition number as used with the corresponding command -append _partition. E.g.:
-append_partition 2 0xef /tmp/efi.img -append_partition 2 0xef /tmp/efi.img
-boot_image any efi_path=--interval:appended_partition_2:all:: -boot_image any efi_path=--interval:appended_partition_2:all::
There are booting mechanisms which do not use an El Torito record but r There are booting mechanisms which do not use an El Torito record but rat
ather start at the first bytes of her start at the first bytes of
the image: PC-BIOS MBR or EFI GPT for hard-disk-like devices, APM partiti the image: PC-BIOS MBR or EFI GPT for hard-disk-like devices, APM partit
on entries for Macs which expect ion entries for Macs which expect
HFS+ boot images, MIPS Volume Header for old SGI computers, DEC Boot B HFS+ boot images, MIPS Volume Header for old SGI computers, DEC Boot Bloc
lock for old MIPS DECstation, SUN k for old MIPS DECstation, SUN
Disk Label for SPARC machines, HP-PA boot sector for HP PA-RISC machines, Disk Label for SPARC machines, HP-PA boot sector for HP PA-RISC machin
DEC Alpha SRM boot sector for es, DEC Alpha SRM boot sector for
old DEC Alpha machines. old DEC Alpha machines.
Several of the following commands expect disk paths as input but also a Several of the following commands expect disk paths as input but also acc
ccept description strings for the ept description strings for the
libisofs interval reader, which is able to cut out data from disk files o libisofs interval reader, which is able to cut out data from disk files
r -indev and to zeroize parts of or -indev and to zeroize parts of
the content: command -append_partition, boot specs system_area the content: command -append_partition, boot specs system_area=,
=, grub2_mbr=, prep_boot_part=, grub2_mbr=, prep_boot_part=,
efi_boot_part=. efi_boot_part=.
The description string consists of the following components, separated by colon ':' The description string consists of the following components, separated by colon ':'
"--interval:"Flags":"Interval":"Zeroizers":"Source "--interval:"Flags":"Interval":"Zeroizers":"Source
The component "--interval" states that this is not a plain disk path but rather an interval reader The component "--interval" states that this is not a plain disk p ath but rather an interval reader
description string. The component Flags modifies the further interpretat ion: description string. The component Flags modifies the further interpretat ion:
"local_fs" demands to read from a file depicted by the path in Source. "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 -outd ev is not the same as -indev. The "imported_iso" demands to read from the -indev. This works only if -outde v is not the same as -indev. The
Source component is ignored. Source component is ignored.
"appended_partition_NNN" with a decimal number NNN works only for -boot_i "appended_partition_NNN" with a decimal number NNN works only for -boot_
mage bootspecs which announce El image bootspecs which announce El
Torito boot image paths: bin_path=, efi_path=. The number gives the Torito boot image paths: bin_path=, efi_path=. The number gives the part
partition number as used with the ition number as used with the
corresponding command -append_partition. corresponding command -append_partition.
The component Interval consists of two byte address numbers separated by a "-" character. E.g. "0-429" The component Interval consists of two byte address numbers separated by a "-" character. E.g. "0-429"
means to read bytes 0 to 429. means to read bytes 0 to 429.
The component Zeroizers consists of zero or more comma separated string The component Zeroizers consists of zero or more comma separated strings.
s. They define which part of the They define which part of the
read data to zeroize. Byte number 0 means the byte read from the Interval read data to zeroize. Byte number 0 means the byte read from the Interva
start address. Each string may l start address. Each string may
be one of: be one of:
"zero_mbrpt" demands to zeroize the MBR partition table if bytes 510 an d 511 bear the MBR signature 0x55 "zero_mbrpt" demands to zeroize the MBR partition table if bytes 510 and 511 bear the MBR signature 0x55
0xaa. 0xaa.
"zero_gpt" demands to check for a GPT header in bytes 512 to 1023, to zer oize it and its partition table "zero_gpt" demands to check for a GPT header in bytes 512 to 1023, to z eroize it and its partition table
blocks. blocks.
"zero_apm" demands to check for an APM block 0 and to zeroize its partiti on table blocks. "zero_apm" demands to check for an APM block 0 and to zeroize its partiti on table blocks.
Start_byte"-"End_byte demands to zeroize the read-in bytes beginning with number Start_byte and ending Start_byte"-"End_byte demands to zeroize the read-in bytes beginning with number Start_byte and ending
after End_byte. after End_byte.
The component Source is the file path with flag "local_fs", and ignored w ith flag "imported_iso". The component Source is the file path with flag "local_fs", and ignored w ith flag "imported_iso".
Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning multi plication by {1024, 1024k, 1024m, Byte numbers may be scaled by a suffix out of {k,m,g,t,s,d} meaning multi plication by {1024, 1024k, 1024m,
1024g, 2048, 512}. A scaled value end number depicts the last byte of the scaled range. 1024g, 2048, 512}. A scaled value end number depicts the last byte of the scaled range.
E.g. "0d-0d" is "0-511". E.g. "0d-0d" is "0-511".
Examples: Examples:
"local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso" "local_fs:0-32767:zero_mbrpt,zero_gpt,440-443:/tmp/template.iso"
"imported_iso:45056d-47103d::" "imported_iso:45056d-47103d::"
-boot_image "any"|"isolinux"|"grub" -boot_image "any"|"isolinux"|"grub"
"discard"|"keep"|"patch"|"replay"|"show_status"| "discard"|"keep"|"patch"|"replay"|"show_status"|
bootspec|"next" bootspec|"next"
Define the equipment of the emerging filesystem with boot entry po ints. Define the equipment of the emerging filesystem with boot entry po ints.
With systems which boot via BIOS or EFI this is a set of El Tori With systems which boot via BIOS or EFI this is a set of El Torito
to boot images, possibly MBR boot boot images, possibly MBR boot
code, and possibly partition tables of type MBR, GPT, or APM. Suc code, and possibly partition tables of type MBR, GPT, or APM. Su
h file sets get produced by boot ch file sets get produced by boot
loader systems like ISOLINUX or GRUB. loader systems like ISOLINUX or GRUB.
Each -boot_image command has two parameters: type and setting. More than one -boot_image command Each -boot_image command has two parameters: type and setting. Mor e than one -boot_image command
may be used to define the handling of one or more boot images. Seq uence matters. may be used to define the handling of one or more boot images. Seq uence matters.
Types isolinux and grub care for known peculiarities. Type any m akes no assumptions about the Types isolinux and grub care for known peculiarities. Type a ny makes no assumptions about the
origin of the boot images. origin of the boot images.
When loading an ISO filesystem, system area and El Torito boot im When loading an ISO filesystem, system area and El Torito boot ima
ages get loaded, too. The default ges get loaded, too. The default
behavior is not to write loaded El Torito boot images and to write behavior is not to write loaded El Torito boot images and to wri
the loaded system area content te the loaded system area content
without alterations. without alterations.
discard gives up the El Torito boot catalog and its boot images. regardless whether loaded from an 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 rela ted boot options get revoked. 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 Nevertheless, loaded system area data stay valid. If desired, they have to be erased by
-boot_image any system_area=/dev/zero -boot_image any system_area=/dev/zero
keep keeps or copies El Torito boot images unaltered and writes a new catalog. 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 s eem to bear a boot info table. patch applies patching to existing El Torito boot images if they s eem to bear a boot info table.
A boot info table needs to be patched when the boot image gets ne wly introduced into the ISO image A boot info table needs to be patched when the boot image gets new ly introduced into the ISO image
or if an existing image gets relocated. This is automatically don e if type "isolinux" or "grub" is or if an existing image gets relocated. This is automatically don e if type "isolinux" or "grub" is
given, but not with "any". given, but not with "any".
If patching is enabled, then boot images from previous sessions If patching is enabled, then boot images from previous sessions wi
will be checked whether they seem ll be checked whether they seem
to bear a boot info table. If not, then they stay unpatched. This to bear a boot info table. If not, then they stay unpatched. Th
check is not infallible. So if is check is not infallible. So if
you do know that the images need no patching, use "any" "keep". you do know that the images need no patching, use "any" "keep". "
"grub" "patch" will not patch EFI grub" "patch" will not patch EFI
images (platform_id=0xef). images (platform_id=0xef).
replay is a more modern version of "patch", which not only cares replay is a more modern version of "patch", which not only
for existing El Torito boot cares for existing El Torito boot
equipment but also for the recognizable boot provisions in equipment but also for the recognizable boot provisions in the
the System Area. It discards any System Area. It discards any
existing -boot_image setting and executes the commands proposed by command -report_el_torito "cmd". existing -boot_image setting and executes the commands proposed by command -report_el_torito "cmd".
This action will only succeed if the file objects mention ed in the output of command This action will only succeed if the file objects mentio ned in the output of command
-report_el_torito "cmd" are still available. Do not remove or rena me boot image files after -indev. -report_el_torito "cmd" are still available. Do not remove or rena me boot image files after -indev.
Drop unknown El Torito: -boot_image "any" "discard" Drop unknown El Torito: -boot_image "any" "discard"
Maintain recognizable stuff: -boot_image "any" "replay" Maintain recognizable stuff: -boot_image "any" "replay"
El Torito only for GRUB: -boot_image "grub" "patch" El Torito only for GRUB: -boot_image "grub" "patch"
El Torito only for ISOLINUX: -boot_image "isolinux" "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. 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 A bootspec is a word of the form name=value. It is used to descr
describe the parameters of a boot ibe the parameters of a boot
feature. The names "dir", "bin_path", "efi_path" lead to El feature. The names "dir", "bin_path", "efi_path" lead to
Torito bootable images. Name El Torito bootable images. Name
"system_area" activates a given file as MBR or other disk header. "system_area" activates a given file as MBR or other disk header.
On all media types this is possible within the first session. In On all media types this is possible within the first session. In f
further sessions an existing boot urther sessions an existing boot
image can get replaced by a new one, but depending on the media ty image can get replaced by a new one, but depending on the media
pe this may have few effect at type this may have few effect at
boot time. See above. boot time. See above.
El Torito boot images have to be added to the ISO image by normal means (image loading, -map, -add, 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 im ...). In case of ISOLINUX the files should reside either in IS
age directory /isolinux or in O image directory /isolinux or in
/boot/isolinux . In that case it suffices to use as boo /boot/isolinux . In that case it suffices to use as bootspe
tspec the text "dir=/isolinux" or c the text "dir=/isolinux" or
"dir=/boot/isolinux". E.g.: "dir=/boot/isolinux". E.g.:
-boot_image isolinux dir=/boot/isolinux -boot_image isolinux dir=/boot/isolinux
which bundles these individual settings: which bundles these individual settings:
-boot_image isolinux bin_path=/boot/isolinux/isolinux.bin -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
-boot_image isolinux cat_path=/boot/isolinux/boot.cat -boot_image isolinux cat_path=/boot/isolinux/boot.cat
-boot_image isolinux load_size=2048 -boot_image isolinux load_size=2048
-boot_image any boot_info_table=on -boot_image any boot_info_table=on
An El Torito boot catalog file gets inserted into the ISO image wi An El Torito boot catalog file gets inserted into the ISO imag
th address cat_path= with the e with address cat_path= with the
first -boot_image "any" "next" or at -commit time. It is first -boot_image "any" "next" or at -commit time. It is sub
subject to normal -overwrite and ject to normal -overwrite and
-reassure processing if there is already a file with the same name -reassure processing if there is already a file with the same
. The catalog lists the boot name. The catalog lists the boot
images and is read by the boot facility to choose one of the boo images and is read by the boot facility to choose one of the boot
t images. But it is not necessary images. But it is not necessary
that it appears in the directory tree at all. One may hide it in a ll trees by cat_hidden=on. Other that it appears in the directory tree at all. One may hide it in a ll trees by cat_hidden=on. Other
possible values are "iso_rr", "joliet", "hfsplus", and the defa possible values are "iso_rr", "joliet", "hfsplus", and the default
ult "off". The timestamps of the "off". The timestamps of the
boot catalog file are refreshed at commit time. Command -volume_d boot catalog file are refreshed at commit time. Command -volu
ate "uuid" can be used to set me_date "uuid" can be used to set
their value. their value.
bin_path= depicts an El Torito boot image file, a binary prog ram which is to be started by the bin_path= depicts an El Torito boot image file, a binary program w hich is to be started by the
hardware boot facility (e.g. the BIOS) at boot time. hardware boot facility (e.g. the BIOS) at boot time.
efi_path= depicts an El Torito boot image file that is ready for E efi_path= depicts an El Torito boot image file that is ready fo
FI booting. This is normally a r EFI booting. This is normally a
FAT filesystem image not larger than 65535 blocks of 512 bytes (= FAT filesystem image not larger than 65535 blocks of 512 bytes (=
32 MiB - 512). Its load_size is 32 MiB - 512). Its load_size is
determined automatically, no boot info table gets written, determined automatically, no boot info table gets written,
no boot medium gets emulated, no boot medium gets emulated,
platform_id is 0xef. platform_id is 0xef.
emul_type= can be one of "no_emulation", "hard_disk", "disket te". It controls the boot medium 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 sui table for ISOLINUX, GRUB, FreeBSD emulation code of a boot image. The default "no_emulation" is sui table for ISOLINUX, GRUB, FreeBSD
cdboot. cdboot.
load_size= is a value which depends on the boot image. load_size= is a value which depends on the boot image. Defau
Default is 2048 which matches the lt is 2048 which matches the
expectations of most boot images. The special value "full" means expectations of most boot images. The special value "full" mean
the full size of the boot image s the full size of the boot image
file rounded up to a multiple of 2048 bytes. Maximum is 33,552,384 bytes. 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 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. "any" "bin_path=". "boot_info_table=off" disables this patching.
grub2_boot_info=on causes address patching to byte 2548 of the boo t image which is given by "any" grub2_boot_info=on causes address patching to byte 2548 of the b oot image which is given by "any"
"bin_path=". The address is written as 64 bit little-endian numbe r. It is the 2KB block address of "bin_path=". The address is written as 64 bit little-endian numbe r. It is the 2KB block address of
the boot image content, multiplied by 4, and then incremented by 5 . "grub2_boot_info=off" disables the boot image content, multiplied by 4, and then incremented by 5 . "grub2_boot_info=off" disables
this patching. this patching.
platform_id= defines by a hexadecimal or decimal number the Plat form ID of the boot image. "0x00" platform_id= defines by a hexadecimal or decimal number the Platfo rm ID of the boot image. "0x00"
is 80x86 PC-BIOS, "0x01" is PowerPC, "0x02" is Mac, "0xef" is EFI (decimal "239"). 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 cata id_string=text|56_hexdigits defines the ID string of the boot cat
log section where the boot image alog section where the boot image
will be listed. If the value consists of 56 characters [0-9A-F will be listed. If the value consists of 56 characters [0-9A-Fa-f]
a-f] then it is converted into 28 then it is converted into 28
bytes, else the first 28 characters become the ID string. The ID bytes, else the first 28 characters become the ID string. The
string of the first boot image ID string of the first boot image
becomes the overall catalog ID. It is limited to 24 characters becomes the overall catalog ID. It is limited to 24 characters. O
. Other id_strings become section ther id_strings become section
IDs. IDs.
sel_crit=hexdigits defines the Selection Criteria of the boot imag e. Up to 20 bytes get read from sel_crit=hexdigits defines the Selection Criteria of the boot ima ge. 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. 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. A ny following -bootimage bootspecs next ends the definition of a boot image and starts a new one. An y following -bootimage bootspecs
will affect the new image. The first "next" discards loaded boot images and their catalog. 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 di system_area=disk_path copies at most 32768 bytes from the given d
sk file to the very start of the isk file to the very start of the
ISO image. This System Area is reserved for system dependent boo ISO image. This System Area is reserved for system dependent boot
t software, e.g. an MBR which can software, e.g. an MBR which can
be used to boot from USB stick or hard disk. be used to boot from USB stick or hard disk.
Other than an El Torito boot image, the file disk_path needs not t o be added to the ISO image. Other than an El Torito boot image, the file disk_path needs not t o be added to the ISO image.
-boot_image isolinux system_area= implies "partition_table=on". I n this case, the disk path should -boot_image isolinux system_area= implies "partition_table=on". I n this case, the disk path should
lead to one of the SYSLINUX files isohdp[fp]x*.bin or to a file wh ich was derived from one of those lead to one of the SYSLINUX files isohdp[fp]x*.bin or to a file wh ich was derived from one of those
files. E.g. to the first 512 bytes from an ISOLINUX isohybrid ISO image. 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=) In this case, El Torito boot images (dir=, bin_path=, efi_pa
may be augmented by isolinux th=) may be augmented by isolinux
partition_entry=gpt_basdat or isolinux partition_entry=gp partition_entry=gpt_basdat or isolinux partition_entry=gpt_
t_hfsplus, and by isolinux hfsplus, and by isolinux
partition_entry=apm_hfsplus. The boot image will then be mentione partition_entry=apm_hfsplus. The boot image will then be mentione
d in GPT as Basic Data or GPT d in an invalid GPT as Basic Data
HFS+ partition, and in APM as HFS+ partition. The first three G or GPT HFS+ partition, and in a valid APM as HFS+ partition. The
PT partitions will also be marked first three GPT partitions will
by MBR partitions. also be marked by MBR partitions. The MBR partition of type 0xE
F is what actually is used by EFI
firmware for booting from USB stick.
In multi-session situations the existing System Area is preserved by default. In in this case, the 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 never theless causes adjustments in the special disk_path "." prevents reading of a disk file but never theless causes adjustments in the
loaded system area data. Such adjustments may get ordered by -boot _image commands. loaded system area data. Such adjustments may get ordered by -boot _image commands.
-boot_image any gpt_disk_guid=value controls whether an emerging G PT shall get a randomly generated -boot_image any gpt_disk_guid=value controls whether an emerging G PT shall get a randomly generated
disk GUID or whether the GUID is supplied by the user. Value "random" is default. Value 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". "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 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 41 22 GUID string to be byte-swapped directly. UEFI prescribes the first three components of a RFC 41 22 GUID string to be byte-swapped
in the binary representation: in the binary representation:
E.g. gpt_disk_guid=2303cd2a-73c7-424a-a298-25632 da7f446 equals E.g. gpt_disk_guid=2303cd2a-73c7-424a-a298-25632 da7f446 equals
skipping to change at line 2328 skipping to change at line 2429
With MBR: With MBR:
partition_number may be 1 to 4. Number 1 will put the whole ISO i mage into the unclaimed space partition_number may be 1 to 4. Number 1 will put the whole ISO i mage into the unclaimed space
before partition 1. So together with most xorriso MBR features, n umber 2 would be the most natural before partition 1. So together with most xorriso MBR features, n umber 2 would be the most natural
choice. choice.
The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal n umber between 0x00 and 0xff. Not The type_code may be "FAT12", "FAT16", "Linux", or a hexadecimal n umber between 0x00 and 0xff. Not
all those numbers will yield usable results. For a list of MB R partition type codes search the all those numbers will yield usable results. For a list of MB R partition type codes search the
Internet for "Partition Types" or run fdisk command "L". Internet for "Partition Types" or run fdisk command "L".
type_code may also be a type GUID as plain hex string like a2a0d0e be5b9334487c068b6b72699c7 or as type_code may also be a type GUID as plain hex string like a2a0d0e be5b9334487c068b6b72699c7 or as
structured text like EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the partition is 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 wil l be mapped to 0xef. Any other mentioned in GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B wil l be mapped to 0xef. Any other
GUID will be mapped to 0x83. GUID will be mapped to 0x83. In APM, 48465300-0000-11AA-AA
If some other command causes the production of GPT, then the appe 11-00306543ECAC will be mapped to
nded partitions will be mentioned partition type "Apple_HFS", any other to "Data".
If some other command causes the production of GPT, then the appen
ded partitions will be mentioned
there too. there too.
The disk_path must provide the necessary data bytes at commit time . An empty disk_path disables The disk_path must provide the necessary data bytes at commit t ime. An empty disk_path disables
this feature for the given partition number. this feature for the given partition number.
With SUN Disk Label (selected by -boot_image any sparc_label=): 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 partition_number may be 2 to 8. Number 1 will always be the ISO im age. Partition start addresses
are aligned to 320 KiB. The type_code does not matter. Submit 0x0. 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. Partition image name "." causes the partition to become a copy of the next lower valid one.
Jigdo Template Extraction: Jigdo Template Extraction:
From man genisoimage: "Jigdo is a tool to help in the distribution of lar From man genisoimage: "Jigdo is a tool to help in the distribution of la
ge files like CD and DVD images; rge files like CD and DVD images;
see http://atterer.net/jigdo/ for more details. Debian CDs and DVD ISO i see http://atterer.net/jigdo/ for more details. Debian CDs and DVD ISO im
mages are published on the web in ages are published on the web in
jigdo format to allow end users to download them more efficiently." 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 xorriso can produce a .jigdo and a .template file together with a sing le-session ISO image. The .jigdo
file contains checksums and symbolic file addresses. The .template file contains the compressed ISO image 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. 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 Input for this process are the normal arguments for a xorriso session o
a blank -outdev, and a .md5 file n a blank -outdev, and a checksum
which lists those data files which may be listed in the .jigdo file file which lists those data files which may be listed in the .jigdo file
and externally referenced in the and externally referenced in the
.template file. Each designated file is represented in the .md5 file by .template file. Each designated file is represented in the checksum file
a single text line: by a single text line:
MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 bl Checksum as hex digits, 2 blanks, size as 12 decimal digits or blanks, 2
anks, symbolic file address blanks, symbolic file address
The file address in an .md5 line has to bear the same basename as the dis The kind of checksum is chosen by -jigdo "checksum_algorithm" wit
k_path of the file which it shall h values "md5" (32 hex digits) or
match. The directory path of the file address is decisive for To=From m "sha256" (64 hex digits). It will also be used for the file address li
apping, not for file recognition. nes in the .jigdo file. The
After To=From mapping, the file address gets written into the .jigdo f default is "md5".
ile. Jigdo restore tools will The file address in a checksum file line has to bear the same basename a
convert these addresses into really reachable data source addresses from s the disk_path of the file which
which they can read. it shall match. The directory path of the file address is decisive for
If the list of jigdo parameters is not empty, then xorriso will refuse To=From mapping, not for file
to write to non-blank targets, it recognition. After To=From mapping, the file address gets written in
to the .jigdo file. Jigdo restore
tools will convert these addresses into really reachable data source addr
esses 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. will disable multi-session emulation, and padding will be counted as part of the ISO image.
-jigdo parameter_name value -jigdo parameter_name value
Clear Jigdo Template Extraction parameter list or add a parameter to that list. The alias names Clear Jigdo Template Extraction parameter list or add a paramet er to that list. The alias names
are the corresponding genisoimage options. They are accepted as pa rameter names as well. Especially are the corresponding genisoimage options. They are accepted as pa rameter names as well. Especially
they are recognized by the -as mkisofs emulation command. they are recognized by the -as mkisofs emulation command.
Parameter clear with any value empties the whole list. No .jigd o and .template file will be Parameter clear with any value empties the whole list. No .jigdo and .template file will be
produced. produced.
template_path sets the disk_path for the .template file with t checksum_algorithm chooses the checksum algorithm which shall be u
he holed and compressed ISO image sed for the data file entries in
the .jigdo file and is expected in the checksum file. Permissible
are "md5" or "sha256". Default is
"md5".
Alias: -jigdo-checksum-algorithm
template_path sets the disk_path for the .template file with the h
oled and compressed ISO image
copy. copy.
Alias: -jigdo-template Alias: -jigdo-template
jigdo_path sets the disk_path for the .jigdo file with the checksu ms and download addresses for jigdo_path sets the disk_path for the .jigdo file with the che cksums and download addresses for
filling the holes in .template. filling the holes in .template.
Alias: -jigdo-jigdo Alias: -jigdo-jigdo
md5_path sets the disk_path where to find the .md5 input file. checksum_path sets the disk_path where to find the checksum file w
ith symbolic file addresses and
checksums according to checksum_algorithm.
Alias: md5_path
Alias: -checksum-list
Alias: -md5-list Alias: -md5-list
min_size sets the minimum size for a data file to be listed in th e .jigdo file and being a hole in min_size sets the minimum size for a data file to be listed in th e .jigdo file and being a hole in
the .template file. the .template file.
Alias: -jigdo-min-file-size Alias: -jigdo-min-file-size
exclude adds a regular expression pattern which will get compared with the absolute disk_path of 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. any data file. A match causes the file to stay in .template in any case.
Alias: -jigdo-exclude Alias: -jigdo-exclude
demand_md5 adds a regular expression pattern which will get compar demand_checksum adds a regular expression pattern which wil
ed with the absolute disk_path of l get compared with the absolute
any data file that was not found in the .md5 list. A match causes disk_path of any data file that was not found in the checksum list
a MISHAP event. file as of "checksum_path". A
match causes a MISHAP event.
Alias: demand_md5
Alias: -jigdo-force-checksum
Alias: -jigdo-force-md5 Alias: -jigdo-force-md5
mapping adds a string pair of the form To=From to the parameter li mapping adds a string pair of the form To=From to the parameter
st. If a data file gets listed list. If a data file gets listed
in the .jigdo file, then it is referred by the file address fro in the .jigdo file, then it is referred by the file address from i
m its line in the .md5 file. This ts line in the checksum file.
file address gets checked whether it begins with the From string. This file address gets checked whether it begins with the From str
If so, then this string will be ing. If so, then this string will
replaced by the To string and a ':' character, before it goes into be replaced by the To string and a ':' character, before it goes i
the .jigdo file. The From string nto the .jigdo file. The From
should end by a '/' character. string should end by a '/' character.
Alias: -jigdo-map Alias: -jigdo-map
compression chooses one of "bzip2" or "gzip" for the compression o f the template file. The jigdo compression chooses one of "bzip2" or "gzip" for the compressio n of the template file. The jigdo
file is put out uncompressed. file is put out uncompressed.
Alias: -jigdo-template-compress Alias: -jigdo-template-compress
checksum_iso chooses one or more of "md5", "sha1", "sha256", "s checksum_iso chooses one or more of "md5", "sha1", "sha256", "sha5
ha512" for the auxiliary "# Image 12" for the auxiliary "# Image
Hex" checksums in the jigdo file. The value may e.g. look like Hex" checksums in the jigdo file. The value may e.g. look li
"md5,sha1,sha512". Value "all" ke "md5,sha1,sha512". Value "all"
chooses all available algorithms. Note that MD5 stays always enab led. chooses all available algorithms. Note that MD5 stays always enab led.
Alias: -checksum_algorithm_iso Alias: -checksum_algorithm_iso
checksum_template is like checksum_iso but for "# Template Hex". checksum_template is like checksum_iso but for "# Template Hex".
Alias: -checksum_algorithm_template Alias: -checksum_algorithm_template
Character sets: Character sets:
File names are strings of non-zero bytes with 8 bit each. Unfortunately t he same byte string may appear as File names are strings of non-zero bytes with 8 bit each. Unfortunately t he same byte string may appear as
different peculiar national characters on differently nationalized termin als. The meanings of byte codes different peculiar national characters on differently nationalized termi nals. The meanings of byte codes
are defined in character sets which have names. Shell command iconv -l li sts them. are defined in character sets which have names. Shell command iconv -l li sts them.
The file names on hard disk are assumed to be encoded by the local cha The file names on hard disk are assumed to be encoded by the local charac
racter set which is also used for ter set which is also used for
the communication with the user. Byte codes 32 to 126 of the local chara the communication with the user. Byte codes 32 to 126 of the local char
cter set must match the US-ASCII acter set must match the US-ASCII
characters of the same code. ISO-8859 and UTF-8 fulfill this demand. 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 "loca le" with argument "charmap". This By default, xorriso uses the character set as told by shell command "loca le" with argument "charmap". This
may be influenced by environment variables LC_ALL, LC_CTYPE, or LANG and should match the expectations of 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 comman d -local_charset. the terminal. In some situations it may be necessary to set it by comman d -local_charset.
Local character sets should not matter as long as only english alphanum Local character sets should not matter as long as only english alphanumer
eric characters are used for file ic characters are used for file
names or as long as all writers and readers of the media use the same loc names or as long as all writers and readers of the media use the same lo
al character set. Outside these cal character set. Outside these
constraints it may be necessary to let xorriso convert byte codes from an d to other character sets. constraints it may be necessary to let xorriso convert byte codes from an d to other character sets.
The Rock Ridge file names in ISO filesystems are assumed to be encoded by the input character set. The 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 enco ded by the output character set. Rock Ridge file names which get written with ISO filesystems will be enco ded by the output character set.
The sets can be defined independently by commands -in_charset and -out_ch The sets can be defined independently by commands -in_charset and -ou
arset. Normally one will have t_charset. Normally one will have
both identical, if ever. Other than the local character set, these tw both identical, if ever. Other than the local character set, these two c
o character sets may deviate from haracter sets may deviate from
US-ASCII. US-ASCII.
The output character sets for Joliet and HFS+ are not influenced by these commands. Joliet uses output The output character sets for Joliet and HFS+ are not influenced by t hese commands. Joliet uses output
character set UCS-2 or UTF-16. HFS+ uses UTF-16. character set UCS-2 or UTF-16. HFS+ uses UTF-16.
The default output charset is the local character set of the terminal whe re xorriso runs. So by default no The default output charset is the local character set of the terminal whe re xorriso runs. So by default no
conversion happens between local filesystem names and emerging Rock R idge names in the image. The conversion happens between local filesystem names and emerging Ro ck Ridge names in the image. The
situation stays ambiguous and the reader has to riddle what character set was used. 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 By command -auto_charset it is possible to attribute the output charset n
name to the image. This makes the ame to the image. This makes the
situation unambiguous. But if your terminal character set does not match situation unambiguous. But if your terminal character set does not mat
the character set of the local ch the character set of the local
file names, then this attribute can become plainly wrong and cause proble ms at read time. To prevent this file names, then this attribute can become plainly wrong and cause proble ms at read time. To prevent this
it is necessary to check whether the terminal properly displays all inten ded filenames. Check especially it is necessary to check whether the terminal properly displays all int ended filenames. Check especially
the exotic national characters. the exotic national characters.
To enforce recording of a particular character set name without any con To enforce recording of a particular character set name without any conve
version at image generation time, rsion at image generation time,
set -charset and -local_charset to the desired name, and enable -backslas set -charset and -local_charset to the desired name, and enable -backsl
h_codes to avoid evil character ash_codes to avoid evil character
display on your terminal. display on your terminal.
-charset character_set_name -charset character_set_name
Set the character set from which to convert file names when loading an image and to which to Set the character set from which to convert file names when loadi ng an image and to which to
convert when writing an image. convert when writing an image.
-local_charset character_set_name -local_charset character_set_name
Override the system assumption of the local character set name. I f this appears necessary, one 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 should consider to set -backslash_codes to "on" in order to avoid dangerous binary codes being sent
to the terminal. to the terminal.
Exception processing: Exception processing:
Since the tasks of xorriso are manifold and prone to external influence, there may arise the need for Since the tasks of xorriso are manifold and prone to external influe nce, there may arise the need for
xorriso to report and handle problem events. xorriso to report and handle problem events.
Those events get classified when they are detected by one of the software modules and forwarded to Those events get classified when they are detected by one of the soft ware modules and forwarded to
reporting and evaluation modules which decide about reactions. Event clas ses are sorted by severity: reporting and evaluation modules which decide about reactions. Event clas ses are sorted by severity:
"NEVER" The upper end of the severity spectrum. "NEVER" The upper end of the severity spectrum.
"ABORT" The program is being aborted and on its way to end. "ABORT" The program is being aborted and on its way to end.
"FATAL" The main purpose of the run failed or an important resource faile d unexpectedly. "FATAL" The main purpose of the run failed or an important resource faile d unexpectedly.
"FAILURE" An important part of the job could not be performed. "FAILURE" An important part of the job could not be performed.
"MISHAP" A FAILURE which can be tolerated during ISO image generation. "MISHAP" A FAILURE which can be tolerated during ISO image generation.
"SORRY" A less important part of the job could not be performed. "SORRY" A less important part of the job could not be performed.
"WARNING" A situation is suspicious of being not intended by the user. "WARNING" A situation is suspicious of being not intended by the user.
"HINT" A proposal to the user how to achieve better results. "HINT" A proposal to the user how to achieve better results.
"NOTE" A harmless information about noteworthy circumstances. "NOTE" A harmless information about noteworthy circumstances.
"UPDATE" A pacifier message during long running operations. "UPDATE" A pacifier message during long running operations.
"DEBUG" A message which would only interest the program developers. "DEBUG" A message which would only interest the program developers.
"ALL" The lower end of the severity spectrum. "ALL" The lower end of the severity spectrum.
-abort_on severity -abort_on severity
Set the severity threshold for events to abort the program. Set the severity threshold for events to abort the program.
Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY" Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY"
It may become necessary to abort the program anyway, despite the s etting by this command. Expect It may become necessary to abort the program anyway, despite th e setting by this command. Expect
not many "ABORT" events to be ignorable. not many "ABORT" events to be ignorable.
A special property of this command is that it works preemptive if A special property of this command is that it works preemptive if
given as program start argument. given as program start argument.
I.e. the first -abort_on setting among the start arguments is in I.e. the first -abort_on setting among the start arguments is
effect already when the first in effect already when the first
operations of xorriso begin. Only "-abort_on" with dash "-" is rec ognized that way. operations of xorriso begin. Only "-abort_on" with dash "-" is rec ognized that way.
-return_with severity exit_value -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 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 indicat ing exit value from the program, allow xorriso to go on after problems but to get a failure indica ting exit value from the program,
nevertheless. Useful is a value lower than the -abort_on threshol d, down to "WARNING". nevertheless. Useful is a value lower than the -abort_on threshol d, down to "WARNING".
exit_value may be either 0 (indicating success to the starter of the program) or a number between exit_value may be either 0 (indicating success to the starter of t he program) or a number between
32 and 63. Some other exit_values are used by xorriso if it decide s to abort the program run: 32 and 63. Some other exit_values are used by xorriso if it decide s to abort the program run:
1=abort due to external signal 1=abort due to external signal
2=no program arguments given 2=no program arguments given
3=creation of xorriso main object failed 3=creation of xorriso main object failed
4=failure to start libburnia-project.org libraries 4=failure to start libburnia-project.org libraries
5=program abort during argument processing 5=program abort during argument processing
6=program abort during dialog processing 6=program abort during dialog processing
-report_about severity -report_about severity
Set the threshold for events to be reported. Set the threshold for events to be reported.
Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "A LL" Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "A LL"
Regardless what is set by -report_about, messages get always repor ted if they reach the severity Regardless what is set by -report_about, messages get always re ported if they reach the severity
threshold of -abort_on . threshold of -abort_on .
Event messages are sent to the info channel "I" which is usuall y stderr but may be influenced by Event messages are sent to the info channel "I" which is usually s tderr but may be influenced by
command -pkt_output. Info messages which belong to no event get a ttributed severity "NOTE". command -pkt_output. Info messages which belong to no event get a ttributed severity "NOTE".
A special property of this command is that the first -report_ A special property of this command is that the first -rep
about setting among the start ort_about setting among the start
arguments is in effect already when the first operations of xo arguments is in effect already when the first operations of xorri
rriso begin. Only "-report_about" so begin. Only "-report_about"
with dash "-" is recognized that way. with dash "-" is recognized that way.
-signal_handling mode -signal_handling mode
Control the installation of a signal handler which shall react o n external signals (e.g. from Control the installation of a signal handler which shall rea ct on external signals (e.g. from
program "kill" or from keys Ctrl+C) or on signals caused by severe program errors. 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 Mode "on" is the default. It uses the signal handler of libburn wh ich produces ugly messages but
puts much effort in releasing optical drives before xorriso ends. puts much effort in releasing optical drives before xorriso ends.
Mode "off" as first -signal_handling among the start arguments pre vents all own signal precautions Mode "off" as first -signal_handling among the start arguments pr events all own signal precautions
of xorriso. Inherited signal handler settings stay as they are. of xorriso. Inherited signal handler settings stay as they are.
It works like "sig_dfl" if given after other signal handling w as already established at program It works like "sig_dfl" if given after other signal handling was already established at program
start. start.
Mode "sig_dfl" uses the system provided default handling of signal Mode "sig_dfl" uses the system provided default handling of si
s, which is normally a sudden gnals, which is normally a sudden
abort of the program. To prevent stuck drives, the libbur abort of the program. To prevent stuck drives, the libburn ha
n handler is used during burning, ndler is used during burning,
blanking, and formatting on MMC drives. blanking, and formatting on MMC drives.
Mode "sig_ign" tries to ignore as many signal types as possible. T his imposes the risk that xorriso Mode "sig_ign" tries to ignore as many signal types as possible. T his imposes the risk that xorriso
refuses to end until externally kill -9 if performed. kill -9 the n imposes the risk that the drive refuses to end until externally kill -9 if performed. kill -9 the n imposes the risk that the drive
is left in unusable state and needs poweroff to be reset. So during burning, blanking, and 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. formatting wait for at least their normal run time before killing externally.
A special property of this command is that the first -signal A special property of this command is that the first -signal_han
_handling setting among the start dling setting among the start
arguments is in effect already when the first operations of xorris arguments is in effect already when the first operations of xorri
o begin. Only "-signal_handling" so begin. Only "-signal_handling"
with dash "-" is recognized that way. with dash "-" is recognized that way.
-error_behavior occasion behavior -error_behavior occasion behavior
Control the program behavior at problem event occasions. Control the program behavior at problem event occasions. For
For now this applies to occasions now this applies to occasions
"image_loading" which is given while an image tree is read f "image_loading" which is given while an image tree is rea
rom the input device, and to d from the input device, and to
"file_extraction" which is given with osirrox commands like -extra ct. "file_extraction" which is given with osirrox commands like -extra ct.
With "image_loading" there are three behaviors available: With "image_loading" there are three behaviors available:
"best_effort" goes on with reading after events with severity below FAILURE if the threshold of "best_effort" goes on with reading after events with severity belo w FAILURE if the threshold of
command -abort_on allows this. command -abort_on allows this.
"failure" aborts image tree reading on first event of at least SOR RY. It issues an own FAILURE "failure" aborts image tree reading on first event of at least SORRY. It issues an own FAILURE
event. This is the default. event. This is the default.
"fatal" acts like "failure" but issues the own event as FATAL. "fatal" acts like "failure" but issues the own event as FATAL.
With occasion "file_extraction" there are three behaviors: With occasion "file_extraction" there are three behaviors:
"keep" maintains incompletely extracted files on disk. This is the default. "keep" maintains incompletely extracted files on disk. This is the default.
"delete" removes files which encountered errors during content ext raction. "delete" removes files which encountered errors during content ext raction.
"best_effort" starts a revovery attempt by means of -extract_cut i f the file content stems from the "best_effort" starts a revovery attempt by means of -extract_cut i f the file content stems from the
loaded ISO image and is not filtered. loaded ISO image and is not filtered.
Dialog mode control: Dialog mode control:
-dialog "on"|"off"|"single_line" -dialog "on"|"off"|"single_line"
Enable or disable to enter dialog mode after all program arguments are processed. In dialog mode Enable or disable to enter dialog mode after all program argumen ts are processed. In dialog mode
input lines get prompted via readline or from stdin. input lines get prompted via readline or from stdin.
If no -abort_on severity was set when dialog starts, then "NEV If no -abort_on severity was set when dialog starts, then "NEVER"
ER" is set to avoid abort in most is set to avoid abort in most
cases of wrong input or other problems. Before dialog begins, the cases of wrong input or other problems. Before dialog begins, th
default is "FAILURE" which e.g. e default is "FAILURE" which e.g.
aborts on unknown commands. aborts on unknown commands.
Mode "on" supports input of newline characters within quotati on marks and line continuation by Mode "on" supports input of newline characters within quotation m arks and line continuation by
trailing backslash outside quotation marks. Mode "single_line" do es not. trailing backslash outside quotation marks. Mode "single_line" do es not.
-page length width -page length width
Describe terminal to the text pager. See also above, paragraph Res ult pager. Describe terminal to the text pager. See also above, paragraph Res ult pager.
If parameter length is nonzero then the user gets prompted after t hat number of terminal lines. If parameter length is nonzero then the user gets prompted aft er that number of terminal lines.
Zero length disables paging. Zero length disables paging.
Parameter width is the number of characters per terminal line. It is used to compute the number of 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 term inal width is 80. terminal lines which get occupied by an output line. A usual term inal width is 80.
-use_readline "on"|"off" -use_readline "on"|"off"
If "on" then use readline for dialog. Else use plain stdin. If "on" then use readline for dialog. Else use plain stdin.
See also above, paragraph Dialog, Readline, Result pager. See also above, paragraph Dialog, Readline, Result pager.
-reassure "on"|"tree"|"off" -reassure "on"|"tree"|"off"
If "on" then ask the user for "y" or "n": If "on" then ask the user for "y" or "n":
before deleting or overwriting any file in the ISO image, before deleting or overwriting any file in the ISO image,
before overwriting any disk file during restore operations, before overwriting any disk file during restore operations,
before rolling back pending image changes, before rolling back pending image changes,
before committing image changes to media, before committing image changes to media,
before changing the input drive, before changing the input drive,
before blanking or formatting media, before blanking or formatting media,
before ending the program. before ending the program.
With setting "tree" the reassuring prompt will appear for an event ual directory only once and not With setting "tree" the reassuring prompt will appear for an eve ntual directory only once and not
for each file in its whole subtree. for each file in its whole subtree.
Setting "off" silently kills any kind of image file object and per forms above irrevocable actions. Setting "off" silently kills any kind of image file object and per forms above irrevocable actions.
To really produce user prompts, command -dialog needs to be set to "on". Note that the prompt does 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 comm and -overwrite. -reassure only not appear in situations where file removal is forbidden by c ommand -overwrite. -reassure only
imposes an additional curb for removing existing file objects. imposes an additional curb for removing existing file objects.
Be aware that file objects get deleted from the ISO image immedia Be aware that file objects get deleted from the ISO image immediat
tely after confirmation. They are ely after confirmation. They are
gone even if the running command gets aborted and its desired eff gone even if the running command gets aborted and its desire
ect gets revoked. In case of d effect gets revoked. In case of
severe mess-up, consider to use -rollback to revoke the whole sess ion. severe mess-up, consider to use -rollback to revoke the whole sess ion.
Drive and media related inquiry actions: Drive and media related inquiry actions:
-devices -devices
Show list of available MMC drives with the addresses of their libb urn standard device files. Show list of available MMC drives with the addresses of their libb urn standard device files.
This is only possible when no ISO image changes are pending. After this command was executed, This is only possible when no ISO image changes are pending. Aft er this command was executed,
there is no drive current and no image loaded. 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. 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. Thus it might be only the superuser who is able to see all drives.
Drives which are occupied by other processes get not shown. Drives which are occupied by other processes get not shown.
-device_links -device_links
Like -devices, but presenting the drives with addresses of symboli c links which point to the actual Like -devices, but presenting the drives with addresses of symboli c links which point to the actual
device files. device files.
Modern GNU/Linux systems may shuffle drive addresses from boot Modern GNU/Linux systems may shuffle drive addresses from
to boot. The udev daemon is boot to boot. The udev daemon is
supposed to create links which always point to the same drive, supposed to create links which always point to the same drive, reg
regardless of its system address. ardless of its system address.
The command -device_links shows the addresses of such links if The command -device_links shows the addresses of such link
they begin by "/dev/dvd" or s if they begin by "/dev/dvd" or
"/dev/cd". Precedence is: "dvdrw", "cdrw", "dvd", "cdrom", "cd". "/dev/cd". Precedence is: "dvdrw", "cdrw", "dvd", "cdrom", "cd".
-toc -toc
Show media specific tables of content. This is the session history of the medium, not the ISO image Show media specific tables of content. This is the session history of the medium, not the ISO image
directory tree. directory tree.
In case of overwriteable media holding a valid ISO image, it may h In case of overwritable media holding a valid ISO image, it may
appen that only a single session happen that only a single session
gets shown. But if the first session on the overwriteable me gets shown. But if the first session on the overwritable media w
dia was written by xorriso then a as written by xorriso then a
complete session history can be emulated. 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 A drive which is incapable of writing may show any media as CD-RO M or DVD-ROM with only one or two
sessions on it. The last of these sessions is supposed to be the m ost recent real session then. sessions on it. The last of these sessions is supposed to be the m ost recent real session then.
Some read-only drives and media show no usable session history at all. Command -rom_toc_scan might Some read-only drives and media show no usable session history at all. Command -rom_toc_scan might
help. help.
If input device and output device are both acquired and not the sa me, then both tables-of-content If input device and output device are both acquired and not the same, then both tables-of-content
get shown. get shown.
-toc_of "in"|"out"|"all"[":short"] -toc_of "in"|"out"|"all"[":short"]
Like command -toc but explicitly choosing which drive's table-of-c ontent to show. "in" shows -indev Like command -toc but explicitly choosing which drive's table-of-c ontent to show. "in" shows -indev
or -dev, "out" shows -outdev or -dev, "all" shows the same as -toc . 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 sh ort summary of drive state and If ":short" is appended to the drive choosing word, then only a short summary of drive state and
medium content is printed. medium content is printed.
As further difference to -toc, this command does not emit FAILU RE events if the desired drive is As further difference to -toc, this command does not emit FAILURE events if the desired drive is
not acquired. not acquired.
-mount_cmd drive entity id path -mount_cmd drive entity id path
Emit an appropriate command line for mounting the ISO session indi cated by drive, entity and id. Emit an appropriate command line for mounting the ISO session i ndicated by drive, entity and id.
The result will be different on GNU/Linux and on FreeBSD or NetBSD . The result will be different on GNU/Linux and on FreeBSD or NetBSD .
drive can be "indev" or "outdev" to indicate already acquired d rives, or it can be the path of a drive can be "indev" or "outdev" to indicate already acquired driv es, or it can be the path of a
not yet acquired drive. Prefix "stdio:" for non-MMC drives is not mandatory. 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 For entity and id, see also command -load. They must be eith
"sbsector" with the superblock er "sbsector" with the superblock
sector address as id, or "track" with a track number as id, or "s sector address as id, or "track" with a track number as id, or "se
ession" with a session number, or ssion" with a session number, or
"volid" with a search pattern for the volume id, or "auto" with wh "volid" with a search pattern for the volume id, or "auto" wit
ich any text as id mounts the h which any text as id mounts the
first track of the last session. first track of the last session.
path will be used as mount point and must already exist as a direc tory on disk. path will be used as mount point and must already exist as a direc tory on disk.
The command gets printed to the result channel. See command -m ount for direct execution of this The command gets printed to the result channel. See command -mount for direct execution of this
command. command.
-mount_opts option[:option...] -mount_opts option[:option...]
Set options which influence -mount and -mount_cmd. Currently there is only option "exclusive" which Set options which influence -mount and -mount_cmd. Currently there is only option "exclusive" which
is default and its counterpart "shared". The latter causes xo is default and its counterpart "shared". The latter causes xorriso
rriso not to give up the affected not to give up the affected
drive with command -mount. On GNU/Linux it adds mount option "loo drive with command -mount. On GNU/Linux it adds mount option "l
p" which may enable mounting of oop" which may enable mounting of
several sessions of the same block device at the same time. several sessions of the same block device at the same time. One s
One should not write to a mounted hould not write to a mounted
optical medium, of course. Take care to umount all sessions before ejecting. optical medium, of course. Take care to umount all sessions before ejecting.
-session_string drive entity id format -session_string drive entity id format
Print to the result channel a text which gets composed according t o format and the parameters of Print to the result channel a text which gets composed accordin g to format and the parameters of
the addressed session. the addressed session.
Formats "linux:"path or "freebsd:"path produce the output of - mount_cmd for the given operating Formats "linux:"path or "freebsd:"path produce the output of -moun t_cmd for the given operating
systems. systems.
In other texts xorriso will substitute the following parameter nam es. An optional prefix "string:" In other texts xorriso will substitute the following parameter nam es. An optional prefix "string:"
will be removed. will be removed.
"%device%" will be substituted by the mountable device path of the drive address. "%device%" will be substituted by the mountable device path of the drive address.
"%sbsector%" will be substituted by the session start sector. "%sbsector%" will be substituted by the session start sector.
"%track%", "%session%", "%volid%" will be substituted by track num ber, session number, or volume id "%track%", "%session%", "%volid%" will be substituted by track num ber, session number, or volume id
of the depicted session. of the depicted session.
-print_size -print_size
Print the foreseeable consumption of 2048 byte blocks by next -com Print the foreseeable consumption of 2048 byte blocks by next -c
mit. This can last a while as a ommit. This can last a while as a
-commit gets prepared and only in last moment is revoked by thi -commit gets prepared and only in last moment is revoked by this c
s command. The result depends on ommand. The result depends on
several settings and also on the kind of output device. If no -j several settings and also on the kind of output device. If
idgo options are set and not no -jigdo options are set and not
command -as "mkisofs" was used, then -padding (300 kB by defau command -as "mkisofs" was used, then -padding (300 kB by default)
lt) is not counted as part of the is not counted as part of the
image size. image size.
If an El Torito boot image file is already depicted, then co If an El Torito boot image file is already depicted, then
mmand -print_size automatically command -print_size automatically
executes -boot_image "any" "next". This means that the proper executes -boot_image "any" "next". This means that the properties
ties of that boot image cannot be of that boot image cannot be
edited by subsequent commands. edited by subsequent commands.
-tell_media_space -tell_media_space
Print available space on the output medium and the free space afte r subtracting already foreseeable Print available space on the output medium and the free space afte r subtracting already foreseeable
consumption by next -commit. consumption by next -commit.
Note that the title of the prediction "After commit :" is mislead ing. It is rather the space that Note that the title of the prediction "After commit :" is misleadi ng. It is rather the space that
may still be filled in this session without making the next -commi t fail from medium overflow. may still be filled in this session without making the next -commi t fail from medium overflow.
The free space after the next -commit might be smaller by several MB. This depends on medium type, 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. number of recorded sessions, and drive habits.
-pvd_info -pvd_info
Print various ID strings and timestamps which can be found in l Print various ID strings and timestamps which can be found in load
oaded ISO images. Some of the IDs ed ISO images. Some of the IDs
may be changed by commands like -volid or -publisher. For these I may be changed by commands like -volid or -publisher. For these
Ds -pvd_info reports what would IDs -pvd_info reports what would
be written with the next -commit. The timestamps get not aut be written with the next -commit. The timestamps get not automa
omatically propagated from loaded tically propagated from loaded
image to newly written image. The ones for new images may be set image to newly written image. The ones for new images may be
by command -volume_date. See set by command -volume_date. See
there for the meaning of the particular timestamps. there for the meaning of the particular timestamps.
-report_el_torito mode -report_el_torito mode
With mode plain print a report about the information found in the El Torito boot catalog of the With mode plain print a report about the information found in the El Torito boot catalog of the
loaded ISO image. loaded ISO image.
With mode help print a text which explains the meaning of the line s put out by "plain". With mode help print a text which explains the meaning of the line s put out by "plain".
Mode cmd tries to print the xorriso commands which are necessa Mode cmd tries to print the xorriso commands which are ne
ry to produce the found boot cessary to produce the found boot
equipment: disk identifiers, El Torito boot images, and System A equipment: disk identifiers, El Torito boot images, and System Are
rea. Disk identifiers are strings a. Disk identifiers are strings
which the booting operating system might use to find the ISO fi which the booting operating system might use to find the IS
lesystem from where it comes. O filesystem from where it comes.
Currently known is the use of volume id and modification date. Currently known is the use of volume id and modification date.
The intended use case is modification of the filesystem by havi The intended use case is modification of the filesystem by having
ng -indev and -outdev pointing to -indev and -outdev pointing to
different images or drives. The result might be insufficient, if different images or drives. The result might be insufficient,
the found equipment cannot be if the found equipment cannot be
produced by xorriso. Various SORRY events may arise in this ca produced by xorriso. Various SORRY events may arise in this case,
se, but it is not guaranteed that but it is not guaranteed that
xorriso recognizes all its insufficiencies. xorriso recognizes all its insufficiencies.
Mode as_mkisofs tries to print the xorriso -as mkisofs options, wh Mode as_mkisofs tries to print the xorriso -as mkisofs options, w
ich are necessary to produce the hich are necessary to produce the
found equipment. The intended use case is to use the mounted found equipment. The intended use case is to use the mounted file
filesystem as input tree together system as input tree together
with the printed options. with the printed options.
-report_system_area mode -report_system_area mode
With mode plain print a report about the information found in the System Area of the loaded ISO 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 tex t, a colon, and information text. image. The report consists of zero to many lines with a header tex t, a colon, and information text.
With mode help print a text which explains the meaning of With mode help print a text which explains the meaning of the l
the lines put out by "plain". You ines put out by "plain". You
probably will have to look for more documentation which explains probably will have to look for more documentation which expl
the technical details of the ains the technical details of the
mentioned boot facilities. mentioned boot facilities.
Modes cmd and as_mkisofs work like with command -report_el_torito. See above. 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 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 th is case nothing is printed to channel. It is not considered an error if no GPT is present. I n this case nothing is printed to
result channel. result channel.
With mode gpt_crc_of:disk_path read up to 32 KiB from the disk f ile with the path given after the With mode gpt_crc_of:disk_path read up to 32 KiB from the disk fil e with the path given after the
colon. Compute the GPT compliant CRC number and print it to the re sult channel. The number is shown colon. Compute the GPT compliant CRC number and print it to the re sult channel. The number is shown
like "0x690fd979". The special disk_path "-" causes reading from standard input. like "0x690fd979". The special disk_path "-" causes reading from standard input.
With mode make_guid print a pseudo-random GUID in RFC 4122 text fo rmat to result channel. With mode make_guid print a pseudo-random GUID in RFC 4122 text fo rmat to result channel.
Navigation in ISO image and disk filesystem: Navigation in ISO image and disk filesystem:
-cd iso_rr_path -cd iso_rr_path
Change the current working directory in the ISO image. This is p repended to iso_rr_paths which do Change the current working directory in the ISO image. This is pr epended to iso_rr_paths which do
not begin with '/'. not begin with '/'.
It is possible to set the working directory to a path which does n It is possible to set the working directory to a path which doe
ot exist yet in the ISO image. s not exist yet in the ISO image.
The necessary parent directories will be created when the first The necessary parent directories will be created when the first fi
file object is inserted into that le object is inserted into that
virtual directory. Use -mkdir if you want to enforce the existenc virtual directory. Use -mkdir if you want to enforce the exis
e of the directory already at tence of the directory already at
first insertion. first insertion.
-cdx disk_path -cdx disk_path
Change the current working directory in the local filesystem. To be prepended to disk_paths which Change the current working directory in the local filesystem. To be prepended to disk_paths which
do not begin with '/'. do not begin with '/'.
-pwd -pwd
Tell the current working directory in the ISO image. Tell the current working directory in the ISO image.
-pwdx -pwdx
Tell the current working directory in the local filesystem. Tell the current working directory in the local filesystem.
-ls iso_rr_pattern [***] -ls iso_rr_pattern [***]
List files in the ISO image which match shell patterns (i.e. with wildcards '*' '?' '[a-z]'). If a 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. 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. Directories are listed by their content rather than as single file item.
Pattern expansion may be disabled by command -iso_rr_pattern. Pattern expansion may be disabled by command -iso_rr_pattern.
-lsd iso_rr_pattern [***] -lsd iso_rr_pattern [***]
Like -ls but listing directories as themselves and not by the ir content. This resembles shell Like -ls but listing directories as themselves and not by their content. This resembles shell
command ls -d. command ls -d.
-lsl iso_rr_pattern [***] -lsl iso_rr_pattern [***]
Like -ls but also list some of the file attributes. The output fo rmat resembles shell command ls Like -ls but also list some of the file attributes. The output format resembles shell command ls
-ln. -ln.
File type 'e' indicates the El Torito boot catalog. File type 'e' indicates the El Torito boot catalog.
If the file has non-trivial ACL, then a '+' is appended to the If the file has non-trivial ACL, then a '+' is appended to the per
permission info. If the file is mission info. If the file is
hidden, then 'I' for "iso_rr", 'J' for "joliet", 'A' for "hfsplus" hidden, then 'I' for "iso_rr", 'J' for "joliet", 'A' for "hfspl
, 'H' for multiple hiding gets us", 'H' for multiple hiding gets
appended. Together with ACL it is 'i', 'j', 'a', 'h'. appended. Together with ACL it is 'i', 'j', 'a', 'h'.
-lsdl iso_rr_pattern [***] -lsdl iso_rr_pattern [***]
Like -lsd but also list some of the file attributes. The output format resembles shell command ls Like -lsd but also list some of the file attributes. The output f ormat resembles shell command ls
-dln. -dln.
-lsx disk_pattern [***] -lsx disk_pattern [***]
List files in the local filesystem which match shell patterns. Pat terns which do not begin with '/' List files in the local filesystem which match shell patterns. Pat terns which do not begin with '/'
are used relative to -cdx. are used relative to -cdx.
Directories are listed by their content rather than as single file item. Directories are listed by their content rather than as single file item.
Pattern expansion may be disabled by command -disk_pattern. Pattern expansion may be disabled by command -disk_pattern.
-lsdx disk_pattern [***] -lsdx disk_pattern [***]
Like -lsx but listing directories as themselves and not by the ir content. This resembles shell Like -lsx but listing directories as themselves and not by their content. This resembles shell
command ls -d. command ls -d.
-lslx disk_pattern [***] -lslx disk_pattern [***]
Like -lsx but also listing some of the file attributes. Output fo rmat resembles shell command ls Like -lsx but also listing some of the file attributes. Output format resembles shell command ls
-ln. -ln.
-lsdlx disk_pattern [***] -lsdlx disk_pattern [***]
Like -lsdx but also listing some of the file attributes. Output format resembles shell command ls Like -lsdx but also listing some of the file attributes. Output f ormat resembles shell command ls
-dln. -dln.
-getfacl iso_rr_pattern [***] -getfacl iso_rr_pattern [***]
Print the access permissions of the given files in the ISO image u Print the access permissions of the given files in the ISO image
sing the format of shell command using the format of shell command
getfacl. If a file has no ACL then it gets fabricated from the - getfacl. If a file has no ACL then it gets fabricated from the -ch
chmod settings. A file may have a mod settings. A file may have a
real ACL if it was introduced into the ISO image while command -ac l was set to "on". real ACL if it was introduced into the ISO image while command -ac l was set to "on".
-getfacl_r iso_rr_pattern [***] -getfacl_r iso_rr_pattern [***]
Like -gefacl but listing recursively the whole file trees undernea th eventual directories. Like -gefacl but listing recursively the whole file trees undernea th eventual directories.
-getfattr iso_rr_pattern [***] -getfattr iso_rr_pattern [***]
Print the xattr of the given files in the ISO image. If a file ha Print the xattr of the given files in the ISO image. If a file
s no such xattr then noting is has no such xattr then noting is
printed for it. The choice of namespaces depends on the setting printed for it. The choice of namespaces depends on the setting o
of command -xattr: "on" or "user" f command -xattr: "on" or "user"
restricts it to namespace "user", "any" only omits namespace "isof s". restricts it to namespace "user", "any" only omits namespace "isof s".
-getfattr_r iso_rr_pattern [***] -getfattr_r iso_rr_pattern [***]
Like -gefattr but listing recursively the whole file trees underne ath of directories. Like -gefattr but listing recursively the whole file trees underne ath of directories.
-du iso_rr_pattern [***] -du iso_rr_pattern [***]
Recursively list size of directories and files in the ISO image wh ich match one of the patterns. Recursively list size of directories and files in the ISO image which match one of the patterns.
similar to shell command du -k. similar to shell command du -k.
-dus iso_rr_pattern [***] -dus iso_rr_pattern [***]
List size of directories and files in the ISO image which match one of the patterns. Similar to List size of directories and files in the ISO image which match on e of the patterns. Similar to
shell command du -sk. shell command du -sk.
-dux disk_pattern [***] -dux disk_pattern [***]
Recursively list size of directories and files in the local files ystem which match one of the Recursively list size of directories and files in the local filesystem which match one of the
patterns. Similar to shell command du -k. patterns. Similar to shell command du -k.
-dusx disk_pattern [***] -dusx disk_pattern [***]
List size of directories and files in the local filesystem which match one of the patterns. List size of directories and files in the local filesystem whic h match one of the patterns.
Similar to shell command du -sk. Similar to shell command du -sk.
-findx disk_path [-name pattern] [-type t] [-exec action [params]] -- -findx disk_path [-name pattern] [-type t] [-exec action [params]] --
Like -find but operating on local filesystem and not on the ISO im age. This is subject to the Like -find but operating on local filesystem and not on the I SO image. This is subject to the
settings of -follow. settings of -follow.
-findx accepts the same -type parameters as -find. Additionally it recognizes type "mountpoint" (or -findx accepts the same -type parameters as -find. Additionally it recognizes type "mountpoint" (or
"m") which matches subdirectories which reside on a different devi ce than their parent. It never "m") which matches subdirectories which reside on a different d evice than their parent. It never
matches the disk_path given as start address for -findx. matches the disk_path given as start address for -findx.
-findx accepts the -exec actions as does -find. But except the fol lowing few actions it will always -findx accepts the -exec actions as does -find. But except the fol lowing few actions it will always
perform action "echo". perform action "echo".
in_iso reports the path if its counterpart exists in the ISO image . For this the disk_path of the in_iso reports the path if its counterpart exists in the ISO imag e. For this the disk_path of the
-findx command gets replaced by the iso_rr_path given as parameter . -findx command gets replaced by the iso_rr_path given as parameter .
E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd -- 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 not_in_iso reports the path if its counterpart does not exist in t he ISO image. The report format
is the same as with command -compare. 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 add_missing iso_rr_path_start adds the counterpart if it does n ot yet exist in the ISO image and
marks it for "rm_merge" as non-removable. marks it for "rm_merge" as non-removable.
E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd -- E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd --
is_full_in_iso reports if the counterpart in the ISO image cont ains files. To be used with -type is_full_in_iso reports if the counterpart in the ISO image contain s files. To be used with -type
"m" to report mount points. "m" to report mount points.
empty_iso_dir deletes all files from the counterpart in the ISO im age. To be used with -type "m" to empty_iso_dir deletes all files from the counterpart in the ISO im age. To be used with -type "m" to
truncate mount points. truncate mount points.
estimate_size prints a lower and an upper estimation of the numbe estimate_size prints a lower and an upper estimation of the number
r of blocks which the found files of blocks which the found files
together will occupy in the emerging ISO image. This does not acc together will occupy in the emerging ISO image. This does not ac
ount for the superblock, for the count for the superblock, for the
directories in the -findx path, or for image padding. directories in the -findx path, or for image padding.
list_extattr mode prints a script to the result channel, which wou ld use FreeBSD command setextattr list_extattr mode prints a script to the result channel, which wou ld use FreeBSD command setextattr
to set the file's xattr name-value pairs of user namespace. Se e -find for a description of to set the file's xattr name-value pairs of user namespace . See -find for a description of
parameter mode. parameter mode.
E.g. -exec list_extattr e -- E.g. -exec list_extattr e --
-compare disk_path iso_rr_path -compare disk_path iso_rr_path
Compare attributes and eventual data file content of a fileobje Compare attributes and eventual data file content of a fileobject
ct in the local filesystem with a in the local filesystem with a
file object in the ISO image. The iso_rr_path may well point to an file object in the ISO image. The iso_rr_path may well point to
image file object which is not an image file object which is not
yet committed, i.e. of which the data content still resides i yet committed, i.e. of which the data content still resides in th
n the local filesystem. Such data e local filesystem. Such data
content is prone to externally caused changes. 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. 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 Differing attributes are reported in detail, differing content i s summarized. Both to the result
channel. In case of no differences no result lines are emitted. channel. In case of no differences no result lines are emitted.
-compare_r disk_path iso_rr_path -compare_r disk_path iso_rr_path
Like -compare but working recursively. I.e. all file objects below both addresses get compared Like -compare but working recursively. I.e. all file objects belo w both addresses get compared
whether they have counterparts below the other address and whether both counterparts match. whether they have counterparts below the other address and whether both counterparts match.
-compare_l disk_prefix iso_rr_prefix disk_path [***] -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 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. disk_path by replacing disk_prefix by iso_rr_prefix.
-show_stream iso_rr_path [***] -show_stream iso_rr_path [***]
Display the content stream chain of data files in the ISO Display the content stream chain of data files in the ISO imag
image. The chain consists of the e. The chain consists of the
iso_rr_name and one or more streams, separated by " < " marks. A iso_rr_name and one or more streams, separated by " < " marks.
stream description consists of A stream description consists of
one or more texts, separated by ":" characters. The firs one or more texts, separated by ":" characters. The first tex
t text tells the stream type, the t tells the stream type, the
following ones, if ever, describe its individual properties. Freq uently used types are: following ones, if ever, describe its individual properties. Freq uently used types are:
disk:'disk_path' for local filesystem objects. disk:'disk_path' for local filesystem objects.
image:'iso_rr_path' for ISO image file objects. image:'iso_rr_path' for ISO image file objects.
cout:'disk_path offset count' for -cut_out files. cout:'disk_path offset count' for -cut_out files.
extf:'filter_name' for external filters. extf:'filter_name' for external filters.
--zisofs:algorithm:block_size for zisofs compression filters.
--zisofs-decode:algorithm:block_size for zisofs uncompression fi
lters.
--gzip for internal gzip compression filters.
--gunzip for internal gzip uncompression filters.
Example: Example:
'/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x' '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
-show_stream_r iso_rr_path [***] -show_stream_r iso_rr_path [***]
Like -show_stream but working recursively. Like -show_stream but working recursively.
Evaluation of readability and recovery: Evaluation of readability and recovery:
It is not uncommon that optical media produce read errors. The reasons ma y be various and get obscured by It is not uncommon that optical media produce read errors. The reasons m ay 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 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 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. fail and the drive is supposed to indicate error.
xorriso can scan a medium for readable data blocks, classify them accordi ng to their read speed, save them xorriso can scan a medium for readable data blocks, classify them accordi ng to their read speed, save them
to a file, and keep track of successfully saved blocks for further tries on the same medium. 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 By command -md5 checksums may get recorded with data files and wh
sessions. These checksums are ole sessions. These checksums are
reachable only via indev and a loaded image. They work independently reachable only via indev and a loaded image. They work independently of
of the media type and can detect the media type and can detect
transmission errors. transmission errors.
-check_media [option [option ...]] -- -check_media [option [option ...]] --
Try to read data blocks from the indev drive, optionally copy them to a disk file, and finally 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. report about the encountered quality. Several options may be used to modify the default behavior.
The parameters given with this command override the default settin gs which may have been changed by The parameters given with this command override the default settin gs which may have been changed by
command -check_media_defaults. See there for a description of avai lable options. command -check_media_defaults. See there for a description of avai lable options.
The result list tells intervals of 2 KiB blocks with start address The result list tells intervals of 2 KiB blocks with start addre
, number of blocks and quality. ss, number of blocks and quality.
Qualities which begin with "+" are supposed to be valid read Qualities which begin with "+" are supposed to be valid readable
able data. Qualities with "-" are data. Qualities with "-" are
unreadable or corrupted data. "0" indicates qualities which are n unreadable or corrupted data. "0" indicates qualities which ar
ot covered by the check run or e not covered by the check run or
are regularly allowed to be unreadable (e.g. gaps between tracks). are regularly allowed to be unreadable (e.g. gaps between tracks).
Alternatively it is possible to report damaged files rather than b locks. Alternatively it is possible to report damaged files rather than b locks.
If -md5 is "on" then the default mode what=tracks looks out for l ibisofs checksum tags for the ISO If -md5 is "on" then the default mode what=tracks looks out for li bisofs checksum tags for the ISO
session data and checks them against the checksums computed from t he data stream. session data and checks them against the checksums computed from t he data stream.
-check_media_defaults [option [option ...]] -- -check_media_defaults [option [option ...]] --
Preset options for runs of -check_media, -extract_cut and best_e Preset options for runs of -check_media, -extract_cut and bes
ffort file extraction. Options t_effort file extraction. Options
given with -check_media will override the preset options. -extra given with -check_media will override the preset options. -extract
ct_cut will override some options _cut will override some options
automatically. automatically.
An option consists of a keyword, a "=" character, and a value. Opt ions may override each other. So An option consists of a keyword, a "=" character, and a value. Op tions may override each other. So
their sequence matters. their sequence matters.
The default setting at program start is: The default setting at program start is:
use=indev what=tracks min_lba=-1 max_lba=-1 retry=default use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
time_limit=28800 item_limit=100000 data_to='' event=ALL time_limit=28800 item_limit=100000 data_to='' event=ALL
abort_file=/var/opt/xorriso/do_abort_check_media abort_file=/var/opt/xorriso/do_abort_check_media
sector_map='' map_with_volid=off patch_lba0=off report=blocks sector_map='' map_with_volid=off patch_lba0=off report=blocks
bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0 bad_limit=invalid slow_limit=1.0 chunk_size=0s async_chunks=0
Option "reset=now" restores these startup defaults. Option "reset=now" restores these startup defaults.
Non-default options are: Non-default options are:
report="files" lists the files which use damaged blocks (not with report="files" lists the files which use damaged blocks (not with
use=outdev). The format is like use=outdev). The format is like
with find -exec report_damage. Note that a MD5 session mismatch m with find -exec report_damage. Note that a MD5 session mismatch
arks all files of the session as marks all files of the session as
damaged. If finer distinction is desired, perform -md5 off before -check_media. damaged. If finer distinction is desired, perform -md5 off before -check_media.
report="blocks_files" first lists damaged blocks and then affected files. report="blocks_files" first lists damaged blocks and then affected files.
use="outdev" reads from the output drive instead of the input d rive. This avoids loading the ISO use="outdev" reads from the output drive instead of the input driv e. This avoids loading the ISO
image tree from media. image tree from media.
use="sector_map" does not read any media but loads the file gi ven by option sector_map= and use="sector_map" does not read any media but loads the fil e given by option sector_map= and
processes this virtual outcome. processes this virtual outcome.
what="disc" scans the payload range of a medium without respecting track gaps. what="disc" scans the payload range of a medium without respecting track gaps.
what="image" similar to "disc", but restricts scanning to th e range of the ISO 9660 image, if what="image" similar to "disc", but restricts scanning to the rang e of the ISO 9660 image, if
present. present.
min_lba=limit omits all blocks with addresses lower than limit. min_lba=limit omits all blocks with addresses lower than limit.
max_lba=limit switches to what=disc and omits all blocks above lim it. max_lba=limit switches to what=disc and omits all blocks above lim it.
chunk_size=size sets the number of bytes to be read in one low-lev el read operation. This gets 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. rounded down to full blocks of 2048 bytes. 0 means automatic size.
retry="on" forces read retries with minimal senseful chunk size wh en the normal read chunk produces retry="on" forces read retries with minimal senseful chunk size wh en the normal read chunk produces
a read error. This size is 1s with CD and stdio files, 16s with DV a read error. This size is 1s with CD and stdio files, 16s with D
D (1 ECC Block), and 32s with BD VD (1 ECC Block), and 32s with BD
(1 Cluster). By default, retries are only enabled with CD media (1 Cluster). By default, retries are only enabled with CD media.
. "retry=off" forbits retries for "retry=off" forbits retries for
all media types. all media types.
abort_file=disk_path gives the path of the file which may abort a scan run. Abort happens if the 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 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 trigger this. Other than an aborted program run, this will repo rt the tested and untested blocks
and go on with running xorriso. and go on with running xorriso.
time_limit=seconds gives the number of seconds after which t time_limit=seconds gives the number of seconds after which the sc
he scan shall be aborted. This is an shall be aborted. This is
useful for unattended scanning of media which may else overwork th useful for unattended scanning of media which may else overwork t
e drive in its effort to squeeze he drive in its effort to squeeze
out some readable blocks. Abort may be delayed by the driv out some readable blocks. Abort may be delayed by the drive gna
e gnawing on the last single read wing on the last single read
operation. Value -1 means unlimited time. operation. Value -1 means unlimited time.
item_limit=number gives the number of report list items after whi ch to abort. Value -1 means item_limit=number gives the number of report list items afte r which to abort. Value -1 means
unlimited item number. unlimited item number.
data_to=disk_path copies the valid blocks to the given file. data_to=disk_path copies the valid blocks to the given file, whi
event=severity sets the given severity for a problem event whic ch must support random access
h shall be issued at the end of a writing, unless disk_path is "-" which means standard output.
check run if data blocks were unreadable or failed to match record In the latter case, patch_lba0= settings other than "off" yield f
ed MD5 checksums. Severity "ALL" ailure. Further the usual result
messages of -check_media get redirected to the info channel. But b
eware of result messages from
other commands. Beware of -*dev "-" which redirect standard outpu
t to standard error. Keep the run
simple:
xorriso -indev /dev/sr0 -check_media data_to=- -- | md5sum
xorriso -outdev /dev/sr0 -check_media data_to=- use=outdev \
what=disc min_lba=0 max_lba=999999 -- | sha256sum
event=severity sets the given severity for a problem event which s
hall be issued at the end of a
check run if data blocks were unreadable or failed to match recor
ded MD5 checksums. Severity "ALL"
disables this event. disables this event.
sector_map=disk_path tries to read the file given by disk_path as sector bitmap and to store such a 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 b een read successfully in previous map file after the scan run. The bitmap tells which blocks have b een read successfully in previous
runs. It is the persistent memory for several scans on the sa runs. It is the persistent memory for several scans on the same
me medium, even with intermediate medium, even with intermediate
eject, in order to collect readable blocks whenever the drive is l eject, in order to collect readable blocks whenever the drive is
ucky enough to produce them. The lucky enough to produce them. The
stored file contains a human readable TOC of tracks and their s stored file contains a human readable TOC of tracks and their star
tart block addresses, followed by t block addresses, followed by
binary bitmap data. binary bitmap data.
By default, untested blocks are not considered bad, but rather as intentionally unread. If you By default, untested blocks are not considered bad, but rathe r as intentionally unread. If you
expect time_limit= or item_limit= to abort the run, then consider to use bad_limit="untested". 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 map_with_volid="on" examines tracks whether they are ISO images an d prints their volume IDs into
the human readable TOC of sector_map=. the human readable TOC of sector_map=.
patch_lba0="on" transfers within the data_to= file a copy of the c patch_lba0="on" transfers within the data_to= file a copy of the
urrently loaded session head to currently loaded session head to
the start of that file and patches it to be valid at that positio the start of that file and patches it to be valid at that position
n. This makes the loaded session . This makes the loaded session
the last valid session of the image file when it gets mounted or the last valid session of the image file when it gets mount
loaded as stdio: drive. New ed or loaded as stdio: drive. New
sessions will be appended after this last session and will sessions will be appended after this last session and will over
overwrite any sessions which have write any sessions which have
followed it. followed it.
patch_lba0="force" performs patch_lba0="on" even if xorriso believ es that the copied data are not patch_lba0="force" performs patch_lba0="on" even if xorriso beli eves that the copied data are not
valid. valid.
patch_lba0= may also bear a number. If it is 32 or higher it patch_lba0= may also bear a number. If it is 32 or higher it is t
is taken as start address of the aken as start address of the
session to be copied. In this case it is not necessary to have a session to be copied. In this case it is not necessary to h
n -indev and a loaded image. ave an -indev and a loaded image.
":force" may be appended after the number. ":force" may be appended after the number.
bad_limit=threshold sets the highest quality which shall be con bad_limit=threshold sets the highest quality which shall be consid
sidered as damage. Choose one of ered as damage. Choose one of
"good", "md5_match", "slow", "partial", "valid", "untested", "md5_ "good", "md5_match", "slow", "partial", "valid", "untested", "md5
mismatch", "invalid", "tao_end", _mismatch", "invalid", "tao_end",
"off_track", "unreadable". "off_track", "unreadable".
"valid" and "invalid" are qualities imported from a sector_map fil e. "tao_end" and "off_track" are "valid" and "invalid" are qualities imported from a sector_map fil e. "tao_end" and "off_track" are
intentionally not readable, but not bad either. "partial" are blo cks retrieved from a partially 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 suspici ous neighborhood. readable chunk. They are supposed to be ok but stem from a suspici ous neighborhood.
"md5_match" and "md5_mismatch" regions overlap with regions o "md5_match" and "md5_mismatch" regions overlap with regions of oth
f other quality. The former is a er quality. The former is a
strong confirmation for quality, the latter only tells that one or strong confirmation for quality, the latter only tells that one
more blocks of the region must or more blocks of the region must
be wrong. be wrong.
By default bad_limit is set higher than md5_mismatch, so that mis By default bad_limit is set higher than md5_mismatch, so that mism
matches are classified as quality atches are classified as quality
class "0" rather than "-". This means that the sectors of a MD5 mi class "0" rather than "-". This means that the sectors of a MD5 m
smatch range are recorded in the ismatch range are recorded in the
sector_map as successfully read, if the drive handed them out at sector_map as successfully read, if the drive handed them out at a
all. Set "bad_limit=md5_mismatch" ll. Set "bad_limit=md5_mismatch"
to let the sector_map record the whole mismatching range as yet no t retrieved. to let the sector_map record the whole mismatching range as yet no t retrieved.
slow_limit=threshold sets the time threshold for a single read chu nk to be considered slow. This 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. 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 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: given number of read chunks is allocated as fifo buffer. On very fast MMC drives try:
chunk_size=64s async_chunks=16. chunk_size=64s async_chunks=16.
-check_md5 severity iso_rr_path [***] -check_md5 severity iso_rr_path [***]
Compare the data content of the given files in the loaded image w Compare the data content of the given files in the loaded image wi
ith their recorded MD5 checksums, th their recorded MD5 checksums,
if there are any. In case of any mismatch an event of the given se if there are any. In case of any mismatch an event of the given s
verity is issued. It may then be everity is issued. It may then be
handled by appropriate settings of commands -abort_on or -return_w ith which both can cause non-zero handled by appropriate settings of commands -abort_on or -return_w ith which both can cause non-zero
exit values of the program run. Severity ALL suppresses that event . exit values of the program run. Severity ALL suppresses that event .
This command reports match and mismatch of data files to the resul t channel. Non-data files cause This command reports match and mismatch of data files to the resu lt channel. Non-data files cause
NOTE events. There will also be UPDATE events from data reading. NOTE events. There will also be UPDATE events from data reading.
If no iso_rr_path is given then the whole loaded session is co mpared with its MD5 sum. Be aware If no iso_rr_path is given then the whole loaded session is compar ed with its MD5 sum. Be aware
that this covers only one session and not the whole image if there are older sessions. that this covers only one session and not the whole image if there are older sessions.
-check_md5_r severity iso_rr_path [***] -check_md5_r severity iso_rr_path [***]
Like -check_md5 but checking all data files underneath the given paths. Only mismatching data Like -check_md5 but checking all data files underneath the gi ven paths. Only mismatching data
files will be reported. files will be reported.
osirrox ISO-to-disk restore commands: osirrox ISO-to-disk restore commands:
Normally xorriso only writes to disk files which were given as stdio: ps Normally xorriso only writes to disk files which were given as stdio: pse
eudo-drives or as log files. But udo-drives or as log files. But
its alter ego osirrox is able to extract file objects from ISO images and its alter ego osirrox is able to extract file objects from ISO images an
to create, overwrite, or delete d to create, overwrite, or delete
file objects on disk. file objects on disk.
Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply. If dis Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply. If disk f
k file objects already exist then ile objects already exist then
the settings of -overwrite and -reassure apply. But -overwrite "on" the settings of -overwrite and -reassure apply. But -overwrite "
only triggers the behavior of on" only triggers the behavior of
-overwrite "nondir". I.e. directories cannot be deleted. -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 Access permissions of files in the ISO image do not restrict restoring. The directory permissions on disk
have to allow rwx. have to allow rwx.
-osirrox setting[:option:...] -osirrox setting[:option:...]
Setting "off" disables disk filesystem manipulations. This is the Setting off disables disk filesystem manipulations. This is t
default unless the program was he default unless the program was
started with leafname "osirrox". Elsewise the capability to restor started with leafname osirrox. Elsewise the capability to restore
e files can be enabled explicitly files can be enabled explicitly
by -osirrox "on". It can be irrevocably disabled by -osirrox "ban by -osirrox on. It can be irrevocably disabled by -osirrox banned
ned". .
The setting "blocked" is like "off". But it can only be revoke The setting blocked is like off. But it can only be revoked by s
d by setting "unblock", which etting unblock, which elsewise is
elsewise is like "on". This can be used to curb command scripts wh like on. This can be used to curb command scripts which might use
ich might use "on" undesiredly. on undesiredly.
To enable restoring of special files by "device_files" is poten To enable restoring of special files by device_files is potentiall
tially dangerous. The meaning of y dangerous. The meaning of the
the number st_rdev (see man 2 stat) depends much on the operating number st_rdev (see man 2 stat) depends much on the operating
system. Best is to restore device system. Best is to restore device
files only to the same system from where they were copied. If not files only to the same system from where they were copied. If not
enabled, device files in the ISO enabled, device files in the ISO
image are ignored during restore operations. image are ignored during restore operations.
Due to a bug of previous versions, device files from previous sess ions might have been altered to Due to a bug of previous versions, device files from previous se ssions might have been altered to
major=0, minor=1. So this combination does not get restored. major=0, minor=1. So this combination does not get restored.
Option "concat_split_on" is default. It enables restoring of spl Option concat_split_on is default. It enables restoring of split f
it file directories as data files ile directories as data files if
if the directory contains a complete collection of -cut_ou the directory contains a complete collection of -cut_out part fi
t part files. With option les. With option concat_split_off
"concat_split_off" such directories are handled like any other ISO such directories are handled like any other ISO image directory.
image directory. Option auto_chmod_off is default. If auto_chmod_on is set then
Option "auto_chmod_off" is default. If "auto_chmod_on" is set access restrictions for disk
then access restrictions for disk
directories get circumvented if those directories are owned by the effective user who runs xorriso. 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. This happens by temporarily granting rwx permission to the owner.
Option "sort_lba_on" may improve read performance with optical dri ves. It can restore large numbers Option sort_lba_on may improve read performance with optical drive s. It can restore large numbers
of hard links without exhausting -temp_mem_limit. It does not pres erve directory mtime and it needs of hard links without exhausting -temp_mem_limit. It does not pres erve directory mtime and it needs
-osirrox option auto_chmod_on in order to extract directories -osirrox option auto_chmod_on in order to extract directories whi
which offer no write permission. ch offer no write permission.
Default is "sort_lba_off". Default is sort_lba_off.
Option "o_excl_on" is the default unless the program was starte Option o_excl_on is the default unless the program was st
d with leafname "osirrox". On arted with leafname "osirrox". On
GNU/Linux it tries to avoid using drives which are mounted or GNU/Linux it tries to avoid using drives which are mounted or in u
in use by other libburn programs. se by other libburn programs.
Option "o_excl_off" on GNU/Linux enables access to such drives by Option o_excl_off on GNU/Linux enables access to such drives b
the equivalent of -drive_access y the equivalent of -drive_access
"shared:readonly". I.e. drives which get acquired while "o_excl "shared:readonly". I.e. drives which get acquired while o_excl_off
_off" will refuse to get blanked, will refuse to get blanked,
formatted, written, or ejected. But be aware that even harmless in formatted, written, or ejected. But be aware that even harmless
quiries can spoil ongoing burns inquiries can spoil ongoing burns
of CD-R[W] and DVD-R[W]. of CD-R[W] and DVD-R[W].
Option "strict_acl_off" is default. It tolerates on FreeBSD th Option strict_acl_off is default. It tolerates on FreeBSD the pres
e presence of directory "default" ence of directory "default" ACLs
ACLs in the ISO image. With "strict_acl_on" these GNU/Linux ACLs c in the ISO image. With strict_acl_on these GNU/Linux ACLs cause
ause on FreeBSD a FAILURE event on FreeBSD a FAILURE event during
during restore with -acl "on". restore with -acl "on".
Option check_md5_off disables MD5 checking during copy to disk. T
he default option check_md5_on
enables it if -md5 is "on". If a data file with recorded MD5
is copied as a whole to the disk
filesystem, then the MD5 of the copied content gets computed and c
ompared with the recorded MD5. A
mismatch causes an error message of severity SORRY. Option check_
md5_force causes an error message
if -md5 is "on" but no MD5 is recorded for the data file.
Option sparse= controls production of sparse files during extr
action of files from the ISO
filesystem. Default is sparse=off.
A positive number like in sparse=1m sets the minimum requiremen
t for the length of a sequence of
0-bytes which shall be represented by a gap. This saves disk spac
e if the disk filesystem supports
sparse files. A gap gets created by help of lseek(2) if a sequen
ce of read buffers, which contain
only 0-bytes, bears at least the minimum amount of bytes. Expect r
ead buffers to be in the size
range of 32k or 64k.
Command -paste_in creates gaps only if the writing begins at or a
fter the end of the existing disk
file. So the sequence of -paste_in commands matters. Command -con
cat does not create sparse files.
-extract iso_rr_path disk_path -extract iso_rr_path disk_path
Copy the file objects at and underneath iso_rr_path to the ir corresponding addresses at and 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. 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 direc If iso_rr_path is a directory and disk_path is an existing
tory then both trees will be directory then both trees will be
merged. Directory attributes get extracted only if the disk direc merged. Directory attributes get extracted only if the disk direct
tory is newly created by the copy ory is newly created by the copy
operation. Disk files get removed only if they are to be replaced operation. Disk files get removed only if they are to be repl
by file objects from the ISO aced by file objects from the ISO
image. image.
As many attributes as possible are copied together with restored f ile objects. As many attributes as possible are copied together with restored f ile objects.
-extract_single iso_rr_path disk_path -extract_single iso_rr_path disk_path
Like -extract, but if iso_rr_path is a directory then its sub tree gets not restored. 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 [***] -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 Perform -extract with each of the iso_rr_path parameters. di sk_path will be composed from
iso_rr_path by replacing iso_rr_prefix by disk_prefix. iso_rr_path by replacing iso_rr_prefix by disk_prefix.
-extract_cut iso_rr_path byte_offset byte_count disk_path -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 n ewly created disk file. The main Copy a byte interval from a data file out of an ISO image into a n ewly created disk file. The main
purpose for this is to offer a way of handling large files if t hey are not supported by mount -t 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. 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 imag If the data bytes of iso_rr_path are stored in the loaded ISO ima
e, and no filter is applied, and ge, and no filter is applied, and
byte_offset is a multiple of 2048, then a special run of -ch byte_offset is a multiple of 2048, then a special run of -check_m
eck_media is performed. It may be edia is performed. It may be
quicker and more rugged than the general reading method. quicker and more rugged than the general reading method.
-cpx iso_rr_path [***] disk_path -cpx iso_rr_path [***] disk_path
Copy single leaf file objects from the ISO image to the address gi Copy single leaf file objects from the ISO image to the address
ven by disk_path. If more then given by disk_path. If more then
one iso_rr_path is given then disk_path must be a directory or no one iso_rr_path is given then disk_path must be a directory or non
n-existent. In the latter case it -existent. In the latter case it
gets created and the extracted files get installed in it with the same leafnames. gets created and the extracted files get installed in it with the same leafnames.
Missing directory components in disk_path will get created, if pos sible. Missing directory components in disk_path will get created, if pos sible.
Directories are allowed as iso_rr_path only with -osirrox "conc at_split_on" and only if they 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 pa rts. actually represent a complete collection of -cut_out split file pa rts.
-cpax iso_rr_path [***] disk_path -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 Like -cpx but restoring mtime, atime as in ISO image and trying to set ownership and group as in
ISO image. ISO image.
-cp_rx iso_rr_path [***] disk_path -cp_rx iso_rr_path [***] disk_path
Like -cpx but also extracting whole directory trees from the ISO i mage. Like -cpx but also extracting whole directory trees from the ISO i mage.
The resulting disk paths are determined as with shell command cp - The resulting disk paths are determined as with shell command cp
r : If disk_path is an existing -r : If disk_path is an existing
directory then the trees will be inserted or merged underneath t directory then the trees will be inserted or merged underneath thi
his directory and will keep their s directory and will keep their
leaf names. The ISO directory "/" has no leaf name and thus gets m apped directly to disk_path. leaf names. The ISO directory "/" has no leaf name and thus gets m apped directly to disk_path.
-cp_rax iso_rr_path [***] 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 Like -cp_rx but restoring mtime, atime as in ISO image and trying to set ownership and group as in
ISO image. ISO image.
-paste_in iso_rr_path disk_path byte_offset byte_count -paste_in iso_rr_path disk_path byte_offset byte_count
Read the content of a ISO data file and write it into a d ata file on disk beginning at the Read the content of a ISO data file and write it into a data f ile on disk beginning at the
byte_offset. Write at most byte_count bytes. This is the inverse of command -cut_out. 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 [***] -concat mode [target | lim prog [args [...]] lim] iso_rr_path [***]
Copy the data content of one or more data files of the ISO image i Copy the data content of one or more data files of the ISO imag
nto a disk file object, into a e into a disk file object, into a
file descriptor, or start a program and copy the data into i file descriptor, or start a program and copy the data into its s
ts standard input. The latter is tandard input. The latter is
subject to the security restrictions for external filters. subject to the security restrictions for external filters.
Modes overwrite and append write into the target which is given by Modes overwrite and append write into the target which is given
the second parameter. This may by the second parameter. This may
be the path to a disk file object, or "-" which means stand be the path to a disk file object, or "-" which means standard ou
ard output, or a text of the form tput, or a text of the form
/dev/fd/number, where number is an open file descriptor (e.g. stan /dev/fd/number, where number is an open file descriptor (e.g.
dard error is /dev/fd/2). An standard error is /dev/fd/2). An
existing target file is not removed before writing begins. If it existing target file is not removed before writing begins. If it i
is not able to take content data, s not able to take content data,
then this command fails. Mode overwrite truncates regular data fi les to 0 size before writing into then this command fails. Mode overwrite truncates regular data fi les to 0 size before writing into
them. Example: them. Example:
-concat append /home/me/accumulated_text /my/iso/text -- -concat append /home/me/accumulated_text /my/iso/text --
Mode pipe expects as second parameter a delimiter word which Mode pipe expects as second parameter a delimiter word which shall
shall mark the end of the program mark the end of the program
argument list. The third argument is the disk_path to the program. argument list. The third argument is the disk_path to the prog
It must contain at least one ram. It must contain at least one
'/'. $PATH is not applied. Further parameters up to the ann '/'. $PATH is not applied. Further parameters up to the announce
ounced delimiter word are used as d delimiter word are used as
arguments with the program start. Example: arguments with the program start. Example:
-iso_rr_pattern on \ -iso_rr_pattern on \
-concat pipe + /usr/bin/wc + "/my/iso/files*" -- -concat pipe + /usr/bin/wc + "/my/iso/files*" --
The further parameters in all modes are the iso_rr_paths of da ta files. Their content gets The further parameters in all modes are the iso_rr_paths o f data files. Their content gets
concatenated in the copy. concatenated in the copy.
-extract_boot_images disk_path
Copy boot equipment to disk, which is not necessarily represent
ed as data files in the ISO
filesystem. The data get written into various files in a disk dire
ctory, which may already exist or
of which the parent must exist so that it can get created.
Files may be missing if their corresponding information is not p
resent in the ISO filesystem.
Existing files do not get overwritten but rather cause a failure e
vent.
The same data may appear in different files. E.g. the El Torit
o boot image for EFI is often the
same data as the EFI partition in MBR or GPT.
File "eltorito_catalog.img" contains the El Torito Boot Catalog.
Files "eltorito_img*_*.img" contain El Torito Boot images. The fir
st "*" gives the image number,
the second "*" gives the type: "bios", "mac", "ppc", "uefi", or a
hex number.
File "mbr_code_isohybrid.img" contains the ISOLINUX MBR template.
File "mbr_code_grub2.img" contains the GRUB2 MBR template.
File "systemarea.img" contains the whole 32 KiB of System Area if
not all zero.
Files "mbr_part*_efi.img" contain EFI partition images from the
MBR partition table. The "*" text
part gives the partition number.
Files "mbr_part*_prep.img" contain PReP partition images.
Files "gpt_part*_efi.img" contain EFI partition images from GPT.
Files "gpt_part*_hfsplus.img" contain HFS+ partition images from
GPT. To avoid extracting the
whole HFS+ aspect of hybrid ISO filesystems, the partition image
is extracted only if it has less
than half of the size of the ISO filesystem or if the partition is
outside the ISO filesystem.
-mount drive entity id path -mount drive entity id path
Produce the same line as -mount_cmd and then execute it as externa l program run after giving up the Produce the same line as -mount_cmd and then execute it as externa l program run after giving up the
depicted drive. See also -mount_opts. This demands -osirrox to depicted drive. See also -mount_opts. This demands -osirro
be enabled and normally will x to be enabled and normally will
succeed only for the superuser. For safety reasons the mount succeed only for the superuser. For safety reasons the mount progr
program is only executed if it is am is only executed if it is
reachable as /bin/mount or /sbin/mount. reachable as /bin/mount or /sbin/mount.
Command compatibility emulations: Command compatibility emulations:
Writing of ISO 9660 on CD is traditionally done by program mkisofs as ISO 9660 image producer and cdrecord 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 emulat as burn program. xorriso does not strive for their comprehensive emulati
ion. Nevertheless it is ready to on. Nevertheless it is ready to
perform some of its core tasks under control of commands which in sa perform some of its core tasks under control of commands which in
id programs trigger comparable said programs trigger comparable
actions. actions.
-as personality option [options] -- -as personality option [options] --
Perform the variable length option list as sparse emulatio n of the program depicted by the Perform the variable length option list as sparse emulation of the program depicted by the
personality word. personality word.
Personality "mkisofs" accepts the options listed with: Personality "mkisofs" accepts the options listed with:
-as mkisofs -help -- -as mkisofs -help --
Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mod e, -file-mode, -path-list, -m, Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mod e, -file-mode, -path-list, -m,
-exclude-list, -f, -print-size, -pad, -no-pad, -V, -v, -version, -exclude-list, -f, -print-size, -pad, -no-pad, -V, -v, -version, -
-graft-points, -z, -no-emul-boot, graft-points, -z, -no-emul-boot,
-b, -c, -boot-info-table, -boot-load-size, -input-charset, -G -b, -c, -boot-info-table, -boot-load-size, -input-charset, -
, -output-charset, -U, -hide, G, -output-charset, -U, -hide,
-hide-joliet, -hide-list, -hide-joliet-list, file paths and pat -hide-joliet, -hide-list, -hide-joliet-list, file paths and pathsp
hspecs. A lot of options are not ecs. A lot of options are not
supported and lead to failure of the mkisofs emulation. Some are i gnored, but better do not rely on supported and lead to failure of the mkisofs emulation. Some are i gnored, but better do not rely on
this tolerance. this tolerance.
The supported options are documented in detail in xorrisof s.info and in man xorrisofs. The The supported options are documented in detail in xorrisofs.in fo and in man xorrisofs. The
description here is focused on the effect of mkisofs emulation in the context of a xorriso run. 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 - Other than with the "cdrecord" personality there is no automatic
commit at the end of a "mkisofs" -commit at the end of a "mkisofs"
option list. Verbosity settings -v (= "UPDATE") and -quiet (= option list. Verbosity settings -v (= "UPDATE") and -quiet (= "SOR
"SORRY") persist. The output file RY") persist. The output file
persists until things happen like -commit, -rollback, -dev, or end of xorriso. 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 Options which affect all file objects in the ISO image, like -r o
-dir-mode, will be applied only r -dir-mode, will be applied only
to files which are present in the ISO image when the command to files which are present in the ISO image when the command -as
-as ends. If you use several -as ends. If you use several -as
mkisofs commands in the same run, then consider to put such option s into the last -as command. mkisofs commands in the same run, then consider to put such option s into the last -as command.
If files are added to the image, then -pacifier gets set to "mkiso fs" and -stdio_sync is defaulted If files are added to the image, then -pacifier gets set to "mkis ofs" and -stdio_sync is defaulted
to "off" if no such setting was made yet. to "off" if no such setting was made yet.
-graft-points is equivalent to -pathspecs on. Note that path -graft-points is equivalent to -pathspecs on. Note that pathspec
specs without "=" are interpreted s without "=" are interpreted
differently than with xorriso command -add. Directories get merge differently than with xorriso command -add. Directories get merg
d with the root directory of the ed with the root directory of the
ISO image, other filetypes get mapped into that root directory. 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, 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 po then standard output (-outdev "-") will get into effect. If -o
ints to a regular file, then it points to a regular file, then it
will be truncated to 0 bytes when finally writing begins. This will be truncated to 0 bytes when finally writing begins. This tru
truncation does not happen if the ncation does not happen if the
drive is chosen by xorriso commands before -as mkisofs or after it s list delimiter. Directories and drive is chosen by xorriso commands before -as mkisofs or after it s list delimiter. Directories and
symbolic links are no valid -o targets. 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 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. arguments pointed the output drive to standard output.
-print-size inhibits automatic image production at program end. Th is ban is lifted only if the -print-size inhibits automatic image production at program en d. This ban is lifted only if the
pending image changes get discarded. pending image changes get discarded.
Padding is counted as part of the ISO image if not option --emul-t oc is given. Padding is counted as part of the ISO image if not option --emul-t oc is given.
If no -iso-level is given, then level 1 is chosen when the first If no -iso-level is given, then level 1 is chosen when the first f
file or directory is added to the ile or directory is added to the
image. At the same occasion directory names get allowed to violat image. At the same occasion directory names get allowed to vi
e the standard by -compliance olate the standard by -compliance
option allow_dir_id_ext. This may be avoided by option -disallow_ dir_id_ext. 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 xo Option -root is supported. Option -old-root is implemented by xorr
rriso commands -mkdir, -cp_clone, iso commands -mkdir, -cp_clone,
-find update_merge, and -find rm_merge. -root and -old-root -find update_merge, and -find rm_merge. -root and -old-roo
set command -disk_dev_ino to t 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 "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-r oot-no-md5 . to "on" by --old-root-devno . -md5 can be set to "off" by --old-r oot-no-md5 .
Not original mkisofs options are --quoted_path_list , --hardlinks Not original mkisofs options are --quoted_path_list , --hard
, --acl , --xattr , --md5 , links , --acl , --xattr , --md5 ,
--stdio_sync . They work like the xorriso commands with the --stdio_sync . They work like the xorriso commands with the same
same name and hardcoded parameter name and hardcoded parameter
"on", e.g. -acl "on". Explicit parameters are expected by --stdio _sync and --scdbackup_tag. "on", e.g. -acl "on". Explicit parameters are expected by --stdio _sync and --scdbackup_tag.
The capability to preserve multi-session history on overwriteable The capability to preserve multi-session history on overwritable m
media gets disabled by default. edia gets disabled by default. It
It can be enabled by using --emul-toc with the first session. See can be enabled by using --emul-toc with the first session. See -co
-compliance no_emul_toc. mpliance no_emul_toc.
--sort-weight gets as parameters a number and an iso_rr_path. T --sort-weight gets as parameters a number and an iso_rr_path. The
he number becomes the LBA sorting number becomes the LBA sorting
weight of regular file iso_rr_path or of all regular files underne weight of regular file iso_rr_path or of all regular files undern
ath directory iso_rr_path. (See eath directory iso_rr_path. (See
-find -exec sort_weight). -find -exec sort_weight).
Adopted from grub-mkisofs are --protective-msdos-label (see -bo ot_image grub partition_table=on) 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 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". 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 pl atform_id for EFI, but performs Alternative option -e from Fedora genisoimage sets bin_path and platform_id for EFI, but performs
no "next". no "next".
For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE, For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE, whe
where FILE is one of the Syslinux re FILE is one of the Syslinux
files mbr/isohdp[fp]x*.bin . Use this instead of -G to apply the files mbr/isohdp[fp]x*.bin . Use this instead of -G to apply t
effect of -boot_image isolinux he effect of -boot_image isolinux
partition_table=on. partition_table=on.
--boot-catalog-hide is -boot_image any cat_hidden=on. --boot-catalog-hide is -boot_image any cat_hidden=on.
-mips-boot is the same as -boot_image any mips_path= . -mips-boot is the same as -boot_image any mips_path= .
-mipsel-boot leads to mipsel_path= . -mipsel-boot leads to mipsel_path= .
-partition_offset number is -boot_image any partition_offset=numbe r. -partition_offset number is -boot_image any partition_offset=numbe r.
Command -append_partition is supported. Command -append_partition is supported.
-untranslated_name_len number is -compliance untranslated_name_len =number. -untranslated_name_len number is -compliance untranslated_name_len =number.
--old-empty is -compliance old_empty. --old-empty is -compliance old_empty.
The options of genisoimage Jigdo Template Extraction are rec ognized and performed via xorriso The options of genisoimage Jigdo Template Extraction are recogni zed and performed via xorriso
command -jigdo. See the "Alias:" names there for the meaning of th e genisoimage options. command -jigdo. See the "Alias:" names there for the meaning of th e genisoimage options.
Personalities "xorrisofs", "genisoimage", and "genisofs" are alias es for "mkisofs". Personalities "xorrisofs", "genisoimage", and "genisofs" are alias es for "mkisofs".
If xorriso is started with one of the leafnames "xorrisof If xorriso is started with one of the leafnames "xorriso
s", "genisofs", "mkisofs", or fs", "genisofs", "mkisofs", or
"genisoimage", then it performs -read_mkisofsrc and prepends "genisoimage", then it performs -read_mkisofsrc and prepends
-as "genisofs" to the program -as "genisofs" to the program
arguments. I.e. all arguments will be interpreted mkisofs style u arguments. I.e. all arguments will be interpreted mkisofs style
ntil "--" is encountered. From until "--" is encountered. From
then on, arguments are interpreted as xorriso commands. then on, arguments are interpreted as xorriso commands.
--no_rc as first argument of such a program start prevents int erpretation of startup files. See --no_rc as first argument of such a program start prevents interpr etation of startup files. See
section FILES below. section FILES below.
Personality "cdrecord" accepts the options listed with: Personality "cdrecord" accepts the options listed with:
-as cdrecord -help -- -as cdrecord -help --
Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsi ze=, tsize=, -isosize, -multi, Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, pa dsize=, tsize=, -isosize, -multi,
-msinfo, --grow_overwriteable_iso, write_start_address=, track sou rce file path or "-" for standard -msinfo, --grow_overwriteable_iso, write_start_address=, track sou rce file path or "-" for standard
input as track source. input as track source.
It ignores most other options of cdrecord and cdrskin but refuses on -audio, -scanbus, and on It ignores most other options of cdrecord and cdrskin but re fuses on -audio, -scanbus, and on
blanking modes unknown to xorriso. blanking modes unknown to xorriso.
The scope is only a single data track per session to be wr itten to blank, overwriteable, or The scope is only a single data track per session to be writt en to blank, overwritable, or
appendable media. The medium gets closed if closing is applicable and not option -multi is present. 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 If an input drive was acquired, then it is given up. This is onl y allowed if no image changes are
pending. pending.
dev= must be given as xorriso device address. Addresses like 0,0,0 or ATA:1,1,0 are not supported. 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 If a track source is given, then an automatic -commit happens at t he end of the "cdrecord" option
list. list.
--grow_overwriteable_iso enables emulation of multi-session on o --grow_overwriteable_iso enables emulation of multi-session o
verwriteable media. To enable n overwritable media. To enable
emulation of a TOC, the first session needs -C 0,32 with emulation of a TOC, the first session needs -C 0,32 with
-as mkisofs (but no -M) and -as mkisofs (but no -M) and
--grow_overwriteable_iso write_start_address=32s with -as cdrecord . --grow_overwriteable_iso write_start_address=32s with -as cdrecord .
A much more elaborate libburn based cdrecord emulator is the progr am cdrskin. A much more elaborate libburn based cdrecord emulator is the progr am cdrskin.
Personalites "xorrecord", "wodim", and "cdrskin" are aliases for " cdrecord". Personalites "xorrecord", "wodim", and "cdrskin" are aliases for " cdrecord".
If xorriso is started with one of the leafnames "xorrecord", "cdr If xorriso is started with one of the leafnames "xorrecord", "
skin", "cdrecord", or "wodim", cdrskin", "cdrecord", or "wodim",
then it automatically prepends -as "cdrskin" to the program argu then it automatically prepends -as "cdrskin" to the program argume
ments. I.e. all arguments will be nts. I.e. all arguments will be
interpreted cdrecord style until "--" is encountered. From then o interpreted cdrecord style until "--" is encountered. From then
n, arguments are interpreted as on, arguments are interpreted as
xorriso commands. xorriso commands.
--no_rc as first argument of such a program start prevents interpr etation of xorriso startup files. --no_rc as first argument of such a program start prevents interpr etation of xorriso startup files.
See section FILES below. See section FILES below.
-read_mkisofsrc -read_mkisofsrc
Try one by one to open for reading: Try one by one to open for reading:
./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc , $(dirname $0)/.mki sofsrc ./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc , $(dirname $0)/.mki sofsrc
On success interpret the file content as of man mkisofs CONFIGURAT ION, and end this command. Do not On success interpret the file content as of man mkisofs CONFIGURAT ION, and end this command. Do not
try further files. The last address is used only if start argumen t 0 has a non-trivial dirname. try further files. The last address is used only if start argumen t 0 has a non-trivial dirname.
The reader currently interprets the following NAME=VALUE pai rs: APPI (-application_id) , PUBL The reader currently interprets the following NAME=VALUE pairs: APPI (-application_id) , PUBL
(-publisher) , SYSI (-system_id) , VOLI (-volid) , VOLS (-volset_i d) (-publisher) , SYSI (-system_id) , VOLI (-volid) , VOLS (-volset_i d)
Any other lines will be silently ignored. Any other lines will be silently ignored.
-pacifier behavior_code -pacifier behavior_code
Control behavior of UPDATE pacifiers during write operations. The following behavior codes are Control behavior of UPDATE pacifiers during write operations. The following behavior codes are
defined: defined:
"xorriso" is the default format: "xorriso" is the default format:
Writing: sector XXXXX of YYYYYY [fifo active, nn% fill] Writing: sector XXXXX of YYYYYY [fifo active, nn% fill]
"cdrecord" looks like: "cdrecord" looks like:
X of Y MB written (fifo nn%) [buf mmm%] X of Y MB written (fifo nn%) [buf mmm%]
"mkisofs" "mkisofs"
nn% done, estimate finish Tue Jul 15 20:13:28 2008 nn% done, estimate finish Tue Jul 15 20:13:28 2008
The frequency of the messages can be adjusted by The frequency of the messages can be adjusted by
"interval=number" "interval=number"
where number gives the seconds between two messages. Permissible s ettings are 0.1 to 60.0. where number gives the seconds between two messages. Permissible s ettings are 0.1 to 60.0.
-scdbackup_tag list_path record_name -scdbackup_tag list_path record_name
Set the parameter "name" for a scdbackup checksum record. It Set the parameter "name" for a scdbackup checksum record. It will
will be appended in an scdbackup be appended in an scdbackup
checksum tag to the -md5 session tag if the image starts at LBA 0. checksum tag to the -md5 session tag if the image starts at L
This is the case if it gets BA 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 written as first session onto a sequential medium, or piped into a program, named pipe or character
device. device.
If list_path is not empty then the record will also be appended to the data file given by this If list_path is not empty then the record will also be append ed to the data file given by this
path. path.
Program scdbackup_verify will recognize and verify tag and file re cord. Program scdbackup_verify will recognize and verify tag and file re cord.
An empty record_name disables this feature. An empty record_name disables this feature.
Scripting, dialog and program control features: Scripting, dialog and program control features:
-no_rc -no_rc
Only if used as first program argument this command prevents read ing and interpretation of startup Only if used as first program argument this command prevents readi ng and interpretation of startup
files. See section FILES below. files. See section FILES below.
-options_from_file fileaddress -options_from_file fileaddress
Read quoted input from fileaddress and execute it like dialog line Read quoted input from fileaddress and execute it like dialog li
s. Empty lines and lines which nes. Empty lines and lines which
begin by # are ignored. Normally one line should hold one xorris begin by # are ignored. Normally one line should hold one xorriso
o command and all its parameters. command and all its parameters.
Nevertheless lines may be concatenated by a trailing backslash. Nevertheless lines may be concatenated by a trailing backslash.
See also section "Command processing", paragraph "Quoted input". See also section "Command processing", paragraph "Quoted input".
-help -help
Print helptext. Print helptext.
-version -version
Print program name and version, component versions, license. Print program name and version, component versions, license.
-list_extras code -list_extras code
Tell whether certain extra features were enabled at compile time. Code "all" lists all features Tell whether certain extra features were enabled at compile tim e. Code "all" lists all features
and a headline. Other codes pick a single feature. Code "codes" lists them. They share names with and a headline. Other codes pick a single feature. Code "codes" lists them. They share names with
related commands (see also there): related commands (see also there):
"acl" tells whether xorriso has an adapter for local filesystems A CLs. "acl" tells whether xorriso has an adapter for local filesystems A CLs.
"xattr" tells whether xorriso has an adapter for local filesystems EA. "xattr" tells whether xorriso has an adapter for local filesystems EA.
"jigdo" tells whether production of Jigdo files is possible. "jigdo" tells whether production of Jigdo files is possible.
"zisofs" tells whether zisofs and built-in gzip filters are enable d. "zisofs" tells whether zisofs and built-in gzip filters are enable d.
"external_filter" tells whether external filter processes are allo wed and whether they are allowed "external_filter" tells whether external filter processes are all owed and whether they are allowed
if real user id and effective user id differ. if real user id and effective user id differ.
"dvd_obs" tells whether 64 kB output to DVD media is default. "dvd_obs" tells whether 64 kB output to DVD media is default.
"use_readline" tells whether readline may be enabled in dialog mod e. "use_readline" tells whether readline may be enabled in dialog mod e.
-history textline -history textline
Copy textline into libreadline history. Copy textline into libreadline history.
-status mode|filter -status mode|filter
Print the current settings of xorriso. Modes: Print the current settings of xorriso. Modes:
short... print only important or altered settings short... print only important or altered settings
long ... print all settings including defaults long ... print all settings including defaults
long_history like long plus history lines long_history like long plus history lines
Filters begin with '-' and are compared literally against the outp ut lines of -status:long_history. Filters begin with '-' and are compared literally against the outp ut lines of -status:long_history.
A line is put out only if its start matches the filter text. No wi ldcards. A line is put out only if its start matches the filter text. No wi ldcards.
-status_history_max number -status_history_max number
Set maximum number of history lines to be reported with -status "l ong_history". Set maximum number of history lines to be reported with -status "l ong_history".
-list_delimiter word -list_delimiter word
Set the list delimiter to be used instead of "--". It has to be a single word, must not be empty, 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 mark s. not longer than 80 characters, and must not contain quotation mark s.
For brevity the list delimiter is referred as "--" throughout this text. For brevity the list delimiter is referred as "--" throughout this text.
-sh_style_result "on"|"off" -sh_style_result "on"|"off"
Make the result output of some filesystem inspection comma Make the result output of some filesystem inspection commands
nds look more like the output of look more like the output of
equivalent shell commands. The most important effect is to prevent equivalent shell commands. The most important effect is to preve
the wrapping of file addresses nt the wrapping of file addresses
into quotation marks with commands into quotation marks with commands
-pwd -pwdx -ls -lsd -lsl -lsdl -lsx -lsdx -lslx -lsdlx -pwd -pwdx -ls -lsd -lsl -lsdl -lsx -lsdx -lslx -lsdlx
-du -dus -dux -dusx -findx -find -du -dus -dux -dusx -findx -find
This will make ambiguous the representation of file names which c This will make ambiguous the representation of file names which co
ontain newline characters. On the ntain newline characters. On the
other hand it should facilitate integration of xorriso into shell other hand it should facilitate integration of xorriso into sh
scripts which already use the ell scripts which already use the
corresponding shell commands. corresponding shell commands.
-backslash_codes "on"|"off"|mode[:mode] -backslash_codes "on"|"off"|mode[:mode]
Enable or disable the interpretation of symbolic representations Enable or disable the interpretation of symbolic representations o
of special characters with quoted f special characters with quoted
input, or with program arguments, or with program text out input, or with program arguments, or with program text ou
put. If enabled the following tput. If enabled the following
translations apply: translations apply:
\a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014) \a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
\n=linefeed(012) \r=carriage_return(015) \t=tab(011) \n=linefeed(012) \r=carriage_return(015) \t=tab(011)
\v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code \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 \x[0-9a-f][0-9a-f]=hex_code \cC=control-C
Translations can occur with quoted input in 3 modes: Translations can occur with quoted input in 3 modes:
"in_double_quotes" translates only inside " quotation. "in_double_quotes" translates only inside " quotation.
"in_quotes" translates inside " and ' quotation. "in_quotes" translates inside " and ' quotation.
"with_quoted_input" translates inside and outside quotes. "with_quoted_input" translates inside and outside quotes.
With the start program arguments there is mode: With the start program arguments there is mode:
"with_program_arguments" translates program arguments. "with_program_arguments" translates program arguments.
Mode "encode_output" encodes output characters. It combines "enc ode_results" with "encode_infos". Mode "encode_output" encodes output characters. It combines "encod e_results" with "encode_infos".
Inside single or double quotation marks encoding applies to 8-bit characters octal 001 to 037 , 177 Inside single or double quotation marks encoding applies to 8-bit characters octal 001 to 037 , 177
to 377 and to backslash(134). Outside quotation marks some harml ess ASCII control characters stay to 377 and to backslash(134). Outside quotation marks some harmle ss ASCII control characters stay
unencoded: bell(007), backspace(010), tab(011), linefeed(012), for mfeed(014), carriage_return(015). unencoded: bell(007), backspace(010), tab(011), linefeed(012), for mfeed(014), carriage_return(015).
Mode "off" is default and disables any trans lation. Mode "on" is Mode "off" is default and disables any tr anslation. Mode "on" is
"with_quoted_input:with_program_arguments:encode_output". "with_quoted_input:with_program_arguments:encode_output".
-temp_mem_limit number["k"|"m"] -temp_mem_limit number["k"|"m"]
Set the maximum size of temporary memory to be used for image de pendent buffering. Currently this Set the maximum size of temporary memory to be used for image depe ndent buffering. Currently this
applies to pattern expansion, LBA sorting, restoring of hard links . applies to pattern expansion, LBA sorting, restoring of hard links .
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 G iB. Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 G iB.
-print text -print text
Print a text line to the result channel which is by default stdout . Print a text line to the result channel which is by default stdout .
-print_info text -print_info text
Print a text line to the info channel which is by default stderr. Print a text line to the info channel which is by default stderr.
-print_mark text -print_mark text
Print a text line to the mark channel which is by default direc ted to both, result and info 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. channel. An empty text will cause no output at all.
-prompt text -prompt text
Show text at beginning of output line and wait for the user to hi t the Enter key or to send a line Show text at beginning of output line and wait for the user to hit the Enter key or to send a line
via stdin. via stdin.
-sleep seconds -sleep seconds
Wait for the given number of seconds before performing the next co mmand. Expect coarse granularity Wait for the given number of seconds before performing the next co mmand. Expect coarse granularity
no better than 1/100 seconds. no better than 1/100 seconds.
-errfile_log mode path|channel -errfile_log mode path|channel
If problem events are related to input files from the filesys tem, then their disk_paths can be 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. logged to a file or to output channels R or I.
Mode can either be "plain" or "marked". The latter causes marker l ines which give the time of log 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 en d. In mode "plain", only the file start, burn session start, burn session end, log end or program en d. In mode "plain", only the file
paths are logged. paths are logged.
If path is "-" or "-R" then the log is directed to the result chan nel. Path "-I" directs it to the If path is "-" or "-R" then the log is directed to the result chan nel. 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 info message channel. Any text that does not begin with "-" is use d as path for a file to append
the log lines. the log lines.
Problematic files can be recorded multiple times during one progra m run. If the program run aborts Problematic files can be recorded multiple times during one progra m run. If the program run aborts
then the list might not be complete because some input files might not have been processed at all. 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 se verity "ERRFILE". This transport The errfile paths are transported as messages of very low sever ity "ERRFILE". This transport
becomes visible with -report_about "ALL". becomes visible with -report_about "ALL".
-session_log path -session_log path
If path is not empty it gives the address of a plain text file whe If path is not empty it gives the address of a plain text file
re a log record gets appended where a log record gets appended
after each session. This log can be used to determine the start_l after each session. This log can be used to determine the start_lb
ba of a session for mount options a of a session for mount options
-o sbsector= (on GNU/Linux) or -s (on FreeBSD) from date or volume ID. -o sbsector= (on GNU/Linux) or -s (on FreeBSD) from date or volume ID.
Record format is: timestamp start_lba size volume-id Record format is: timestamp start_lba size volume-id
The first three items are single words, the rest of the line is th e volume ID. The first three items are single words, the rest of the line is th e volume ID.
-scsi_log "on"|"off" -scsi_log "on"|"off"
Mode "on" enables very verbose logging of SCSI commands and drive replies. Logging messages get Mode "on" enables very verbose logging of SCSI commands and dri ve replies. Logging messages get
printed to stderr, not to any of the xorriso output channels. printed to stderr, not to any of the xorriso output channels.
A special property of this command is that the first -scsi_log set ting among the start arguments is A special property of this command is that the first -scsi_log set ting among the start arguments is
in effect already when the first operations of xorriso begin. Onl y "-scsi_log" with dash "-" is in effect already when the first operations of xorriso begin. Only "-scsi_log" with dash "-" is
recognized that way. recognized that way.
-end -end
End program after writing pending changes. End program after writing pending changes.
-rollback_end -rollback_end
Discard pending changes. End program immediately. Discard pending changes. End program immediately.
# any text # any text
Only in dialog or file execution mode, and only as first non-white space in line: Do not execute the Only in dialog or file execution mode, and only as first non-white space in line: Do not execute the
line but store it in readline history. line but store it in readline history.
Support for frontend programs via stdin and stdout: Support for frontend programs via stdin and stdout:
-pkt_output "on"|"off" -pkt_output "on"|"off"
Consolidate text output on stdout and classify each line by a chan nel indicator: Consolidate text output on stdout and classify each line by a chan nel indicator:
'R:' for result lines, 'R:' for result lines,
'I:' for notes and error messages, 'I:' for notes and error messages,
'M:' for -mark texts. 'M:' for -mark texts.
Next is a decimal number of which only bit 0 has a meaning for now Next is a decimal number of which only bit 0 has a meaning for n
. 0 means no newline at end of ow. 0 means no newline at end of
payload, 1 means that the newline character at the end of the ou payload, 1 means that the newline character at the end of the outp
tput line belongs to the payload. ut line belongs to the payload.
After another colon and a blank follows the payload text. After another colon and a blank follows the payload text.
Example: Example:
I:1: enter option and parameters : I:1: enter option and parameters :
-logfile channel fileaddress -logfile channel fileaddress
Copy output of a channel to the given file. Channel may be one of: "." for all channels, "I" for 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. info messages, "R" for result lines, "M" for -mark texts.
-mark text -mark text
If text is not empty it will get put out on "M" channel each t ime xorriso is ready for the next 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. dialog line or before xorriso performs a command that was entered to the pager prompt.
-msg_op opcode parameter_text -msg_op opcode parameter_text
This command shall facilitate extraction of particular information from the message output of other 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_lin commands. It gives access to the C API function Xorriso_parse_line
e() and to the message sieve that () and to the message sieve that
is provided by the C API. Please refer to their descriptions in f is provided by the C API. Please refer to their descriptions in
ile xorriso.h. Further it helps file xorriso.h. Further it helps
to interpret the severity codes of info messages. to interpret the severity codes of info messages.
Intended users are frontend programs which operate xorriso in dial og mode. Intended users are frontend programs which operate xorriso in dial og mode.
The result output of this command is not caught by the message sie ve. The result output of this command is not caught by the message sie ve.
The following opcodes are defined: The following opcodes are defined:
start_sieve start_sieve
Install the message sieve as of Xorriso_sieve_big() and sta rt watching program messages. The Install the message sieve as of Xorriso_sieve_big() and start watching program messages. The
parameter_text has no meaning. parameter_text has no meaning.
show_sieve show_sieve
Show a list of filter rule names. The parameter_text has no meanin g. The list begins by a line Show a list of filter rule names. The parameter_text has no me aning. 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, 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. then the next line tells the number of names. The following lines show one name each.
read_sieve read_sieve
Use the parameter_text as name of a filter rule and inquire i ts next recorded result. See Use the parameter_text as name of a filter rule and inqui re its next recorded result. See
Xorriso_sieve_big() for a list of names and reply strings. Xorriso_sieve_big() for a list of names and reply strings.
The recorded strings are put out on result channel. They get wr The recorded strings are put out on result channel. They get wrapp
apped into lines which tell their ed into lines which tell their
structure. The first line tells the return value of Xorriso_siev structure. The first line tells the return value of Xorriso_s
e_get_result(). The next line ieve_get_result(). The next line
tells the number of strings. Each string begins by a line that tells the number of strings. Each string begins by a line that tel
tells the number of lines of the ls the number of lines of the
string. Then follow these lines. They are to be concatenated with string. Then follow these lines. They are to be concatenated with
a newline character between each a newline character between each
of them. Finally the number of still available recorded results o f the given name is put out. of them. Finally the number of still available recorded results o f the given name is put out.
clear_sieve clear_sieve
Dispose all recorded strings and continue watching program mes sages. The parameter_text has no Dispose all recorded strings and continue watching program message s. The parameter_text has no
meaning. meaning.
end_sieve end_sieve
Dispose the sieve with its filter rules and stop watching program messages. The parameter_text has Dispose the sieve with its filter rules and stop watching program messages. The parameter_text has
no meaning. no meaning.
parse parse
Read a text from dialog input and submit it to Xorriso_parse_line( ). The parameter_text word shall 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 necessar y to use both kinds of quotation consist of several words separated by blanks. It will be necessa ry to use both kinds of quotation
marks. marks.
E.g. "'ISO session :' '' 0 0 1" E.g. "'ISO session :' '' 0 0 1"
The five parameter words are: prefix, separators, max_words, The five parameter words are: prefix, separators, max_words, fl
flag, number_of_input_lines. The ag, number_of_input_lines. The
former four are handed over to Xorriso_parse_line(). The number of former four are handed over to Xorriso_parse_line(). The numb
input lines minus one tells er of input lines minus one tells
xorriso how many newline characters are part of the input text. xorriso how many newline characters are part of the input text.
The announced number of text lines will be read from dialog i nput, concatenated with a newline 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_lin e() as parameter line. Note that character between each of them, and submitted to Xorriso_parse_lin e() as parameter line. Note that
newlines outside of quotation marks are interpreted as separato rs if the separators parameter is newlines outside of quotation marks are interpreted as separators if the separators parameter is
empty. empty.
The parsed strings are put out on result channel. They get wrapped into lines which tell their The parsed strings are put out on result channel. They get wr apped into lines which tell their
structure. The first line tells the return value of Xorriso_parse _line(). The next line tells the 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 num ber of lines of the string. Then number of strings. Each string begins by a line that tells the nu mber of lines of the string. Then
follow these lines. They are to be concatenated with a newline cha racter between each of them. follow these lines. They are to be concatenated with a newline cha racter between each of them.
If -backslash_codes "encode_output" is enabled, then the strings undergo encoding as if they were If -backslash_codes "encode_output" is enabled, then the strings u ndergo encoding as if they were
enclosed in quotes. Escpecially each string will be put out as a s ingle result line. enclosed in quotes. Escpecially each string will be put out as a s ingle result line.
parse_bulk parse_bulk
Like "parse", but with the fifth parameter word being num Like "parse", but with the fifth parameter word being nu
ber_of_input_texts rather than mber_of_input_texts rather than
number_of_input_lines. Each input text has to be pre number_of_input_lines. Each input text has to be preced
ceded by a line that tells ed by a line that tells
number_of_input_lines as with "parse". Then come the announced nu mber of text lines. number_of_input_lines as with "parse". Then come the announced nu mber of text lines.
All input texts will be read before printing of result lines beg All input texts will be read before printing of result lines
ins. This consumes memory in begins. This consumes memory in
xorriso. So the number_of_input_texts should not be extreme xorriso. So the number_of_input_texts should not be extremely hi
ly high. On the other hand, large gh. On the other hand, large
transactions of command, input texts, and results are desirable if connection latency is an issue. transactions of command, input texts, and results are desirable if connection latency is an issue.
parse_silently parse_silently
Like "parse" but not issuing a prompting message. Confusing to hum ans. Like "parse" but not issuing a prompting message. Confusing to hum ans.
parse_bulk_silently parse_bulk_silently
Like "parse_bulk" but not issuing a prompting message. Confusing t o humans. Like "parse_bulk" but not issuing a prompting message. Confusing t o humans.
compare_sev compare_sev
The parameter_text should contain two comma separated severity tex ts as issued by this program. The parameter_text should contain two comma separated severity texts as issued by this program.
Like "SORRY,UPDATE". See also paragraph "Exception processing". Like "SORRY,UPDATE". See also paragraph "Exception processing".
These two severity texts get compared and a number gets printed t These two severity texts get compared and a number gets printed to
o the result channel. This number the result channel. This number
is 0 if both severities are equal. It is -1 if the first severity is 0 if both severities are equal. It is -1 if the first sever
is lower than the second one. ity is lower than the second one.
It is 1 is the first severity is higher than the second one. It is 1 is the first severity is higher than the second one.
Above example "SORRY,UPDATE" will yield 1. Above example "SORRY,UPDATE" will yield 1.
list_sev list_sev
Print to the result channel a blank separated list of all severit y names. Sorted from low to high Print to the result channel a blank separated list of all severity names. Sorted from low to high
severity. severity.
-named_pipe_loop mode[:mode] disk_path_stdin disk_path_stdout disk_path_s tderr -named_pipe_loop mode[:mode] disk_path_stdin disk_path_stdout disk_path_s tderr
Temporarily replace standard input, standard output and standard e rror by named pipes. Enter dialog Temporarily replace standard input, standard output and standard e rror by named pipes. Enter dialog
mode without readline. mode without readline.
Defined modes are: Defined modes are:
"cleanup" removes the submitted pipe files when the loop ends. "cleanup" removes the submitted pipe files when the loop ends.
"keep" does not delete them. This is the default. "keep" does not delete them. This is the default.
"buffered" reads all lines from the input pipe until EOF bef ore it opens the output pipes and "buffered" reads all lines from the input pipe until EOF before i t opens the output pipes and
processes the input lines. processes the input lines.
"direct" opens the output pipes after the first input line was read. Each line is executed "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. directly after it is read. This is the default.
The other three parameters must either be disk paths to existin g named pipes, or be "-" to leave The other three parameters must either be disk paths to existing n amed pipes, or be "-" to leave
the according standard i/o channel unreplaced. the according standard i/o channel unreplaced.
xorriso will open the stdin pipe, read and execute dialog lines fr om it until the sender closes the xorriso will open the stdin pipe, read and execute dialog lines fr om it until the sender closes the
pipe. The output pipes get opened depending on mode "buffered" pipe. The output pipes get opened depending on mode "buffered" or
or "direct". After all lines are "direct". After all lines are
executed, xorriso will close its side of the pipes and enter a new executed, xorriso will close its side of the pipes and enter a
cycle of opening, reading and new cycle of opening, reading and
executing. executing.
If an input line consists only of the word "end_named_pipe_loop" t hen -named_pipe_loop will end and If an input line consists only of the word "end_named_pipe_loop" t hen -named_pipe_loop will end and
further xorriso commands may be executed from other sources. further xorriso commands may be executed from other sources.
-launch_frontend program [arguments ...] -- -launch_frontend program [arguments ...] --
Start the program that is given as first parameter. Submit th e other parameters as program Start the program that is given as first parameter. Submi t the other parameters as program
arguments. Enable xorriso dialog mode. arguments. Enable xorriso dialog mode.
Two nameless pipe objects are created. xorriso standard input gets connected to the standard output Two nameless pipe objects are created. xorriso standard input gets connected to the standard output
of the started program. xorriso standard output and standard erro r get connected to the standard of the started program. xorriso standard output and standard er ror get connected to the standard
input of that program. input of that program.
xorriso will abort when the started program ends or if it cannot xorriso will abort when the started program ends or if it cannot b
be started at all. In both cases e started at all. In both cases
it will return a non-zero exit value. The exit value will be zero it will return a non-zero exit value. The exit value will be z
if the frontend sends -end or ero if the frontend sends -end or
-rollback_end before ending itself. -rollback_end before ending itself.
This command may be totaly banned at compile time. It is banned by default if xorriso runs under This command may be totaly banned at compile time. It is banned by default if xorriso runs under
setuid permissions. setuid permissions.
The program name will not be searched in the $PATH directories. To make this clear, it must The program name will not be searched in the $PATH director ies. To make this clear, it must
contain at least one /-character. Best is an absolute path. contain at least one /-character. Best is an absolute path.
Example: Example:
xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio -- xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio --
The frontend program should first send via its standard output: The frontend program should first send via its standard output:
-mark 0 -pkt_output on -msg_op start_sieve - -reassure off -mark 0 -pkt_output on -msg_op start_sieve - -reassure off
It should be ready to decode -pkt_output and to react on -mark me It should be ready to decode -pkt_output and to react on -mark mes
ssages. Best is to increment the sages. Best is to increment the
-mark number after each sent command sequence and then to wait for -mark number after each sent command sequence and then to wait f
the new number to show up in a or the new number to show up in a
mark message: mark message:
...some...commands... -mark <incremented_number> ...some...commands... -mark <incremented_number>
Further are advised: Further are advised:
-report_about UPDATE -abort_on NEVER -report_about UPDATE -abort_on NEVER
-iso_rr_pattern off -disk_pattern off -iso_rr_pattern off -disk_pattern off
A check of the xorriso version should be done, in order to make s ure that all desired features are A check of the xorriso version should be done, in order to make su re that all desired features are
present. present.
Command -launch_frontend will only work once per xorriso run. Command -launch_frontend will only work once per xorriso r
If no command parameters are un. If no command parameters are
submitted or if program is an empty text, then no program submitted or if program is an empty text, then no program wil
will be started but nevertheless l be started but nevertheless
-launch_frontend will be irrevocably disabled. -launch_frontend will be irrevocably disabled.
-prog text -prog text
Use text as name of this program in subsequent messages Use text as name of this program in subsequent messages
-prog_help text -prog_help text
Use text as name of this program and perform -help. Use text as name of this program and perform -help.
EXAMPLES EXAMPLES
Overview of examples: Overview of examples:
skipping to change at line 3540 skipping to change at line 3703
Burn an existing ISO image file to medium Burn an existing ISO image file to medium
Perform multi-session runs as of cdrtools traditions Perform multi-session runs as of cdrtools traditions
Let xorriso work underneath growisofs Let xorriso work underneath growisofs
Adjust thresholds for verbosity, exit value and program abort Adjust thresholds for verbosity, exit value and program abort
Examples of input timestrings Examples of input timestrings
Incremental backup of a few directory trees Incremental backup of a few directory trees
Restore directory trees from a particular ISO session to disk Restore directory trees from a particular ISO session to disk
Try to retrieve blocks from a damaged medium Try to retrieve blocks from a damaged medium
As superuser learn about available drives As superuser learn about available drives
On Linux, FreeBSD or NetBSD consider to give rw-permissions to those user On Linux, FreeBSD or NetBSD consider to give rw-permissions to those us
s or groups which shall be able ers or groups which shall be able
to use the drives with xorriso. On Solaris use pfexec. Consider to to use the drives with xorriso. On Solaris use pfexec. Consider to rest
restrict privileges of xorriso to rict privileges of xorriso to
"base,sys_devices" and to give r-permission to user or group. "base,sys_devices" and to give r-permission to user or group.
$ xorriso -device_links $ xorriso -device_links
1 -dev '/dev/cdrom1' rwrw-- : 'TSSTcorp' 'DVD-ROM SH-D162C 1 -dev '/dev/cdrom1' rwrw-- : 'TSSTcorp' 'DVD-ROM SH-D162C
1 -dev '/dev/cdrw' rwrw-- : 'TSSTcorp' 'CDDVDW SH-S223B' 1 -dev '/dev/cdrw' rwrw-- : 'TSSTcorp' 'CDDVDW SH-S223B'
2 -dev '/dev/cdrw3' rwrw-- : 'HL-DT-ST' 'BDDVDRW_GGC-H20L' 2 -dev '/dev/cdrw3' rwrw-- : 'HL-DT-ST' 'BDDVDRW_GGC-H20L'
Blank medium and compose a new ISO image as batch run Blank medium and compose a new ISO image as batch run
Acquire drive /dev/sr2, make medium ready for writing a new image, fill t he image with the files from hard Acquire drive /dev/sr2, make medium ready for writing a new image, fill t he image with the files from hard
disk directories /home/me/sounds and /home/me/pictures. disk directories /home/me/sounds and /home/me/pictures.
Because no -dialog "on" is given, the program will then end by writing th e session to the medium. Because no -dialog "on" is given, the program will then end by writing th e session to the medium.
$ xorriso -outdev /dev/sr2 \ $ xorriso -outdev /dev/sr2 \
-blank as_needed \ -blank as_needed \
-map /home/me/sounds /sounds \ -map /home/me/sounds /sounds \
-map /home/me/pictures /pictures -map /home/me/pictures /pictures
The ISO image may be shaped in a more elaborate way like the follo wing: Omit some unwanted stuff by The ISO image may be shaped in a more elaborate way like the following: Omit some unwanted stuff by
removing it from the image directory tree. Reintroduce some wanted stuff . removing it from the image directory tree. Reintroduce some wanted stuff .
$ cd /home/me $ cd /home/me
$ xorriso -outdev /dev/sr2 \ $ xorriso -outdev /dev/sr2 \
-blank as_needed \ -blank as_needed \
-map /home/me/sounds /sounds \ -map /home/me/sounds /sounds \
-map /home/me/pictures /pictures \ -map /home/me/pictures /pictures \
-rm_r \ -rm_r \
/sounds/indecent \ /sounds/indecent \
'/pictures/*private*' \ '/pictures/*private*' \
/pictures/confidential \ /pictures/confidential \
-- \ -- \
-cd / \ -cd / \
-add pictures/confidential/work* -- -add pictures/confidential/work* --
Note that '/pictures/*private*' is a pattern for iso_rr_paths while Note that '/pictures/*private*' is a pattern for iso_rr_paths while
pictures/confidential/work* gets pictures/confidential/work* gets
expanded by the shell with addresses from the hard disk. Commands -add expanded by the shell with addresses from the hard disk. Commands -add an
and -map have different parameter d -map have different parameter
rules but finally the same effect: they put files into the image. rules but finally the same effect: they put files into the image.
A dialog session doing about the same A dialog session doing about the same
Some settings are already given as start argument. The other activities a re done as dialog input. The Some settings are already given as start argument. The other activit ies are done as dialog input. The
pager gets set to 20 lines of 80 characters. pager gets set to 20 lines of 80 characters.
The drive is acquired by command -dev rather than -outdev in order to The drive is acquired by command -dev rather than -outdev in order to see
see the message about its current the message about its current
content. By command -blank this content is made ready for being overwritt content. By command -blank this content is made ready for being overwr
en and the loaded ISO image is itten and the loaded ISO image is
made empty. made empty.
In order to be able to eject the medium, the session needs to be committe d explicitly. In order to be able to eject the medium, the session needs to be committe d explicitly.
$ xorriso -dialog on -page 20 80 -disk_pattern on $ xorriso -dialog on -page 20 80 -disk_pattern on
enter option and arguments : enter option and arguments :
-dev /dev/sr2 -dev /dev/sr2
enter option and arguments : enter option and arguments :
-blank as_needed -blank as_needed
enter option and arguments : enter option and arguments :
-map /home/me/sounds /sounds -map /home/me/pictures /pictures -map /home/me/sounds /sounds -map /home/me/pictures /pictures
enter option and arguments : enter option and arguments :
skipping to change at line 3601 skipping to change at line 3764
enter option and arguments : enter option and arguments :
-cdx /home/me/pictures -cd /pictures -cdx /home/me/pictures -cd /pictures
enter option and arguments : enter option and arguments :
-add confidential/office confidential/factory -add confidential/office confidential/factory
enter option and arguments : enter option and arguments :
-du / -du /
enter option and arguments : enter option and arguments :
-commit_eject all -end -commit_eject all -end
Manipulate an existing ISO image on the same medium Manipulate an existing ISO image on the same medium
Load image from drive. Remove (i.e. hide) directory /sounds and it Load image from drive. Remove (i.e. hide) directory /sounds and its
s subordinates. Rename directory subordinates. Rename directory
/pictures/confidential to /pictures/restricted. Change access /pictures/confidential to /pictures/restricted. Change acces
permissions of directory s permissions of directory
/pictures/restricted. Add new directory trees /sounds and /movies /pictures/restricted. Add new directory trees /sounds and /movies. Bu
. Burn to the same medium, check rn to the same medium, check
whether the tree can be loaded, and eject. whether the tree can be loaded, and eject.
$ xorriso -dev /dev/sr2 \ $ xorriso -dev /dev/sr2 \
-rm_r /sounds -- \ -rm_r /sounds -- \
-mv \ -mv \
/pictures/confidential \ /pictures/confidential \
/pictures/restricted \ /pictures/restricted \
-- \ -- \
-chmod go-rwx /pictures/restricted -- \ -chmod go-rwx /pictures/restricted -- \
-map /home/me/prepared_for_dvd/sounds_dummy /sounds \ -map /home/me/prepared_for_dvd/sounds_dummy /sounds \
-map /home/me/prepared_for_dvd/movies /movies \ -map /home/me/prepared_for_dvd/movies /movies \
-commit -eject all -commit -eject all
Copy modified ISO image from one medium to another Copy modified ISO image from one medium to another
Load image from input drive. Do the same manipulations as in the previous example. Acquire output drive Load image from input drive. Do the same manipulations as in the previ ous example. Acquire output drive
and blank it. Burn the modified image as first and only session to the ou tput drive. and blank it. Burn the modified image as first and only session to the ou tput drive.
$ xorriso -indev /dev/sr2 \ $ xorriso -indev /dev/sr2 \
-rm_r /sounds -- \ -rm_r /sounds -- \
... ...
-outdev /dev/sr0 -blank as_needed \ -outdev /dev/sr0 -blank as_needed \
-commit -eject all -commit -eject all
Bring a prepared ISOLINUX tree onto medium and make it bootable Bring a prepared ISOLINUX tree onto medium and make it bootable
The user has already created a suitable file tree on disk and copied the ISOLINUX files into subdirectory The user has already created a suitable file tree on disk and copied the ISOLINUX files into subdirectory
./boot/isolinux of that tree. Now xorriso can burn an El Torito bootable medium: ./boot/isolinux of that tree. Now xorriso can burn an El Torito bootable medium:
$ xorriso -outdev /dev/sr0 -blank as_needed \ $ xorriso -outdev /dev/sr0 -blank as_needed \
-map /home/me/ISOLINUX_prepared_tree / \ -map /home/me/ISOLINUX_prepared_tree / \
-boot_image isolinux dir=/boot/isolinux -boot_image isolinux dir=/boot/isolinux
Change existing file name tree from ISO-8859-1 to UTF-8 Change existing file name tree from ISO-8859-1 to UTF-8
This example assumes that the existing ISO image was written with charact This example assumes that the existing ISO image was written with char
er set ISO-8859-1 but that the acter set ISO-8859-1 but that the
readers expected UTF-8. Now a new session gets added with converted file readers expected UTF-8. Now a new session gets added with converted file
names. Command -changes_pending names. Command -changes_pending
"yes" enables writing despite the lack of any manipulation command. "yes" enables writing despite the lack of any manipulation command.
In order to avoid any weaknesses of the local character set, this command In order to avoid any weaknesses of the local character set, this comm
pretends that it uses already and pretends that it uses already
the final target set UTF-8. Therefore strange file names may appea the final target set UTF-8. Therefore strange file names may appear in
r in messages, which will be made messages, which will be made
terminal-safe by command -backslash_codes. terminal-safe by command -backslash_codes.
$ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \ $ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
-out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \ -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
-changes_pending yes -commit -eject all -changes_pending yes -commit -eject all
Operate on storage facilities other than optical drives Operate on storage facilities other than optical drives
Full read-write operation is possible with regular files and block device s: Full read-write operation is possible with regular files and block device s:
$ xorriso -dev /tmp/regular_file ... $ xorriso -dev /tmp/regular_file ...
Paths underneath /dev normally need prefix "stdio:" Paths underneath /dev normally need prefix "stdio:"
$ xorriso -dev stdio:/dev/sdb ... $ xorriso -dev stdio:/dev/sdb ...
If /dev/sdb is to be used frequently and /dev/sda is the system disk, the n consider to place the following If /dev/sdb is to be used frequently and /dev/sda is the system disk, the n consider to place the following
lines in a xorriso Startup File. They allow you to use /dev/sdb without prefix and protect disk /dev/sda lines in a xorriso Startup File. They allow you to use /dev/sdb without prefix and protect disk /dev/sda
from xorriso: from xorriso:
-drive_class banned /dev/sda* -drive_class banned /dev/sda*
-drive_class harmless /dev/sdb -drive_class harmless /dev/sdb
Other writeable file types are supported write-only: Other writeable file types are supported write-only:
$ xorriso -outdev /tmp/named_pipe ... $ xorriso -outdev /tmp/named_pipe ...
Among the write-only drives is standard output: Among the write-only drives is standard output:
$ xorriso -outdev - \ $ xorriso -outdev - \
... ...
| gzip >image.iso.gz | gzip >image.iso.gz
skipping to change at line 3676 skipping to change at line 3839
The first session is written like this: The first session is written like this:
$ xorriso -as mkisofs prepared_for_iso/tree1 | \ $ xorriso -as mkisofs prepared_for_iso/tree1 | \
xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
Follow-up sessions are written like this (the run of dd is only to give d emons a chance to spoil it): Follow-up sessions are written like this (the run of dd is only to give d emons a chance to spoil it):
$ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo) $ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1 $ dd if=/dev/sr0 count=1 >/dev/null 2>&1
$ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \ $ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject - xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
Always eject the drive tray between sessions. Always eject the drive tray between sessions.
The run of xorriso -as mkisofs will read old sessions via the CD-ROM driv er of /dev/sr0. This driver might The run of xorriso -as mkisofs will read old sessions via the CD-ROM driv er of /dev/sr0. This driver might
not be aware of the changed content as long as the medium is not loaded not be aware of the changed content as long as the medium is not loaded a
again. In this case the previous gain. In this case the previous
session would not be properly assessed by xorriso and the new session wou session would not be properly assessed by xorriso and the new session w
ld contain only the newly added ould contain only the newly added
files. files.
Some systems have not enough patience with automatic tray loading and some demons may interfere with a Some systems have not enough patience with automatic tray loading and som e demons may interfere with a
first CD-ROM driver read attempt from a freshly loaded medium. first CD-ROM driver read attempt from a freshly loaded medium.
When loading the tray manually, wait 10 seconds after the drive has stopp ed blinking. When loading the tray manually, wait 10 seconds after the drive has stopp ed blinking.
A safe automatic way seems to be a separate run of xorriso for loading th e tray with proper waiting, and a A safe automatic way seems to be a separate run of xorriso for loading th e tray with proper waiting, and a
subsequent run of dd which shall offer itself to any problems caused by d emons assessing the changed drive subsequent run of dd which shall offer itself to any problems caused by d emons assessing the changed drive
status. If this does not help, insert a run of "sleep 10" between xorris o and dd. status. If this does not help, insert a run of "sleep 10" between xorris o and dd.
This example works for multi-session media only. Add cdrskin option --gr This example works for multi-session media only. Add cdrskin option --
ow_overwriteable_iso to all -as grow_overwriteable_iso to all -as
cdrecord runs in order to enable multi-session emulation on overwriteable cdrecord runs in order to enable multi-session emulation on overwritable
media. media.
Let xorriso work underneath growisofs Let xorriso work underneath growisofs
growisofs expects an ISO formatter program which understands options -C a nd -M. If xorriso gets started by growisofs expects an ISO formatter program which understands options -C a nd -M. If xorriso gets started by
name "xorrisofs" then it is suitable for that. name "xorrisofs" then it is suitable for that.
$ export MKISOFS="xorrisofs" $ export MKISOFS="xorrisofs"
$ growisofs -Z /dev/dvd /some/files $ growisofs -Z /dev/dvd /some/files
$ growisofs -M /dev/dvd /more/files $ growisofs -M /dev/dvd /more/files
If no "xorrisofs" is available on your system, then you will have to crea te a link pointing to the xorriso If no "xorrisofs" is available on your system, then you will have to crea te a link pointing to the xorriso
binary and tell growisofs to use it. E.g. by: binary and tell growisofs to use it. E.g. by:
$ ln -s $(which xorriso) "$HOME/xorrisofs" $ ln -s $(which xorriso) "$HOME/xorrisofs"
$ export MKISOFS="$HOME/xorrisofs" $ export MKISOFS="$HOME/xorrisofs"
One may quit mkisofs emulation by argument "--" and make use of all xor riso commands. growisofs dislikes One may quit mkisofs emulation by argument "--" and make use of all xorri so commands. growisofs dislikes
options which start with "-o" but -outdev must be set to "-". So use "ou tdev" instead: options which start with "-o" but -outdev must be set to "-". So use "ou tdev" instead:
$ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files $ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
$ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files $ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
growisofs has excellent burn capabilities with DVD and BD. It does n growisofs has excellent burn capabilities with DVD and BD. It do
ot emulate session history on es not emulate session history on
overwriteable media, though. overwritable media, though.
Adjust thresholds for verbosity, exit value and program abort Adjust thresholds for verbosity, exit value and program abort
Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not abort prematurely but forcibly go Be quite verbose, exit 32 if severity "FAILURE" was encountered, do not a bort prematurely but forcibly go
on until the end of commands. on until the end of commands.
$ xorriso ... \ $ xorriso ... \
-report_about UPDATE \ -report_about UPDATE \
-return_with FAILURE 32 \ -return_with FAILURE 32 \
-abort_on NEVER \ -abort_on NEVER \
... ...
Examples of input timestrings Examples of input timestrings
As printed by program date: 'Thu Nov 8 14:51:13 CET 2007' As printed by program date: 'Thu Nov 8 14:51:13 CET 2007'
The same without ignored parts: 'Nov 8 14:51:13 2007' The same without ignored parts: 'Nov 8 14:51:13 2007'
The same as expected by date: 110814512007.13 The same as expected by date: 110814512007.13
Four weeks in the future: +4w Four weeks in the future: +4w
The current time: +0 The current time: +0
Three hours ago: -3h Three hours ago: -3h
Seconds since Jan 1 1970: =1194531416 Seconds since Jan 1 1970: =1194531416
Incremental backup of a few directory trees Incremental backup of a few directory trees
This changes the directory trees /projects and /personal_mail in the ISO image so that they become exact This changes the directory trees /projects and /personal_mail in the IS O image so that they become exact
copies of their disk counterparts. ISO file objects get created, deleted or get their attributes adjusted copies of their disk counterparts. ISO file objects get created, deleted or get their attributes adjusted
accordingly. accordingly.
ACL, xattr, hard links and MD5 checksums will be recorded. Accelerated ACL, xattr, hard links and MD5 checksums will be recorded. Acceler
comparison is enabled at the ated comparison is enabled at the
expense of potentially larger backup size. Only media with the expe expense of potentially larger backup size. Only media with the expected
cted volume ID or blank media are volume ID or blank media are
accepted. Files with names matching *.o or *.swp get excluded explicitly . accepted. Files with names matching *.o or *.swp get excluded explicitly .
When done with writing the new session gets checked by its recorded MD5. When done with writing the new session gets checked by its recorded MD5.
$ xorriso \ $ xorriso \
-abort_on FATAL \ -abort_on FATAL \
-for_backup -disk_dev_ino on \ -for_backup -disk_dev_ino on \
-assert_volid 'PROJECTS_MAIL_*' FATAL \ -assert_volid 'PROJECTS_MAIL_*' FATAL \
-dev /dev/sr0 \ -dev /dev/sr0 \
-volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \ -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
-not_leaf '*.o' -not_leaf '*.swp' \ -not_leaf '*.o' -not_leaf '*.swp' \
-update_r /home/thomas/projects /projects \ -update_r /home/thomas/projects /projects \
-update_r /home/thomas/personal_mail /personal_mail \ -update_r /home/thomas/personal_mail /personal_mail \
-commit -toc -check_md5 FAILURE -- -eject all -commit -toc -check_md5 FAILURE -- -eject all
To be used several times on the same medium, whenever an update of the tw To be used several times on the same medium, whenever an update of th
o disk trees to the medium is e two disk trees to the medium is
desired. Begin with a blank medium and update it until the run fails gr desired. Begin with a blank medium and update it until the run fails grac
acefully due to lack of remaining efully due to lack of remaining
space on the old one. space on the old one.
This makes sense if the full backup leaves substantial remaining capacity This makes sense if the full backup leaves substantial remaining capa
on media and if the expected city on media and if the expected
changes are much smaller than the full backup. To apply zisofs compress changes are much smaller than the full backup. To apply zisofs compressi
ion to those data files which get on to those data files which get
newly copied from the local filesystem, insert these commands immediately before -commit : newly copied from the local filesystem, insert these commands immediately before -commit :
-hardlinks perform_update \ -hardlinks perform_update \
-find / -type f -pending_data -exec set_filter --zisofs -- \ -find / -type f -pending_data -exec set_filter --zisofs -- \
Commands -disk_dev_ino and -for_backup depend on stable device and inode numbers on disk. Without them, an Commands -disk_dev_ino and -for_backup depend on stable device and inode numbers on disk. Without them, an
update run may use -md5 "on" to match recorded MD5 sums against the c urrent file content on hard disk. update run may use -md5 "on" to match recorded MD5 sums against the curre nt file content on hard disk.
This is usually much faster than the default which compares both contents directly. This is usually much faster than the default which compares both contents directly.
With mount option -o "sbsector=" on GNU/Linux or -s on FreeBSD or NetBSD With mount option -o "sbsector=" on GNU/Linux or -s on FreeBSD or Ne
it is possible to access the tBSD it is possible to access the
session trees which represent the older backup versions. With CD media session trees which represent the older backup versions. With CD media, G
, GNU/Linux mount accepts session NU/Linux mount accepts session
numbers directly by its option "session=". numbers directly by its option "session=".
Multi-session media and most overwriteable media written by xorriso can Multi-session media and most overwritable media written by xorris
tell the sbsectors of their o can tell the sbsectors of their
sessions by xorriso command -toc. Used after -commit the following sessions by xorriso command -toc. Used after -commit the following comm
command prints the matching mount and prints the matching mount
command for the newly written session (here for mount point /mnt): command for the newly written session (here for mount point /mnt):
-mount_cmd "indev" "auto" "auto" /mnt -mount_cmd "indev" "auto" "auto" /mnt
Commands -mount_cmd and -mount are also able to produce the mount comman ds for older sessions in the Commands -mount_cmd and -mount are also able to produce the mount c ommands for older sessions in the
table-of-content. E.g. as superuser: table-of-content. E.g. as superuser:
# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
Above example produces a result similar to -root / -old-root / with mkisofs. For getting the session Above example produces a result similar to -root / -old-root / with mkis ofs. For getting the session
trees accumulated in the new sessions, let all -update commands use a com mon parent directory and clone it trees accumulated in the new sessions, let all -update commands use a com mon parent directory and clone it
after updating is done: after updating is done:
-update_r /home/thomas/projects /current/projects \ -update_r /home/thomas/projects /current/projects \
-update_r /home/thomas/personal_mail /current/personal_mail \ -update_r /home/thomas/personal_mail /current/personal_mail \
-clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \ -clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \
The cloned tree will have a name like /2011_02_12_155700. The cloned tree will have a name like /2011_02_12_155700.
Sessions on multi-session media are separated by several MB of unused bl ocks. So with small sessions the Sessions on multi-session media are separated by several MB of unused blo cks. So with small sessions the
payload capacity can become substantially lower than the overall media ca pacity. If the remaining space on payload capacity can become substantially lower than the overall media ca pacity. If the remaining space on
a medium does not suffice for the next gap, the drive is supposed to clos e the medium automatically. a medium does not suffice for the next gap, the drive is supposed to clos e the medium automatically.
Better do not use your youngest backup for -update_r. Have at least two media which you use Better do not use your youngest backup for -update_r. Have at l east two media which you use
alternatingly. So only older backups get endangered by the new write oper ation, while the newest backup is alternatingly. So only older backups get endangered by the new write oper ation, while the newest backup is
stored safely on a different medium. stored safely on a different medium.
Always have a blank medium ready to perform a full backup in cas e the update attempt fails due to Always have a blank medium ready to perform a full backup in case the update attempt fails due to
insufficient remaining capacity. This failure will not spoil the old medi um, of course. insufficient remaining capacity. This failure will not spoil the old medi um, of course.
Restore directory trees from a particular ISO session to disk Restore directory trees from a particular ISO session to disk
This is an alternative to mounting the medium and using normal file opera tions. This is an alternative to mounting the medium and using normal file opera tions.
First check which backup sessions are on the medium: First check which backup sessions are on the medium:
$ xorriso -outdev /dev/sr0 -toc $ xorriso -outdev /dev/sr0 -toc
Then enable restoring of ACL, xattr and hard links. Load the desired sess ion and copy the file trees to Then enable restoring of ACL, xattr and hard links. Load the desired s ession and copy the file trees to
disk. Avoid to create /home/thomas/restored without rwx-permission. disk. Avoid to create /home/thomas/restored without rwx-permission.
$ xorriso -for_backup \ $ xorriso -for_backup \
-load volid 'PROJECTS_MAIL_2008_06_19*' \ -load volid 'PROJECTS_MAIL_2008_06_19*' \
-indev /dev/sr0 \ -indev /dev/sr0 \
-osirrox on:auto_chmod_on \ -osirrox on:auto_chmod_on \
-chmod u+rwx / -- \ -chmod u+rwx / -- \
-extract /projects /home/thomas/restored/projects \ -extract /projects /home/thomas/restored/projects \
-extract /personal_mail /home/thomas/restored/personal_mail \ -extract /personal_mail /home/thomas/restored/personal_mail \
-rollback_end -rollback_end
The final command -rollback_end prevents an error message about the alter ed image being discarded. The final command -rollback_end prevents an error message about the alter ed image being discarded.
Try to retrieve blocks from a damaged medium Try to retrieve blocks from a damaged medium
$ xorriso -abort_on NEVER -indev /dev/sr0 \ $ xorriso -abort_on NEVER -indev /dev/sr0 \
-check_media time_limit=1800 report=blocks_files \ -check_media time_limit=1800 report=blocks_files \
data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map -- data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
This can be repeated several times, if necessary with -eject or with o This can be repeated several times, if necessary with -eject or with othe
ther -indev drives. See the human r -indev drives. See the human
readable part of "$HOME"/dvd_copy.map for addresses which can be used readable part of "$HOME"/dvd_copy.map for addresses which can be us
on "$HOME"/dvd_copy with mount ed on "$HOME"/dvd_copy with mount
option -o sbsector= or -s. option -o sbsector= or -s.
FILES FILES
Program alias names: Program alias names:
Normal installation of xorriso creates three links or copies which by their program name pre-select Normal installation of xorriso creates three links or copies which by their program name pre-select
certain settings: certain settings:
xorrisofs starts xorriso with -as mkisofs emulation. xorrisofs starts xorriso with -as mkisofs emulation.
xorrecord starts xorriso with -as cdrecord emulation. xorrecord starts xorriso with -as cdrecord emulation.
osirrox starts with -osirrox "on:o_excl_off" which allows further command s to copy files from ISO image to osirrox starts with -osirrox "on:o_excl_off" which allows further command s to copy files from ISO image to
disk and to apply command -mount to one or more of the existing ISO sessi ons. disk and to apply command -mount to one or more of the existing ISO sessi ons.
Startup files: Startup files:
If not -no_rc is given as the first argument then xorriso attempts on startup to read and execute lines If not -no_rc is given as the first argument then xorriso attempts on sta rtup to read and execute lines
from the following files: from the following files:
/etc/default/xorriso /etc/default/xorriso
/etc/opt/xorriso/rc /etc/opt/xorriso/rc
/etc/xorriso/xorriso.conf /etc/xorriso/xorriso.conf
$HOME/.xorrisorc $HOME/.xorrisorc
The files are read in the sequence given above, but none of them is requi red to exist. The line format is The files are read in the sequence given above, but none of them is requ ired to exist. The line format is
described with command -options_from_file. described with command -options_from_file.
If mkisofs emulation was enabled by program name "xorrisofs", "mkisof s", "genisoimage", or "genisofs", If mkisofs emulation was enabled by program name "xorrisofs", "mkisofs", "genisoimage", or "genisofs",
then afterwards -read_mkisofsrc is performed, which reads .mkisofsrc file s. See there. then afterwards -read_mkisofsrc is performed, which reads .mkisofsrc file s. See there.
Runtime control files: Runtime control files:
The default setting of -check_media abort_file= is: The default setting of -check_media abort_file= is:
/var/opt/xorriso/do_abort_check_media /var/opt/xorriso/do_abort_check_media
ENVIRONMENT ENVIRONMENT
The following environment variables influence the program behavior: The following environment variables influence the program behavior:
HOME is used to find startup files of xorriso and mkisofs. HOME is used to find startup files of xorriso and mkisofs.
SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. It is SOURCE_DATE_EPOCH belongs to the specs of reproducible-builds.org. It i
supposed to be either undefined s supposed to be either undefined
or to contain a decimal number which tells the seconds since january 1 or to contain a decimal number which tells the seconds since january 1st
st 1970. If it contains a number, 1970. If it contains a number,
then it is used as time value to set the default of -volume date then it is used as time value to set the default of -volume da
"uuid", sets -boot_image "any" te "uuid", sets -boot_image "any"
"gpt_disk_guid=" to "volume_date_uuid", -volume_date "all_file_dates" to "gpt_disk_guid=" to "volume_date_uuid", -volume_date "all_file_dates" to
"set_to_mtime", and -iso_nowtime "set_to_mtime", and -iso_nowtime
to "=$SOURCE_DATE_EPOCH". to "=$SOURCE_DATE_EPOCH".
Startup files and program options can override the effect of SOURCE_DATE_ EPOCH. Startup files and program options can override the effect of SOURCE_DATE_ EPOCH.
SEE ALSO SEE ALSO
For the mkisofs emulation of xorriso For the mkisofs emulation of xorriso
xorrisofs(1) xorrisofs(1)
For the cdrecord emulation of xorriso For the cdrecord emulation of xorriso
xorrecord(1) xorrecord(1)
skipping to change at line 3869 skipping to change at line 4032
ACL and xattr ACL and xattr
getfacl(1), setfacl(1), getfattr(1), setfattr(1) getfacl(1), setfacl(1), getfattr(1), setfattr(1)
MD5 checksums MD5 checksums
md5sum(1) md5sum(1)
On FreeBSD the commands for xattr and MD5 differ On FreeBSD the commands for xattr and MD5 differ
getextattr(8), setextattr(8), md5(1) getextattr(8), setextattr(8), md5(1)
BUGS BUGS
To report bugs, request help, or suggest enhancements for xorriso, please send electronic mail to the To report bugs, request help, or suggest enhancements for xorriso, p lease send electronic mail to the
public list <bug-xorriso@gnu.org>. If more privacy is desired, mail to < scdbackup@gmx.net>. public list <bug-xorriso@gnu.org>. If more privacy is desired, mail to < scdbackup@gmx.net>.
Please describe what you expect xorriso to do, the program arguments or d ialog commands by which you tried Please describe what you expect xorriso to do, the program arguments or d ialog commands by which you tried
to achieve it, the messages of xorriso, and the undesirable outcome of yo ur program run. to achieve it, the messages of xorriso, and the undesirable outcome of yo ur program run.
Expect to get asked more questions before solutions can be proposed. Expect to get asked more questions before solutions can be proposed.
AUTHOR AUTHOR
Thomas Schmitt <scdbackup@gmx.net> Thomas Schmitt <scdbackup@gmx.net>
for libburnia-project.org for libburnia-project.org
COPYRIGHT COPYRIGHT
Copyright (c) 2007 - 2019 Thomas Schmitt Copyright (c) 2007 - 2021 Thomas Schmitt
Permission is granted to distribute this text freely. It shall only be mo dified in sync with the technical Permission is granted to distribute this text freely. It shall only be mo dified in sync with the technical
properties of xorriso. If you make use of the license to derive modified versions of xorriso then you are properties of xorriso. If you make use of the license to derive modified versions of xorriso then you are
entitled to modify this text under that same license. entitled to modify this text under that same license.
CREDITS CREDITS
xorriso is in part based on work by Vreixo Formoso who provides libisofs xorriso is in part based on work by Vreixo Formoso who provides libis
together with Mario Danic who ofs together with Mario Danic who
also leads the libburnia team. Vladimir Serbinenko contributed the also leads the libburnia team. Vladimir Serbinenko contributed the HFS
HFS+ filesystem code and related + filesystem code and related
knowledge. Thanks to Andy Polyakov who invented emulated growing, to Der knowledge. Thanks to Andy Polyakov who invented emulated growing, to
ek Foreman and Ben Jansens who Derek Foreman and Ben Jansens who
once founded libburn. once founded libburn.
Compliments towards Joerg Schilling whose cdrtools served me for ten year s. Compliments towards Joerg Schilling whose cdrtools served me for ten year s.
Version 1.5.2, Oct 26, 2019 XORRISO(1) Version 1.5.4, Jan 30, 2021 XORRISO(1)
 End of changes. 609 change blocks. 
1563 lines changed or deleted 1828 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)