"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "xorriso/xorriso.texi" 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.texi  (xorriso-1.5.2):xorriso.texi  (xorriso-1.5.4)
\input texinfo @c -*-texinfo-*- \input texinfo @c -*-texinfo-*-
@c %**start of header @c %**start of header
@setfilename xorriso.info @setfilename xorriso.info
@settitle GNU xorriso 1.5.2 @settitle GNU xorriso 1.5.4
@c %**end of header @c %**end of header
@c @c
@c man-ignore-lines begin @c man-ignore-lines begin
@dircategory Archiving @dircategory Archiving
@direntry @direntry
* Xorriso: (xorriso). Burns ISO 9660 on CD, DVD, BD. * Xorriso: (xorriso). Burns ISO 9660 on CD, DVD, BD.
@end direntry @end direntry
@c man-ignore-lines end @c man-ignore-lines end
@c @c
@c Notes about embedded man page: @c Notes about embedded man page:
skipping to change at line 53 skipping to change at line 53
@c man .\" @c man .\"
@c man .\" IMPORTANT NOTE: @c man .\" IMPORTANT NOTE:
@c man .\" @c man .\"
@c man .\" The original of this file is kept in xorriso/xorriso.texi @c man .\" The original of this file is kept in xorriso/xorriso.texi
@c man .\" This here was generated by program xorriso/make_xorriso_1 @c man .\" This here was generated by program xorriso/make_xorriso_1
@c man .\" @c man .\"
@c man .\" @c man .\"
@c man .\" First parameter, NAME, should be all caps @c man .\" First parameter, NAME, should be all caps
@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
@c man .\" other parameters are allowed: see man(7), man(1) @c man .\" other parameters are allowed: see man(7), man(1)
@c man .TH XORRISO 1 "Version 1.5.2, Oct 26, 2019" @c man .TH XORRISO 1 "Version 1.5.4, Jan 30, 2021"
@c man .\" Please adjust this date whenever revising the manpage. @c man .\" Please adjust this date whenever revising the manpage.
@c man .\" @c man .\"
@c man .\" Some roff macros, for reference: @c man .\" Some roff macros, for reference:
@c man .\" .nh disable hyphenation @c man .\" .nh disable hyphenation
@c man .\" .hy enable hyphenation @c man .\" .hy enable hyphenation
@c man .\" .ad l left justify @c man .\" .ad l left justify
@c man .\" .ad b justify to both left and right margins @c man .\" .ad b justify to both left and right margins
@c man .\" .nf disable filling @c man .\" .nf disable filling
@c man .\" .fi enable filling @c man .\" .fi enable filling
@c man .\" .br insert line break @c man .\" .br insert line break
@c man .\" .sp <n> insert n+1 empty lines @c man .\" .sp <n> insert n+1 empty lines
@c man .\" for manpage-specific macros, see man(7) @c man .\" for manpage-specific macros, see man(7)
@c man .nh @c man .nh
@c man-ignore-lines begin @c man-ignore-lines begin
@copying @copying
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions. with Rock Ridge extensions.
Copyright @copyright{} 2007 - 2019 Thomas Schmitt Copyright @copyright{} 2007 - 2021 Thomas Schmitt
@quotation @quotation
Permission is granted to distribute this text freely. Permission is granted to distribute this text freely.
@end quotation @end quotation
@end copying @end copying
@c man-ignore-lines end @c man-ignore-lines end
@titlepage @titlepage
@title Manual of GNU xorriso 1.5.2 @title Manual of GNU xorriso 1.5.4
@author Thomas Schmitt @author Thomas Schmitt
@page @page
@vskip 0pt plus 1filll @vskip 0pt plus 1filll
@insertcopying @insertcopying
@end titlepage @end titlepage
@contents @contents
@ifnottex @ifnottex
@node Top @node Top
@top GNU xorriso 1.5.2 @top GNU xorriso 1.5.4
@c man-ignore-lines 1 @c man-ignore-lines 1
@c man .SH NAME @c man .SH NAME
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions. with Rock Ridge extensions.
@end ifnottex @end ifnottex
@menu @menu
* Overview:: Overview * Overview:: Overview
* Model:: Session model * Model:: Session model
* Media:: Media types and states * Media:: Media types and states
skipping to change at line 171 skipping to change at line 171
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.
@* @*
@sp 1 @sp 1
@c man .sp 1 @c man .sp 1
Note that @command{xorriso} does not write audio CDs and that it does not Note that @command{xorriso} does not write audio CDs and that it does not
skipping to change at line 244 skipping to change at line 244
This session usually contains an updated directory tree for the whole medium This session usually contains an updated directory tree for the whole medium
which governs the data contents in all recorded sessions. which governs the data contents in all recorded sessions.
So in the view of the mount program all sessions of a particular medium So in the view of the mount program all sessions of a particular medium
together form a single filesystem image. together form a single filesystem image.
@* @*
Adding a session to an existing ISO image is in this text referred as Adding a session to an existing ISO image is in this text referred as
@strong{growing}. @strong{growing}.
@* @*
The multi-session model of the MMC standard does not apply to all media The multi-session model of the MMC standard does not apply to all media
types. But program growisofs by Andy Polyakov showed how to extend this types. But program growisofs by Andy Polyakov showed how to extend this
functionality to overwriteable media or disk files which carry valid ISO 9660 functionality to overwritable media or disk files which carry valid ISO 9660
filesystems. filesystems.
@c man .PP @c man .PP
@sp 1 @sp 1
@command{xorriso} provides growing as well as an own method named @command{xorriso} provides growing as well as an own method named
@strong{modifying} which produces a completely new ISO image from the old @strong{modifying} which produces a completely new ISO image from the old
one and the modifications. one and the modifications.
See paragraph Creating, Growing, Modifying, Blind Growing below. See paragraph Creating, Growing, Modifying, Blind Growing below.
@c man .PP @c man .PP
@sp 1 @sp 1
@command{xorriso} adopts the concept of multi-session by loading an @command{xorriso} adopts the concept of multi-session by loading an
skipping to change at line 290 skipping to change at line 290
@* @*
@cindex Multi-session media, _definition @cindex Multi-session media, _definition
@strong{Multi-session media} are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and @strong{Multi-session media} are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and
unformatted DVD-RW. These media provide a table of content which unformatted DVD-RW. These media provide a table of content which
describes their existing sessions. See command @strong{-toc}. describes their existing sessions. See command @strong{-toc}.
@* @*
Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW. Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW.
They record only a single session of which the size must be known in advance. They record only a single session of which the size must be known in advance.
@command{xorriso} will write onto them only if command -close is set to "on". @command{xorriso} will write onto them only if command -close is set to "on".
@* @*
@cindex Overwriteable media, _definition @cindex Overwritable media, _definition
@strong{Overwriteable media} are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. @strong{Overwritable media} are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
They offer random write access but do not provide information about their They offer random write access but do not provide information about their
session history. If they contain one or more ISO 9660 sessions and if the session history. If they contain one or more ISO 9660 sessions and if the
first session was written by @command{xorriso}, then a table of content can first session was written by @command{xorriso}, then a table of content can
be emulated. Else only a single overall session will be visible. be emulated. Else only a single overall session will be visible.
@* @*
DVD-RW media can be formatted by -format "full". DVD-RW media can be formatted by -format "full".
They can be made unformatted by -blank "deformat". They can be made unformatted by -blank "deformat".
@* @*
Regular files and block devices are handled as overwriteable media. Regular files and block devices are handled as overwritable media.
Pipes and other writeable file types are handled as blank multi-session media. Pipes and other writeable file types are handled as blank multi-session media.
@c man .PP @c man .PP
@sp 1 @sp 1
These media can assume several states in which they offer different These media can assume several states in which they offer different
capabilities. capabilities.
@* @*
@sp 1 @sp 1
@cindex Blank media, _definition @cindex Blank media, _definition
@strong{Blank} media can be written from scratch. They contain no ISO image @strong{Blank} media can be written from scratch. They contain no ISO image
suitable for @command{xorriso}. suitable for @command{xorriso}.
@* @*
Blank is the state of newly purchased optical media. 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". With used CD-RW and DVD-RW it can be achieved by action -blank "as_needed".
Overwriteable media are considered blank if they are new or if they have Overwritable media are considered blank if they are new or if they have
been marked as blank by @command{xorriso}. been marked as blank by @command{xorriso}.
Action -blank "as_needed" can be used to do this marking on overwriteable Action -blank "as_needed" can be used to 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.
@* @*
@sp 1 @sp 1
@cindex Appendable media, _definition @cindex Appendable media, _definition
@strong{Appendable} media accept further sessions. Either they are MMC @strong{Appendable} media accept further sessions. Either they are MMC
multi-session media in appendable state, or they are overwriteable media multi-session media in appendable state, or they are overwritable media
which contain an ISO image suitable for @command{xorriso}. which contain an ISO image suitable for @command{xorriso}.
@* @*
Appendable is the state after writing a session with command -close off. Appendable is the state after writing a session with command -close off.
@* @*
@sp 1 @sp 1
@cindex Closed media, _definition @cindex Closed media, _definition
@strong{Closed} media cannot be written. They may contain an ISO image suitable @strong{Closed} media cannot be written. They may contain an ISO image suitable
for @command{xorriso}. for @command{xorriso}.
@* @*
Closed is the state of DVD-ROM media and of multi-session media which were Closed is the state of DVD-ROM media and of multi-session media which were
written with command -close on. If the drive is read-only hardware then it will written with command -close on. If the drive is read-only hardware then it will
probably show any media as closed CD-ROM or DVD-ROM. probably show any media as closed CD-ROM or DVD-ROM.
@* @*
Overwriteable media assume this state in such read-only drives or if they Overwritable media assume this state in such read-only drives or if they
contain unrecognizable data in the first 32 data blocks. contain unrecognizable data in the first 32 data blocks.
@* @*
Read-only drives may or may not show session histories of multi-session Read-only drives may or may not show session histories of multi-session
media. Often only the first and the last session are visible. Sometimes media. Often only the first and the last session are visible. Sometimes
not even that. Command -rom_toc_scan might or might not help in such cases. not even that. Command -rom_toc_scan might or might not help in such cases.
@c man .SS @c man .SS
@node Methods, Drives, Media, Top @node Methods, Drives, Media, Top
@chapter Creating, Growing, Modifying, Blind Growing: @chapter Creating, Growing, Modifying, Blind Growing:
@c man .B Creating, Growing, Modifying, Blind Growing: @c man .B Creating, Growing, Modifying, Blind Growing:
@* @*
skipping to change at line 421 skipping to change at line 421
access readable libburn drive: optical media with readable data, access readable libburn drive: optical media with readable data,
blank optical media, regular files, block devices. blank optical media, regular files, block devices.
@* @*
Output drive, i.e. target for writing, can be any libburn drive. Output drive, i.e. target for writing, can be any libburn drive.
Some drive types do not support the method of growing but only the methods Some drive types do not support the method of growing but only the methods
of modifying and blind growing. They all are suitable for newly created images. of modifying and blind growing. They all are suitable for newly created images.
@c man .PP @c man .PP
@sp 1 @sp 1
All drive file objects have to offer rw-permission to the user of All drive file objects have to offer rw-permission to the user of
@command{xorriso}. @command{xorriso}.
Even those which will not be useable for reading an ISO image. Even those which will not be usable for reading an ISO image.
@* @*
@cindex LBA, _definition @cindex LBA, _definition
With any type of drive object, the data are considered to be organized in With any type of drive object, the data are considered to be organized in
blocks of 2 KiB. Access happens in terms of Logical Block Address blocks of 2 KiB. Access happens in terms of Logical Block Address
(@strong{LBA}) which gives the number of a particular data block. (@strong{LBA}) which gives the number of a particular data block.
@c man .PP @c man .PP
@sp 1 @sp 1
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by 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. the path of their block device or of their generic character device. E.g.
@* @*
skipping to change at line 558 skipping to change at line 558
@command{xorriso} is able to create or maintain an El Torito object which @command{xorriso} is able to create or maintain an El Torito object which
makes such an image bootable. For details see command -boot_image. makes such an image bootable. For details see command -boot_image.
@* @*
@cindex MBR, _definition @cindex MBR, _definition
It is possible to make ISO images bootable from USB stick or other It is possible to make ISO images bootable from USB stick or other
hard-disk-like media. Several options install a @strong{MBR} hard-disk-like media. Several options install a @strong{MBR}
(Master Boot Record), It may get adjusted according to the needs of the (Master Boot Record), It may get adjusted according to the needs of the
intended boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. intended boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX.
A MBR contains boot code and a partition table. A MBR contains boot code and a partition table.
The new MBR of a follow-up session can get in effect The new MBR of a follow-up session can get in effect
only on overwriteable media. only on overwritable media.
@* @*
MBR is read by PC-BIOS when booting from USB stick or hard disk, MBR is read by PC-BIOS when booting from USB stick or hard disk,
and by PowerPC CHRP or PReP when booting. and by PowerPC 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 ISOLINUX wiki, Emulation -as mkisofs supports the example options out of the ISOLINUX wiki,
the options used in GRUB script grub-mkrescue, and the example in the the options used in GRUB script grub-mkrescue, and the example in the
FreeBSD AvgLiveCD wiki. FreeBSD AvgLiveCD wiki.
@* @*
@cindex GPT, _definition @cindex GPT, _definition
skipping to change at line 992 skipping to change at line 992
@* @*
So for simultaneous burn runs on modern GNU/Linux it is advisable to perform So for simultaneous burn runs on modern GNU/Linux it is advisable to perform
-scsi_dev_family "sg" before any -dev, -indev, or -outdev. The drive addresses -scsi_dev_family "sg" before any -dev, -indev, or -outdev. The drive addresses
may then well be given as /dev/sr* but will nevertheless get used as may then well be given as /dev/sr* but will nevertheless get used as
the matching /dev/sg*. the matching /dev/sg*.
@* @*
If you decide so, consider to put the command into a global startup file like If you decide so, consider to put the command into a global startup file like
/etc/opt/xorriso/rc. /etc/opt/xorriso/rc.
@c man .TP @c man .TP
@item -grow_blindly "off"|predicted_nwa @item -grow_blindly "off"|predicted_nwa
@kindex -grow_blindly overides next writeable address @kindex -grow_blindly overrides next writeable address
@cindex Next writeable address, -grow_blindly @cindex Next writeable address, -grow_blindly
If predicted_nwa is a non-negative number then perform blind growing rather If predicted_nwa is a non-negative number then perform blind growing rather
than modifying if -indev and -outdev are set to different drives. than modifying if -indev and -outdev are set to different drives.
"off" or "-1" switch to modifying, which is the default. "off" or "-1" switch to modifying, which is the default.
@* @*
predicted_nwa is the block address where the add-on session of blind predicted_nwa is the block address where the add-on session of blind
growing will finally end up. It is the responsibility of the user to ensure growing will finally end up. It is the responsibility of the user to ensure
this final position and the presence of the older sessions. Else the this final position and the presence of the older sessions. Else the
overall ISO image will not be mountable or will produce read errors when overall ISO image will not be mountable or will produce read errors when
accessing file content. @command{xorriso} will write the session to the address accessing file content. @command{xorriso} will write the session to the address
skipping to change at line 1050 skipping to change at line 1050
5540k = 5540kB/s = 4d = 4xDVD 5540k = 5540kB/s = 4d = 4xDVD
@* @*
If there is no hint about the speed unit attached, then the If there is no hint about the speed unit attached, then the
medium in the -indev will decide. Default unit is CD = 176.4k. medium in the -indev will decide. Default unit is CD = 176.4k.
@* @*
Depending on the drive, the reported read speeds can be deceivingly low Depending on the drive, the reported read speeds can be deceivingly low
or high. Therefore "min" cannot become higher than 1x speed of the involved or high. Therefore "min" cannot become higher than 1x speed of the involved
medium type. Read speed "max" cannot become lower than 52xCD, 24xDVD, medium type. Read speed "max" cannot become lower than 52xCD, 24xDVD,
or 20xBD, depending on the medium type. or 20xBD, depending on the medium type.
@* @*
MMC drives usually activate their own idea of speed and take MMC drives usually activate their own idea of speed and take the speed value
the speed value given by the burn program only as hint given by the burn program only as hint for their own decision. Friendly drives
for their own decision. adjust their constant angular velocity so that the desired speed is reached
at the outer rim of the medium. 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
software 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.
Setting "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
enables short times of higher speed to compensate short times of low speed.
Prefix "soft_corr:" sets this 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 function cannot be compensated.
@*
Examples (combinable):
@*
-read_speed 6xBD
@*
-read_speed soft_force:4xBD -read_speed soft_corr:100000
@c man .TP @c man .TP
@item -load entity id @item -load entity id
@kindex -load addresses a particular session as input @kindex -load addresses a particular session as input
@cindex Session, select as input, -load @cindex Session, select as input, -load
Load a particular (possibly outdated) ISO session from -dev or -indev. Load a particular (possibly outdated) ISO session from -dev or -indev.
Usually all available sessions are shown with command -toc. Usually all available sessions are shown with command -toc.
@* @*
entity depicts the kind of addressing. id depicts the particular entity depicts the kind of addressing. id depicts the particular
address. The following entities are defined: address. The following entities are defined:
@* @*
skipping to change at line 1241 skipping to change at line 1264
each single data file. If enabled then images with checksum tags get loaded each single data file. If enabled then images with checksum tags get loaded
only if the tags of superblock and directory tree match properly. The MD5 only if the tags of superblock and directory tree match properly. The MD5
checksums of data files and whole session get loaded from the image if there checksums of data files and whole session get loaded from the image if there
are any. are any.
@* @*
With commands -compare and -update the recorded MD5 of a file 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 will be used to avoid content reading from the image. Only the disk file
content will be read and compared with that MD5. This can save much time content will be read and compared with that MD5. This can save much time
if -disk_dev_ino "on" is not suitable. if -disk_dev_ino "on" is not suitable.
@* @*
Commands which copy whole data files from ISO to hard disk will verify the
copied data stream by the recorded MD5, if -osirrox "check_md5_on" is set.
@*
At image generation time they are computed for each file which gets its data At image generation time they are computed for each file which gets its data
written into the new session. The checksums of files which have their data written into the new session. The checksums of files which have their data
in older sessions get copied into the new session. Superblock, tree and whole in older sessions get copied into the new session. Superblock, tree and whole
session get a checksum tag each. session get a checksum tag each.
@* @*
Mode "all" will additionally check during image generation whether the checksum Mode "all" will additionally check during image generation whether the checksum
of a data file changed between the time when its reading began and the time of a data file changed between the time when its reading began and the time
when it ended. This implies reading every file twice. when it ended. This implies reading every file twice.
@* @*
Mode "load_check_off" together with "on" or "all" will load recorded MD5 sums Mode "load_check_off" together with "on" or "all" will load recorded MD5 sums
skipping to change at line 1283 skipping to change at line 1309
such attributes. At recording time, xorriso will try to tolerate missing such attributes. At recording time, xorriso will try to tolerate missing
privileges and just record what is readable. privileges and just record what is readable.
But at restore time, missing privileges will cause failure events. But at restore time, missing privileges will cause failure events.
@* @*
Command -xattr "user" after command -for_backup excludes non-user attributes Command -xattr "user" after command -for_backup excludes non-user attributes
from being recorded or restored. from being recorded or restored.
@c man .TP @c man .TP
@item -ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase" @item -ecma119_map "stripped"|"unmapped"|"lowercase"|"uppercase"
@kindex -ecma119_map names w/o Rock Ridge, Joliet @kindex -ecma119_map names w/o Rock Ridge, Joliet
@cindex File names, if neither Rock Ridge nor Joliet @cindex File names, if neither Rock Ridge nor Joliet
Choose the conversion of file names from the loaded session if neither Choose the conversion of file names when a session gets loaded, if they stem
a Rock Ridge name nor a Joliet name was read from the session. neither from a Rock Ridge name nor from a Joliet name.
@* @*
Mode "stripped" is the default. It shows the names as found in the ISO but Mode "stripped" is the default. It shows the names as found in the ISO but
removes trailing ";1" or ".;1" if present. removes trailing ";1" or ".;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 letters to Mode "lowercase" is like "stripped" but also maps uppercase letters to
lowercase letters. This is compatible to default GNU/Linux mount behavior. lowercase letters. This is compatible to default GNU/Linux mount behavior.
@* @*
Mode "uppercase" is like "stripped" but maps lowercase letters to uppercase, Mode "uppercase" is like "stripped" but maps lowercase letters to uppercase,
if any occur despite the prescriptions of ECMA-119. if any occur despite the prescriptions of ECMA-119.
@c man .TP @c man .TP
@item -joliet_map "stripped"|"unmapped"
@kindex -joliet_map Joliet names
@cindex File names, if Joliet is loaded
Choose the conversion of file names when a session gets loaded from 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".
@c man .TP
@item -iso_nowtime "dynamic"|timestring @item -iso_nowtime "dynamic"|timestring
@kindex -iso_nowtime fixed "now" time for ISO 9660 objects @kindex -iso_nowtime fixed "now" time for ISO 9660 objects
@cindex libisofs, fixed "now" time @cindex libisofs, fixed "now" time
Choose whether to use the current time ("dynamic") or a fixed time point 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 timestamps of ISO 9660 nodes without a disk source file and as default
for superblock timestamps. for superblock timestamps.
@* @*
If a timestring is given, then it is used for such timestamps. For the formats If a timestring is given, then it is used for such timestamps. For the formats
of timestrings see command @strong{-alter_date}. of timestrings see command @strong{-alter_date}.
@c man .TP @c man .TP
skipping to change at line 1378 skipping to change at line 1416
If you expect such names in or under disk_paths and plan to mount the ISO If you expect such names in or under disk_paths and plan to mount the ISO
by such Linux kernels, consider to set -file_name_limit 253. by such Linux kernels, consider to set -file_name_limit 253.
Else just avoid names longer than 253 characters. Else just avoid names longer than 253 characters.
@c man .TP @c man .TP
@item -rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"] @item -rom_toc_scan "on"|"force"|"off"[:"emul_off"][:"emul_wide"]
@kindex -rom_toc_scan searches for sessions @kindex -rom_toc_scan searches for sessions
@cindex Table-of-content, search sessions, -rom_toc_scan @cindex Table-of-content, search sessions, -rom_toc_scan
Read-only drives do not tell the actual media type but show any media as Read-only drives do not tell the actual media type but show any media as
ROM (e.g. as DVD-ROM). The session history of MMC multi-session media might ROM (e.g. as DVD-ROM). The session history of MMC multi-session media might
be truncated to first and last session or even be completely false. be truncated to first and last session or even be completely false.
(The emulated history of overwriteable media is not affected by this.) (The emulated history of overwritable media is not affected by this.)
@* @*
To have in case of failure a chance of getting the session history and To have in case of failure a chance of getting the session history and
especially the address of the last session, there is a scan for ISO 9660 especially the address of the last session, there is a scan for ISO 9660
filesystem headers which might help but also might yield worse results filesystem headers which might help but also might yield worse results
than the drive's table of content. At its end it can cause read attempts than the drive's table of content. At its end it can cause read attempts
to invalid addresses and thus ugly drive behavior. to invalid addresses and thus ugly drive behavior.
Setting "on" enables that scan for alleged read-only media. Setting "on" enables that scan for alleged read-only media.
@* @*
Some operating systems are not able to mount the most recent session of Some operating systems are not able to mount the most recent session of
multi-session DVD or BD. If on such a system @command{xorriso} has no own MMC multi-session DVD or BD. If on such a system @command{xorriso} has no own MMC
capabilities then it may still find that session from a scanned table of capabilities then it may still find that session from a scanned table of
content. Setting "force" handles any media like a ROM medium with setting "on". content. Setting "force" handles any media like a ROM medium with setting "on".
@* @*
On the other hand the emulation of session history on overwriteable media On the other hand the emulation of session history on overwritable media
can hamper reading of partly damaged media. Setting "off:emul_off" disables can hamper reading of partly damaged media. Setting "off:emul_off" disables
the elsewise trustworthy table-of-content scan for those media. the elsewise trustworthy table-of-content scan for those media.
@* @*
The table-of-content scan on overwriteable media normally searches only up to The table-of-content scan on overwritable media normally searches only up to
the end of the session that is pointed to by the superblock at block 0. the end of the session that is pointed to by the superblock at block 0.
Setting "on:emul_wide" lets the scan continue up to the end of the medium. Setting "on:emul_wide" lets the scan continue up to the end of the medium.
This may be useful after copying a medium with -check_media patch_lba0=on This may be useful after copying a medium with -check_media patch_lba0=on
when not the last session was loaded. when not the last session was loaded.
@c man .TP @c man .TP
@item -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" @item -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
@kindex -calm_drive reduces drive activity @kindex -calm_drive reduces drive activity
@cindex Drive, reduce activity, -calm_drive @cindex Drive, reduce activity, -calm_drive
Reduce drive noise until it is actually used again. Some drives stay alert Reduce drive noise until it is actually used again. Some drives stay alert
for substantial time after they have been used for reading. This reduces for substantial time after they have been used for reading. This reduces
skipping to change at line 1431 skipping to change at line 1469
Once set, this command cannot be revoked. Once set, this command cannot be revoked.
@c man .TP @c man .TP
@item -early_stdio_test "on"|"appendable_wo"|"off" @item -early_stdio_test "on"|"appendable_wo"|"off"
@kindex -early_stdio_test classifies stdio drives @kindex -early_stdio_test classifies stdio drives
@cindex Drive, classify stdio, -early_stdio_test @cindex Drive, classify stdio, -early_stdio_test
If enabled by "on" then regular files and block devices get tested for If enabled by "on" then regular files and block devices get tested for
effective access permissions. This implies to try opening those files for effective access permissions. This implies to try opening those files for
writing, which otherwise will happen only later and only if actual writing, which otherwise will happen only later and only if actual
writing is desired. writing is desired.
@* @*
The test result is used for classifying the pseudo drives as overwriteable, The test result is used for classifying the pseudo drives as overwritable,
read-only, write-only, or uselessly empty. This may lead to earlier detection read-only, write-only, or uselessly empty. This may lead to earlier detection
of severe problems, and may avoid some less severe error events. of severe problems, and may avoid some less severe error events.
@* @*
Mode "appendable_wo" is like "on" with the additional property that Mode "appendable_wo" is like "on" with the additional property that
non-empty write-only files are regarded as appendable rather than blank. non-empty write-only files are regarded as appendable rather than blank.
@c man .TP @c man .TP
@item -data_cache_size number_of_tiles blocks_per_tile @item -data_cache_size number_of_tiles blocks_per_tile
@kindex -data_cache_size adjusts read cache size @kindex -data_cache_size adjusts read cache size
@cindex Image reading, cache size, -data_cache_size @cindex Image reading, cache size, -data_cache_size
Set the size and granularity of the data cache which is used when ISO images Set the size and granularity of the data cache which is used when ISO images
skipping to change at line 2982 skipping to change at line 3020
@kindex -blank erases media @kindex -blank erases media
@cindex Media, erase, -blank @cindex Media, erase, -blank
Make media ready for writing from scratch (if not -dummy is activated). Make media ready for writing from scratch (if not -dummy is activated).
@* @*
This affects only the -outdev not the -indev. This affects only the -outdev not the -indev.
If both drives are the same and if the ISO image was altered If both drives are the same and if the ISO image was altered
then this command leads to a FAILURE event. then this command leads to a FAILURE event.
Defined modes are: 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 overwriteable media "as_needed" cares for used CD-RW, DVD-RW and for used overwritable media
by applying -blank "fast". It applies -format "full" to yet unformatted by applying -blank "fast". It applies -format "full" to yet unformatted
DVD-RAM and BD-RE. Other media in blank state are gracefully ignored. DVD-RAM and BD-RE. Other media in blank state are gracefully ignored.
Media which cannot be made ready for writing from scratch cause a FAILURE Media which cannot be made ready for writing from scratch cause a FAILURE
event. event.
@* @*
"fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates "fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates
overwriteable ISO images. "all" might work more thoroughly and need more time. overwritable ISO images. "all" 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 "deformat_quickest" is a faster way to deformat or blank DVD-RW
but produces media which are only suitable for a single session. but produces media which are only suitable for a single session.
Some drives announce this state by not offering feature 21h, Some drives announce this state by not offering feature 21h,
but some drives offer it anyway. but some drives offer it anyway.
If feature 21h is missing, then @command{xorriso} If feature 21h is missing, then @command{xorriso}
will refuse to write on DVD-RW if not command -close is set to "on". will refuse to write on DVD-RW if not command -close is set to "on".
@* @*
The progress reports issued by some drives while blanking are The progress reports issued by some drives while blanking are
quite unrealistic. Do not conclude success or failure from the quite unrealistic. Do not conclude success or failure from the
skipping to change at line 3013 skipping to change at line 3051
worse occurred. worse occurred.
@* @*
Mode may be prepended by "force:" in order to override the evaluation Mode may be prepended by "force:" in order to override the evaluation
of the medium state by libburn. E.g. "force:fast". of the medium state by libburn. E.g. "force:fast".
Blanking will nevertheless only succeed if the drive is willing to do it. Blanking will nevertheless only succeed if the drive is willing to do it.
@* @*
@c man .TP @c man .TP
@item -format mode @item -format mode
@kindex -format formats media @kindex -format formats media
@cindex Media, format, -format @cindex Media, format, -format
Convert unformatted DVD-RW into overwriteable ones, "de-ice" DVD+RW, format Convert unformatted DVD-RW into overwritable ones, "de-ice" DVD+RW, format
newly purchased BD-RE or BD-R, re-format DVD-RAM or BD-RE. newly purchased BD-RE or 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 blank "as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or blank
unformatted BD-R. Other media are left untouched. unformatted BD-R. Other media are left untouched.
@* @*
skipping to change at line 3111 skipping to change at line 3149
@* @*
Only if the drive reports contradicting speed information there will appear Only if the drive reports contradicting speed information there will appear
"Write speed 0", which tells the outcome of speed selection by command "Write speed 0", which tells the outcome of speed selection by command
-speed 0, if it deviates from "Write speed H". -speed 0, if it deviates from "Write speed H".
@* @*
"Read speed L" and "Read speed H" tell the minimum and maximum read speeds, "Read speed L" and "Read speed H" tell the minimum and maximum read speeds,
as reported by the drive. They would be chosen by -read_speed "min" or as reported by the drive. They would be chosen by -read_speed "min" or
"max" if they undercut or surpass the built-in limits. These are "1x", "max" if they undercut or surpass the built-in limits. These are "1x",
"52xCD", "24xDVD", "20xBD". "52xCD", "24xDVD", "20xBD".
@c man .TP @c man .TP
@item -list_profiles "in"|"out"|"all"
@kindex -list_profiles lists supported media
@cindex Drive, list supported media, -list_profiles
Put out a list of media types supported by -indev, -outdev, or both,
respectively.
The currently recognized type is marked by text "(current)".
@c man .TP
@item -truncate_overwritable entity id adjust
@kindex -truncate_overwritable activates older session
@cindex Older session, activate, -truncate_overwritable
On overwritable medium copy the volume descriptors of an existing session to
the overall descriptors at LBA 0 ff. This makes all sessions
@strong{inaccessible} which are younger than the activated one.
A reason to do this would be read errors in the younger sessions and
the wish to re-write or skip them.
@*
This operation is only allowed if no changes to the loaded filesystem 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 with command -load.
They choose the existing ISO session which shall become the youngest accessible
session. Available entity names are "session", "track", "lba", "sbsector",
"volid". "auto" makes few sense. id is a number or search text as appropriate
for the given entity.
@*
Parameter "adjust" controls the claimed size of the activated session. Text
"new" means the size of the newly activated session as it was before this
command. I.e. the 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 session.
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 added 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 useless part of
session 4:
@*
-truncate_overwritable session 4 old
@*
Let session 4 claim additional 500 MiB as useless data:
@*
-truncate_overwritable session 4 +500m
@c man .TP
@item -close_damaged "as_needed"|"force" @item -close_damaged "as_needed"|"force"
@kindex -close_damaged closes damaged track and session @kindex -close_damaged closes damaged track and session
@cindex Damaged track and session, close, -close_damaged @cindex Damaged track and session, close, -close_damaged
Try to close the upcoming track and session if the drive reported the medium Try to close the upcoming track and session if the drive reported the medium
as damaged. This may apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL, as damaged. This may apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL,
or BD-R media. It is indicated by warning messages when the drive gets or BD-R media. It is indicated by warning messages when the drive gets
acquired, and by a remark "but next track is damaged" with the line acquired, and by a remark "but next 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 Mode "as_needed" gracefully refuses on media which are not reported as
damaged. Mode "force" attempts the close operation even with media which damaged. Mode "force" attempts the close operation even with media which
appear undamaged. appear undamaged.
@* @*
No image changes are allowed to be pending before this command is performed. No image changes are allowed to be pending before this command is performed.
After closing was attempted, both drives are given up. After closing was attempted, both drives are given up.
@c man .TP
@item -list_profiles "in"|"out"|"all"
@kindex -list_profiles lists supported media
@cindex Drive, list supported media, -list_profiles
Put out a list of media types supported by -indev, -outdev, or both,
respectively.
The currently recognized type is marked by text "(current)".
@end table @end table
@c man .TP @c man .TP
@c man .B Settings for result writing: @c man .B Settings for result writing:
@node SetWrite, Bootable, Writing, Commands @node SetWrite, Bootable, Writing, Commands
@section Settings for result writing @section Settings for result writing
@c man .PP @c man .PP
Rock Ridge info will be generated by default. Rock Ridge info will be generated by default.
ACLs will be written according to the setting of command -acl. ACLs will be written according to the setting of command -acl.
@table @asis @table @asis
@sp 1 @sp 1
skipping to change at line 3193 skipping to change at line 3279
Information about HFS creator, type, and blessings gets stored by xorriso 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 if -hfsplus is enabled at -commit time. It is stored as copy outside the
HFS+ partition, but rather along with the Rock Ridge information. HFS+ partition, but rather along with the Rock Ridge information.
xorriso does not read any information from the HFS+ meta data. xorriso does not read any information from the HFS+ meta data.
@* @*
Be aware that HFS+ is case-insensitive although it can record file names Be aware that HFS+ is case-insensitive although it can record file names
with upper-case and lower-case letters. Therefore, file names from the iso_rr with upper-case and lower-case letters. Therefore, file names from the iso_rr
name tree may collide in the HFS+ name tree. In this case they get changed name tree may collide in the HFS+ name tree. In this case they get changed
by adding underscore characters and counting numbers. In case of very long by adding underscore characters and counting numbers. In case of very long
names, it might be necessary to map them to "MANGLED_...". names, it might be necessary to map them to "MANGLED_...".
@*
WARNING:
@*
The HFS+ implementation in libisofs has a limit of 125,829,120 bytes for the
size of the overall directory tree. This suffices for about 300,000 files
of normal name length. If the limit gets exceeded, a FAILURE event will be
issued and the ISO production will not happen.
@sp 1 @sp 1
@c man .TP @c man .TP
@item -rockridge "on"|"off" @item -rockridge "on"|"off"
@kindex -rockridge disables production of Rock Ridge info @kindex -rockridge disables production of Rock Ridge info
@cindex Write, disable Rock Ridge, -rockridge @cindex Write, disable Rock Ridge, -rockridge
Mode "off" disables production of Rock Ridge information for the ISO 9660 file Mode "off" disables production of Rock Ridge information for the ISO 9660 file
objects. The multi-session capabilities of xorriso depend much on the naming objects. The multi-session capabilities of xorriso depend much on the naming
fidelity of Rock Ridge. So it is strongly discouraged to deviate from fidelity of Rock Ridge. So it is strongly discouraged to deviate from
default setting "on". default setting "on".
@c man .TP @c man .TP
skipping to change at line 3293 skipping to change at line 3386
"new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux but not for older "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 FreeBSD or for Solaris). This implies "aaip_susp_1_10_off" which may be changed
by subsequent "aaip_susp_1_10". by subsequent "aaip_susp_1_10".
@* @*
Default is "old_rr" which uses Rock Ridge version 1.10. This implies also Default is "old_rr" which uses Rock Ridge version 1.10. This implies also
"aaip_susp_1_10" which may be changed by subsequent "aaip_susp_1_10_off". "aaip_susp_1_10" which may be changed by subsequent "aaip_susp_1_10_off".
@* @*
"aaip_susp_1_10" allows AAIP to be written as unofficial extension of RRIP "aaip_susp_1_10" allows AAIP to be written as unofficial extension of RRIP
rather than as official extension under SUSP-1.12. rather than as official extension under SUSP-1.12.
@* @*
"no_emul_toc" saves 64 kB with the first session on overwriteable media "no_emul_toc" saves 64 kB with the first session on overwritable media
but makes the image incapable of displaying its session history. but makes the image incapable of displaying its session history.
@* @*
"iso_9660_1999" causes the production of an additional directory tree "iso_9660_1999" causes the production of an additional directory tree
compliant to ISO 9660:1999. It can record long filenames for readers which compliant to ISO 9660:1999. It can record long filenames for readers which
do not understand Rock Ridge. do not understand Rock Ridge.
@* @*
"old_empty" uses the old way of of giving block addresses in the range "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 of [0,31] to files with no own data content. The new way is to have
a dedicated block to which all such files will point. a dedicated block to which all such files will point.
@* @*
skipping to change at line 3476 skipping to change at line 3569
@c man .TP @c man .TP
@item -biblio_file text @item -biblio_file text
@kindex -biblio_file sets biblio file name @kindex -biblio_file sets biblio file name
@cindex Image, set biblio file name, -biblio_file @cindex Image, set biblio file name, -biblio_file
Set the biblio file name to be written with the next -commit. This should 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 be the ISO 9660 path of a file in the image which contains bibliographic
records. records.
Permissible are up to 37 characters. This setting gets overridden by Permissible are up to 37 characters. This setting gets overridden by
image loading. image loading.
@c man .TP @c man .TP
@item -preparer_id @item -preparer_id text
@kindex -preparer_id sets preparer id @kindex -preparer_id sets preparer id
@cindex Image, set preparer id, -preparer_id @cindex Image, set preparer id, -preparer_id
Set the preparer ID string to be written with the next -commit. This may Set the preparer ID string to be written with the next -commit. This may
identify the person or other entity which controls the preparation of the data identify the person or other entity which controls the preparation of the data
which shall be recorded. Normally this should be the ID of @command{xorriso} which shall be recorded. Normally this should be the ID of @command{xorriso}
and not of the person or program which operates @command{xorriso}. and not of the person or program which operates @command{xorriso}.
Please avoid to change it. Permissible are up to 128 characters. Please avoid to change it. Permissible are up to 128 characters.
@* @*
The special text "@@xorriso@@" gets converted to the ID string of The special text "@@xorriso@@" gets converted to the ID string of
@command{xorriso} which is default at program startup. @command{xorriso} which is default at program startup.
skipping to change at line 3525 skipping to change at line 3618
@item -uid uid @item -uid uid
@kindex -uid sets global ownership @kindex -uid sets global ownership
@cindex Ownership, global in ISO image, -uid @cindex Ownership, global in ISO image, -uid
User id to be used for all files when the new ISO tree gets written to media. User id to be used for all files when the new ISO tree gets written to media.
@c man .TP @c man .TP
@item -gid gid @item -gid gid
@kindex -gid sets global ownership @kindex -gid sets global ownership
@cindex Group, global in ISO image, -gid @cindex Group, global in ISO image, -gid
Group id to be used for all files when the new ISO tree gets written to media. Group id to be used for all files when the new ISO tree gets written to media.
@c man .TP @c man .TP
@item -zisofs option[:options] @item -zisofs parameter[:parameters]
@kindex -zisofs controls zisofs production @kindex -zisofs controls zisofs production
@cindex Filter, zisofs parameters, -zisofs @cindex Filter, zisofs parameters, -zisofs
Set global parameters for zisofs compression. This data format is recognized Set global parameters for zisofs compression. This data format is recognized
and transparently uncompressed by some Linux kernels. It is to be applied and transparently uncompressed by some Linux kernels. It is to be applied
via command -set_filter with built-in filter "@minus{}@minus{}zisofs". via command -set_filter with built-in filter "@minus{}@minus{}zisofs".
@*
Note: This command is only permitted while no --zisofs filters are applied to
any files.
@*
Parameters are: 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 "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 files from disk whether they already are zisofs compressed, e.g. by program
mkzftree. mkzftree. "by_magic=v2" enables processing of already zisofs2 compressed files
additionally to those of zisofs version 1. "by_magic=off" disables both.
@* @*
"default" same as "level=6:block_size=32k:by_magic=off" "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 not yet know this format and will complain like
@*
isofs: Unknown ZF compression algorithm: PZ
@*
The files will then appear in their compressed form with zisofs2 header,
block pointer list, and compressed data.
@*
zisofs2 is recognized by xorriso in files from loaded images and gets equipped
with --zisofs-decode filters, unless restrictions on the number of
block pointers prevent this.
@*
Mode "off" restricts compression to files smaller than 4 GiB uncompressed size.
Mode "as_needed" uses zisofs2 for larger files. Mode "on" uses zisofs2 for all
zisofs 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 compression 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 they 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 block pointer
memory. Block pointers occupy virtual memory while a file gets uncompressed
and while a file, 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 of 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 block
pointer list of a single file. max_bpt_f is never larger than max_bpt.
If either is set 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 max_bpt_f=.
@*
"bpt_free_ratio="-1|0.0...1.0 sets a threshold for switching to block
pointer discarding during compression. If less than the given fraction of the
max_bpt_f= memory is free, then block pointers of compression filters get
discarded immediately after being added. Value -1 disables this feature.
@*
"default" is the same as "level=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".
@c man .TP @c man .TP
@item -speed code|number[k|m|c|d|b] @item -speed code|number[k|m|c|d|b]
@kindex -speed set write speed @kindex -speed set write speed
@cindex Write, set speed, -speed @cindex Write, set speed, -speed
Set the burn speed. Default is "max" (or "0") = maximum speed as announced Set the burn speed. Default is "max" (or "0") = maximum speed as announced
by the drive. by the drive.
Further special speed codes are: Further 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.
@* @*
skipping to change at line 3740 skipping to change at line 3903
written as part of the image. written as part of the image.
The same effect is achieved by -padding mode "included". The same effect is achieved by -padding mode "included".
@end table @end table
@c man .TP @c man .TP
@c man .B Bootable ISO images: @c man .B Bootable ISO images:
@node Bootable, Jigdo, SetWrite, Commands @node Bootable, Jigdo, SetWrite, Commands
@section Bootable ISO images @section Bootable ISO images
@c man .PP @c man .PP
Contrary to published specifications many BIOSes will load an El Torito Contrary to published specifications many BIOSes will load an El Torito
record from the first session on media and not from the last one, which record from the first session on media and not from the last one, which
gets mounted by default. This makes no problems with overwriteable media, gets mounted by default. This makes no problems with overwritable media,
because they appear to inadverted readers as one single session. 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 But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that the
whole bootable system has to reside already in the first session and that whole bootable system has to reside already in the first session and that
the last session still has to bear all files which the booted system expects the last session still has to bear all files which the booted system expects
after mounting the ISO image. after mounting the ISO image.
@* @*
If a boot image from ISOLINUX or GRUB is known to be present on media then If a boot image from ISOLINUX or GRUB is known to be present on media then
it is advised to patch it it is advised to patch it
when a follow-up session gets written. But one should not rely on the when a follow-up session gets written. But one should not rely on the
capability to influence the bootability of the existing sessions, unless one capability to influence the bootability of the existing sessions, unless one
can assume overwriteable media. can assume overwritable media.
@* @*
Normally the boot images are data files inside the ISO filesystem. By Normally the boot images are data files inside the ISO filesystem. By
special path "--interval:appended_partition_NNN:all::" it is possible to special path "--interval:appended_partition_NNN:all::" it is possible to
refer to an appended partition. The number NNN gives the partition number refer to an appended partition. The number NNN gives the partition number
as used with the corresponding command -append_partition. as used with the corresponding command -append_partition.
E.g.: 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::
skipping to change at line 4024 skipping to change at line 4187
@strong{-boot_image isolinux system_area=} implies "partition_table=on". @strong{-boot_image isolinux system_area=} implies "partition_table=on".
In this case, the disk path should lead to one of the SYSLINUX files In this case, the disk path should lead to one of the SYSLINUX files
isohdp[fp]x*.bin or to a file which was derived from one of those files. isohdp[fp]x*.bin or to a file which was derived from one of those files.
E.g. to the first 512 bytes from an ISOLINUX isohybrid ISO image. 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_path=)
may be augmented by may be augmented by
@strong{isolinux partition_entry=gpt_basdat} @strong{isolinux partition_entry=gpt_basdat}
or @strong{isolinux partition_entry=gpt_hfsplus}, or @strong{isolinux partition_entry=gpt_hfsplus},
and by @strong{isolinux partition_entry=apm_hfsplus}. and by @strong{isolinux partition_entry=apm_hfsplus}.
The boot image will then be mentioned in GPT as Basic Data The boot image will then be mentioned in an invalid GPT as Basic Data
or GPT HFS+ partition, and in APM as HFS+ partition. or GPT HFS+ partition, and in a valid APM as HFS+ partition.
The first three GPT partitions will also be marked by MBR partitions. The first three GPT partitions will also be marked by MBR partitions. The
MBR partition of type 0xEF 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 multi-session situations the existing System Area is preserved by default.
In in this case, the special disk_path "." prevents reading of In in this case, the special disk_path "." prevents reading of
a disk file but nevertheless causes adjustments in the a disk file but nevertheless causes adjustments in the
loaded system area data. Such adjustments may get ordered by -boot_image loaded system area data. Such adjustments may get ordered by -boot_image
commands. commands.
@* @*
@cindex GPT, control GUID, -boot_image gpt_disk_guid= @cindex GPT, control GUID, -boot_image gpt_disk_guid=
@strong{-boot_image any gpt_disk_guid=}value controls whether an emerging GPT @strong{-boot_image any gpt_disk_guid=}value controls whether an emerging GPT
shall get a randomly generated disk GUID or whether the GUID is supplied by shall get a randomly generated disk GUID or whether the GUID is supplied by
skipping to change at line 4318 skipping to change at line 4483
The type_code may be "FAT12", "FAT16", "Linux", The type_code may be "FAT12", "FAT16", "Linux",
or a hexadecimal number between 0x00 and 0xff. Not all those numbers will or a hexadecimal number between 0x00 and 0xff. Not all those numbers will
yield usable results. For a list of MBR partition type codes search the yield usable results. For a list of MBR 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 type_code may also be a type GUID as plain hex string like
a2a0d0ebe5b9334487c068b6b72699c7 or as structured text like a2a0d0ebe5b9334487c068b6b72699c7 or as structured text like
EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the partition is EBD0A0A2-B9E5-4433-87C0-68B6B72699C7. It will be used if the partition is
mentioned in GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped mentioned in GPT. In MBR, C12A7328-F81F-11D2-BA4B-00A0C93EC93B will be mapped
to 0xef. Any other GUID will be mapped to 0x83. to 0xef. Any other GUID will be mapped to 0x83.
In APM, 48465300-0000-11AA-AA11-00306543ECAC will be mapped to partition
type "Apple_HFS", any other to "Data".
@* @*
If some other command causes the production of GPT, then the appended If some other command causes the production of GPT, then the appended
partitions will be mentioned there too. partitions will be mentioned there too.
@* @*
The disk_path must provide the necessary data bytes at commit time. The disk_path must provide the necessary data bytes at commit time.
An empty disk_path disables this feature for the given partition number. An empty disk_path disables this feature for the given partition number.
@* @*
@cindex SUN SPARC boot images, activation @cindex SUN SPARC boot images, activation
With SUN Disk Label (selected by -boot_image any sparc_label=): With SUN Disk Label (selected by -boot_image any sparc_label=):
@* @*
skipping to change at line 4354 skipping to change at line 4521
and DVD ISO images are published on the web in jigdo format to allow and DVD ISO images are published on the web in jigdo format to allow
end users to download them more efficiently." end users to download them more efficiently."
@* @*
@command{xorriso} can produce a .jigdo and a .template file together with a @command{xorriso} can produce a .jigdo and a .template file together with a
single-session ISO image. single-session ISO image.
The .jigdo file contains checksums and symbolic file addresses. The .jigdo file contains checksums and symbolic file addresses.
The .template file contains the compressed ISO image with reference tags The .template file contains the compressed ISO image with reference tags
instead of the content bytes of the listed files. instead of the content bytes of the listed files.
@* @*
Input for this process are the normal arguments for a @command{xorriso} session Input for this process are the normal arguments for a @command{xorriso} session
on a blank -outdev, and a .md5 file which lists those data files which may be on a blank -outdev, and a checksum file which lists those data files which may
listed in the .jigdo file and externally referenced in the .template file. be listed in the .jigdo file and externally referenced in the .template file.
Each designated file is represented in the .md5 file by a single text line: Each designated file is represented in the checksum file by a single text line:
@* @*
MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks, Checksum as hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks,
symbolic file address symbolic file address
@* @*
The file address in an .md5 line has to bear the same basename as the The kind of checksum is chosen by -jigdo "checksum_algorithm" with values "md5"
(32 hex digits) or "sha256" (64 hex digits).
It will also be used for the file address lines in the .jigdo file.
The default is "md5".
@*
The file address in a checksum file line has to bear the same basename as the
disk_path of the file which it shall match. The directory path of disk_path of the file which it shall match. The directory path of
the file address is decisive for To=From mapping, not for file recognition. the file address is decisive for To=From mapping, not for file recognition.
After To=From mapping, the file address gets written into the .jigdo After To=From mapping, the file address gets written into the .jigdo
file. Jigdo restore tools will convert these addresses into really file. Jigdo restore tools will convert these addresses into really
reachable data source addresses from which they can read. reachable data source addresses from which they can read.
@* @*
If the list of jigdo parameters is not empty, then @command{xorriso} will If the list of jigdo parameters is not empty, then @command{xorriso} will
refuse to refuse to
write to non-blank targets, it will disable multi-session emulation, and write to non-blank targets, it will disable multi-session emulation, and
padding will be counted as part of the ISO image. padding will be counted as part of the ISO image.
skipping to change at line 4387 skipping to change at line 4559
@kindex -jigdo clears JTE or or adds parameter to JTE @kindex -jigdo clears JTE or or adds parameter to JTE
@cindex Jigdo Template Extraction, -jigdo @cindex Jigdo Template Extraction, -jigdo
Clear Jigdo Template Extraction parameter list or add a parameter to that list. Clear Jigdo Template Extraction parameter list or add a parameter to that list.
The alias names are the corresponding genisoimage options. They are accepted The alias names are the corresponding genisoimage options. They are accepted
as parameter names as well. Especially they are recognized by the -as mkisofs as parameter names as well. Especially they are recognized by the -as mkisofs
emulation command. emulation command.
@* @*
Parameter @strong{clear} with any value empties the whole list. Parameter @strong{clear} with any value empties the whole list.
No .jigdo and .template file will be produced. No .jigdo and .template file will be produced.
@* @*
@strong{checksum_algorithm} chooses the checksum algorithm which shall be used
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
@*
@strong{template_path} sets the disk_path for the .template file with the @strong{template_path} sets the disk_path for the .template file with the
holed and compressed ISO image copy. holed and compressed ISO image copy.
@* @*
Alias: -jigdo-template Alias: -jigdo-template
@* @*
@strong{jigdo_path} sets the disk_path for the .jigdo file with the checksums @strong{jigdo_path} sets the disk_path for the .jigdo file with the checksums
and download addresses for filling the holes in .template. and download addresses for filling the holes in .template.
@* @*
Alias: -jigdo-jigdo Alias: -jigdo-jigdo
@* @*
@strong{md5_path} sets the disk_path where to find the .md5 input file. @strong{checksum_path} sets the disk_path where to find the checksum file with
symbolic file addresses and checksums according to @strong{checksum_algorithm}.
@*
Alias: md5_path
@*
Alias: -checksum-list
@* @*
Alias: -md5-list Alias: -md5-list
@* @*
@strong{min_size} sets the minimum size for a data file to be listed @strong{min_size} sets the minimum size for a data file to be listed
in the .jigdo file and being a hole in the .template file. in the .jigdo file and being a hole in the .template file.
@* @*
Alias: -jigdo-min-file-size Alias: -jigdo-min-file-size
@* @*
@strong{exclude} adds a regular expression pattern which will get compared @strong{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 with the absolute disk_path of any data file. A match causes the file to
stay in .template in any case. stay in .template in any case.
@* @*
Alias: -jigdo-exclude Alias: -jigdo-exclude
@* @*
@strong{demand_md5} adds a regular expression pattern which will get compared @strong{demand_checksum} adds a regular expression pattern which will get
with the absolute disk_path of any data file that was not found in the .md5 compared with the absolute disk_path of any data file that was not found
list. A match causes a MISHAP event. in the checksum list 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
@* @*
@strong{mapping} adds a string pair of the form To=From to the parameter list. @strong{mapping} adds a string pair of the form To=From to the parameter list.
If a data file gets listed in the .jigdo file, then it is referred by the If a data file gets listed in the .jigdo file, then it is referred by the
file address from its line in the .md5 file. This file address gets checked file address from its line in the checksum file. This file address gets checked
whether it begins with the From string. If so, then this string will be whether it begins with the From string. If so, then this string will be
replaced by the To string and a ':' character, before it goes into the .jigdo replaced by the To string and a ':' character, before it goes into the .jigdo
file. The From string should end by a '/' character. file. The From string should end by a '/' character.
@* @*
Alias: -jigdo-map Alias: -jigdo-map
@* @*
@strong{compression} chooses one of "bzip2" or "gzip" for the compression of @strong{compression} chooses one of "bzip2" or "gzip" for the compression of
the template file. The jigdo file is put out uncompressed. the template file. The jigdo file is put out uncompressed.
@* @*
Alias: -jigdo-template-compress Alias: -jigdo-template-compress
skipping to change at line 4801 skipping to change at line 4988
by "/dev/dvd" or "/dev/cd". by "/dev/dvd" or "/dev/cd".
Precedence is: "dvdrw", "cdrw", "dvd", "cdrom", "cd". Precedence is: "dvdrw", "cdrw", "dvd", "cdrom", "cd".
@c man .TP @c man .TP
@item -toc @item -toc
@* @*
@kindex -toc shows list of sessions @kindex -toc shows list of sessions
@cindex Table-of-content, show, -toc @cindex Table-of-content, show, -toc
Show media specific tables of content. This is the session history Show media specific tables of content. This is the session history
of the medium, not the ISO image directory tree. of the medium, not the ISO image directory tree.
@* @*
In case of overwriteable media holding a valid ISO image, it may happen that In case of overwritable media holding a valid ISO image, it may happen that
only a single session gets shown. But if the first session on the only a single session gets shown. But if the first session on the
overwriteable media was written by @command{xorriso} then a complete overwritable media was written by @command{xorriso} then a complete
session history can be emulated. session history can be emulated.
@* @*
A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM
with only one or two sessions on it. The last of these sessions is supposed with only one or two sessions on it. The last of these sessions is supposed
to be the most recent real session then. to be the most recent real session then.
@* @*
Some read-only drives and media show no usable session history at all. Some read-only drives and media show no usable session history at all.
Command -rom_toc_scan might help. Command -rom_toc_scan might help.
@* @*
If input device and output device are both acquired and not the same, If input device and output device are both acquired and not the same,
skipping to change at line 4888 skipping to change at line 5075
"%track%", "%session%", "%volid%" will be substituted by track number, "%track%", "%session%", "%volid%" will be substituted by track number,
session number, or volume id of the depicted session. session number, or volume id of the depicted session.
@c man .TP @c man .TP
@item -print_size @item -print_size
@kindex -print_size predicts image size @kindex -print_size predicts image size
@cindex Write, predict image size, -print_size @cindex Write, predict image size, -print_size
Print the foreseeable consumption of 2048 byte blocks Print the foreseeable consumption of 2048 byte blocks
by next -commit. This can last a while as a -commit gets by next -commit. This can last a while as a -commit gets
prepared and only in last moment is revoked by this command. prepared and only in last moment is revoked by this command.
The result depends on several settings and also on the kind of output device. The result depends on several settings and also on the kind of output device.
If no -jidgo options are set and not command -as "mkisofs" was used, If no -jigdo options are set and not command -as "mkisofs" was used,
then -padding (300 kB by default) is not counted as part of the image size. then -padding (300 kB by default) is not counted as part of the image size.
@* @*
If an El Torito boot image file is already depicted, then command -print_size If an El Torito boot image file is already depicted, then command -print_size
automatically executes -boot_image "any" "next". automatically executes -boot_image "any" "next".
This means that the properties of that boot image cannot be edited by This means that the properties of that boot image cannot be edited by
subsequent commands. subsequent commands.
@c man .TP @c man .TP
@item -tell_media_space @item -tell_media_space
@kindex -tell_media_space reports free space @kindex -tell_media_space reports free space
@cindex Write, free space, -tell_media_space @cindex Write, free space, -tell_media_space
skipping to change at line 5234 skipping to change at line 5421
Frequently used types are: Frequently 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 filters.
@*
--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'
@c man .TP @c man .TP
@item -show_stream_r iso_rr_path [***] @item -show_stream_r iso_rr_path [***]
@kindex -show_stream_r shows data source and filters @kindex -show_stream_r shows data source and filters
@cindex Filter, show chains of tree, -show_stream_r @cindex Filter, show chains of tree, -show_stream_r
Like -show_stream but working recursively. Like -show_stream but working recursively.
@end table @end table
@c man .TP @c man .TP
skipping to change at line 5377 skipping to change at line 5572
aborted. This is useful for unattended scanning of media which may else aborted. This is useful for unattended scanning of media which may else
overwork the drive in its effort to squeeze out some readable blocks. overwork the drive in its effort to squeeze out some readable blocks.
Abort may be delayed by the drive gnawing on the last single read operation. Abort may be delayed by the drive gnawing on the last single read operation.
Value -1 means unlimited time. Value -1 means unlimited time.
@* @*
@item item_limit=number @item item_limit=number
gives the number of report list items after which to abort. gives the number of report list items after which to abort.
Value -1 means unlimited item number. Value -1 means unlimited item number.
@* @*
@item data_to=disk_path @item data_to=disk_path
copies the valid blocks to the given file. copies the valid blocks to the given file, which must support random access
writing, unless disk_path is "-" which means standard output.
@*
In the latter case, patch_lba0= settings other than "off" yield failure.
Further the usual result messages of -check_media get redirected to the info
channel. But beware of result messages from other commands. Beware of -*dev "-"
which redirect standard output 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
@* @*
@item event=severity @item event=severity
sets the given severity for a problem event which shall be issued at sets the given severity for a problem event which shall be issued at
the end of a check run if data blocks were unreadable or failed to match the end of a check run if data blocks were unreadable or failed to match
recorded MD5 checksums. Severity "ALL" disables this event. recorded MD5 checksums. Severity "ALL" disables this event.
@* @*
@item sector_map=disk_path @item sector_map=disk_path
tries to read the file given by disk_path as tries to read the file given by disk_path as
sector bitmap and to store such a map file after the scan run. sector bitmap and to store such a map file after the scan run.
The bitmap tells which blocks have been read successfully in previous runs. The bitmap tells which blocks have been read successfully in previous runs.
skipping to change at line 5493 skipping to change at line 5699
of -overwrite "nondir". I.e. directories cannot be deleted. of -overwrite "nondir". I.e. directories cannot be deleted.
@* @*
Access permissions of files in the ISO image do not restrict restoring. Access permissions of files in the ISO image do not restrict restoring.
The directory permissions on disk have to allow rwx. The directory permissions on disk have to allow rwx.
@table @asis @table @asis
@sp 1 @sp 1
@c man .TP @c man .TP
@item -osirrox setting[:option:...] @item -osirrox setting[:option:...]
@kindex -osirrox enables ISO-to-disk copying @kindex -osirrox enables ISO-to-disk copying
@cindex Restore, enable ISO-to-disk, -osirrox @cindex Restore, enable ISO-to-disk, -osirrox
Setting "off" disables disk filesystem manipulations. This is the default Setting @strong{off} disables disk filesystem manipulations. This is the default
unless the program was started with leafname "osirrox". Elsewise unless the program was started with leafname @strong{osirrox}. Elsewise the
the capability to restore files can be enabled explicitly by -osirrox "on". capability to restore files can be enabled explicitly by -osirrox @strong{on}.
It can be irrevocably disabled by -osirrox "banned". It can be irrevocably disabled by -osirrox @strong{banned}.
@* @*
The setting "blocked" is like "off". But it can only be revoked by The setting @strong{blocked} is like @strong{off}. But it can only be revoked
setting "unblock", which elsewise is like "on". This can be used to curb by setting @strong{unblock}, which elsewise is like @strong{on}. This can be
command scripts which might use "on" undesiredly. used to curb command scripts which might use @strong{on} undesiredly.
@* @*
To enable restoring of special files by "device_files" is potentially To enable restoring of special files by @strong{device_files} is potentially
dangerous. dangerous.
The meaning of the number st_rdev (see man 2 stat) depends much on the The meaning of the number st_rdev (see man 2 stat) depends much on the
operating system. Best is to restore device files only to the same system operating system. Best is to restore device files only to the same system
from where they were copied. If not enabled, device files in the ISO image from where they were copied. If not enabled, device files in the ISO image
are ignored during restore operations. are ignored during restore operations.
@* @*
Due to a bug of previous versions, device files from previous sessions might Due to a bug of previous versions, device files from previous sessions might
have been altered to major=0, minor=1. So this combination does not get have been altered to major=0, minor=1. So this combination does not get
restored. restored.
@* @*
Option "concat_split_on" is default. It enables restoring of split file Option @strong{concat_split_on} is default. It enables restoring of split file
directories as data files if the directory contains a complete collection directories as data files if the directory contains a complete collection
of -cut_out part files. With option "concat_split_off" such directories are of -cut_out part files. With option @strong{concat_split_off} such directories
handled like any other ISO image directory. are handled like any other ISO image directory.
@* @*
Option "auto_chmod_off" is default. If "auto_chmod_on" is set then access Option @strong{auto_chmod_off} is default. If @strong{auto_chmod_on} is set
restrictions for disk directories get circumvented if those directories then access restrictions for disk directories get circumvented if those
are owned by the effective user who runs @command{xorriso}. This happens directories are owned by the effective user who runs @command{xorriso}.
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 drives. It Option @strong{sort_lba_on} may improve read performance with optical drives.
can restore large numbers of hard links without exhausting It can restore large numbers of hard links without exhausting
-temp_mem_limit. It does not preserve directory mtime and it needs -temp_mem_limit. It does not preserve directory mtime and it needs
-osirrox option auto_chmod_on in order to extract directories which offer no -osirrox option auto_chmod_on in order to extract directories which offer no
write permission. Default is "sort_lba_off". write permission. Default is @strong{sort_lba_off}.
@* @*
Option "o_excl_on" is the default unless the program was started with leafname Option @strong{o_excl_on} is the default unless the program was started with
"osirrox". On GNU/Linux it tries to avoid using drives which are mounted or in leafname "osirrox". On GNU/Linux it tries to avoid using drives which are
use by other libburn programs. mounted or in use by other libburn programs.
Option "o_excl_off" on GNU/Linux enables access to such drives by the Option @strong{o_excl_off} on GNU/Linux enables access to such drives by the
equivalent of -drive_access "shared:readonly". I.e. drives which equivalent of -drive_access "shared:readonly". I.e. drives which
get acquired while "o_excl_off" will refuse to get blanked, formatted, get acquired while @strong{o_excl_off} will refuse to get blanked, formatted,
written, or ejected. But be aware that even harmless inquiries can spoil written, or ejected. But be aware that even harmless inquiries can spoil
ongoing burns of CD-R[W] and DVD-R[W]. ongoing burns of CD-R[W] and DVD-R[W].
@* @*
Option "strict_acl_off" is default. It tolerates on FreeBSD the presence of Option @strong{strict_acl_off} is default. It tolerates on FreeBSD the presence
directory "default" ACLs in the ISO image. With "strict_acl_on" these of directory "default" ACLs in the ISO image.
GNU/Linux ACLs cause on FreeBSD a FAILURE event during restore with -acl "on". With @strong{strict_acl_on} these GNU/Linux ACLs cause on FreeBSD a FAILURE
event during restore with -acl "on".
@*
Option @strong{check_md5_off} disables MD5 checking during copy to disk.
The default option @strong{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 compared with the recorded MD5.
A mismatch causes an error message of severity SORRY.
Option @strong{check_md5_force} causes an error message if -md5 is "on"
but no MD5 is recorded for the data file.
@*
Option @strong{sparse=} controls production of sparse files during
extraction of files from the ISO filesystem.
Default is @strong{sparse=off}.
@*
A positive number like in @strong{sparse=1m} sets the minimum requirement
for the length of a sequence of 0-bytes which shall be represented by a gap.
This saves disk space if the disk filesystem supports sparse files.
A gap gets created by help of lseek(2) if a sequence of read buffers, which
contain only 0-bytes, bears at least the minimum amount of bytes. Expect
read buffers to be in the size range of 32k or 64k.
@*
Command -paste_in creates gaps only if the writing begins at or after the end
of the existing disk file. So the sequence of -paste_in commands matters.
Command -concat does not create sparse files.
@c man .TP @c man .TP
@item -extract iso_rr_path disk_path @item -extract iso_rr_path disk_path
@kindex -extract copies file tree to disk @kindex -extract copies file tree to disk
@cindex Restore, copy file tree to disk, -extract @cindex Restore, copy file tree to disk, -extract
Copy the file objects at and underneath iso_rr_path to their corresponding Copy the file objects at and underneath iso_rr_path to their corresponding
addresses at and underneath disk_path. addresses at and underneath disk_path.
This is the inverse of -map or -update_r. This is the inverse of -map or -update_r.
@* @*
If iso_rr_path is a directory and disk_path is an existing directory then If iso_rr_path is a directory and disk_path is an existing directory then
both trees will be merged. Directory attributes get extracted only if the disk both trees will be merged. Directory attributes get extracted only if the disk
skipping to change at line 5666 skipping to change at line 5896
@sp 1 @sp 1
-iso_rr_pattern on \ -iso_rr_pattern on \
@* @*
-concat pipe + /usr/bin/wc + "/my/iso/files*" -- -concat pipe + /usr/bin/wc + "/my/iso/files*" --
@* @*
@sp 1 @sp 1
The further parameters in all modes are the iso_rr_paths of data files. The further parameters in all modes are the iso_rr_paths of data files.
Their content gets concatenated in the copy. Their content gets concatenated in the copy.
@c man .TP @c man .TP
@item -extract_boot_images disk_path
@kindex -extract_boot_images copies boot equipment to disk
@cindex Restore, copy boot equipment to disk, -extract_boot_images
Copy boot equipment to disk, which is not necessarily represented as data files
in the ISO filesystem. The data get written into various files in a disk
directory, 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 present in the ISO filesystem. Existing files do not get overwritten but
rather cause a failure event.
@*
The same data may appear in different files. E.g. the El Torito 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 first "*" 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.
@c man .TP
@item -mount drive entity id path @item -mount drive entity id path
@kindex -mount issues mount command for ISO session @kindex -mount issues mount command for ISO session
@cindex Session, issue mount command, -mount @cindex Session, issue mount command, -mount
Produce the same line as -mount_cmd and then execute it as external program run Produce the same line as -mount_cmd and then execute it as external program run
after giving up the depicted drive. See also -mount_opts. after giving up the depicted drive. See also -mount_opts.
This demands -osirrox to be enabled and normally will succeed only for the This demands -osirrox to be enabled and normally will succeed only for the
superuser. For safety reasons the mount program is only executed if it is superuser. For safety reasons the mount program is only executed if it is
reachable as /bin/mount or /sbin/mount. reachable as /bin/mount or /sbin/mount.
@end table @end table
@c man .TP @c man .TP
skipping to change at line 5774 skipping to change at line 6043
@minus{}md5 can be set to "off" by @minus{}@minus{}old-root-no-md5 . @minus{}md5 can be set to "off" by @minus{}@minus{}old-root-no-md5 .
@* @*
Not original mkisofs options are @minus{}@minus{}quoted_path_list , Not original mkisofs options are @minus{}@minus{}quoted_path_list ,
@minus{}@minus{}hardlinks , @minus{}@minus{}acl , @minus{}@minus{}hardlinks , @minus{}@minus{}acl ,
@minus{}@minus{}xattr , @minus{}@minus{}md5 , @minus{}@minus{}stdio_sync . @minus{}@minus{}xattr , @minus{}@minus{}md5 , @minus{}@minus{}stdio_sync .
They work like the @command{xorriso} commands with the They work like the @command{xorriso} commands with the
same name and hardcoded parameter "on", e.g. -acl "on". same name and hardcoded parameter "on", e.g. -acl "on".
Explicit parameters are expected by @minus{}@minus{}stdio_sync Explicit parameters are expected by @minus{}@minus{}stdio_sync
and @minus{}@minus{}scdbackup_tag. and @minus{}@minus{}scdbackup_tag.
@* @*
The capability to preserve multi-session history on overwriteable media The capability to preserve multi-session history on overwritable media
gets disabled by default. It can be enabled by using @minus{}@minus{}emul-toc gets disabled by default. It can be enabled by using @minus{}@minus{}emul-toc
with the first session. See -compliance no_emul_toc. with the first session. See -compliance no_emul_toc.
@* @*
@minus{}@minus{}sort-weight gets as parameters a number and an iso_rr_path. @minus{}@minus{}sort-weight gets as parameters a number and an iso_rr_path.
The number becomes the LBA sorting weight of regular file iso_rr_path or The number becomes the LBA sorting weight of regular file iso_rr_path or
of all regular files underneath directory iso_rr_path. of all regular files underneath directory iso_rr_path.
(See -find -exec sort_weight). (See -find -exec sort_weight).
@* @*
Adopted from grub-mkisofs are @minus{}@minus{}protective-msdos-label Adopted from grub-mkisofs are @minus{}@minus{}protective-msdos-label
(see -boot_image grub partition_table=on) and (see -boot_image grub partition_table=on) and
skipping to change at line 5850 skipping to change at line 6119
@* @*
Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=, tsize=, Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=, tsize=,
-isosize, -multi, -msinfo, @minus{}@minus{}grow_overwriteable_iso, -isosize, -multi, -msinfo, @minus{}@minus{}grow_overwriteable_iso,
write_start_address=, write_start_address=,
track source file path or "-" for standard input as track source. track source file path or "-" for standard input as track source.
@* @*
It ignores most other options of cdrecord and cdrskin but refuses on It ignores most other options of cdrecord and cdrskin but refuses on
-audio, -scanbus, and on blanking modes unknown to @command{xorriso}. -audio, -scanbus, and on blanking modes unknown to @command{xorriso}.
@* @*
The scope is only a single data track per session to be written The scope is only a single data track per session to be written
to blank, overwriteable, or appendable media. The medium gets closed if to blank, overwritable, or appendable media. The medium gets closed if
closing is applicable and not option -multi is present. closing is applicable and not option -multi is present.
@* @*
If an input drive was acquired, then it is given up. If an input drive was acquired, then it is given up.
This is only allowed if no image changes are pending. This is only allowed if no image changes are pending.
@* @*
dev= must be given as @command{xorriso} device address. Addresses like 0,0,0 dev= must be given as @command{xorriso} device address. Addresses like 0,0,0
or ATA:1,1,0 are not supported. or ATA:1,1,0 are not supported.
@* @*
If a track source is given, then an automatic -commit happens at the end of If a track source is given, then an automatic -commit happens at the end of
the "cdrecord" option list. the "cdrecord" option list.
@* @*
@minus{}@minus{}grow_overwriteable_iso @minus{}@minus{}grow_overwriteable_iso
enables emulation of multi-session on overwriteable enables emulation of multi-session on overwritable
media. To enable emulation of a TOC, the first session needs -C 0,32 with media. To enable emulation of a TOC, the first session needs -C 0,32 with
-as mkisofs (but no -M) and @minus{}@minus{}grow_overwriteable_iso -as mkisofs (but no -M) and @minus{}@minus{}grow_overwriteable_iso
write_start_address=32s with -as cdrecord. write_start_address=32s with -as cdrecord.
@* @*
A much more elaborate libburn based cdrecord emulator is the program cdrskin. A much more elaborate libburn based cdrecord emulator is the program cdrskin.
@* @*
Personalites "@strong{xorrecord}", "@strong{wodim}", and "@strong{cdrskin}" Personalites "@strong{xorrecord}", "@strong{wodim}", and "@strong{cdrskin}"
are aliases for "cdrecord". are aliases for "cdrecord".
@* @*
If @command{xorriso} is started with one of the leafnames "xorrecord", If @command{xorriso} is started with one of the leafnames "xorrecord",
skipping to change at line 6848 skipping to change at line 7117
@* @*
A safe automatic way seems to be a separate run of xorriso for loading A safe automatic way seems to be a separate run of xorriso for loading
the tray with proper waiting, and a subsequent run of dd which shall offer the tray with proper waiting, and a subsequent run of dd which shall offer
itself to any problems caused by demons assessing the changed drive status. itself to any problems caused by demons assessing the changed drive status.
If this does not help, insert a run of "sleep 10" between xorriso and dd. If this does not help, insert a run of "sleep 10" between xorriso and dd.
@* @*
@sp 1 @sp 1
This example works for multi-session media only. This example works for multi-session media only.
Add cdrskin option @minus{}@minus{}grow_overwriteable_iso Add cdrskin option @minus{}@minus{}grow_overwriteable_iso
to all -as cdrecord runs to all -as cdrecord runs
in order to enable multi-session emulation on overwriteable media. in order to enable multi-session emulation on overwritable media.
@c man .SS @c man .SS
@c man .B Let xorriso work underneath growisofs @c man .B Let xorriso work underneath growisofs
@node ExGrowisofs, ExException, ExMkisofs, Examples @node ExGrowisofs, ExException, ExMkisofs, Examples
@section Let @command{xorriso} work underneath growisofs @section Let @command{xorriso} work underneath growisofs
growisofs expects an ISO formatter program which understands options -C and growisofs expects an ISO formatter program which understands options -C and
-M. If @command{xorriso} gets started by name "xorrisofs" then it is suitable -M. If @command{xorriso} gets started by name "xorrisofs" then it is suitable
for that. for that.
@* @*
@sp 1 @sp 1
$ export MKISOFS="xorrisofs" $ export MKISOFS="xorrisofs"
skipping to change at line 6887 skipping to change at line 7156
start with "-o" but -outdev must be set to "-". start with "-o" but -outdev must be set to "-".
So use "outdev" instead: So use "outdev" instead:
@* @*
@sp 1 @sp 1
$ growisofs -Z /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files $ growisofs -Z /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
@* @*
$ growisofs -M /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files $ growisofs -M /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
@* @*
@sp 1 @sp 1
growisofs has excellent burn capabilities with DVD and BD. growisofs has excellent burn capabilities with DVD and BD.
It does not emulate session history on overwriteable media, though. It does not emulate session history on overwritable media, though.
@c man .SS @c man .SS
@c man .B Adjust thresholds for verbosity, exit value and program abort @c man .B Adjust thresholds for verbosity, exit value and program abort
@node ExException, ExTime, ExGrowisofs, Examples @node ExException, ExTime, ExGrowisofs, Examples
@section Adjust thresholds for verbosity, exit value and program abort @section Adjust thresholds for verbosity, exit value and program abort
Be quite verbose, exit 32 if severity "FAILURE" was encountered, Be quite verbose, exit 32 if severity "FAILURE" was encountered,
do not abort prematurely but forcibly go on until the end of commands. do not abort prematurely but forcibly go on until the end of commands.
@* @*
@sp 1 @sp 1
$ xorriso ... \ $ xorriso ... \
@* @*
skipping to change at line 7024 skipping to change at line 7293
on disk. Without them, an update run may use -md5 "on" to match recorded MD5 on disk. Without them, an update run may use -md5 "on" to match recorded MD5
sums against the current file content on hard disk. This is usually much faster sums against the current file content on hard disk. This is usually much faster
than the default which compares both contents directly. than the default which compares both contents directly.
@* @*
With @strong{mount} option @strong{-o "sbsector="} on GNU/Linux With @strong{mount} option @strong{-o "sbsector="} on GNU/Linux
or @strong{-s} on FreeBSD or NetBSD or @strong{-s} on FreeBSD or NetBSD
it is possible to access the session trees which represent the older backup it is possible to access the session trees which represent the older backup
versions. With CD media, GNU/Linux mount accepts session numbers directly by versions. With CD media, GNU/Linux mount accepts session numbers directly by
its option "session=". its option "session=".
@* @*
Multi-session media and most overwriteable media written by @command{xorriso} Multi-session media and most overwritable media written by @command{xorriso}
can tell the sbsectors of their sessions by @command{xorriso} command -toc. can tell the sbsectors of their sessions by @command{xorriso} command -toc.
Used after -commit the following command prints the matching mount command for Used after -commit the following command prints the matching mount command for
the newly written session (here for mount point /mnt): the newly written session (here for mount point /mnt):
@* @*
@sp 1 @sp 1
-mount_cmd "indev" "auto" "auto" /mnt -mount_cmd "indev" "auto" "auto" /mnt
@* @*
@sp 1 @sp 1
Commands -mount_cmd and -mount are also able to produce the mount commands for Commands -mount_cmd and -mount are also able to produce the mount commands for
older sessions in the table-of-content. E.g. as superuser: older sessions in the table-of-content. E.g. as superuser:
skipping to change at line 7291 skipping to change at line 7560
Expect to get asked more questions before solutions can be proposed. Expect to get asked more questions before solutions can be proposed.
@c man .SH AUTHOR @c man .SH AUTHOR
@node Legal, CommandIdx, Bugreport, Top @node Legal, CommandIdx, Bugreport, Top
@chapter Author, Copyright, Credits @chapter Author, Copyright, Credits
@section Author @section Author
Thomas Schmitt <scdbackup@@gmx.net> Thomas Schmitt <scdbackup@@gmx.net>
@* @*
for libburnia-project.org for libburnia-project.org
@c man .SH COPYRIGHT @c man .SH COPYRIGHT
@section Copyright @section 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 Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of @command{xorriso}. modified in sync with the technical properties of @command{xorriso}.
If you make use of the license to derive modified versions of If you make use of the license to derive modified versions of
@command{xorriso} then you are entitled to modify this text under that @command{xorriso} then you are entitled to modify this text under that
same license. same license.
@c man .SH CREDITS @c man .SH CREDITS
@section Credits @section Credits
@command{xorriso} is in part based on work by Vreixo Formoso who provides @command{xorriso} is in part based on work by Vreixo Formoso who provides
libisofs together with Mario Danic who also leads the libburnia team. libisofs together with Mario Danic who also leads the libburnia team.
 End of changes. 73 change blocks. 
96 lines changed or deleted 365 lines changed or added

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