xorriso
(1)
Name
xorriso - creates, loads, manipulates and writes ISO 9660
filesystem images with Rock Ridge extensions.
Synopsis
xorriso [settings|actions]
Description
User Commands XORRISO(1)
NAME
xorriso - creates, loads, manipulates and writes ISO 9660
filesystem images with Rock Ridge extensions.
SYNOPSIS
xorriso [settings|actions]
DESCRIPTION
xorriso is a program which copies file objects from POSIX
compliant filesystems into Rock Ridge enhanced ISO 9660
filesystems and allows session-wise manipulation of such
filesystems. It can load the management information of
existing ISO images and it writes the session results to
optical media or to filesystem objects.
Vice versa xorriso is able to copy file objects out of ISO
9660 filesystems.
A special property of xorriso is that it needs neither an
external ISO 9660 formatter program nor an external burn
program for CD, DVD or BD but rather incorporates the
libraries of libburnia-project.org .
Overview of features:
Operates on an existing ISO image or creates a new one.
Copies files from disk filesystem into the ISO image.
Copies files from ISO image to disk filesystem (see
osirrox).
Renames or deletes file objects in the ISO image.
Changes file properties in the ISO image.
Updates ISO subtrees incrementally to match given disk
subtrees.
Writes result either as completely new image or as add-on
session to optical media or filesystem objects.
Can activate ISOLINUX and GRUB boot images via El Torito and
MBR.
Can perform multi-session tasks as emulation of mkisofs and
cdrecord.
Can record and restore hard links and ACL.
Content may get zisofs compressed or filtered by external
processes.
Can issue commands to mount older sessions on GNU/Linux or
FreeBSD.
Can check media for damages and copy readable blocks to
disk.
Can attach MD5 checksums to each data file and the whole
session.
Scans for optical drives, blanks re-useable optical media.
Reads its instructions from command line arguments, dialog,
and files.
Provides navigation commands for interactive ISO image
manipulation.
SunOS 5.11 Last change: Jun 27, 2010 1
User Commands XORRISO(1)
Adjustable thresholds for abort, exit value, and problem
reporting.
General information paragraphs:
Session model
Media types and states
Creating, Growing, Modifying, Blind Growing
Libburn drives
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
Command processing
Dialog, Readline, Result pager
Maybe you first want to have a look at section EXAMPLES near
the end of this text before reading the next few hundred
lines of background information.
Session model:
Unlike other filesystems, ISO 9660 is not intended for read-
write operation but rather for being generated in a single
sweep and being written to media as a session.
The data content of the session is called filesystem image.
The written image in its session can then be mounted by the
operating system for being used read-only. GNU/Linux is able
to mount ISO images from block devices, which may represent
optical media, other media or via a loop device even from
regular disk files. FreeBSD mounts ISO images from devices
that represent arbitrary media or from regular disk files.
This session usage model has been extended on CD media by
the concept of multi-session , which allows to add
information to the CD and gives the mount programs of the
operating systems the addresses of the entry points of each
session. The mount programs recognize block devices which
represent CD media and will by default mount the image in
the last session.
This session usually contains an updated directory tree for
the whole media which governs the data contents in all
recorded sessions. So in the view of the mount program all
sessions of a particular media together form a single
filesystem image.
Adding a session to an existing ISO image is in this text
referred as growing.
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 functionality to overwriteable
media or disk files which carry valid ISO 9660 filesystems.
xorriso provides growing as well as an own method named
modifying which produces a completely new ISO image from the
SunOS 5.11 Last change: Jun 27, 2010 2
User Commands XORRISO(1)
old one and the modifications. See paragraph Creating,
Growing, Modifying, Blind Growing below.
xorriso adopts the concept of multi-session by loading an
eventual image directory tree, allowing to manipulate it by
several actions, and to write the new image to the target
media.
The first session of a xorriso run begins by the definition
of the input drive with the eventual ISO image or by the
definition of an output drive. The session ends by command
-commit which triggers writing. A -commit is done
automatically when the program ends regularly.
After -commit a new session begins with the freshly written
one as input. A new input drive can only be chosen as long
as the loaded ISO image was not altered. Pending alteration
can be revoked by command -rollback.
Writing a session to the target is supposed to be very
expensive in terms of time and of consumed space on
appendable or write-once media. Therefore all intended
manipulations of a particular ISO image should be done in a
single session. But in principle it is possible to store
intermediate states and to continue with image
manipulations.
Media types and states: There are two families of media in
the MMC standard:
Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL,
BD-R, and unformatted DVD-RW. These media provide a table of
content which describes their existing sessions. See option
-toc.
Overwriteable media are DVD-RAM, DVD+RW, BD-RE, and
formatted DVD-RW. They allow random write access but do not
provide information about their session history. If they
contain one or more ISO 9660 sessions and if the first
session was written by xorriso, then a table of content can
be emulated. Else only a single overall session will be
visible.
DVD-RW media can be formatted by -format "full". They can
be made unformatted by -blank "deformat".
Regular files and block devices are handled as overwriteable
media. Pipes and other writeable file types are handled as
blank multi-session media.
These media can assume several states in which they offer
different capabilities.
Blank media can be written from scratch. They contain no ISO
image suitable for xorriso.
Blank is the state of newly purchased optical media. With
used CD-RW and DVD-RW it can be achieved by action -blank
SunOS 5.11 Last change: Jun 27, 2010 3
User Commands XORRISO(1)
"as_needed". Overwriteable media are considered blank if
they are new or if they have been marked as blank by
xorriso. Action -blank "as_needed" can be used to do this
marking on overwriteable media, or to apply eventual
mandatory formatting to new media.
Appendable media accept further sessions. Either they are
MMC multi-session media in appendable state, or they are
overwriteable media which contain an ISO image suitable for
xorriso.
Appendable is the state after writing a session with option
-close off.
Closed media cannot be written. They may contain an ISO
image suitable for xorriso.
Closed is the state of DVD-ROM media and of multi-session
media which were written with option -close on. If the drive
is read-only hardware then it will probably show any media
as closed CD-ROM resp. DVD-ROM.
Overwriteable media assume this state in such read-only
drives or if they contain unrecognizable data in the first
32 data blocks.
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 not even that. Option
-rom_toc_scan might or might not help in such cases.
Creating, Growing, Modifying, Blind Growing:
A new empty ISO image gets created if there is no input
drive with a valid ISO 9660 image when the first time an
output drive is defined. This is achieved by option -dev on
blank media or by option -outdev on media in any state.
The new empty image can be populated with directories and
files. Before it can be written, the media in the output
drive must get into blank state if it was not blank already.
If there is a input drive with a valid ISO image, then this
image gets loaded as foundation for manipulations and
extension. The constellation of input and output drive
determines which write method will be used. They have quite
different capabilities and constraints.
The method of growing adds new data to the existing media.
These data comprise of eventual new file content and they
override the existing ISO 9660 + Rock Ridge directory tree.
It is possible to hide files from previous sessions but they
still exist on media and with many types of optical media it
is quite easy to recover them by mounting older sessions.
Growing is achieved by option -dev.
The write method of modifying produces compact filesystem
images with no outdated files or directory trees. Modifying
can write its images to target media which are completely
SunOS 5.11 Last change: Jun 27, 2010 4
User Commands XORRISO(1)
unsuitable for multi-session operations. E.g. DVD-RW which
were treated with -blank deformat_quickest, named pipes,
character devices, sockets. On the other hand modified
sessions cannot be written to appendable media but to blank
media only.
So for this method one needs either two optical drives or
has to work with filesystem objects as source and/or target
media.
Modifying takes place if input drive and output drive are
not the same and if option -grow_blindly is set to its
default "off". This is achieved by options -indev and
-outdev.
If option -grow_blindly is set to a non-negative number and
if -indev and -outdev are both set to different drives, then
blind growing is performed. It produces an add-on session
which is ready for being written to the given block address.
This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
which gives much room for wrong parameter combinations and
should thus only be employed if a strict distinction between
ISO formatter xorriso and the burn program is desired. -C
$msc1,$msc2 is equivalent to:
-load sbsector $msc1 -grow_blindly $msc2
Libburn drives:
Input drive, i.e. source of an existing or empty ISO image,
can be any random access readable libburn drive: optical
media with readable data, blank optical media, regular
files, block devices.
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 of modifying and blind growing.
They all are suitable for newly created images.
All drive file objects have to offer rw-permission to the
user of xorriso. Even those which will not be useable for
reading an ISO image.
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.
-dev /dev/sr0
-dev /dev/hdc
-dev /dev/sg2
On FreeBSD the device files have names like
-dev /dev/cd0
On OpenSolaris:
-dev /dev/rdsk/c4t0d0s2
Get a list of accessible drives by command
-devices
SunOS 5.11 Last change: Jun 27, 2010 5
User Commands XORRISO(1)
It might be necessary to do this as superuser in order to
see all drives and to then allow rw-access for the intended
users. Consider to bundle the authorized users in a group
like old "floppy".
Filesystem objects of nearly any type can be addressed by
prefix "stdio:" and their path in the filesystem. E.g.:
-dev stdio:/dev/sdc
The default setting of -drive_class allows to address files
outside the /dev tree without that prefix. E.g.:
-dev /tmp/pseudo_drive
If path leads to a regular file or to a block device then
the emulated drive is random access readable and can be used
for the method of growing if it already contains a valid ISO
9660 image. Any other file type is not readable via "stdio:"
and can only be used as target for the method of modifying
or blind growing. Non-existing paths in existing
directories are handled as empty regular files.
A very special kind of pseudo drive are open file
descriptors. They are depicted by "stdio:/dev/fd/" and
descriptor number (see man 2 open).
Addresses "-" or "stdio:/dev/fd/1" depict standard output,
which normally is the output channel for result texts. To
prevent a fatal intermingling of ISO image and text
messages, all result texts get redirected to stderr if -*dev
"-" or "stdio:/dev/fd/1" is among the start arguments of the
program.
Standard output is currently suitable for creating one
session per program run without dialog. Use in other
situations is discouraged and several restrictions apply:
It is not allowed to use standard output as pseudo drive if
it was not among the start arguments. Do not try to fool
this ban via backdoor addresses to stdout.
If stdout is used as drive, then -use_readline is
permanently disabled. Use of backdoors can cause severe
memory and/or tty corruption.
Be aware that especially the superuser can write into any
accessible file or device by using its path with the
"stdio:" prefix. By default any address in the /dev tree
without prefix "stdio:" will work only if it leads to a MMC
drive.
One may use option -ban_stdio_write to surely prevent this
risk and to allow only MMC drives.
One may prepend "mmc:" to a path to surely disallow any
automatic "stdio:".
By option -drive_class one may ban certain paths or allow
access without prefix "stdio:" to other paths.
Rock Ridge, POSIX, X/Open, El Torito,
SunOS 5.11 Last change: Jun 27, 2010 6
User Commands XORRISO(1)
Rock Ridge is the name of a set of additional information
which enhance an ISO 9660 filesystem so that it can
represent a POSIX compliant filesystem with ownership,
access permissions, symbolic links, and other attributes.
This is what xorriso uses for a decent representation of the
disk files within the ISO image. Rock Ridge information is
produced with any xorriso image.
xorriso is not named "porriso" because POSIX only guarantees
14 characters of filename length. It is the X/Open System
Interface standard XSI which demands a file name length of
up to 255 characters and paths of up to 1024 characters.
Rock Ridge fulfills this demand.
An El Torito boot record connects one or more boot images,
which are binary program files stored in the ISO image, with
the bootstrapping facility of contemporary computers. The
content of the boot image files is not in the scope of El
Torito.
Most bootable GNU/Linux CDs are equipped with ISOLINUX or
GRUB boot images. xorriso is able to create or maintain an
El Torito object which makes such an image bootable. For
details see option -boot_image.
It is possible to make ISO images bootable from USB stick or
other hard-disk-like media by -boot_image argument
system_area= . This installs a Master Boot Record which may
get adjusted according to the needs of GRUB resp. ISOLINUX.
An MBR contains boot code and a partition table. It does not
hamper CDROM booting. The new MBR of a follow-up session can
get in effect only on overwriteable media.
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 FreeBSD AvgLiveCD wiki.
The support for other boot image types is sparse.
ACL are an advanced way of controlling access permissions to
file objects. Neither ISO 9660 nor Rock Ridge specify a way
to record ACLs. So libisofs has introduced a standard
conformant extension named AAIP for that purpose. It uses
this extension if enabled by option -acl.
AAIP enhanced images are supposed to be mountable normally,
but one cannot expect that the mounted filesystem will show
and respect the eventual ACLs. For now, only xorriso is
able to retrieve those ACLs. It can bring them into effect
when files get restored to an ACL enabled file system or it
can print them in a format suitable for tool setfacl.
Files with ACL show as group permissions the setting of
entry "mask::" if that entry exists. Nevertheless the non-
listed group members get handled according to entry
"group::". xorriso brings "group::" into effect before
eventually removing the ACL from a file.
SunOS 5.11 Last change: Jun 27, 2010 7
User Commands XORRISO(1)
xattr (aka EA) are pairs of name and value which can be
attached to file objects. AAIP is able to represent them and
xorriso allows to record and restore pairs which have names
out of the user namespace. I.e. those which begin with
"user.", like "user.x" or "user.whatever". Name has to be a
0 terminated string. Value may be any array of bytes which
does not exceed the size of 4095 bytes. xattr processing
happens only if it is enabled by option -xattr.
As with ACL, currently only xorriso is able to retrieve
xattr from AAIP enhanced images, to restore them to xattr
capable file systems, or to print them.
Command processing:
Commands are either actions which happen immediately or
settings which influence following actions. So their
sequence does matter.
Commands consist of a command word, followed by zero or more
parameter words. If the list of parameter words is of
variable length (indicated by "[...]" or "[***]") then it
has to be terminated by either the list delimiter, or the
end of argument list, or an end of an input line.
At program start the list delimiter is the word "--". This
may be changed by option -list_delimiter in order to allow
"--" as argument in a list of variable length. It is
advised to reset the delimiter to "--" immediately
afterwards.
For brevity the list delimiter is referred as "--"
throughout this text.
The list delimiter is silently tolerated if it appears after
the parameters of a command with a fixed list length. It is
handled as normal text if it appears among the arguments of
such a command.
Pattern expansion converts a list of pattern words into a
list of existing file addresses. Eventual unmatched pattern
words appear themselves in that result list, though.
Pattern matching supports the usual shell parser wildcards
'*' '?' '[xyz]' and respects '/' as separator which may only
be matched literally.
It is a property of some particular commands and not a
general feature. It gets controlled by commands
-iso_rr_pattern and -disk_pattern. Commands which
eventually use pattern expansion all have variable argument
lists which are marked in this man page by "[***]" rather
than "[...]".
Some other commands perform pattern matching
unconditionally.
Command and parameter words are either read from program
arguments, where one argument is one word, or from quoted
SunOS 5.11 Last change: Jun 27, 2010 8
User Commands XORRISO(1)
input lines where words are recognized similar to the
quotation rules of a shell parser.
xorriso is not a shell, although it might appear so on first
glimpse. Be aware that the interaction of quotation marks
and pattern symbols like "*" differs from the usual shell
parsers. In xorriso, a quotation mark does not make a
pattern symbol literal.
Quoted input converts whitespace separated text pieces into
words. The double quotation mark " and the single quotation
mark ' can be used to enclose whitespace and make it part of
words (e.g. of file names). Each mark type can enclose the
marks of the other type. A trailing backslash \ outside
quotations or an open quotation cause the next input line to
be appended.
Quoted input accepts any ASCII character except NUL (0) as
content of quotes. Nevertheless it can be cumbersome for
the user to produce those characters at all. Therefore
quoted input and program arguments allow optional Backslash
Interpretation which can represent all ASCII characters
except NUL (0) by backslash codes as in $'...' of bash.
It is not enabled by default. See option -backslash_codes.
When the program begins then it first looks for argument
-no_rc. If this is not present then it looks for its startup
files and eventually reads their content as command input
lines. Then it interprets the program arguments as commands
and parameters and finally it enters dialog mode if command
-dialog "on" was executed up to then.
The program ends either by command -end, or by the end of
program arguments if not dialog was enabled up to that
moment, or by a problem event which triggers the threshold
of command -abort_on.
Dialog, Readline, Result pager:
Dialog mode prompts for a quoted input line, parses it into
words, and performs them as commands with their parameters.
It provides assisting services to make dialog more
comfortable.
Readline is an enhancement for the input line. You may know
it already from the bash shell. Whether it is available in
xorriso depends on the availability of package readline-dev
at the time when xorriso was built from its sourcecode.
It allows to move the cursor over the text in the line by
help of the Leftward and the Rightward arrow key. Text may
be inserted at the cursor position. The Delete key removes
the character under the cursor. Upward and Downward arrow
keys navigate through the history of previous input lines.
See man readline for more info about libreadline.
SunOS 5.11 Last change: Jun 27, 2010 9
User Commands XORRISO(1)
Option -page activates a built-in result text pager which
may be convenient in dialog. After an action has put out the
given number of terminal lines, the pager prompts the user
for a line of input.
An empty line lets xorriso resume work until the next page
is put out.
The single character "@" disables paging for the current
action.
"@@@", "x", "q", "X", or "Q" urge the current action to
abort and suppress further result output.
Any other line will be interpreted as new dialog line. The
current action is urged to abort. Afterwards, the input line
is executed.
Some actions apply paging to their info output, too.
The urge to abort may or may not be obeyed by the current
action. All actions try to abort as soon as possible.
OPTIONS
All command words are shown with a leading dash although
this dash is not mandatory for the option to be recognized.
Nevertheless within option -as the dashes of the emulated
options are mandatory.
Normally any number of leading dashes is ignored with
command words and inner dashes are interpreted as
underscores.
Aquiring source and target drive:
Before aquiring a drive one will eventually enable options
which influence the behavior of image loading. See next
option group.
-dev address
Set input and output drive to the same address and load
an eventual ISO image. If there is no ISO image then
create a blank one. Set the image expansion method to
growing.
This is only allowed as long as no changes are pending
in the currently loaded ISO image. Eventually one has
to perform -commit or -rollback first.
Special address string "-" means standard output, to
which several restrictions apply. See above paragraph
"Libburn drives".
An empty address string "" gives up the current device
without aquiring a new one.
-indev address
Set input drive and load an eventual ISO image. If the
new input drive differs from -outdev then switch from
growing to modifying or to blind growing. It depends
on the setting of -grow_blindly which of both gets
SunOS 5.11 Last change: Jun 27, 2010 10
User Commands XORRISO(1)
activated. The same rules and restrictions apply as
with -dev.
-outdev address
Set output drive and if it differs from the input drive
then switch from growing to modifying or to blind
growing. Unlike -dev and -indev this action does not
load a new ISO image. So it can be performed even if
there are pending changes.
-outdev can be performed without previous -dev or
-indev. In that case an empty ISO image with no changes
pending is created. It can either be populated by help
of -map, -add et.al. or it can be discarded silently if
-dev or -indev are performed afterwards.
Special address string "-" means standard output, to
which several restrictions apply. See above paragraph
"Libburn drives".
An empty address string "" gives up the current output
drive without aquiring a new one. No writing is
possible without an output drive.
-grow_blindly "off"|predicted_nwa
If predicted_nwa is a non-negative number then perform
blind growing rather than modifying if -indev and
-outdev are set to different drives. "off" or "-1"
switch to modifying, which is the default.
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 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 accessing file content.
xorriso will write the session to the address as
obtained from examining -outdev and not necessarily to
predicted_nwa.
During a run of blind growing, the input drive is given
up before output begins. The output drive is given up
when writing is done.
Influencing the behavior of image loading:
The following options should normally be performed before
loading an image by aquiring an input drive. In rare cases
it is desirable to activate them only after image loading.
-load entity id
Load a particular (possibly outdated) ISO session from
-dev or -indev. Usually all available sessions are
shown with option -toc.
entity depicts the kind of addressing. id depicts the
particular address. The following entities are defined:
"auto" with any id addresses the last session in -toc.
SunOS 5.11 Last change: Jun 27, 2010 11
User Commands XORRISO(1)
This is the default.
"session" with id being a number as of a line "ISO
session", column "Idx".
"track" with id being a number as of a line "ISO
track", column "Idx".
"lba" or "sbsector" with a number as of a line "ISO
...", column "sbsector".
"volid" with a search pattern for a text as of a line
"ISO ...", column "Volume Id".
Adressing a non-existing entity or one which does not
represent an ISO image will either abandon -indev or at
least lead to a blank image.
If an input drive is set at the moment when -load is
executed, then the addressed ISO image is loaded
immediately. Else, the setting will be pending until
the next -dev or -indev. After the image has been
loaded once, the setting is valid for -rollback until
next -dev or -indev, where it will be reset to "auto".
disk_pattern
-drive_class
"harmless"|"banned"|"caution"|"clear_list"
Add a drive path pattern to one of the safety lists or
make those lists empty. There are three lists defined
which get tested in the following sequence:
If a drive address path matches the "harmless" list
then the drive will be accepted. If it is not a MMC
device then the prefix "stdio:" will be prepended
automatically. This list is empty by default.
Else if the path matches the "banned" list then the
drive will not be accepted by xorriso but rather lead
to a FAILURE event. This list is empty by default.
Else if the path matches the "caution" list and if it
is not a MMC device, then its address must have the
prefix "stdio:" or it will be rejected. This list has
by default one entry: "/dev".
If a drive path matches no list then it is considered
"harmless". By default these are all paths which do not
begin with directory "/dev".
A path matches a list if one of its parent paths or
itself matches a list entry. An eventual address prefix
"stdio:" or "mmc:" will be ignored when testing for
matches.
By pseudo-class "clear_list" and pseudo-patterns
"banned", "caution", "harmless", or "all", the lists
may be made empty.
E.g.: -drive_class clear_list banned
One will normally define the -drive_class lists in one
of the xorriso Startup Files.
Note: This is not a security feature but rather a
bumper for the superuser to prevent inadverted mishaps.
For reliably blocking access to a device file you have
SunOS 5.11 Last change: Jun 27, 2010 12
User Commands XORRISO(1)
to deny its rw-permissions in the filesystem.
-assert_volid pattern severity
Refuse to load ISO images with volume ids which do not
match the given search pattern. When refusing an image,
give up the input drive and issue an event of the given
severity (like FAILURE, see -abort_on). An empty search
pattern accepts any image.
This option does not hamper the creation of an empty
image from blank input media and does not discard an
already loaded image.
-in_charset character_set_name
Set the character set from which to convert file names
when loading an image. This has eventually to be done
before specifying -dev , -indev or -rollback. See
paragraph "Character sets" for more explanations. When
loading the written image after -commit the setting of
-out_charset will be copied to -in_charset.
-auto_charset "on"|"off"
Enable or disable recording and interpretation of the
output character set name in an xattr attribute of the
image root directory. If enabled then an eventual
recorded character set name gets used as input
character set when reading an image.
Note that the default output charset is the local
character set of the terminal where xorriso runs.
Before attributing this local character set to the
produced ISO image, check whether the terminal properly
displays all intended filenames, especially exotic
national characters.
-hardlinks mode[:mode...]
Enable or disable loading and recording of hardlink
relations.
In default mode "off", iso_rr files lose their inode
numbers at image load time. Each iso_rr file object
which has no inode number at image generation time will
get a new unique inode number if -compliance is set to
new_rr.
Mode "on" preserves eventual inode numbers from the
loaded image. When committing a session it searches
for families of iso_rr files which stem from the same
disk file, have identical content filtering and have
identical properties. The family members all get the
same inode number. Whether these numbers are respected
at mount time depends on the operating system.
Commands -update and -update_r track splits and fusions
of hard links in filesystems which have stable device
and inode numbers. This can cause automatic last minute
changes before the session gets written. Command
SunOS 5.11 Last change: Jun 27, 2010 13
User Commands XORRISO(1)
-hardlinks "perform_update" may be used to do these
changes earlier, e.g. if you need to apply filters to
all updated files.
Mode "without_update" avoids hardlink processing during
update commands. Use this if your filesystem situation
does not allow -disk_dev_ino "on".
xorriso commands which extract files from an ISO image
try to hardlink files with identical inode number. The
normal scope of this operation is from image load to
image load. One may give up the accumulated hard link
addresses by -hardlinks "discard_extract".
A large number of hardlink families may exhaust
-temp_mem_limit if not -osirrox "sort_lba_on" and
-hardlinks "cheap_sorted_extract" are both in effect.
This restricts hard linking to other files restored by
the same single extract command. -hardlinks
"normal_extract" re-enables wide and expensive hardlink
accumulation.
-acl "on"|"off"
Enable or disable processing of ACLs. If enabled, then
xorriso will obtain ACLs from disk file objects, store
ACLs in the ISO image using the libisofs specific AAIP
format, load AAIP data from ISO images, test ACL during
file comparison, and restore ACLs to disk files when
extracting them from ISO images. See also options
-getfacl, -setfacl.
-xattr "on"|"off"
Enable or disable processing of xattr attributes in
user namespace. If enabled, then xorriso will handle
xattr similar to ACL. See also options -getfattr,
-setfattr and above paragraph about xattr.
-md5 "on"|"all"|"off"
Enable or disable processing of MD5 checksums for the
overall session and for each single data file. If
enabled then images get loaded only if eventual
checksums tags of superblock and directory tree match
properly. The MD5 checksums of data files and whole
session get loaded from the image if there are any.
With options -compare and -update the eventually
recorded MD5 of a 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 if -disk_dev_ino "on" is not suitable.
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 in older
sessions get copied into the new session. Superblock,
tree and whole session get a checksum tag each.
Mode "all" will additionally check during image
SunOS 5.11 Last change: Jun 27, 2010 14
User Commands XORRISO(1)
generation whether the checksum of a data file changed
between the time when its reading began and the time
when it ended. This implies reading every file twice.
Checksums can be exploited via options -check_md5,
-check_md5_r, via find actions get_md5, check_md5, and
via -check_media.
-for_backup
Enable all extra features which help to produce or to
restore backups with highest fidelity of file
properties. Currently this is a shortcut for:
-hardlinks on -acl on -xattr on -md5 on.
-disk_dev_ino "on"|"ino_only"|"off"
Enable or disable processing of recorded file
identification numbers (dev_t and ino_t). They are
eventually stored as xattr and allow to substantially
accelerate file comparison. The root node gets a global
start timestamp. If during comparison a file with
younger timestamps is found in the ISO image, then it
is suspected to have inconsistent content.
If device numbers and inode numbers of the disk
filesystems are persistent and if no irregular
alterations of timestamps or system clock happen, then
potential content changes can be detected without
reading that content. File content change is assumed
if any of mtime, ctime, device number or inode number
have changed.
Mode "ino_only" replaces the precondition that device
numbers are stable by the precondition that mount
points in the compared tree always lead to the same
filesystems. Use this if mode "on" always sees all
files changed.
The speed advantage appears only if the loaded session
was produced with -disk_dev_ino "on" too.
Note that -disk_dev_ino "off" is totally in effect only
if -hardlinks is "off", too.
-rom_toc_scan "on"|"force"|"off"[:"emul_on"|"emul_off"]
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 be truncated
to first and last session or even be completely false.
(The eventual emulated history of overwriteable media
is not affected by this.)
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 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 to invalid addresses and
thus ugly drive behavior. Setting "on" enables that
SunOS 5.11 Last change: Jun 27, 2010 15
User Commands XORRISO(1)
scan for alleged read-only media.
Some operating systems are not able to mount the most
recent session of multi-session DVD or BD. If on such a
system xorriso has no own MMC capabilities then it may
still find that session from a scanned table of
content. Setting "force" handles any media like a ROM
media with setting "on".
On the other hand the emulation of session history on
overwriteable media can hamper reading of partly
damaged media. Setting "off:emul_off" disables the
elsewise trustworthy table-of-content scan for those
media.
To be in effect, the -rom_toc_scan setting has to be
made before the -*dev command which aquires drive and
media.
-calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
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 the startup
time for the next drive operation but can be loud and
waste energy if no i/o with the drive is expected to
happen soon.
Modes "in", "out", "all" immediately calm down -indev,
-outdev, resp. both. Mode "revoke" immediately alerts
both. Mode "on" causes -calm_drive to be performed
automatically after each -dev, -indev, and -outdev.
Mode "off" disables this.
-ban_stdio_write
Allow for writing only the usage of MMC optical drives.
Disallow to write the result into files of nearly
arbitrary type. Once set, this command cannot be
revoked.
Inserting files into ISO image:
The following commands expect file addresses of two kinds:
disk_path is a path to an object in the local filesystem
tree.
iso_rr_path is the Rock Ridge name of a file object in the
ISO image. (Do not confuse with the lowlevel ISO 9660 names
visible if Rock Ridge gets ignored.)
Note that in the ISO image you are as powerful as the
superuser. Access permissions of the existing files in the
image do not apply to your write operations. They are
intended to be in effect with the read-only mounted image.
If the iso_rr_path of a newly inserted file leads to an
existing file object in the ISO image, then the following
collision handling happens:
SunOS 5.11 Last change: Jun 27, 2010 16
User Commands XORRISO(1)
If both objects are directories then they get merged by
recursively inserting the subobjects from filesystem into
ISO image. If other file types collide then the setting of
command -overwrite decides.
Renaming of files has similar collision handling, but
directories can only be replaced, not merged. Note that -mv
inserts the source objects into an eventual existing target
directory rather than attempting to replace it.
The commands in this section alter the ISO image and not the
local filesystem.
-disk_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the disk_path
arguments of several commands which support this
feature.
Setting "off" disables this feature for all commands
which are marked in this man page by "disk_path [***]"
or "disk_pattern [***]".
Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked
by "disk_pattern [***]".
Default is "ls".
-add pathspec [...] | disk_path [***]
Insert the given files or directory trees from
filesystem into the ISO image.
If -pathspecs is set to "on" then pattern expansion is
always disabled and character '=' has a special
meaning. It eventually separates the ISO image path
from the disk path:
iso_rr_path=disk_path
The separator '=' can be escaped by '\'. If
iso_rr_path does not begin with '/' then -cd is
prepended. If disk_path does not begin with '/' then
-cdx is prepended.
If no '=' is given then the word is used as both,
iso_rr_path and disk path. If in this case the word
does not begin with '/' then -cdx is prepended to the
disk_path and -cd is prepended to the iso_rr_path.
If -pathspecs is set to "off" then eventual
-disk_pattern expansion applies. The resulting words
are used as both, iso_rr_path and disk path. Eventually
-cdx gets prepended to disk_path and -cd to
iso_rr_path.
-add_plainly mode
If set to mode "unknown" then any command word that
does not begin with "-" and is not recognized as known
command will be subject to a virtual -add command.
I.e. it will be used as pathspec or as disk_path and
added to the image. Eventually -disk_pattern expansion
SunOS 5.11 Last change: Jun 27, 2010 17
User Commands XORRISO(1)
applies to disk_paths.
Mode "dashed" is similar to "unknown" but also adds
unrecognized command words even if they begin with "-".
Mode "any" announces that all further words are to be
added as pathspecs or disk_paths. This does not work in
dialog mode.
Mode "none" is the default. It prevents any words from
being understood as files to add, if they are not
parameters to appropriate commands.
-path_list disk_path
Like -add but read the parameter words from file
disk_path or standard input if disk_path is "-". The
list must contain exactly one pathspec resp. disk_path
pattern per line.
-quoted_path_list disk_path
Like -path_list but with quoted input reading rules.
Lines get split into parameter words for -add.
Whitespace outside quotes is discarded.
-map disk_path iso_rr_path
Insert file object disk_path into the ISO image as
iso_rr_path. If disk_path is a directory then its whole
sub tree is inserted into the ISO image.
-map_single disk_path iso_rr_path
Like -map, but if disk_path is a directory then its sub
tree is not inserted.
-map_l disk_prefix iso_rr_prefix disk_path [***]
Perform -map with each of the disk_path arguments.
iso_rr_path will be composed from disk_path by
replacing disk_prefix by iso_rr_prefix.
-update disk_path iso_rr_path
Compare file object disk_path with file object
iso_rr_path. If they do not match, then perform the
necessary image manipulations to make iso_rr_path a
matching copy of disk_path. By default this comparison
will imply lengthy content reading before a decision is
made. Options -disk_dev_ino or -md5 may accelerate
comparison if they were already in effect when the
loaded session was recorded.
If disk_path is a directory and iso_rr_path does not
exist yet, then the whole subtree will be inserted.
Else only directory attributes will be updated.
-update_r disk_path iso_rr_path
Like -update but working recursively. I.e. all file
objects below both addresses get compared whether they
have counterparts below the other address and whether
SunOS 5.11 Last change: Jun 27, 2010 18
User Commands XORRISO(1)
both counterparts match. If there is a mismatch then
the necessary update manipulation is done.
Note that the comparison result may depend on option
-follow. Its setting should always be the same as with
the first adding of disk_path as iso_rr_path.
If iso_rr_path does not exist yet, then it gets added.
If disk_path does not exist, then iso_rr_path gets
deleted.
-update_l disk_prefix iso_rr_prefix disk_path [***]
Perform -update_r with each of the disk_path arguments.
iso_rr_path will be composed from disk_path by
replacing disk_prefix by iso_rr_prefix.
-cut_out disk_path byte_offset byte_count iso_rr_path
Map a byte interval of a regular disk file into a
regular file in the ISO image. This may be necessary
if the disk file is larger than a single media, or if
it exceeds the traditional limit of 2 GiB - 1 for old
operating systems, or the limit of 4 GiB - 1 for newer
ones. Only the newest Linux kernels seem to read
properly files >= 4 GiB - 1.
A clumsy remedy for this limit is to backup file pieces
and to concatenate them at restore time. A well tested
chopping size is 2047m. It is permissible to request a
higher byte_count than available. The resulting file
will be truncated to the correct size of a final piece.
To request a byte_offset higher than available yields
no file in the ISO image but a SORRY event. E.g:
-cut_out /my/disk/file 0 2047m \
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \
-cut_out /my/disk/file 2047m 2047m \
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
-cut_out /my/disk/file 4094m 2047m \
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821
While option -split_size is set larger than 0, and if
all pieces of a file reside in the same ISO directory
with no other files, and if the names look like above,
then their ISO directory will be recognized and handled
like a regular file. This affects options -compare*,
-update*, and overwrite situations. See option
-split_size for details.
-cpr disk_path [***] iso_rr_path
Insert the given files or directory trees from
filesystem into the ISO image.
The rules for generating the ISO addresses are similar
as with shell command cp -r. Nevertheless, directories
of the iso_rr_path are created if necessary. Especially
a not yet existing iso_rr_path will be handled as
directory if multiple disk_paths are present. The
leafnames of the multiple disk_paths will be grafted
SunOS 5.11 Last change: Jun 27, 2010 19
User Commands XORRISO(1)
under that directory as would be done with an existing
directory.
If a single disk_path is present then a non-existing
iso_rr_path will get the same type as the disk_path.
If a disk_path does not begin with '/' then -cdx is
prepended. If the iso_rr_path does not begin with '/'
then -cd is prepended.
-mkdir iso_rr_path [...]
Create empty directories if they do not exist yet.
Existence as directory generates a WARNING event,
existence as other file causes a FAILURE event.
Settings for file insertion:
-file_size_limit value [value [...]] --
Set the maximum permissible size for a single data
file. The values get summed up for the actual limit. If
the only value is "off" then the file size is not
limited by xorriso. Default is a limit of 100 extents,
4g -2k each:
-file_size_limit 400g -200k --
When mounting ISO 9660 filesystems, old operating
systems can handle only files up to 2g -1 --. Newer
ones are good up to 4g -1 --. You need quite a new
Linux kernel to read correctly the final bytes of a
file >= 4g if its size is not aligned to 2048 byte
blocks.
xorriso's own data read capabilities are not affected
by eventual operating system size limits. They apply to
mounting only. Nevertheless, the target filesystem of
an -extract must be able to take the file size.
-not_mgt code[:code[...]]
Control the behavior of the exclusion lists.
Exclusion processing happens before disk_paths get
mapped to the ISO image and before disk files get
compared with image files. The absolute disk path of
the source is matched against the -not_paths list. The
leafname of the disk path is matched against the
patterns in the -not_leaf list. If a match is detected
then the disk path will not be regarded as an existing
file and not be added to the ISO image.
Several codes are defined. The _on/_off settings
persist until they are revoked by their_off/_on
counterparts.
"erase" empties the lists which were accumulated by
-not_paths and -not_leaf.
"reset" is like "erase" but also re-installs default
behavior.
"off" disables exclusion processing temporarily without
invalidating the lists and settings.
SunOS 5.11 Last change: Jun 27, 2010 20
User Commands XORRISO(1)
"on" re-enables exclusion processing.
"param_off" applies exclusion processing only to paths
below disk_path parameter of commands. I.e. explicitly
given disk_paths are exempted from exclusion
processing.
"param_on" applies exclusion processing to command
parameters as well as to files below such parameters.
"subtree_off" with "param_on" excludes parameter paths
only if they match a -not_paths item exactly.
"subtree_on" additionally excludes parameter paths
which lead to a file address below any -not_paths item.
"ignore_off" treats excluded disk files as if they were
missing. I.e. they get reported with -compare and
deleted from the image with -update.
"ignore_on" keeps excluded files out of -compare or
-update activities.
-not_paths disk_path [***]
Add the given paths to the list of excluded absolute
disk paths. If a given path is relative, then the
current -cdx is prepended to form an absolute path.
Eventual pattern matching happens at definition time
and not when exclusion checks are made.
(Do not forget to end the list of disk_paths by "--")
-not_leaf pattern
Add a single shell parser style pattern to the list of
exclusions for disk leafnames. These patterns are
evaluated when the exclusion checks are made.
-not_list disk_path
Read lines from disk_path and use each of them either
as -not_paths argument, if they contain a / character,
or as -not_leaf pattern.
-quoted_not_list disk_path
Like -not_list but with quoted input reading rules.
Each word is handled as one argument for -not_paths
resp. -not_leaf.
-follow occasion[:occasion[...]]
Enable or disable resolution of symbolic links and
mountpoints under disk_paths. This applies to actions
-add, -du*x, -ls*x, -findx, and to -disk_pattern
expansion.
There are two kinds of follow decisison to be made:
"link" is the hop from a symbolic link to its target
file object. If enabled then symbolic links are
handled as their target file objects, else symbolic
links are handled as themselves.
"mount" is the hop from one filesystem to another
subordinate filesystem. If enabled then mountpoint
SunOS 5.11 Last change: Jun 27, 2010 21
User Commands XORRISO(1)
directories are handled as any other directory, else
mountpoints are handled as empty directories if they
are encountered in directory tree traversals.
Less general than above occasions:
"pattern" is mount and link hopping, but only during
-disk_pattern expansion.
"param" is link hopping for parameter words (after
eventual pattern expansion). If enabled then -ls*x
will show the link targets rather than the links
themselves. -du*x, -findx, and -add will process the
link targets but not follow links in an eventual
directory tree below the targets (unless "link" is
enabled).
Occasions can be combined in a colon separated list.
All occasions mentioned in the list will then lead to a
positive follow decision.
"off" prevents any positive follow decision. Use it if
no other occasion applies.
Shortcuts:
"default" is equivalent to "pattern:mount:limit=100".
"on" always decides positive. Equivalent to
"link:mount".
Not an occasion but an optional setting is:
"limit="<number> which sets the maximum number of link
hops. A link hop consists of a sequence of symbolic
links and a final target of different type.
Nevertheless those hops can loop. Example:
$ ln -s .. uploop
Link hopping has a built-in loop detection which stops
hopping at the first repetition of a link target. Then
the repeated link is handled as itself and not as its
target. Regrettably one can construct link networks
which cause exponential workload before their loops get
detected. The number given with "limit=" can curb this
workload at the risk of truncating an intentional
sequence of link hops.
-pathspecs "on"|"off"
Control parameter interpretation with xorriso actions
-add and -path_list.
"on" enables pathspecs of the form target=source like
with program mkisofs -graft-points. It also disables
-disk_pattern expansion for command -add.
"off" disables pathspecs of the form target=source and
eventually enables -disk_pattern expansion.
-overwrite "on"|"nondir"|"off"
Allow or disallow to overwrite existing files in the
ISO image by files with the same name.
With setting "off", name collisions cause FAILURE
events. With setting "nondir", only directories are
SunOS 5.11 Last change: Jun 27, 2010 22
User Commands XORRISO(1)
protected by such events, other existing file types get
treated with -rm before the new file gets added.
Setting "on" allows automatic -rm_r. I.e. a non-
directory can replace an existing directory and all its
subordinates.
If restoring of files is enabled, then the overwrite
rule applies to the target file objects on disk as
well, but "on" is downgraded to "nondir".
-split_size number["k"|"m"]
Set the threshold for automatic splitting of regular
files. Such splitting maps a large disk file onto a ISO
directory with several part files in it. This is
necessary if the size of the disk file exceeds
-file_size_limit. Older operating systems can handle
files in mounted ISO 9660 filesystems only if they are
smaller than 2 GiB resp. 4 GiB.
Default is 0 which will exclude files larger than
-file_size_limit by a FAILURE event. A well tested
-split_size is 2047m. Sizes above -file_size_limit are
not permissible.
While option -split_size is set larger than 0 such a
directory with split file pieces will be recognized and
handled like a regular file by options -compare* ,
-update*, and in overwrite situations. There are
-ossirox options "concat_split_on" and
"concat_split_off" which control the handling when
files get restored to disk.
In order to be recognizable, the names of the part
files have to describe the splitting by 5 numbers:
part_number,total_parts,byte_offset,byte_count,disk_file_size
which are embedded in the following text form:
part_#_of_#_at_#_with_#_of_#
Scaling characters like "m" or "k" are taken into
respect. All digits are interpreted as decimal, even
if leading zeros are present.
E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
No other files are allowed in the directory. All parts
have to be present and their numbers have to be
plausible. E.g. byte_count must be valid as -cut_out
argument and their contents may not overlap.
File manipulations:
The following commands manipulate files in the ISO image,
regardless whether they stem from the loaded image or were
newly inserted.
-iso_rr_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the iso_rr_path
arguments of several commands which support this
feature.
SunOS 5.11 Last change: Jun 27, 2010 23
User Commands XORRISO(1)
Setting "off" disables pattern expansion for all
commands which are marked in this man page by
"iso_rr_path [***]" or "iso_rr_pattern [***]".
Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked
by "iso_rr_pattern [***]".
Default is "on".
-rm iso_rr_path [***]
Delete the given files from the ISO image.
Note: This does not free any space on the -indev media,
even if the deletion is committed to that same media.
The image size will shrink if the image is written to a
different media in modification mode.
-rm_r iso_rr_path [***]
Delete the given files or directory trees from the ISO
image. See also the note with option -rm.
-rmdir iso_rr_path [***]
Delete empty directories.
-mv iso_rr_path [***] iso_rr_path
Rename the given file objects in the ISO tree to the
last argument in the list. Use the same rules as with
shell command mv.
If pattern expansion is enabled and if the last
argument contains wildcard characters then it must
match exactly one existing file address, or else the
command fails with a FAILURE event.
-chown uid iso_rr_path [***]
Set ownership of file objects in the ISO image. uid may
either be a decimal number or the name of a user known
to the operating system.
-chown_r uid iso_rr_path [***]
Like -chown but affecting all files below eventual
directories.
-chgrp gid iso_rr_path [***]
Set group attribute of file objects in the ISO image.
gid may either be a decimal number or the name of a
group known to the operating system.
-chgrp_r gid iso_rr_path [***]
Like -chgrp but affecting all files below eventual
directories.
-chmod mode iso_rr_path [***]
Equivalent to shell command chmod in the ISO image.
mode is either an octal number beginning with "0" or a
SunOS 5.11 Last change: Jun 27, 2010 24
User Commands XORRISO(1)
comma separated list of statements of the form
[ugoa]*[+-=][rwxst]* .
Like: go-rwx,u+rwx .
Personalities: u=user, g=group, o=others, a=all
Operators: + adds given permissions, - revokes given
permissions, = revokes all old permissions and then
adds the given ones.
Permissions: r=read, w=write, x=execute|inspect,
s=setuid|setgid, t=sticky bit
For octal numbers see man 2 stat.
-chmod_r mode iso_rr_path [***]
Like -chmod but affecting all files below eventual
directories.
-setfacl acl_text iso_rr_path [***]
Attach the given ACL to the given iso_rr_paths after
deleting their eventually existing ACLs. If acl_text
is empty, or contains the text "clear" or the text
"--remove-all", then the existing ACLs will be removed
and no new ones will be attached. Any other content of
acl_text will be interpreted as a list of ACL entries.
It may be in the long multi-line format as put out by
-getfacl but may also be abbreviated as follows:
ACL entries are separated by comma or newline. If an
entry is empty text or begins with "#" then it will be
ignored. A valid entry has to begin by a letter out of
{ugom} for "user", "group", "other", "mask". It has to
contain two colons ":". A non-empty text between those
":" gives a user id resp. group id. After the second
":" there may be letters out of {rwx- #}. The first
three give read, write resp. execute permission.
Letters "-", " " and TAB are ignored. "#" causes the
rest of the entry to be ignored. Letter "X" or any
other letters are not supported. Examples:
g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
A valid entry may be prefixed by "d", some following
characters and ":". This indicates that the entry goes
to the "default" ACL rather than to the "access" ACL.
Example:
u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
-setfacl_r acl_text iso_rr_path [***]
Like -setfacl but affecting all files below eventual
directories.
-setfacl_list disk_path
Read the output of -getfacl_r or shell command getfacl
-R and apply it to the iso_rr_paths as given in lines
beginning with "# file:". This will change ownership,
group and ACL of the given files. If disk_path is "-"
SunOS 5.11 Last change: Jun 27, 2010 25
User Commands XORRISO(1)
then lines are read from standard input. Line "@" ends
the list, "@@@" aborts without changing the pending
iso_rr_path.
Since -getfacl and getfacl -R strip leading "/" from
file paths, the setting of -cd does always matter.
-setfattr [-]name value iso_rr_path [***]
Attach the given xattr pair of name and value to the
given iso_rr_paths. If the given name is prefixed by
"-", then the pair with that name gets removed from the
xattr list. If name is "--remove-all" then all user
namespace xattr of the given iso_rr_paths get deleted.
In case of deletion, value must be an empty text.
Only names from the user namespace are allowed. I.e. a
name has to begin with "user.", like "user.x" or
"user.whatever".
Values and names undergo the normal input processing of
xorriso. See also option -backslash_codes. Other than
with option -setfattr_list, the byte value 0 cannot be
expressed via -setfattr.
-setfattr_r [-]name value iso_rr_path [***]
Like -setfattr but affecting all files below eventual
directories.
-setfattr_list disk_path
Read the output of -getfattr_r or shell command
getfattr -Rd and apply it to the iso_rr_paths as given
in lines beginning with "# file:". All previously
existing user space xattr of the given iso_rr_paths
will be deleted. If disk_path is "-" then lines are
read from standard input.
Since -getfattr and getfattr -Rd strip leading "/" from
file paths, the setting of -cd does always matter.
Empty input lines and lines which begin by "#" will be
ignored (except "# file:"). Line "@" ends the list,
"@@@" aborts without changing the pending iso_rr_path.
Other input lines must have the form
name="value"
Name must be from user namespace. I.e. user.xyz where
xyz should consist of printable characters only. The
separator "=" is not allowed in names. Value may
contain any kind of bytes. It must be in quotes.
Trailing whitespace after the end quote will be
ignored. Non-printables bytes and quotes must be
represented as \XYZ by their octal ASCII code XYZ. Use
code \000 for 0-bytes.
-alter_date type timestring iso_rr_path [***]
Alter the date entries of a file in the ISO image. type
is one of "a", "m", "b" for access time, modification
time, both times.
SunOS 5.11 Last change: Jun 27, 2010 26
User Commands XORRISO(1)
timestring may be in the following formats (see also
section EXAMPLES):
As expected by program date:
MMDDhhmm[[CC]YY][.ss]]
As produced by program date:
[Day] MMM DD hh:mm:ss [TZON] YYYY
Relative times counted from current clock time:
+|-Number["s"|"h"|"d"|"w"|"m"|"y"]
where "s" means seconds, "h" hours, "d" days, "w"
weeks, "m"=30d, "y"=365.25d plus 1d added to
multiplication result.
Absolute seconds counted from Jan 1 1970:
=Number
xorriso's own timestamps:
YYYY.MM.DD[.hh[mm[ss]]]
scdbackup timestamps:
YYMMDD[.hhmm[ss]]
where "A0" is year 2000, "B0" is 2010, etc.
-alter_date_r type timestring iso_rr_path [***]
Like -alter_date but affecting all files below eventual
directories.
-hide hide_state iso_rr_path [***]
Prevent the names of the given files from showing up in
the directory trees of ISO 9660 and/or Joliet when the
image gets written. The eventual data content of such
hidden files will be included in the resulting image,
even if they do not show up in any directory. But you
will need own means to find nameless data in the image.
Warning: Data which are hidden from the ISO 9660 tree
will not be copied by the write method of modifying.
Possible values of hide_state are: "iso_rr" for hiding
from ISO 9660 tree, "joliet" for Joliet tree, "on" for
both trees. "off" means visibility in both directory
trees.
This command does not apply to the boot catalog.
Rather use: -boot_image "any" "cat_hidden=on"
Tree traversal command -find:
--
-find iso_rr_path [test [op] [test ...]] [-exec action
[params]]
A restricted substitute for shell command find in the
ISO image. It performs an action on matching file
objects at or below iso_rr_path.
If not used as last command in the line then the
argument list needs to get terminated by "--".
Tests are optional. If they are omitted then action is
applied to all file objects. If tests are given then
they form together an expression. The action is
SunOS 5.11 Last change: Jun 27, 2010 27
User Commands XORRISO(1)
applied only if the expression matches the file object.
Default expression operator between tests is -and, i.e.
the expression matches only if all its tests match.
Available tests are:
-name pattern : Matches if pattern matches the file
leaf name.
-wholename pattern : Matches if pattern matches the
file path as it would be printed by action "echo".
Character '/' is not special but can be matched by
wildcards.
-disk_name pattern : Like -name but testing the leaf
name of the file source on disk. Can be true only for
data files which stem not from the loaded image.
-type type_letter : Matches files of the given type:
"block", "char", "dir", "pipe", "file", "link",
"socket", "eltorito", "Xotic" which eventually matches
what is not matched by the other types.
Only the first letter is interpreted. E.g.: -find /
-type d
-damaged : Matches files which use data blocks marked
as damaged by a previous run of -check_media. The
damage info vanishes when a new ISO image gets loaded.
-pending_data : Matches files which get their content
from outside the loaded ISO image.
-lba_range start_lba block_count : Matches files which
use data blocks within the range of start_lba and
start_lba+block_count-1.
-has_acl : Matches files which have a non-trivial ACL.
-has_xattr : Matches files which have xattr name-value
pairs from user namespace.
-has_aaip : Matches files which have ACL or any xattr.
-has_any_xattr : Matches files which have any xattr
other than ACL.
-has_md5 : Matches data files which have MD5 checksums.
-has_filter : Matches files which are filtered by
-set_filter.
-hidden hide_state : Matches files which are hidden in
"iso_rr" tree, in "joliet" tree, in both trees ("on"),
or not hidden in any tree ("off"). Those which are
hidden in some tree match -not -hidden "off".
-prune : If this test is reached and the tested file is
a directory then -find will not dive into that
directory. This test itself does always match.
-decision "yes"|"no" : If this test is reached then the
evaluation ends immediately and action is performed if
the decision is "yes" or "true". See operator -if.
-true and -false : Always match resp. match not.
Evaluation goes on.
-sort_lba : Always match. This causes -find to perform
its action in a sequence sorted by the ISO image block
addresses of the files. It may improve throughput with
actions which read data from optical drives. Action
SunOS 5.11 Last change: Jun 27, 2010 28
User Commands XORRISO(1)
will always get the absolute path as parameter.
Available operators are:
-not : Matches if the next test or sub expression does
not match. Several tests do this specifically:
-undamaged, -lba_range with negative start_lba,
-has_no_acl, -has_no_xattr, -has_no_aaip,
-has_no_filter .
-and : Matches if both neighboring tests or expressions
match.
-or : Matches if at least one of both neighboring tests
or expressions matches.
-sub ... -subend or ( ... ) : Enclose a sub expression
which gets evaluated first before it is processed by
neighboring operators. Normal precedence is: -not, -or
, -and.
-if ... -then ... -elseif ... -then ... -else ...
-endif : Enclose one or more sub expressions. If the
-if expression matches, then the -then expression is
evaluated as the result of the whole expression up to
-endif. Else the next -elseif expression is evaluated
and eventually its -then expression. Finally in case of
no match, the -else expression is evaluated. There may
be more than one -elseif. Neither -else nor -elseif are
mandatory. If -else is missing and would be hit, then
the result is a non-match.
-if-expressions are the main use case for above test
-decision.
Default action is echo, i.e. to print the address of
the found file. Other actions are certain xorriso
commands which get performed on the found files. These
commands may have specific parameters. See also their
particular descriptions.
chown and chown_r change the ownership and get the user
id as parameter. E.g.: -exec chown thomas --
chgrp and chgrp_r change the group attribute and get
the group id as parameter. E.g.: -exec chgrp_r staff --
chmod and chmod_r change access permissions and get a
mode string as parameter. E.g.: -exec chmod a-w,a+r --
alter_date and alter_date_r change the timestamps. They
get a type character and a timestring as parameters.
E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" --
lsdl prints file information like shell command ls -dl.
compare performs command -compare with the found file
address as iso_rr_path and the corresponding file
address below its argument disk_path_start. For this
the iso_rr_path of the -find command gets replaced by
the disk_path_start.
E.g.: -find /thomas -exec compare /home/thomas --
update performs command -update with the found file
address as iso_rr_path. The corresponding file address
is determined like with above action "compare".
SunOS 5.11 Last change: Jun 27, 2010 29
User Commands XORRISO(1)
rm removes the found iso_rr_path from the image if it
is not a directory with files in it. I.e. this "rm"
includes "rmdir".
rm_r removes the found iso_rr_path from the image,
including whole directory trees.
report_damage classifies files whether they hit a data
block that is marked as damaged. The result is printed
together with the eventual address of the first damaged
byte, the maximum span of damages, file size, and the
path of the file.
report_lba prints files which are associated to image
data blocks. It tells the logical block address, the
block number, the byte size, and the path of each file.
There may be reported more than one line per file if
the file is very large. In this case each line has a
different extent number in column "xt".
getfacl prints access permissions in ACL text form to
the result channel.
setfacl attaches ACLs after removing eventually exiting
ones. The new ACL is given in text form as defined with
option -setfacl.
E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
getfattr prints eventual xattr name-value pairs from
user namespace to the result channel.
get_any_xattr prints eventual xattr name-value pairs
from any namespace except ACL to the result channel.
This is mostly for debugging of namespace "isofs".
get_md5 prints eventual recorded MD5 sum together with
file path.
check_md5 compares eventual recorded MD5 sum with the
file content and reports if mismatch.
E.g.: -find / -not -pending_data -exec check_md5
FAILURE --
make_md5 equips a data file with an MD5 sum of its
content. Useful to upgrade the files in the loaded
image to full MD5 coverage by the next commit with -md5
"on".
E.g.: -find / -type f -not -has_md5 -exec make_md5 --
setfattr sets or deletes xattr name value pairs.
E.g.: -find / -has_xattr -exec setfattr --remove-all ''
--
set_filter applies or removes filters.
E.g.: -exec set_filter --zisofs --
mkisofs_r applies the rules of mkisofs -r to the file
object:
user id and group id become 0, all r-permissions get
granted, all w denied. If there is any x-permission,
then all three x get granted. s- and t-bits get
removed.
sort_weight attributes a LBA weight number to regular
files.
The number may range from -2147483648 to 2147483647.
SunOS 5.11 Last change: Jun 27, 2010 30
User Commands XORRISO(1)
The higher it is, the lower will be the block address
of the file data in the emerging ISO image. Currently
the boot catalog has a hardcoded weight of 1 billion.
Normally it should occupy the block with the lowest
possible address. Data files get added or loaded with
initial weight 0.
E.g.: -exec sort_weight 3 --
show_stream shows the content stream chain of a data
file.
hide brings the file into one of the hide states "on",
"iso_rr", "joliet", "off".
E.g.:
-find / -disk_name *_secret -exec hide on
find performs another run of -find on the matching file
address. It accepts the same params as -find, except
iso_rr_path.
E.g.:
-find / -name '???' -type d -exec find -name '[abc]*'
-exec chmod a-w,a+r --
Filters for data file content:
Filters may be installed between data files in the ISO image
and their content source outside the image. They may also be
used vice versa between data content in the image and target
files on disk.
Built-in filters are "--zisofs" and "--zisofs-decode". The
former is to be applied via -set_filter, the latter is
automatically applied if zisofs compressed content is
detected with a file when loading the ISO image.
Another built-in filter pair is "--gzip" and "--gunzip" with
suffix ".gz". They behave about like external gzip and
gunzip but avoid forking a process for each single file. So
they are much faster if there are many small files.
-external_filter name option[:option] program_path
[arguments] --
Register a content filter by associating a name with a
program path, program arguments, and some behavioral
options. Once registered it can be applied to multiple
data files in the ISO image, regardless whether their
content resides in the loaded ISO image or in the local
filesystem. External filter processes may produce
synthetic file content by reading the original content
from stdin and writing to stdout whatever they want.
They must deliver the same output on the same input in
repeated runs.
Options are:
"default" means that no other option is intended.
"suffix=..." sets a file name suffix. If it is not
empty then it will be appended to the file name or
removed from it.
SunOS 5.11 Last change: Jun 27, 2010 31
User Commands XORRISO(1)
"remove_suffix" will remove an eventual file name
suffix rather than appending it.
"if_nonempty" will leave 0-sized files unfiltered.
"if_reduction" will try filtering and revoke it if the
content size does not shrink.
"if_block_reduction" will revoke if the number of 2 kB
blocks does not shrink.
"used=..." is ignored. Command -status shows it with
the number of files which currently have the filter
applied.
Examples:
-external_filter bzip2 suffix=.bz2:if_block_reduction
\
/usr/bin/bzip2 --
-external_filter bunzip2 suffix=.bz2:remove_suffix \
/usr/bin/bunzip2 --
-unregister_filter name
Remove an -external_filter registration. This is only
possible if the filter is not applied to any file in
the ISO image.
-close_filter_list
Irrevocably ban commands -external_filter and
-unregister_filter, but not -set_filter. Use this to
prevent external filtering in general or when all
intended filters are registered. External filters may
also be banned totally at compile time of xorriso. By
default they are banned if xorriso runs under setuid
permission.
-set_filter name iso_rr_path [***]
Apply an -external_filter or a built-in filter to the
given data files in the ISO image. If the filter
suffix is not empty , then it will be applied to the
file name. Renaming only happens if the filter really
gets attached and is not revoked by its options. By
default files which already bear the suffix will not
get filtered. The others will get the suffix appended
to their names. If the filter has option
"remove_suffix", then the filter will only be applied
if the suffix is present and can be removed. Name
oversize or collision caused by suffix change will
prevent filtering.
With most filter types this command will immediately
run the filter once for each file in order to determine
the output size. Content reading operations like
-extract , -compare and image generation will perform
further filter runs and deliver filtered content.
At image generation time the filter output must still
be the same as the output from the first run. Filtering
for image generation does not happen with files from
SunOS 5.11 Last change: Jun 27, 2010 32
User Commands XORRISO(1)
the loaded ISO image if the write method of growing is
in effect (i.e -indev and -outdev are identical).
The reserved filter name "--remove-all-filters" revokes
filtering. This will revoke eventual suffix renamings
as well. Use "--remove-all-filters+" to prevent any
suffix renaming.
-set_filter_r name iso_rr_path [***]
Like -set_filter but affecting all data files below
eventual directories.
Writing the result, drive control:
(see also paragraph about settings below)
-rollback
Discard the manipulated ISO image and reload it from
-indev. (Use -rollback_end if immediate program end is
desired.)
-commit
Perform the write operation. Afterwards eventually make
the -outdev the new -dev and load the image from there.
Switch to growing mode. (A subsequent -outdev will
activate modification mode or blind growing.) -commit
is performed automatically at end of program if there
are uncommitted manipulations pending.
So, to perform a final write operation with no new -dev
and no new loading of image, rather execute option
-end. If you want to go on without image loading,
execute -commit_eject "none". To eject after write
without image loading, use -commit_eject "all".
To suppress a final write, execute -rollback_end.
Writing can last quite a while. It is not unnormal with
several types of media that there is no progress
visible for the first few minutes or that the drive
gnaws on the media for a few minutes after all data
have been transmitted. xorriso and the drives are in a
client-server relationship. The drives have much
freedom about what to do with the media. Some
combinations of drives and media simply do not work,
despite the promises by their vendors. If writing
fails then try other media or another drive. The reason
for such failure is hardly ever in the code of the
various burn programs but you may well try some of
those listed below under SEE ALSO.
-eject "in"|"out"|"all"
Eject the media in -indev, resp. -outdev, resp. both
drives. Note: It is not possible yet to effectively
eject disk files.
SunOS 5.11 Last change: Jun 27, 2010 33
User Commands XORRISO(1)
-commit_eject "in"|"out"|"all"|"none"
Combined -commit and -eject. When writing has finished
do not make -outdev the new -dev, and load no ISO
image. Rather eject -indev and/or -outdev. Eventually
give up any non-ejected drive.
-blank mode
Make media ready for writing from scratch (if not
-dummy is activated).
This affects only the -outdev not the -indev. If both
drives are the same and if the ISO image was altered
then this command leads to a FAILURE event. Defined
modes are:
as_needed, fast, all, deformat, deformat_quickest
"as_needed" cares for used CD-RW, DVD-RW and for used
overwriteable media by applying -blank "fast". It
applies -format "full" to yet unformatted 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 event.
"fast" makes CD-RW and unformatted DVD-RW re-usable, or
invalidates overwriteable ISO images. "all" might work
more thoroughly and need more time.
"deformat" converts overwriteable DVD-RW into
unformatted ones.
"deformat_quickest" is a faster way to deformat or
blank DVD-RW but produces media which are only suitable
for a single session. xorriso will write onto them
only if option -close is set to "on".
The progress reports issued by some drives while
blanking are quite unrealistic. Do not conclude success
or failure from the reported percentages. Blanking was
successful if no SORRY event or worse occured.
-format mode
Convert unformatted DVD-RW into overwriteable ones,
"de-ice" DVD+RW, format newly purchased BD-RE or BD-R,
re-format DVD-RAM or BD-RE.
Defined modes are:
as_needed, full, fast, by_index_<num>,
fast_by_index_<num>
"as_needed" formats yet unformatted DVD-RW, DVD-RAM,
BD-RE, or blank unformatted BD-R. Other media are left
untouched.
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or
blank unformatted BD-R.
"fast" does the same as "full" but tries to be quicker.
"by_index_" selects a format out of the descriptor list
issued by option -list_formats. The index number from
that list is to be appended to the mode word. E.g:
"by_index_3".
"fast_by_index_" does the same as "by_index_" but tries
SunOS 5.11 Last change: Jun 27, 2010 34
User Commands XORRISO(1)
to be quicker.
"by_size_" selects a format out of the descriptor list
which provides at least the given size. That size is to
be appended to the mode word. E.g: "by_size_4100m".
This applies to media with Defect Management.
"fast_by_size_" does the same as "by_size_" but tries
to be quicker.
The formatting action has no effect on media if -dummy
is activated.
Formatting is normally needed only once during the
lifetime of a media, if ever. But it is a reason for
re-formatting if:
DVD-RW was deformatted by -blank,
DVD+RW has read failures (re-format before next
write),
DVD-RAM or BD-RE shall change their amount of defect
reserve.
BD-R may be written unformatted or may be formatted
before first use. Formatting activates Defect
Management which tries to catch and repair bad spots on
media during the write process at the expense of half
speed even with flawless media.
The progress reports issued by some drives while
formatting are quite unrealistic. Do not conclude
success or failure from the reported percentages.
Formatting was successful if no SORRY event or worse
occured. Be patient with apparently frozen progress.
-list_formats
Put out a list of format descriptors as reported by the
output drive for the current media. The list gives the
index number after "Format idx", a MMC format code, the
announced size in blocks (like "2236704s") and the same
size in MiB.
MMC format codes are manifold. Most important are:
"00h" general formatting, "01h" increases reserve space
for DVD-RAM, "26h" for DVD+RW, "30h" for BD-RE with
reserve space, "31h" for BD-RE without reserve space,
"32h" for BD-R.
Smaller format size with DVD-RAM, BD-RE, or BD-R means
more reserve space.
-list_profiles "in"|"out"|"all"
Put out a list of media types supported by -indev,
resp. -outdev, resp. both. The currently recognized
type is marked by text "(current)".
Settings for result writing:
Rock Ridge info will be generated by the program
unconditionally. ACLs will be written according to the
setting of option -acl.
SunOS 5.11 Last change: Jun 27, 2010 35
User Commands XORRISO(1)
-joliet "on"|"off"
If enabled by "on", generate Joliet tree additional to
ISO 9660 + Rock Ridge tree.
-compliance rule[:rule...]
Adjust the compliance to specifications of ISO 9660 and
its contemporary extensions. In some cases it is worth
to deviate a bit in order to circumvent bugs of the
intended reader system or to get unofficial extra
features.
There are several adjustable rules which have a keyword
each. If they are mentioned with this option then their
rule gets added to the relaxation list. This list can
be erased by rules "strict" or "clear". It can be reset
to its start setting by "default". All of the following
relaxation rules can be revoked individually by
appending "_off". Like "deep_paths_off".
Rule keywords are:
"omit_version" do not add versions (";1") to ISO and
Joliet file names.
"only_iso_version" do not add versions (";1") to Joliet
file names.
"deep_paths" allow ISO file paths deeper than 8 levels.
"long_paths" allow ISO file paths longer than 255
characters.
"long_names" allow up to 37 characters with ISO file
names.
"no_force_dots" do not add a dot to ISO file names
which have none.
"no_j_force_dots" do not add a dot to Joliet file names
which have none.
"lowercase" allow lowercase characters in ISO file
names.
"full_ascii" allow all ASCII characters in ISO file
names.
"joliet_long_paths" allow Joliet paths longer than 240
characters.
"always_gmt" store timestamps in GMT representation
with timezone 0.
"rec_mtime" record with ISO files the disk file's mtime
and not the creation time of the image.
"new_rr" use 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
by subsequent "aaip_susp_1_10".
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" allows AAIP to be written as
unofficial extension of RRIP rather than as official
extension under SUSP-1.12.
"no_emul_toc" saves 64 kB with the first session on
SunOS 5.11 Last change: Jun 27, 2010 36
User Commands XORRISO(1)
overwriteable media but makes the image incapable of
displaying its session history.
Default setting is
"clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
always_gmt:old_rr".
Note: The term "ISO file" means the plain ISO 9660
names and attributes which get visible if the reader
ignores Rock Ridge.
-volid text
Specify the volume ID. xorriso accepts any text up to
32 characters, but according to rarely obeyed specs
stricter rules apply:
ECMA 119 demands ASCII characters out of [A-Z0-9_].
Like: "IMAGE_23"
Joliet allows 16 UCS-2 characters. Like: "Windows name"
Be aware that the volume id might get used
automatically as name of the mount point when the media
is inserted into a playful computer system.
If an ISO image gets loaded while the volume ID is set
to default "ISOIMAGE" or to "", then the volume ID of
the loaded image will become the effective volume id
for the next write run. But as soon as command -volid
is performed afterwards, this pending id is overridden
by the new setting.
Consider this when setting -volid "ISOIMAGE" before
executing -dev, -indev, or -rollback. If you insist in
-volid "ISOIMAGE", set it again after those commands.
-volset_id text
Set the volume set id string to be written with the
next -commit. Permissible are up to 128 characters.
This setting gets overridden by image loading.
-publisher text
Set the publisher id string to be written with the next
-commit. This may identify the person or organisation
who specified what shall be recorded. Permissible are
up to 128 characters. This setting gets overridden by
image loading.
-application_id text
Set the application id string to be written with the
next -commit. This may identify the specification of
how the data are recorded. Permissible are up to 128
characters. This setting gets overridden by image
loading.
-system_id text
Set the system id string to be written with the next
-commit. This may identify the system which can
recognize and act upon the content of the System Area
SunOS 5.11 Last change: Jun 27, 2010 37
User Commands XORRISO(1)
in image blocks 0 to 15. Permissible are up to 32
characters. This setting gets overridden by image
loading.
-volume_date type timestring
Set one of the four overall timestamps for subsequent
image writing. Available types are:
"c" time when the volume was created.
"m" time when volume was last modified.
"x" time when the information in the volume expires.
"f" time since when the volume is effectively valid.
"uuid" sets a timestring that overrides "c" and "m"
times literally. It must consist of 16 decimal digits
which form YYYYMMDDhhmmsscc, with YYYY between 1970 and
2999. Time zone is GMT. It is supposed to match this
GRUB line:
search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc
E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0
centiseconds).
Timestrings for the other types may be given as with
option -alter_date. They are prone to timezone
computations. The timestrings "default" or "overridden"
cause default settings: "c" and "m" will show the
current time of image creation. "x" and "f" will be
marked as insignificant. "uuid" will be deactivated.
-copyright_file text
Set the copyright file name to be written with the next
-commit. This should be the ISO 9660 path of a file in
the image which contains a copyright statement.
Permissible are up to 37 characters. This setting gets
overridden by image loading.
-abstract_file text
Set the abstract file name to be written with the next
-commit. This should be the ISO 9660 path of a file in
the image which contains an abstract statement about
the image content. Permissible are up to 37
characters. This setting gets overridden by image
loading.
-biblio_file text
Set the biblio file name to be written with the next
-commit. This should be the ISO 9660 path of a file in
the image which contains bibliographic records.
Permissible are up to 37 characters. This setting gets
overridden by image loading.
-out_charset character_set_name
Set the character set to which file names get converted
when writing an image. See paragraph "Character sets"
for more explanations. When loading the written image
SunOS 5.11 Last change: Jun 27, 2010 38
User Commands XORRISO(1)
after -commit the setting of -out_charset will be
copied to -in_charset.
-uid uid
User id to be used for all files when the new ISO tree
gets written to media.
-gid gid
Group id to be used for all files when the new ISO tree
gets written to media.
-zisofs option[:options]
Set global parameters for zisofs compression. This data
format is recognized and transparently uncompressed by
some Linux kernels. It is to be applied via option
-set_filter with built-in filter "--zisofs".
Parameters are:
"level="[0-9] zlib compression: 0=none, 1=fast,...,
9=slow
"block_size="32k|64k|128k size of compression blocks
"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
mkzftree.
"default" same as
"level=6:block_size=32k:by_magic=off"
-speed number[k|m|c|d|b]
Set the burn speed. Default is 0 = maximum speed.
Speed can be given in media dependent numbers or as a
desired throughput per second in MMC compliant kB (=
1000) or MB (= 1000 kB). Media x-speed factor can be
set explicity by "c" for CD, "d" for DVD, "b" for BD,
"x" is optional.
Example speeds:
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then
the media in the -outdev will decide. Default unit is
CD = 176.4k.
MMC drives usually activate their own idea of speed and
take the speed value given by the burn program only as
upper limit for their own decision.
-stream_recording "on"|"off"|"full"|"data"|number
Setting "on" tries to circumvent the management of
defects on DVD-RAM, BD-RE, or BD-R. Defect management
keeps partly damaged media usable. But it reduces write
speed to half nominal speed even if the media is in
perfect shape. For the case of flawless media, one may
use -stream_recording "on" to get full speed.
"full" tries full speed with all write operations,
SunOS 5.11 Last change: Jun 27, 2010 39
User Commands XORRISO(1)
whereas "on" does this only above byte address 32s. One
may give a number of at least 16s in order to set an
own address limit.
"data" causes full speed to start when superblock and
directory entries are written and writing of file
content blocks begins.
-dvd_obs "default"|"32k"|"64k"
GNU/Linux specific: Set the number of bytes to be
transmitted with each write operation to DVD or BD
media. A number of 64 KB may improve throughput with
bus systems which show latency problems. The default
depends on media type, on option -stream_recording ,
and on compile time options.
-stdio_sync "on"|"off"|number
Set the number of bytes after which to force output to
stdio: pseudo drives. This forcing keeps the memory
from being clogged with lots of pending data for slow
devices. Default "on" is the same as "16m". Forced
output can be disabled by "off".
-dummy "on"|"off"
If "on" then simulate burning or refuse with FAILURE
event if no simulation is possible, do neither blank
nor format.
-fs number["k"|"m"]
Set the size of the fifo buffer which smoothens the
data stream from ISO image generation to media burning.
Default is 4 MiB, minimum 64 kiB, maximum 1 GiB. The
number may be followed by letter "k" or "m" which means
unit is kiB (= 1024) or MiB (= 1024 kiB).
-close "on"|"off"
If "on" then mark the written media as not appendable
any more (if possible at all with the given type of
target media).
This is the contrary of cdrecord, wodim, cdrskin option
-multi, and is one aspect of growisofs option -dvd-
compat.
-padding number["k"|"m"]
Append the given number of extra bytes to the image
stream. This is a traditional remedy for a traditional
bug in block device read drivers. Needed only for CD
recordings in TAO mode. Since one can hardly predict
on what media an image might end up, xorriso adds the
traditional 300k of padding by default to all images.
For images which will never get to a CD it is safe to
use -padding 0 .
SunOS 5.11 Last change: Jun 27, 2010 40
User Commands XORRISO(1)
El Torito bootable ISO images:
Contrary to published specifications many BIOSes will load
an El Torito record from the first session on media and not
from the last one, which gets mounted by default. This makes
no problems with overwriteable media, because they appear to
inadverted readers as one single session.
But with multi-session media CD-R[W], DVD-R[W], DVD+R, it
implies that the whole bootable system has to reside already
in the first session and that the last session still has to
bear all files which the booted system expects after
eventually mounting the ISO image.
If a boot image from ISOLINUX or GRUB is known to be present
on media then it is advised to patch it when a follow-up
session gets written. But one should not rely on the
capability to influence the bootability of the existing
sessions, unless one can assume overwriteable media.
-boot_image "any"|"isolinux"|"grub"
"discard"|"keep"|"patch"|"show_status"|bootspec|"next"
Define the handling of an eventual set of El Torito
boot images which has been read from an existing ISO
image or define how to make a prepared boot image file
set bootable. Such file sets get produced by ISOLINUX
or GRUB.
Each -boot_image command has two arguments: type and
setting. More than one -boot_image command may be used
to define the handling of one or more boot images.
Sequence matters.
Types isolinux and grub care for known peculiarities.
Type any makes no assumptions about the origin of the
boot images.
El Torito boot images of any type can be newly
inserted, or discarded, or patched, or kept unaltered.
Whether to patch or to keep depends on whether the boot
images contain boot info tables.
A boot info table needs to be patched when the boot
image gets newly introduced into the ISO image or if an
existing image gets relocated. This is automatically
done if type "isolinux" or "grub" is given, but not
with "any".
If patching is enabled, then boot images from previous
sessions will be checked whether they seem to bear a
boot info table. If not, then they stay unpatched. This
check is not infallible. So if you do know that the
images need no patching, use "any" "keep". "grub"
"patch" will not patch EFI images (platform_id=0xef).
Most safe is the default: -boot_image "any" "discard".
Advised for GRUB : -boot_image "grub" "patch"
For ISOLINUX : -boot_image "isolinux" "patch"
show_status will print what is known about the loaded
SunOS 5.11 Last change: Jun 27, 2010 41
User Commands XORRISO(1)
boot images and their designated fate.
A bootspec is a word of the form name=value and is used
to describe the parameters of a boot image by an El
Torito record and eventually a MBR. The names "dir",
"bin_path", "efi_path" lead to El Torito bootable
images. Name "system_area" activates a given file as
MBR.
On all media types this is possible within the first
session. In further sessions an existing boot image can
get replaced by a new one, but depending on the media
type this may have few effect at boot time. See above.
The boot image and its supporting files have to be
added to the ISO image by normal means (image loading,
-map, -add, ...). In case of ISOLINUX the files should
reside either in ISO image directory /isolinux or in
/boot/isolinux . In that case it suffices to use as
bootspec the text "dir=/isolinux" or
"dir=/boot/isolinux". E.g.:
-boot_image isolinux dir=/boot/isolinux
which bundles these individual settings:
-boot_image isolinux
bin_path=/boot/isolinux/isolinux.bin
-boot_image isolinux cat_path=/boot/isolinux/boot.cat
-boot_image isolinux load_size=2048
-boot_image any boot_info_table=on
bin_path= depicts the boot image file, a binary program
which is to be started by the hardware boot facility
(e.g. the BIOS) at boot time.
efi_path= depicts a boot image file that is ready for
EFI booting. Its load_size is determined
automatically, no boot info table gets written,
platform_id is 0xef.
An El Torito boot catalog file gets inserted into the
ISO image with address cat_path= at -commit time. It
is subject to normal -overwrite and -reassure
processing if there is already a file with the same
name. The catalog lists the boot images and is read by
the boot facility to choose one of the boot images. But
it is not necessary that it appears in the directory
tree at all. One may hide it in all trees by
cat_hidden=on. Other possible values are "iso_rr",
"joliet", and the default "off".
load_size= is a value which depends on the boot image.
Default 2048 should be overridden only if a better
value is known.
boot_info_table=on may be used to apply patching to a
boot image which is given by "any" "bin_path=".
"boot_info_table=off" disables patching.
platform_id= defines by two hex digits the Platform ID
of the boot image. "00" is 80x86 PC-BIOS, "01" is
PowerPC, "02" is Mac, "ef" is EFI.
SunOS 5.11 Last change: Jun 27, 2010 42
User Commands XORRISO(1)
id_string=text|56_hexdigits defines the ID string of
the boot catalog section where the boot image will be
listed. If the value consists of 56 characters [0-9A-
Fa-f] then it is converted into 28 bytes, else the
first 28 characters become the ID string. The ID
string of the first boot image becomes the overall
catalog ID. It is limited to 24 characters. Other
id_strings become section IDs.
sel_crit=hexdigits defines the Selection Criteria of
the boot image. Up to 20 bytes get read from the given
characters [0-9A-Fa-f]. They get attributed to the
boot image entry in the catalog.
next ends the definition of a boot image and starts a
new one. Any following -bootimage bootspecs will
affect the new image. The first "next" discards
eventually loaded boot images and their catalog.
discard gives up an existing boot catalog and its boot
images.
keep keeps or copies boot images unaltered and writes a
new catalog.
patch applies patching to existing boot images if they
seem to bear a boot info table.
system_area=disk_path copies at most 32768 bytes from
the given disk file to the very start of the ISO image.
This System Area is reserved for system dependent boot
software, e.g. an MBR which can be used to boot from
USB stick or hard disk.
Other than a El Torito boot image, the file disk_path
needs not to be added to the ISO image.
-boot_image isolinux system_area= implies
"partition_table=on".
partition_table=on causes a simple partition table to
be written into bytes 446 to 511 of the System Area.
With type "isolinux" it shows a partition that begins
at byte 0 and it causes the LBA of the first boot image
to be written into the MBR. For the first session this
works only if also "system_area=" and "bin_path=" or
"dir=" is given.
With types "any" and "grub" it shows a single partiton
which starts at byte 512 and ends where the ISO image
ends. This works with or without system_area= or boot
image.
In follow-up sessions the existing System Area is
preserved by default. If types "isolinux" or "grub"
are set to "patch", then "partition_table=on" is
activated without new boot image. In this case the
existing System Area gets checked whether it bears
addresses and sizes as if it had been processed by
"partition_table=on". If so, then those parameters get
updated when the new System Area is written.
Special "system_area=/dev/zero" causes 32k of NUL-
bytes. Use this to discard an MBR which eventually was
SunOS 5.11 Last change: Jun 27, 2010 43
User Commands XORRISO(1)
loaded with the ISO image.
Character sets:
File names are strings of non-zero bytes with 8 bit each.
Unfortunately the same byte string may appear as different
peculiar national characters on differently nationalized
terminals. The meanings of byte codes are defined in
character sets which have names. Shell command iconv -l
lists them.
Character sets should not matter as long as only english
alphanumeric characters are used for file names or as long
as all writers and readers of the media use the same
character set. Outside these constraints it may be
necessary to let xorriso convert byte codes.
There is an input conversion from input character set to the
local character set which applies when an ISO image gets
loaded. A conversion from local character set to the output
character set is performed when an image tree gets written.
The sets can be defined independently by options -in_charset
and -out_charset. Normally one will have both identical, if
ever.
If conversions are desired then xorriso needs to know the
name of the local character set. xorriso can inquire the
same info as shell command "locale" with argument "charmap".
This may be influenced by environment variables LC_ALL,
LC_CTYPE, or LANG and should match the expectations of the
terminal.
The default output charset is the local character set of the
terminal where xorriso runs. So by default no conversion
happens between local filesystem names and emerging names in
the image. The situation stays ambigous and the reader has
to riddle what character set was used.
By option -auto_charset it is possible to attribute the
output charset name to the image. This makes the situation
unambigous. But if your terminal character set does not
match the character set of the local file names, then this
attribute can become plainly wrong and cause problems at
read time. To prevent this it is necessary to check whether
the terminal properly displays all intended filenames. Check
especially the exotic national characters.
To enforce recording of a particular character set name
without any conversion at image generation time, set
-charset and -local_charset to the desired name, and enable
-backslash_codes to avoid evil character display on your
terminal.
-charset character_set_name
Set the character set from which to convert file names
when loading an image and to which to convert when
writing an image.
SunOS 5.11 Last change: Jun 27, 2010 44
User Commands XORRISO(1)
-local_charset character_set_name
Override the system assumption of the local character
set name. If this appears necessary, one should
consider to set -backslash_codes to "on" in order to
avoid dangerous binary codes being sent to the
terminal.
Exception processing:
Since the tasks of xorriso are manifold and prone to
external influence, there may arise the need for xorriso to
report and handle problem events.
Those events get classified when they are detected by one of
the software modules and forwarded to reporting and
evaluation modules which decide about reactions. Event
classes are sorted by severity:
"NEVER" The upper end of the severity spectrum.
"ABORT" The program is being aborted and on its way to end.
"FATAL" The main purpose of the run failed or an important
resource failed unexpectedly.
"FAILURE" An important part of the job could not be
performed.
"MISHAP" A FAILURE which can be tolerated during ISO image
generation.
"SORRY" A less important part of the job could not be
performed.
"WARNING" A situation is suspicious of being not intended by
the user.
"HINT" A proposal to the user how to achieve better results.
"NOTE" A harmless information about noteworthy
circumstances.
"UPDATE" A pacifier message during long running operations.
"DEBUG" A message which would only interest the program
developers.
"ALL" The lower end of the severity spectrum.
-abort_on severity
Set the severity threshold for events to abort the
program.
Useful: "NEVER", "ABORT", "FATAL", "FAILURE" ,
"MISHAP", "SORRY"
It may become necessary to abort the program anyway,
despite the setting by this option. Expect not many
"ABORT" events to be ignorable.
A special property of this option is that it works
preemptive if given as program start argument. I.e. the
first -abort_on setting among the start arguments is in
effect already when the first operations of xorriso
begin. Only "-abort_on" with dash "-" is recognized
that way.
-return_with severity exit_value
SunOS 5.11 Last change: Jun 27, 2010 45
User Commands XORRISO(1)
Set the threshold and exit_value to be returned at
program end if no abort has happened. This is to allow
xorriso to go on after problems but to get a failure
indicating exit value from the program, nevertheless.
Useful is a value lower than the -abort_on threshold,
down to "WARNING".
exit_value may be either 0 (indicating success to the
starter of the program) or a number between 32 and 63.
Some other exit_values are used by xorriso if it
decides to abort the program run:
1=abort due to external signal
2=no program arguments given
3=creation of xorriso main object failed
4=failure to start libburnia-project.org libraries
5=program abort during argument processing
6=program abort during dialog processing
-report_about severity
Set the threshold for events to be reported.
Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE",
"DEBUG", "ALL"
Regardless what is set by -report_about, messages get
always reported if they reach the severity threshold of
-abort_on .
Event messages are sent to the info channel "I" which
is usually stderr but may be influenced by command
-pkt_output. Info messages which belong to no event
get attributed severity "NOTE".
A special property of this option is that the first
-report_about setting among the start arguments is in
effect already when the first operations of xorriso
begin. Only "-report_about" with dash "-" is recognized
that way.
-error_behavior occasion behavior
Control the program behavior at problem event
occasions. For now this applies to occasions
"image_loading" which is given while an image tree is
read from the input device, and to "file_extraction"
which is given with osirrox options like -extract.
With "image_loading" there are three behaviors
available:
"best_effort" goes on with reading after events with
severity below FAILURE if the threshold of option
-abort_on allows this.
"failure" aborts image tree reading on first event of
at least SORRY. It issues an own FAILURE event.
"fatal" acts like "failure" but issues the own event as
FATAL. This is the default.
With occasion "file_extraction" there are three
behaviors:
"keep" maintains incompletely extracted files on disk.
SunOS 5.11 Last change: Jun 27, 2010 46
User Commands XORRISO(1)
This is the default.
"delete" removes files which encountered errors during
content extraction.
"best_effort" starts a revovery attempt by means of
-extract_cut if the file content stems from the loaded
ISO image and is not filtered.
Dialog mode control:
-dialog "on"|"off"|"single_line"
Enable or disable to enter dialog mode after all
arguments are processed. In dialog mode input lines
get prompted via readline or from stdin.
Mode "on" supports input of newline characters within
quotation marks and line continuation by trailing
backslash outside quotation marks. Mode "single_line"
does not.
-page length width
Describe terminal to the text pager. See also above,
paragraph Result pager.
If parameter length is nonzero then the user gets
prompted after that number of terminal lines. Zero
length disables paging.
Parameter width is the number of characters per
terminal line. It is used to compute the number of
terminal lines which get occupied by an output line. A
usual terminal width is 80.
-use_readline "on"|"off"
If "on" then use readline for dialog. Else use plain
stdin.
See also above, paragraph Dialog, Readline, Result
pager.
-reassure "on"|"tree"|"off"
If "on" then ask the user for "y" or "n":
before deleting or overwriting any file in the ISO
image,
before overwriting any disk file during restore
operations,
before rolling back pending image changes,
before committing image changes to media,
before changing the input drive,
before blanking or formatting media,
before ending the program.
With setting "tree" the reassuring prompt will appear
for an eventual directory only once and not for each
file in its whole subtree.
Setting "off" silently kills any kind of image file
object resp. performs above irrevocable actions.
To really produce user prompts, option -dialog needs to
SunOS 5.11 Last change: Jun 27, 2010 47
User Commands XORRISO(1)
be set to "on". Note that the prompt does not appear
in situations where file removal is forbidden by option
-overwrite. -reassure only imposes an additional curb
for removing existing file objects.
Be aware that file objects get deleted from the ISO
image immediately after confirmation. They are gone
even if the running command gets aborted and its
desired effect gets revoked. In case of severe mess-up,
consider to use -rollback to revoke the whole session.
Drive and media related inquiry actions:
-devices
Show list of available MMC drives with the addresses of
their libburn standard device files.
This is only possible when no ISO image changes are
pending. After this option was executed, there is no
drive current and no image loaded. Eventually one has
to aquire a drive again.
In order to be visible, a device has to offer rw-
permissions with its libburn standard device file. Thus
it might be only the superuser who is able to see all
drives.
Drives which are occupied by other processes get not
shown.
-toc
Show media specific table of content. This is the media
session history, not the ISO image directory tree.
In case of overwriteable media holding a valid ISO
image, it may happen that only a single session gets
shown. But if the first session on the overwriteable
media was written by xorriso then a complete session
history can be emulated.
A drive which is incapable of writing may show any
media as CD-ROM or DVD-ROM with only one or two
sessions on it. The last of these sessions is supposed
to be the most recent real session then.
Some read-only drives and media show no usable session
history at all. Eventually option -rom_toc_scan might
help.
-mount_cmd drive entity id path
Emit an appropriate command line for mounting the ISO
session indicated by drive, entity and id. The result
will be different on GNU/Linux and on FreeBSD.
drive can be "indev" or "outdev" to indicate already
acquired drives, or it can be the path of a not yet
acquired drive. Prefix "stdio:" for non-MMC drives is
not mandatory.
entity must be either "sbsector" with the superblock
sector address as id, or "track" with a track number as
SunOS 5.11 Last change: Jun 27, 2010 48
User Commands XORRISO(1)
id, or "session" with a session number, or "volid" with
a search pattern for the volume id, or "auto" with any
text as id.
path will be used as mount point and must already exist
as a directory on disk.
The command gets printed to the result channel. See
option -mount for direct execution of this command.
-mount_opts option[:option...]
Set options which influence -mount and -mount_cmd.
Currently there is only option "exclusive" which is
default and its counterpart "shared". The latter causes
xorriso not to give up the affected drive with command
-mount. On GNU/Linux it adds mount option "loop" which
may allow to mount several sessions of the same block
device at the same time. One should not write to a
mounted optical media, of course. Take care to umount
all sessions before ejecting.
-session_string drive entity id format
Print to the result channel a text which gets composed
according to format and the parameters of the addressed
session.
Formats "linux:"path or "freebsd:"path produce the
output of -mount_cmd for the given operating systems.
In other texts xorriso will substitute the following
parameter names. An optional prefix "string:" will be
removed.
"%device%" will be substituted by the mountable device
path of the drive address.
"%sbsector%" will be substituted by the session start
sector.
"%track%", "%session%", "%volid%" will be substituted
by track number, session number, resp. volume id of the
depicted session.
-print_size
Print the foreseeable consumption of 2048 byte blocks
by next -commit. This can last a while as a -commit
gets prepared and only in last moment is revoked by
this option.
-tell_media_space
Print available space on output media and the free
space after subtracting already foreseeable consumption
by next -commit.
-pvd_info
Print various id strings which can be found in loaded
ISO images. Some of them may be changed by options like
-volid or -publisher. For these ids -pvd_info reports
what would be written with the next -commit.
SunOS 5.11 Last change: Jun 27, 2010 49
User Commands XORRISO(1)
Navigation in ISO image and disk
-cd iso_rr_path
Change the current working directory in the ISO image.
This is prepended to iso_rr_paths which do not begin
with '/'.
It is possible to set the working directory to a path
which does not exist yet in the ISO image. The
necessary parent directories will be created when the
first file object is inserted into that virtual
directory. Use -mkdir if you want to enforce the
existence of the directory already at first insertion.
-cdx disk_path
Change the current working directory in the local
filesystem. To be prepended to disk_paths which do not
begin with '/'.
-pwd
Tell the current working directory in the ISO image.
-pwdx
Tell the current working directory in the local
filesystem.
-ls iso_rr_pattern [***]
List files in the ISO image which match shell patterns
(i.e. with wildcards '*' '?' '[a-z]'). If a pattern
does not begin with '/' then it is compared with
addresses relative to -cd.
Directories are listed by their content rather than as
single file item.
Pattern expansion may be disabled by command
-iso_rr_pattern.
-lsd iso_rr_pattern [***]
Like -ls but listing directories as themselves and not
by their content. This resembles shell command ls -d.
-lsl iso_rr_pattern [***]
Like -ls but also list some of the file attributes.
The output format resembles shell command ls -ln.
If the file has non-trivial ACL, then a '+' is appended
to the permission info. If the file is hidden, then
'I' for "iso_rr", 'J' for "joliet", resp. 'H' for "on"
gets appended. Together with ACL it is 'i', 'j', resp.
'h'.
-lsdl iso_rr_pattern [***]
Like -lsd but also list some of the file attributes.
The output format resembles shell command ls -dln.
SunOS 5.11 Last change: Jun 27, 2010 50
User Commands XORRISO(1)
-lsx disk_pattern [***]
List files in the local filesystem which match shell
patterns. Patterns which do not begin with '/' are used
relative to -cdx.
Directories are listed by their content rather than as
single file item.
Pattern expansion may be disabled by command
-disk_pattern.
-lsdx disk_pattern [***]
Like -lsx but listing directories as themselves and not
by their content. This resembles shell command ls -d.
-lslx disk_pattern [***]
Like -lsx but also listing some of the file attributes.
Output format resembles shell command ls -ln.
-lsdlx disk_pattern [***]
Like -lsdx but also listing some of the file
attributes. Output format resembles shell command ls
-dln.
-getfacl iso_rr_pattern [***]
Print the access permissions of the given files in the
ISO image using the format of shell command getfacl. If
a file has no ACL then it gets fabricated from the
-chmod settings. A file may have a real ACL if it was
introduced into the ISO image while option -acl was set
to "on".
-getfacl_r iso_rr_pattern [***]
Like -gefacl but listing recursively the whole file
trees underneath eventual directories.
-getfattr iso_rr_pattern [***]
Print the xattr of the given files in the ISO image.
If a file has no such xattr then noting is printed for
it.
-getfattr_r iso_rr_pattern [***]
Like -gefattr but listing recursively the whole file
trees underneath eventual directories.
-du iso_rr_pattern [***]
Recursively list size of directories and files in the
ISO image which match one of the patterns. similar to
shell command du -k.
-dus iso_rr_pattern [***]
List size of directories and files in the ISO image
which match one of the patterns. Similar to shell
command du -sk.
SunOS 5.11 Last change: Jun 27, 2010 51
User Commands XORRISO(1)
-dux disk_pattern [***]
Recursively list size of directories and files in the
local filesystem which match one of the patterns.
Similar to shell command du -k.
-dusx disk_pattern [***]
List size of directories and files in the local
filesystem which match one of the patterns. Similar to
shell command du -sk.
[params]] --
-findx disk_path [-name pattern] [-type t] [-exec
action
Like -find but operating on local filesystem and not on
the ISO image. This is subject to the settings of
-follow.
-findx accepts the same -type arguments as -find.
Additionally it recognizes type "mountpoint" (or "m")
which matches subdirectories which reside on a
different device than their parent. It never matches
the disk_path given as start address for -findx.
-findx accepts the -exec actions as does -find. But
except the following few actions it will always perform
action "echo".
in_iso reports the path if its counterpart exist in the
ISO image. For this the disk_path of the -findx
command gets replaced by the iso_rr_path given as
parameter.
E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd --
not_in_iso reports the path if its counterpart does not
exist in the ISO image. The report format is the same
as with command -compare.
add_missing iso_rr_path_start adds the counterpart if
it does not yet exist in the ISO image.
E.g.: -findx /home/thomas -exec add_missing
/thomas_on_cd --
is_full_in_iso reports if the counterpart in the ISO
image contains files. To be used with -type "m" to
report mount points.
empty_iso_dir deletes all files from the counterpart in
the ISO image. To be used with -type "m" to truncate
mount points.
-compare disk_path iso_rr_path
Compare attributes and eventual data file content of a
fileobject in the local filesystem with a file object
in the ISO image. The iso_rr_path may well point to an
image file object which is not yet committed, i.e. of
which the data content still resides in the local
filesystem. Such data content is prone to externally
caused changes.
If iso_rr_path is empty then disk_path is used as path
SunOS 5.11 Last change: Jun 27, 2010 52
User Commands XORRISO(1)
in the ISO image too.
Differing attributes are reported in detail, differing
content is summarized. Both to the result channel. In
case of no differences no result lines are emitted.
-compare_r disk_path iso_rr_path
Like -compare but working recursively. I.e. all file
objects below both addresses get compared whether they
have counterparts below the other address and whether
both counterparts match.
-compare_l disk_prefix iso_rr_prefix disk_path [***]
Perform -compare_r with each of the disk_path
arguments. iso_rr_path will be composed from disk_path
by replacing disk_prefix by iso_rr_prefix.
-show_stream iso_rr_path [***]
Display the content stream chain of data files in the
ISO image. The chain consists of the iso_rr_name and
one or more streams, separated by " < " marks. A
stream consists of one or more texts eventually in
''-quotation marks, eventually separated by ":"
characters. The first text describes the stream type,
the following ones describe its individual properties.
Frequently used types are:
disk:'disk_path' for local filesystem objects.
image:'iso_rr_path' for ISO image file objects.
cout:'disk_path offset count' for -cut_out files.
extf:'filter_name' for external filters.
Example:
'/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
-show_stream_r iso_rr_path [***]
Like -show_stream but working recursively.
Evaluation of readability and recovery:
It is not uncommon that optical media produce read errors.
The reasons may be various and get obscured by error
correction which is performed by the drives and based on
extra data on the media. If a drive returns data then one
can quite trust that they are valid. But at some degree of
read problems the correction will fail and the drive is
supposed to indicate error.
xorriso can scan the media for readable data blocks,
classify them according to their read speed, save them to a
file, and keep track of successfuly saved blocks for further
tries on the same media.
By option -md5 checksums may get recorded with data files
and whole sessions. These checksums are reachable only via
indev and a loaded image. They work independently of the
media type and can detect transmission errors.
SunOS 5.11 Last change: Jun 27, 2010 53
User Commands XORRISO(1)
-check_media [option [option ...]] --
Try to read data blocks from the indev drive,
eventually copy them to a disk file, and finally report
about the encountered quality. Several options may be
used to modify the default behavior.
The options given with this command override the
default settings which may have been changed by option
-check_media_defaults. See there for a description of
options.
The result list tells intervals of 2 KiB blocks with
start address, number of blocks and quality. Qualities
which begin with "+" are supposed to be valid readable
data. Qualities with "-" are unreadable or corrupted
data. "0" indicates qualities which are not covered by
the check run or are regularly allowed to be unreadable
(e.g. gaps between tracks).
Alternatively it is possible to report damaged files
rather than blocks.
If -md5 is "on" then the default mode what=tracks looks
out for libisofs checksum tags for the ISO session data
and eventually checks them against the checksums
computed from the data stream.
-check_media_defaults [option [option ...]] --
Preset options for runs of -check_media, -extract_cut
and best_effort file extraction. Eventual options given
with -check_media will override the preset options.
-extract_cut will override some options automatically.
An option consists of a keyword, a "=" character, and a
value. Options may override each other. So their
sequence matters.
The default setting at program start is:
use=indev what=tracks min_lba=-1 max_lba=-1
retry=default
time_limit=28800 item_limit=100000 data_to='' event=ALL
abort_file=/var/opt/xorriso/do_abort_check_media
sector_map='' map_with_volid=off patch_lba0=off
report=blocks
bad_limit=valid slow_limit=1.0 chunk_size=0s
Option "reset=now" restores these startup defaults.
Non-default options are:
report="files" lists the files which use damaged blocks
(not with use=outdev). The format is like with find
-exec report_damage.
report="blocks_files" first lists damaged blocks and
then affected files.
use="outdev" reads from the output drive instead of the
input drive. This avoids loading the ISO image tree
from media.
use="sector_map" does not read any media but loads the
file given by option sector_map= and processes this
virtual outcome.
SunOS 5.11 Last change: Jun 27, 2010 54
User Commands XORRISO(1)
what="disc" scans the payload range of a media without
respecting track gaps.
min_lba=limit omits all blocks with addresses lower
than limit.
max_lba=limit switches to what=disc and omits all
blocks above limit.
retry="on" forces read retries with single blocks when
the normal read chunk produces a read error. By
default, retries are only enabled with CD media.
"retry=off" forbits retries for all media types.
abort_file=disk_path gives the path of the file which
may abort a scan run. Abort happens if the file exists
and its mtime is not older than the start time of the
run. Use shell command "touch" to trigger this. Other
than an aborted program run, this will report the
tested and untested blocks and go on with running
xorriso.
time_limit=seconds gives the number of seconds after
which the scan shall be aborted. This is useful for
unattended scanning of media which may else overwork
the drive in its effort to squeeze out some readable
blocks. Abort may be delayed by the drive gnawing on
the last single read operation. Value -1 means
unlimited time.
item_limit=number gives the number of report list items
after which to abort. Value -1 means unlimited item
number.
data_to=disk_path copies the valid blocks to the given
file.
event=severity sets the given severity for a problem
event which shall be issued at the end of a check run
if data blocks were unreadable or failed to match
recorded MD5 checksums. Severity "ALL" disables this
event.
sector_map=disk_path tries to read the file given by
disk_path as sector bitmap and to store such a map file
after the scan run. The bitmap tells which blocks have
been read successfully in previous runs. It allows to
do several scans on the same media, eventually with
intermediate eject, in order to collect readable blocks
whenever the drive is lucky enough to produce them. The
stored file contains a human readable TOC of tracks and
their start block addresses, followed by binary bitmap
data.
map_with_volid="on" examines tracks whether they are
ISO images and eventually prints their volume ids into
the human readable TOC of sector_map=.
patch_lba0="on" transfers within the data_to= file a
copy of the currently loaded session head to the start
of that file and patches it to be valid at that
position. This makes the loaded session the default
session of the image file when it gets mounted or
SunOS 5.11 Last change: Jun 27, 2010 55
User Commands XORRISO(1)
loaded as stdio: drive. But it usually makes the
original session 1 inaccessible.
patch_lba0="force" performs patch_lba0="on" even if
xorriso believes that the copied data are not valid.
patch_lba0= may also bear a number. If it is 32 or
higher it is taken as start address of the session to
be copied. In this case it is not necessary to have an
-indev and a loaded image. ":force" may be appended
after the number.
bad_limit=threshold sets the highest quality which
shall be considered as damage. Choose one of "good",
"md5_match", "slow", "partial", "valid", "untested",
"invalid", "tao_end", "off_track", "md5_mismatch",
"unreadable".
slow_limit=threshold sets the time threshold for a
single read chunk to be considered slow. This may be a
fractional number like 0.1 or 1.5.
chunk_size=size sets the number of bytes to be read in
one read operation. This gets rounded down to full
blocks of 2048 bytes. 0 means automatic size.
-check_md5 severity iso_rr_path [***]
Compare the data content of the given files in the
loaded image with their recorded MD5 checksums, if
there are any. In case of any mismatch an event of the
given severity is issued. It may then be handled by
appropriate settings of options -abort_on or
-return_with which both can cause non-zero exit values
of the program run. Severity ALL suppresses that event.
This option reports match and mismatch of data files to
the result channel. Non-data files cause NOTE events.
There will also be UPDATE events from data reading.
If no iso_rr_path is given then the whole loaded
session is compared with its MD5 sum. Be aware that
this covers only one session and not the whole image if
there are older sessions.
-check_md5_r severity iso_rr_path [***]
Like -check_md5 but checking all data files underneath
the given paths. Only mismatching data files will be
reported.
osirrox ISO-to-disk restore options:
Normally xorriso only writes to disk files which were given
as stdio: pseudo-drives or as log files. But its alter ego
osirrox is able to extract file objects from ISO images and
to create, overwrite, or delete file objects on disk.
Disk file exclusions by -not_mgt, -not_leaf, -not_paths
apply. If disk file objects already exist then the settings
of -overwrite and -reassure apply. But -overwrite "on" only
triggers the behavior of -overwrite "nondir". I.e.
SunOS 5.11 Last change: Jun 27, 2010 56
User Commands XORRISO(1)
directories cannot be deleted.
Access permissions of files in the ISO image do not restrict
restoring. The directory permissions on disk have to allow
rwx.
-osirrox "on"|"device_files"|"off"|"banned"|[:option:...]
Setting "off" disables disk filesystem manipulations.
This is the default unless the program was started with
leafname "osirrox". Elsewise the capability to restore
files can be enabled explicitly by -osirrox "on". It
can be irrevocably disabled by -osirrox "banned".
To enable restoring of special files by "device_files"
is potentially dangerous. The meaning of the number
st_rdev (see man 2 stat) depends much on the operating
system. Best is to restore device files only to the
same system from where they were copied. If not
enabled, device files in the ISO image are ignored
during restore operations.
Due to a bug of previous versions, device files from
previous sessions might have been altered to major=0,
minor=1. So this combination does not get restored.
Option "concat_split_on" is default. It enables
restoring of split file directories as data files if
the directory contains a complete collection of
-cut_out part files. With option "concat_split_off"
such directories are handled like any other ISO image
directory.
Option "auto_chmod_off" is default. If "auto_chmod_on"
is set then access restrictions for disk directories
get circumvented if those directories are owned by the
effective user who runs xorriso. This happens by
temporarily granting rwx permission to the owner.
Option "sort_lba_on" may improve read performance with
optical drives. It allows to restore large numbers of
hard links without exhausting -temp_mem_limit. It does
not preserve directory mtime and it needs -osirrox
option auto_chmod_on in order to extract directories
which offer no write permission. Default is
"sort_lba_off".
Option "o_excl_on" is the default unless the program
was started with leafname "osirrox". On GNU/Linux it
tries to avoid using drives which are mounted or in use
by other libburn programs. Option "o_excl_off" allows
on GNU/Linux to access such drives. Drives which get
acquired while "o_excl_off" will refuse to get blanked,
formatted, written, or ejected. But be aware that even
harmless inquiries can spoil ongoing burns of CD-R[W]
and DVD-R[W].
-extract iso_rr_path disk_path
Copy the file objects at and underneath iso_rr_path to
their corresponding addresses at and underneath
SunOS 5.11 Last change: Jun 27, 2010 57
User Commands XORRISO(1)
disk_path. This is the inverse of -map or -update_r.
If iso_rr_path is a directory and disk_path is an
existing directory then both trees will be merged.
Directory attributes get extracted only if the disk
directory is newly created by the copy operation. Disk
files get removed only if they are to be replaced by
file objects from the ISO image.
As many attributes as possible are copied together with
restored file objects.
-extract_single iso_rr_path disk_path
Like -extract, but if iso_rr_path is a directory then
its sub tree gets not restored.
-extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
Perform -extract with each of the iso_rr_path
arguments. disk_path will be composed from iso_rr_path
by replacing iso_rr_prefix by disk_prefix.
-extract_cut iso_rr_path byte_offset byte_count disk_path
Copy a byte interval from a data file out of an ISO
image into a newly created disk file. The main purpose
for this is to allow handling of large files if they
are not supported by mount -t iso9660 and if the
reading system is unable to buffer them as a whole.
If the data bytes of iso_rr_path are stored in the
loaded ISO image, and no filter is applied, and
byte_offset is a multiple of 2048, then a special run
of -check_media is performed. It may be quicker and
more rugged than the general reading method.
-cpx iso_rr_path [***] disk_path
Copy single leaf file objects from the ISO image to the
address given by disk_path. If more then one
iso_rr_path is given then disk_path must be a directory
or non-existent. In the latter case it gets created and
the extracted files get installed in it with the same
leafnames.
Missing directory components in disk_path will get
created, if possible.
Directories are allowed as iso_rr_path only with
-osirrox "concat_split_on" and only if they actually
represent a complete collection of -cut_out split file
parts.
-cpax iso_rr_path [***] disk_path
Like -cpx but restoring mtime, atime as in ISO image
and trying to set ownership and group as in ISO image.
-cp_rx iso_rr_path [***] disk_path
Like -cpx but also extracting whole directory trees
from the ISO image.
SunOS 5.11 Last change: Jun 27, 2010 58
User Commands XORRISO(1)
The resulting disk paths are determined as with shell
command cp -r : If disk_path is an existing directory
then the trees will be inserted or merged underneath
this directory and will keep their leaf names. The ISO
directory "/" has no leaf name and thus gets mapped
directly to disk_path.
-cp_rax iso_rr_path [***] disk_path
Like -cp_rx but restoring mtime, atime as in ISO image
and trying to set ownership and group as in ISO image.
-paste_in iso_rr_path disk_path byte_offset byte_count
Read the content of a ISO data file and write it into a
data file on disk beginning at the byte_offset. Write
at most byte_count bytes. This is the inverse of
option -cut_out.
-mount drive entity id path
Produce the same line as -mount_cmd and then execute it
as external program run after giving up the depicted
drive. See also -mount_opts. This demands -osirrox to
be enabled and normally will succeed only for the
superuser. For safety reasons the mount program is only
executed if it is reachable as /bin/mount or
/sbin/mount.
Command compatibility emulations:
Writing of ISO 9660 on CD is traditionally done by program
mkisofs as ISO 9660 image producer and cdrecord as burn
program. xorriso does not strive for their comprehensive
emulation. Nevertheless it is ready to perform some of its
core tasks under control of commands which in said programs
trigger comparable actions.
-as personality option [options] --
Perform the variable length option list as sparse
emulation of the program depicted by the personality
word.
Personality "mkisofs" accepts the options listed with:
-as mkisofs -help --
Among them: -R (always on), -r, -J, -o, -M, -C, -dir-
mode, -file-mode, -path-list, -m, -exclude-list, -f,
-print-size, -pad, -no-pad, -V, -v, -version, -graft-
points, -z, -no-emul-boot, -b, -c, -boot-info-table,
-boot-load-size, -input-charset, -G, -output-charset,
-U, -hide, -hide-joliet, -hide-list, -hide-joliet-list,
file paths and pathspecs. A lot of options are not
supported and lead to failure of the mkisofs emulation.
Some are ignored, but better do not rely on this
tolerance.
SunOS 5.11 Last change: Jun 27, 2010 59
User Commands XORRISO(1)
-graft-points is equivalent to -pathspecs on. Note that
pathspecs without "=" are interpreted differently than
with xorriso option -add. Directories get merged with
the root directory of the ISO image, other filetypes
get mapped into that root directory.
Other than with the "cdrecord" personality there is no
automatic -commit at the end of a "mkisofs" option
list. Verbosity settings -v (= "UPDATE") and -quiet (=
"SORRY") persist. The output file, eventually chosen
with -o, persists until things happen like -commit,
-rollback, -dev, or end of xorriso. -pacifier gets set
to "mkisofs" if files are added to the image.
If pathspecs are given and if no output file was chosen
before or during the "mkisofs" option list, then
standard output (-outdev "-") will get into effect. If
-o points to a regular file, then it will be truncated
to 0 bytes when finally writing begins. This truncation
does not happen if the drive is chosen by xorriso
options before -as mkisofs or after its list delimiter.
Directories and symbolic links are no valid -o targets.
Writing to stdout is possible only if -as "mkisofs" was
among the start arguments or if other start arguments
pointed the output drive to standard output.
Not original mkisofs options are --quoted_path_list ,
--hardlinks , --acl , --xattr , --md5 , --stdio_sync .
They work like the xorriso options with the same name
and hardcoded argument "on", e.g. -acl "on". Explicit
arguments are expected by --stdio_sync and
--scdbackup_tag. --no-emul-toc is -compliance
no_emul_toc.
--sort-weight gets as arguments a number and an
iso_rr_path. The number becomes the LBA sorting weight
of regular file iso_rr_path or of all regular files
underneath directory iso_rr_path. (See -find -exec
sort_weight).
Adopted from grub-mkisofs are --protective-msdos-label
(see -boot_image grub partition_table=on) and
--modification-date=YYYYMMDDhhmmsscc (see -volume_date
uuid). For EFI bootable GRUB boot images use --efi-
boot. It performs -boot_image grub efi_path=
surrounded by two -boot_image any next.
For MBR bootable ISOLINUX images there is -isohybrid-
mbr FILE, where FILE is one of the Syslinux files
mbr/isohdp[fp]x*.bin . Use this instead of -G to apply
the effect of -boot_image isolinux partition_table=on.
--boot-catalog-hide is -boot_image any cat_hidden=on.
Personalites "xorrisofs", "genisoimage", and "genisofs"
are aliases for "mkisofs".
If xorriso is started with one of the leafnames
"xorrisofs", "genisofs", "mkisofs", or "genisoimage",
then it performs -read_mkisofsrc and prepends -as
"genisofs" to the command line arguments. I.e. all
SunOS 5.11 Last change: Jun 27, 2010 60
User Commands XORRISO(1)
arguments will be interpreted mkisofs style until "--"
is encountered. From then on, options are interpreted
as xorriso options.
Personality "cdrecord" accepts the options listed with:
-as cdrecord -help --
Among them: -v, dev=, speed=, blank=, fs=, -eject,
-atip, padsize=, tsize=, -isosize, -multi, -msinfo,
--grow_overwriteable_iso, write_start_address=, track
source file path or "-" for standard input as track
source.
It ignores most other options of cdrecord and cdrskin
but refuses on -audio, -scanbus, and on blanking modes
unknown to xorriso.
The scope is only a single data track per session to be
written to blank, overwriteable, or appendable media.
The media gets closed if closing is applicable and not
option -multi is present.
An eventually acquired input drive is given up. This
is only allowed if no image changes are pending.
dev= must be given as xorriso device address. Addresses
like 0,0,0 or ATA:1,1,0 are not supported.
If a track source is given, then an automatic -commit
happens at the end of the "cdrecord" option list.
--grow_overwriteable_iso enables emulation of multi-
session on overwriteable media. To enable emulation of
a TOC, the first session needs -C 0,32 with -as mkisofs
(but no -M) and --grow_overwriteable_iso
write_start_address=32s with -as cdrecord.
A much more elaborate libburn based cdrecord emulator
is the program cdrskin.
Personalites "xorrecord", "wodim", and "cdrskin" are
aliases for "cdrecord".
If xorriso is started with one of the leafnames
"xorrecord", "cdrskin", "cdrecord", or "wodim", then it
automatically prepends -as "cdrskin" to the command
line arguments. I.e. all arguments will be interpreted
cdrecord style until "--" is encountered and an
eventual commit happens. From then on, options are
interpreted as xorriso options.
-read_mkisofsrc
Try one by one to open for reading:
./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc ,
$(basename $0)/.mkisofs
On success interpret the file content as of man mkisofs
CONFIGURATION, and end this command. Do not try further
files. The last address is used only if start argument
0 has a non-trivial basename.
The reader currently interprets the following
NAME=VALUE pairs: APPI (-application_id) , PUBL
(-publisher) , SYSI (-system_id) , VOLI (-volid) , VOLS
SunOS 5.11 Last change: Jun 27, 2010 61
User Commands XORRISO(1)
(-volset_id)
Any other lines will be silently ignored.
-pacifier behavior_code
Control behavior of UPDATE pacifiers during write
operations. The following behavior codes are defined:
"xorriso" is the default format:
Writing: sector XXXXX of YYYYYY [fifo active, nn%
fill]
"cdrecord" looks like:
X of Y MB written (fifo nn%) [buf mmm%]
"mkisofs"
nn% done, estimate finish Tue Jul 15 20:13:28 2008
-scdbackup_tag list_path record_name
Set the parameter "name" for a scdbackup checksum
record. It will be appended in an scdbackup checksum
tag to the -md5 session tag if the image starts at LBA
0. This is the case if it gets written as first session
onto a sequential media, or piped into a program, named
pipe or character device.
If list_path is not empty then the record will also be
appended to the data file given by this path.
Program scdbackup_verify will recognize and verify tag
resp. record.
Scripting, dialog and program control features:
-no_rc
Only if used as first command line argument this option
prevents reading and interpretation of eventual startup
files. See section FILES below.
-options_from_file fileaddress
Read quoted input from fileaddress and executes it like
dialog lines.
-help
Print helptext.
-version
Print program name and version, component versions,
license.
-history textline
Copy textline into libreadline history.
-status mode|filter
Print the current settings of xorriso. Modes:
short... print only important or altered settings
long ... print all settings including defaults
long_history like long plus history lines
SunOS 5.11 Last change: Jun 27, 2010 62
User Commands XORRISO(1)
Filters begin with '-' and are compared literally
against the output lines of -status:long_history. A
line is put out only if its start matches the filter
text. No wildcards.
-status_history_max number
Set maximum number of history lines to be reported with
-status "long_history".
-list_delimiter word
Set the list delimiter to be used instead of "--". It
has to be a single word, must not be empty, not longer
than 80 characters, and must not contain quotation
marks.
For brevity the list delimiter is referred as "--"
throughout this text.
-backslash_codes "on"|"off"|mode[:mode]
Enable or disable the interpretation of symbolic
representations of special characters with quoted
input, or with program arguments, or with program text
output. If enabled the following translations apply:
\a=bell(007) \b=backspace(010) \e=Escape(033)
\f=formfeed(014)
\n=linefeed(012) \r=carriage_return(015) \t=tab(011)
\v=vtab(013) \\=backslash(134)
\[0-7][0-7][0-7]=octal_code
\x[0-9a-f][0-9a-f]=hex_code \cC=control-C
Translations can occur with quoted input in 3 modes:
"in_double_quotes" translates only inside " quotation.
"in_quotes" translates inside " and ' quotation.
"with_quoted_input" translates inside and outside
quotes.
With the start program arguments there is mode:
"with_program_arguments" translates all program
arguments.
Mode "encode_output" encodes output characters. It
combines "encode_results" with "encode_infos". Inside
single or double quotation marks encoding applies to
ASCII characters octal 001 to 037 , 177 to 377 and to
backslash(134). Outside quotation marks some harmless
control characters stay unencoded: bell(007),
backspace(010), tab(011), linefeed(012), formfeed(014),
carriage_return(015).
Mode "off" is default and disables any translation.
Mode "on" is
"with_quoted_input:with_program_arguments:encode_output".
-temp_mem_limit number["k"|"m"]
Set the maximum size of temporary memory to be used for
image dependent buffering. Currently this applies to
pattern expansion, LBA sorting, restoring of hard
SunOS 5.11 Last change: Jun 27, 2010 63
User Commands XORRISO(1)
links.
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum
1024m = 1 GiB.
-print text
Print a text to result channel.
-prompt text
Show text at beginning of output line and wait for the
user to hit the Enter key resp. to send a line via
stdin.
-errfile_log mode path|channel
If problem events are related to input files from the
filesystem, then their disk_paths can be logged to a
file or to output channels R or I.
Mode can either be "plain" or "marked". The latter
causes marker lines which give the time of log start,
burn session start, burn session end, log end or
program end. In mode "plain", only the file paths are
logged.
If path is "-" or "-R" then the log is directed to the
result channel. Path "-I" directs it to the info
message channel. Any text that does not begin with "-"
is used as path for a file to append the log lines.
Problematic files can be recorded multiple times during
one program run. If the program run aborts then the
list might not be complete because some input file
arguments might not have been processed at all.
The errfile paths are transported as messages of very
low severity "ERRFILE". This transport becomes visible
with -report_about "ALL".
-session_log path
If path is not empty it gives the address of a plain
text file where a log record gets appended after each
session. This log can be used to determine the
start_lba of a session for mount options -o sbsector=
resp. -s from date or volume id.
Record format is: timestamp start_lba size volume-id
The first three items are single words, the rest of the
line is the volume id.
-scsi_log "on"|"off"
Mode "on" enables very verbous logging of SCSI commands
and drive replies. Logging messages get printed to
stderr, not to any of the xorriso output channels.
A special property of this option is that the first
-scsi_log setting among the start arguments is in
effect already when the first operations of xorriso
begin. Only "-scsi_log" with dash "-" is recognized
that way.
SunOS 5.11 Last change: Jun 27, 2010 64
User Commands XORRISO(1)
-end
End program after writing eventually pending changes.
-rollback_end
Discard pending changes. End program immediately.
# any text
Only in dialog or file execution mode, and only as
first non-whitespace in line: Do not execute the line
but eventually store it in history.
Support for frontend programs via stdin
-pkt_output "on"|"off"
Consolidate text output on stdout and classify each
line by a channel indicator:
'R:' for result lines,
'I:' for notes and error messages,
'M:' for -mark texts.
Next is a decimal number of which only bit 0 has a
meaning for now. 0 means no newline at end of payload,
1 means that the newline character at the end of the
output line belongs to the payload. After another colon
follows the payload text.
Example:
I:1: enter option and arguments :
-logfile channel fileaddress
Copy output of a channel to the given file. Channel may
be one of: "." for all channels, "I" for info messages,
"R" for result lines, "M" for -mark texts.
-mark text
If text is not empty it will get put out on "M" channel
each time after a dialog line has been processed.
-prog text
Use text as name of this program in subsequent messages
-prog_help text
Use text as name of this program and perform -help.
EXAMPLES
Overview of examples: As superuser learn about available
drives
Blank media and compose a new ISO image as batch run
A dialog session doing about the same
Manipulate an existing ISO image on the same media
Copy modified ISO image from one media to another
Bring a prepared ISOLINUX tree onto media and make it
bootable
SunOS 5.11 Last change: Jun 27, 2010 65
User Commands XORRISO(1)
Change existing file name tree from ISO-8859-1 to UTF-8
Operate on storage facilities other than optical drives
Burn an existing ISO image file to media
Perform multi-session runs as of cdrtools traditions
Let xorriso work underneath growisofs
Adjust thresholds for verbosity, exit value and program
abort
Examples of input timestrings
Incremental backup of a few directory trees
Restore directory trees from a particular ISO session to
disk
Try to retrieve blocks from a damaged media
As superuser learn about available drives On Linux or
FreeBSD consider to give rw-permissions to those users or
groups which shall be able to use the drives with xorriso.
On Solaris use pfexec. Consider to restrict privileges of
xorriso to "base,sys_devices" and to give r-permission to
user or group.
$ xorriso -devices
0 -dev '/dev/sr0' rwrw-- : '_NEC ' 'DVD_RW ND-4570A'
1 -dev '/dev/sr1' rwrw-- : 'HL-DT-ST' 'DVDRAM GSA-4082B'
2 -dev '/dev/sr2' rwrw-- : 'PHILIPS ' 'SPD3300L'
Blank media and compose a new Aquire drive /dev/sr2, make
media ready for writing a new image, fill the image with the
files from hard disk directories /home/me/sounds and
/home/me/pictures.
Because no -dialog "on" is given, the program will then end
by writing the session to media.
$ xorriso -outdev /dev/sr2 \
-blank as_needed \
-map /home/me/sounds /sounds \
-map /home/me/pictures /pictures
The ISO image may be shaped in a more elaborate way like the
following: Omit some unwanted stuff by removing it from the
image directory tree. Reintroduce some wanted stuff.
$ cd /home/me
$ xorriso -outdev /dev/sr2 \
-blank as_needed \
-map /home/me/sounds /sounds \
-map /home/me/pictures /pictures \
-rm_r \
/sounds/indecent \
'/pictures/*private*' \
/pictures/confidential \
-- \
-cd / \
-add pictures/confidential/work* --
SunOS 5.11 Last change: Jun 27, 2010 66
User Commands XORRISO(1)
Note that '/pictures/*private*' is a pattern for
iso_rr_paths while pictures/confidential/work* gets expanded
by the shell with addresses from the hard disk. Options -add
and -map have different argument rules but finally the same
effect: they put files into the image.
A dialog session doing about the
Some settings are already given as start argument. The other
activities are done as dialog input. The pager gets set to
20 lines of 80 characters.
The drive is acquired by option -dev rather than -outdev in
order to see the message about its current content. By
option -blank this content is made ready for being
overwritten and the loaded ISO image is made empty.
In order to be able to eject the media, the session needs to
be committed explicitly.
$ xorriso -dialog on -page 20
enter option and arguments :
-dev /dev/sr2
enter option and arguments :
-blank as_needed
enter option and arguments :
-map /home/me/sounds /sounds -map /home/me/pictures
/pictures
enter option and arguments :
-rm_r /sounds/indecent /pictures/*private*
/pictures/confidential
enter option and arguments :
-cdx /home/me/pictures -cd /pictures
enter option and arguments :
-add confidential/office confidential/factory
enter option and arguments :
-du /
enter option and arguments :
-commit_eject all -end
Manipulate an existing ISO image on Load image from drive.
Remove (i.e. hide) directory /sounds and its subordinates.
Rename directory /pictures/confidential to
/pictures/restricted. Change access permissions of
directory /pictures/restricted. Add new directory trees
/sounds and /movies. Burn to the same media, check whether
the tree can be loaded, and eject.
$ xorriso -dev /dev/sr2 \
-rm_r /sounds -- \
-mv \
/pictures/confidential \
/pictures/restricted \
-- \
-chmod go-rwx /pictures/restricted -- \
SunOS 5.11 Last change: Jun 27, 2010 67
User Commands XORRISO(1)
-map /home/me/prepared_for_dvd/sounds_dummy /sounds \
-map /home/me/prepared_for_dvd/movies /movies \
-commit -eject all
Copy modified ISO image from one Load image from input
drive. Do the same manipulations as in the previous example.
Aquire output drive and blank it. Burn the modified image as
first and only session to the output drive.
$ xorriso -indev /dev/sr2 \
-rm_r /sounds -- \
...
-outdev /dev/sr0 -blank as_needed \
-commit -eject all
Bring a prepared ISOLINUX tree onto The user has already
created a suitable file tree on disk and copied the ISOLINUX
files into subdirectory ./boot/isolinux of that tree. Now
xorriso can burn an El Torito bootable media:
$ xorriso -outdev /dev/sr0 -blank as_needed \
-map /home/me/ISOLINUX_prepared_tree / \
-boot_image isolinux dir=/boot/isolinux
Change existing file name tree from This example assumes
that the existing ISO image was written with character set
ISO-8859-1 but that the readers expected UTF-8. Now a new
session with the same files gets added with converted file
names. In order to avoid any weaknesses of the local
character set, this command pretends that it uses already
the final target set UTF-8. Therefore strange file names
may appear in eventual messages which will be made terminal-
safe by option -backslash_codes.
$ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
-out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
-alter_date m +0 / -- -commit -eject all
Operate on storage facilities other than Full read-write
operation is possible with regular files and block devices:
$ xorriso -dev /tmp/regular_file ...
Paths underneath /dev normally need prefix "stdio:"
$ xorriso -dev stdio:/dev/sdb ...
If /dev/sdb is to be used frequently and /dev/sda is the
system disk, then consider to place the following lines in a
xorriso Startup File. They allow to use /dev/sdb without
prefix and protect disk /dev/sda from xorriso:
-drive_class banned /dev/sda*
-drive_class harmless /dev/sdb
Other writeable file types are supported write-only:
$ xorriso -outdev /tmp/named_pipe ...
SunOS 5.11 Last change: Jun 27, 2010 68
User Commands XORRISO(1)
Among the write-only drives is standard output:
$ xorriso -outdev - \
...
| gzip >image.iso.gz
Burn an existing ISO image file Actually this works with any
kind of data, not only ISO images:
$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed
image.iso
Perform multi-session runs as of cdrtools Between both
processes there can be performed arbitrary transportation or
filtering.
The first session is written like this:
$ xorriso -as mkisofs prepared_for_iso/tree1 | \
xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi
-eject -
Follow-up sessions are written like this:
$ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
$ xorriso -as mkisofs -M /dev/sr0 -C $m
prepared_for_iso/tree2 | \
xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
Always eject the drive tray between sessions. The old
sessions get read via stdio:/dev/sr0 and thus are prone to
device driver peculiarities.
This example works for multi-session media only. Add
cdrskin option --grow_overwriteable_iso to all -as cdrecord
runs in order to enable multi-session emulation on
overwriteable media.
Let xorriso work underneath growisofs growisofs expects an
ISO formatter program which understands options -C and -M.
If xorriso gets started by name "xorrisofs" then it is
suitable for that.
$ export MKISOFS="xorrisofs"
$ growisofs -Z /dev/dvd /some/files
$ growisofs -M /dev/dvd /more/files
If no "xorrisofs" is available on your system, then you will
have to create a link pointing to the xorriso binary and
tell growisofs to use it. E.g. by:
$ ln -s $(which xorriso) "$HOME/xorrisofs"
$ export MKISOFS="$HOME/xorrisofs"
One may quit mkisofs emulation by argument "--" and make use
of all xorriso commands. growisofs dislikes options which
start with "-o" but -outdev must be set to "-". So use
"outdev" instead:
$ growisofs -Z /dev/dvd -- outdev - -update_r /my/files
/files
$ growisofs -M /dev/dvd -- outdev - -update_r /my/files
SunOS 5.11 Last change: Jun 27, 2010 69
User Commands XORRISO(1)
/files
growisofs has excellent burn capabilities with DVD and BD.
It does not emulate session history on overwriteable media,
though.
Adjust thresholds for verbosity, exit value Be quite
verbous, exit 32 if severity "FAILURE" was encountered, do
not abort prematurely but forcibly go on until the end of
commands.
$ xorriso ... \
-report_about UPDATE \
-return_with FAILURE 32 \
-abort_on NEVER \
...
Examples of input timestrings
As printed by program date: 'Thu Nov 8 14:51:13 CET 2007'
The same without ignored parts: 'Nov 8 14:51:13 2007'
The same as expected by date: 110814512007.13
Four weeks in the future: +4w
The current time: +0
Three hours ago: -3h
Seconds since Jan 1 1970: =1194531416
Incremental backup of a few directory This changes the
directory trees /open_source_project and /personal_mail in
the ISO image so that they become exact copies of their disk
counterparts. ISO file objects get created, deleted or get
their attributes adjusted accordingly.
ACL, xattr, hard links and MD5 checksums will be recorded.
Accelerated comparison is enabled at the expense of
potentially larger backup size. Only media with the expected
volume id or blank media are accepted. Files with names
matching *.o or *.swp get excluded explicitly.
When done with writing the new session gets checked by its
recorded MD5.
$ xorriso \
-for_backup -disk_dev_ino on \
-assert_volid 'PROJECTS_MAIL_*' FATAL \
-dev /dev/sr0 \
-volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
-not_leaf '*.o' -not_leaf '*.swp' \
-update_r /home/thomas/open_source_projects
/open_source_projects \
-update_r /home/thomas/personal_mail /personal_mail \
-commit -toc -check_md5 FAILURE -- -eject all
To be used several times on the same media, whenever an
update of the two disk trees to the media is desired. Begin
with blank media and start a new blank media when the run
SunOS 5.11 Last change: Jun 27, 2010 70
User Commands XORRISO(1)
fails due to lack of remaining space on the old one.
This makes sense if the full backup leaves substantial
remaining capacity on media and if the expected changes are
much smaller than the full backup. To apply zisofs
compression to those data files which get newly copied from
the local filesystem, insert these options immediately
before -commit :
-hardlinks perform_update \
-find / -type f -pending_data -exec set_filter --zisofs --
\
Options -disk_dev_ino and -for_backup depend on stable
device and inode numbers on disk. Without them, an update
run may use -md5 "on" to match recorded MD5 sums against the
current file content on hard disk. This is usually much
faster than the default which compares both contents
directly.
With mount option -o "sbsector=" on GNU/Linux resp. -s on
FreeBSD 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 its
option "session=".
Multi-session media and most overwriteable media written by
xorriso can tell the sbsectors of their sessions by xorriso
option -toc. Used after -commit the following option prints
the matching mount command for the newly written session
(here for mount point /mnt):
-mount_cmd "indev" "auto" "auto" /mnt
Options -mount_cmd and -mount are also able to produce the
mount commands for older sessions in the table-of-content.
E.g. as superuser:
# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
Sessions on multi-session media are separated by several MB
of unused blocks. So with small sessions the payload
capacity can become substantially lower than the overall
media capacity. If the remaining space on media does not
suffice for the next gap, the drive is supposed to close the
media automatically.
Better do not use your youngest backup for -update_r. Have
at least two media which you use alternatingly. So only
older backups get endangered by the new write operation,
while the newest backup is stored safely on a different
media. Always have a blank media ready to perform a full
backup in case the update attempt fails due to insufficient
remaining capacity.
Restore directory trees from a particular This is an
alternative to mounting the media and using normal file
operations.
First check which backup sessions are on the media:
$ xorriso -outdev /dev/sr0 -toc
Then load the desired session and copy the file trees to
SunOS 5.11 Last change: Jun 27, 2010 71
User Commands XORRISO(1)
disk. Enable restoring of ACL, xattr and hard links. Avoid
to eventually create /home/thomas/restored without rwx-
permission.
$ xorriso -for_backup \
-load volid 'PROJECTS_MAIL_2008_06_19*' \
-indev /dev/sr0 \
-osirrox on:auto_chmod_on \
-chmod u+rwx / -- \
-extract /open_source_projects \
/home/thomas/restored/open_source_projects \
-extract /personal_mail /home/thomas/restored/personal_mail
\
-rollback_end
The final command -rollback_end prevents an error message
about the altered image being discarded.
Try to retrieve blocks from a
$ xorriso -abort_on NEVER -indev /dev/sr0 \
-check_media time_limit=1800 report=blocks_files \
data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
This can be repeated several times, eventually with -eject
or with other -indev drives. See the human readable part of
"$HOME"/dvd_copy.map for addresses which can be used on
"$HOME"/dvd_copy with mount option -o sbsector= resp. -s.
FILES
Program alias names:
Normal installation of xorriso creates three links or copies
which by their program name pre-select certain settings:
xorrisofs starts xorriso with -as mkisofs emulation.
xorrecord starts xorriso with -as cdrecord emulation.
osirrox starts with -osirrox "on:o_excl_off" which allows to
copy files from ISO image to disk and to apply option -mount
to one or more of the existing ISO sessions.
Startup files:
If not -no_rc is given as the first argument then xorriso
attempts on startup to read and execute lines from the
following files:
/etc/default/xorriso
/etc/opt/xorriso/rc
/etc/xorriso/xorriso.conf
$HOME/.xorrisorc
The files are read in the sequence given above, but none of
them is required to exist.
If mkisofs emulation was enabled by program name
"xorrisofs", "mkisofs", "genisoimage", or "genisofs", then
afterwards -read_mkisofsrc is performed, which reads
.mkisofsrc files. See there.
SunOS 5.11 Last change: Jun 27, 2010 72
User Commands XORRISO(1)
Runtime control files:
The default setting of -check_media abort_file= is:
/var/opt/xorriso/do_abort_check_media
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+------------------+
|Availability | media/xorriso |
+---------------+------------------+
|Stability | Uncommitted |
+---------------+------------------+
SEE ALSO
For mounting xorriso generated ISO 9660 images (-t iso9660)
mount(8)
Libreadline, a comfortable input line facility
readline(3)
Other programs which produce ISO 9660 images
mkisofs(8), genisoimage(8)
Other programs which burn sessions to optical media
growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
ACL and xattr
getfacl(1), setfacl(1), getfattr(1), setfattr(1)
MD5 checksums
md5sum(1)
AUTHOR
Thomas Schmitt <scdbackup@gmx.net>
for libburnia-project.org
COPYRIGHT
Copyright (c) 2007 - 2010 Thomas Schmitt
Permission is granted to distribute this text freely. It
shall only be modified in sync with the technical properties
of xorriso. If you make use of the license to derive
modified versions of xorriso then you are entitled to modify
this text under that same license.
CREDITS
xorriso is in part based on work by Vreixo Formoso who
provides libisofs together with Mario Danic who also leads
the libburnia team. Thanks to Andy Polyakov who invented
SunOS 5.11 Last change: Jun 27, 2010 73
User Commands XORRISO(1)
emulated growing, to Derek Foreman and Ben Jansens who once
founded libburn.
Compliments towards Joerg Schilling whose cdrtools served me
for ten years.
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://scdbackup.sourceforge.net/xorriso-0.6.0.tar.gz
Further information about this software can be found on the
open source community website at
http://scdbackup.sourceforge.net/xorriso/.
SunOS 5.11 Last change: Jun 27, 2010 74