legacy/libisoburn/trunk/xorriso/xorriso.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH XORRISO 1 "Mar 12, 2009"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.nh
.SH NAME
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions.
.SH SYNOPSIS
.B xorriso
.RI [ settings | actions ]
.br
.SH DESCRIPTION
.PP
.B xorriso
is a program which maps 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.
.br
Vice versa xorriso is able to restore file objects from ISO 9660 filesystems.
.PP
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 .
.SS
.B Overview of features:
.br
Operates on an existing ISO image or creates a new one.
.br
Copies files from filesystem into the ISO image.
.br
Renames or deletes file objects in the ISO image.
.br
Changes file properties in the ISO image.
.br
Updates ISO subtrees incrementally to match given disk subtrees.
.br
Writes result either as completely new image or as add-on session
to optical media or filesystem objects.
.br
Can activate ISOLINUX boot images via El Torito.
.br
Can perform multi-session tasks as emulation of mkisofs and cdrecord.
.br
Can restore files from ISO image to disk filesystem (see osirrox).
.br
Can record and restore ACL of disk files.
.br
Can issue commands to mount older sessions on Linux or FreeBSD.
.br
Can check media for damages and copy readable blocks to disk.
.br
Scans for optical drives, blanks re-useable optical media.
.br
Reads its instructions from command line arguments, dialog, and batch files.
.br
Provides navigation commands for interactive ISO image manipulation.
.br
Adjustable thresholds for abort, exit value, and problem reporting.
.SS
.B General information paragraphs:
.br
Session model
.br
Media types and states
.br
Creating, Growing, Modifying, Blind Growing
.br
Libburn drives
.br
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
.br
Command processing
.br
Dialog, Readline, Result pager
.sp 1
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.
.SS
.B Session model:
.br
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
.B session.
.br
The data content of the session is called filesystem
.B image.
.PP
The written image in its session can then be mounted by the operating system
for being used read-only. 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.
.PP
This session usage model has been extended on CD media by the concept of
.B 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.
.br
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.
.br
Adding a session to an existing ISO image is in this text referred as
\fBgrowing\fR.
.br
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. This expansion method is referred as emulated growing.
.PP
xorriso provides both ways of growing as well as an own method named
\fBmodifying\fR which produces a completely new ISO image from the old
one and the modifications.
See paragraph Creating, Growing, Modifying, Blind Growing below.
.PP
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.
.br
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.
.PP
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.
.PP
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.
.br
In some special situations (e.g. in a file-to-file situation) it can be
useful to store intermediate states and to continue with image manipulations.
.SS
.B Media types and states:
There are two families of media in the MMC standard:
.br
\fBMulti-session media\fR are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, and
unformatted DVD-RW. These media provide a table of content which
describes their existing sessions. See option \fB-toc\fR.
.br
\fBOverwriteable media\fR 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.
.br
DVD-RW media can be formatted by -format full. 
They can be made unformatted by -blank deformat.
.br
Emulated drives are handled as overwriteable media if they are random
read-write accessible. If they are only sequentially writeable then
they are handled as blank multi-session media.
.PP
These media can assume several states in which they offer different
capabilities.
.br
\fBBlank\fR media can be written from scratch. They contain no ISO image
suitable for xorriso.
.br
Blank is the state of newly purchased optical media.
With used CD-RW and DVD-RW it can be achieved by action -blank "as_needed".
Overwriteable media are considered blank if 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 of new media.
.br
\fBAppendable\fR 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.
.br
Appendable is the state after writing a session with option -close off.
.br
\fBClosed\fR media cannot be written. They may contain an ISO image suitable
for xorriso.
.br
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.
.br
Overwriteable media assume this state in such read-only drives or if they
contain unrecognizable data in the first 32 data blocks.
.br
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.
.SS
.B Creating, Growing, Modifying, Blind Growing:
.br
A new empty ISO image gets \fBcreated\fR
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.
.br
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.
.PP
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.
.PP
The method of \fBgrowing\fR 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.
.br
Growing is achieved by option -dev.
.PP
The write method of \fBmodifying\fR produces compact filesystem
images with no outdated files or directory trees. Modifying can write its
images to target media which are completely 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.
.br
So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target media.
.br
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.
.PP
If option -grow_blindly is set to a non-negative number and if -indev and
-outdev are both set to different drives, then \fBblind growing\fR 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
.br
 mkisofs -M $indev -C $msc1,$msc2 -o $outdev
.br
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:
.br
 -load sbsector $msc1 -grow_blindly $msc2
.SS
.B Libburn drives:
.br
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.
.PP
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.
.br
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.
.PP
MMC compliant (i.e. optical) drives on Linux usually get addressed by
the path of their block device or of their generic character device. E.g.
.br
  -dev /dev/sr0
.br
  -dev /dev/hdc
.br
  -dev /dev/sg2
.br
On FreeBSD the device files have names like
.br
  -dev /dev/cd0
.br
  -dev /dev/acd0
.br
Get a list of accessible drives by command
.br
  -devices
.br
It might be necessary to do this as
.B 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".
.PP
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and
their path in the filesystem. E.g.:
.br
  -dev stdio:/dev/sdc
.br
The default setting of -drive_class allows to address files outside the
/dev tree without that prefix. E.g.:
.br
  -dev /tmp/pseudo_drive
.br
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.
.PP
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).
.br
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.
.br
Standard output is currently suitable for creating one session
per program run without dialog. Use in other situations is discouraged
and several restrictions apply: 
.br
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.
.br
If stdout is used as drive, then -use_readline is permanently disabled.
Use of backdoors will cause severe memory and/or tty corruption.
.PP
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.
.br
One may use option
.B -ban_stdio_write
to surely prevent this risk and to allow only MMC drives.
.br
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
.br
By option -drive_class one may ban certain paths or allow access without
prefix "stdio:" to other paths.
.SS
.B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
.br
.B Rock Ridge
is the name of a set of additional informations which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
.PP
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.
.PP
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.
.PP
An
.B El Torito
boot record connects a boot image, which is a binary program plus some
other 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.
.br
Most bootable Linux CDs are equipped with ISOLINUX 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.
Emulation -as mkisofs supports the example options out of the ISOLINUX wiki.
.br
The support for other boot image types is sparse.
.br
An MBR is generated together with the El Torito boot record if the boot image
bears the isohybrid signature of ISOLINUX 3.72 or later. It will occupy the
first 512 bytes of the emerging ISO image and enable booting from media which
appear as hard disk rather than as CDROM. An MBR does not hamper CDROM booting.
The MBR of a follow-up session can get in effect only on overwriteable media.
.PP
.B 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
.B -acl.
.br
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.
.br
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.
.PP
.B xattr
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
.B -xattr.
.br
As with ACL, currently only xorriso is able to retrieve xattr from AAIP
enhanced images and to restore them to xattr capable file systems.
.SS
.B Command processing:
.br
Commands are either actions which happen immediately or settings which
influence following actions. So their sequence does matter.
.br
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 \fBlist delimiter\fR, or the end of argument list,
or an end of an input line.
.PP
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.
.br
For brevity the list delimiter is referred as "--" throughout this text.
.br
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.
.PP
.B Pattern expansion
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 "[...]".
.br
Some other commands perform pattern matching unconditionally.
.PP
Command and parameter words are either read from program arguments, where one
argument is one word, or from quoted input lines where words are recognized
similar to the quotation rules of a shell parser.
.br
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.
.PP
.B 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.
.br
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
.B Backslash Interpretation
which can represent all ASCII characters except NUL (0) by backslash codes
as in $'...' of bash.
.br
It is not enabled by default. See option -backslash_codes.
.PP
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.
.PP
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.
.SS
.B Dialog, Readline, Result pager:
.br
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.
.PP
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
package readline-dev at the time when xorriso was built from its sourcecode.
.br
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. 
.br
See man readline for more info about libreadline.
.PP
Option -page activates a builtin 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.
.br
An empty line lets xorriso resume work until the next page is put out.
.br
The single character "@" disables paging for the current action.
.br
"@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress
further result output.
.br
Any other line will be interpreted as new dialog line. The current action
is urged to abort. Afterwards, the input line is executed.
.PP
Some actions apply paging to their info output, too.
.br
The urge to abort may or may not be obeyed by the current action. All actions
try to abort as soon as possible.
.br
.SH OPTIONS
.br
All command words are shown with a leading dash although this dash is not
mandatory for the option to be recognized. There may be future emulation
modes, where dashes may become mandatory in order to distinguish options
from file addresses.
.br
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
.TP
.B Aquiring source and target drive:
.TP
\fB\-dev\fR 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.
.br
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.
Violation yields a FAILURE event.
.br
Special address string "-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
.br
An empty address string "" gives up the current device
without aquiring a new one.
.TP
\fB\-indev\fR 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 activated.
The same rules and restrictions apply as with -dev.
.TP
\fB\-outdev\fR 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.
.br
-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.
.br
Special address string "-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
.br
An empty address string "" gives up the current output drive
without aquiring a new one. No writing is possible without an output drive.
.TP
\fB\-drive_class\fR "harmless"|"banned"|"caution"|"clear_list" disk_pattern
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:
.br
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.
.br
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.
.br
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".
.br
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".
.br
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.
.br
By pseudo-class "clear_list" and pseudo-patterns "banned", "caution",
"harmless", or "all", the lists may be made empty.
.br
E.g.: -drive_class clear_list banned
.br
One will normally define the -drive_class lists in one of the xorriso
Startup Files.
.br
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 to deny its rw-permissions in the filesystem.
.TP
\fB\-grow_blindly\fR "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.
.br
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.
.br
During a run of blind growing, the input drive gets released before output
begins. The output drive gets released when writing is done.
.TP
\fB\-load\fR entity id
Load a particular (possibly outdated) ISO image from a -dev or -indev which
hosts more than one session. Usually all available sessions are shown with
option -toc.
.br
entity depicts the kind of addressing. id depicts the particular
address. The following entities are defined:
.br
"auto" with any id addresses the last session in -toc. This is the default.
.br
"session" with id being a number as of a line "ISO session", column "Idx".
.br
"track" with id being a number as of a line "ISO track", column "Idx".
.br
"lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector".
.br
"volid" with a search pattern for a text as of a line "ISO ...",
column "Volume Id".
.br
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.
.br
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".
.TP
\fB\-assert_volid\fR 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. An empty search pattern accepts any image.
.br
This option does not hamper the creation of an empty image from blank
input media and does not discard an already loaded image.
.TP
\fB\-in_charset\fR 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.
.TP
\fB\-acl\fR "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.
.TP
\fB\-xattr\fR "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.
.TP
\fB\-disk_dev_ino\fR "on"|"ino_only"|"off"
Enable or disable processing of recorded file identification numbers
(dev_t and ino_t). They are eventually stored as xattr "isofs.di" and allow
to substantially accelerate file comparison.
.br
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.
.br
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.
.br
The speed advantage appears only if the loaded session was produced with
-disk_dev_ino "on" too.
.TP
\fB\-rom_toc_scan\fR "on"|"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.)
.br
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 scan for alleged read-only media.
.br
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.
.br
To be in effect, the -rom_toc_scan setting has to be made before the -*dev
command which aquires drive and media.
.TP
\fB\-ban_stdio_write\fR
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.
.TP
.B Data manipulations:
.PP
The following commands expect file addresses of two kinds:
.br
.B disk_path
is a path to an object in the local filesystem tree.
.br
.B 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.)
.PP
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.
.PP
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:
.br
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
.B \-overwrite
decides.
.br
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.
.PP
The commands in this section alter the ISO image and not the local filesystem.
.TP
\fB\-iso_rr_pattern\fR "on"|"ls"|"off"
Set the pattern expansion mode for the iso_rr_path arguments of several
commands which support this feature.
.br
.B 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.
.br
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]'
and respects '/' as separator which may only be matched literally.
.br
Setting "off" disables this feature for all commands which are marked in this
man page by "iso_rr_path [***]" or "iso_rr_pattern [***]".
.br
Setting "on" enables it for all those commands.
.br
Setting "ls" enables it only for those which are marked by
"iso_rr_pattern [***]".
.br
Default is "on".
.TP
\fB\-disk_pattern\fR "on"|"ls"|"off"
Set the pattern expansion mode for the disk_path arguments of several
commands which support this feature.
.br
Setting "off" disables this feature for all commands which are marked in this
man page by "disk_path [***]" or "disk_pattern [***]".
.br
Setting "on" enables it for all those commands.
.br
Setting "ls" enables it only for those which are marked by
"disk_pattern [***]".
.br
Default is "ls".
.TP
\fB\-add\fR pathspec [...] | disk_path [***]
Insert the given files or directory trees from filesystem
into the ISO image.
.br
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:
.br
iso_rr_path=disk_path
.br
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.
.br
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.
.br
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.
.TP
\fB\-add_plainly\fR 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 applies to disk_paths.
.br
Mode "dashed" is similar to "unknown" but also adds unrecognized command
words even if they begin with "-".
.br
Mode "any" announces that all further words are to be added as pathspecs
or disk_paths. This does not work in dialog mode.
.br
Mode "none" is the default. It prevents any words from being understood
as files to add, if they are not parameters to appropriate commands.
.TP
\fB\-path_list\fR 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. 
.TP
\fB\-quoted_path_list\fR disk_path
Like -path_list but with quoted input reading rules. Lines get split into
parameter words for -add. Whitespace outside quotes is discarded.
.TP
\fB\-map\fR 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.
.TP
\fB\-map_single\fR disk_path iso_rr_path
Like -map, but if disk_path is a directory then its sub tree is not inserted.
.TP
\fB\-map_l\fR 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.
.TP
\fB\-update\fR 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. This comparison will imply lengthy content
reading before a decision is made. On the other hand it strives for the
smallest possible amount of add-on data which is needed to achieve the
matching copy.
.br
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.
.TP
\fB\-update_r\fR 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 both counterparts match. If there is a mismatch then the necessary
update manipulation is done.
.br
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.
.br
If iso_rr_path does not exist yet, then it gets added. If disk_path does not
exist, then iso_rr_path gets deleted.
.TP
\fB\-update_l\fR 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.
.TP
\fB\-cut_out\fR 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.
.br
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:
.br
 -cut_out /my/disk/file 0 2047m \\
.br
 /file/part_1_of_3_at_0_with_2047m_of_5753194821 \\
.br
 -cut_out /my/disk/file 2047m 2047m \\
.br
 /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \\
.br
 -cut_out /my/disk/file 4094m 2047m \\
.br
 /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
.br
-cut_out is coordinated with -compare* and -update* if the names of the
part files follow a convention by which xorriso is able to recognize
file parts and process them accordingly:
.br
A disk file gets mapped to an ISO directory containing its split parts
as regular files. The parts have names which describe the splitting
by 5 numbers which are separated by some non-numerical text:
.br
part_number, total_parts, byte_offset, byte_count, disk_file_size
.br
Scaling characters like "m" or "k" are taken into respect and may
serve as separators as well. All digits are interpreted as decimal,
even if leading zeros are present.
.br
Not all parts have to be present on the same media. But those parts
which are present have to sit in the same directory. No other files
are allowed in there. Parts have to be disjoint. Their numbers have
to be plausible. E.g. byte_count must be valid as -cut_out argument
and it must be the same with all parts.
.br
If the disk file grows enough to need new parts then those get added
to the directory if it already contains all parts of the old disk file.
If not all parts are present, then only those present parts will
be updated.
.TP
\fB\-cpr\fR disk_path [***] iso_rr_path
Insert the given files or directory trees from filesystem 
into the ISO image.
.br
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 under that
directory as would be done with an existing directory.
.br
If a single disk_path is present then a non-existing iso_rr_path will
get the same type as the disk_path.
.br
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. 
.TP
\fB\-rm\fR iso_rr_path [***]
Delete the given files from the ISO image.
.br
Note: This does not free any space on the -indev media, even if
the deletion is committed to that same media.
.br
The image size will shrink if the image is written to a different
media in modification mode.
.TP
\fB\-rm_r\fR iso_rr_path [***]
Delete the given files or directory trees from the ISO image.
See also the note with option -rm.
.TP
\fB\-mv\fR 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.
.br
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.
.TP
\fB\-chown\fR 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.
.TP
\fB\-chown_r\fR uid iso_rr_path [***]
Like -chown but affecting all files below eventual directories.
.TP
\fB\-chgrp\fR 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.
.TP
\fB\-chgrp_r\fR gid iso_rr_path [***]
Like -chgrp but affecting all files below eventual directories.
.TP
\fB\-chmod\fR mode iso_rr_path [***]
Equivalent to shell command chmod in the ISO image.
mode is either an octal number beginning with "0" or a comma separated
list of statements of the form [ugoa]*[+-=][rwxst]* .
.br
Like: go-rwx,u+rwx .
.br
.B Personalities:
u=user, g=group, o=others, a=all
.br
.B Operators:
+ adds given permissions, - revokes given permissions,
= revokes all old permissions and then adds the given ones.
.br
.B Permissions:
r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit
.br
For octal numbers see man 2 stat.
.TP
\fB\-chmod_r\fR mode iso_rr_path [***]
Like -chmod but affecting all files below eventual directories.
.TP
\fB\-setfacl\fR 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:
.br
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:
.br
  g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
.br
  group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
.br
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:
.br
  u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
.TP
\fB\-setfacl_r\fR acl_text iso_rr_path [***]
Like -setfacl but affecting all files below eventual directories.
.TP
\fB\-setfacl_list\fR 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 "-" then lines are read from standard input. Line "@" ends the
list, "@@@" aborts without changing the pending iso_rr_path.
.br
Since -getfacl and getfacl -R strip leading "/" from file paths, the setting of
-cd does always matter.
.TP
\fB\-setfattr\fR [-]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 the whole xattr
list of the given iso_rr_paths is deleted. In case of deletion, value must
be an empty text.
.br
Only names from the user namespace are allowed. I.e. a name has to begin with
"user.", like "user.x" or "user.whatever".
.br
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.
.TP
\fB\-setfattr_r\fR [-]name value iso_rr_path [***]
Like -setfattr but affecting all files below eventual directories.
.TP
\fB\-setfattr_list\fR 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.
.br
Since -getfattr and getfattr -Rd strip leading "/" from file paths, the setting
of -cd does always matter.
.br
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
.br
  name="value"
.br
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.
.TP
\fB\-alter_date\fR 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.
.br
timestring may be in the following formats
(see also section EXAMPLES):
.br
As expected by program date:
 MMDDhhmm[[CC]YY][.ss]]
.br
As produced by program date:
 [Day] MMM DD hh:mm:ss [TZON] YYYY
.br
Relative times counted from current clock time:
 +|-Number["s"|"h"|"d"|"w"|"m"|"y"]
.br
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d,
"y"=365.25d plus 1d added to multiplication result.
.br
Absolute seconds counted from Jan 1 1970:
 =Number
.br
xorriso's own timestamps:
 YYYY.MM.DD[.hh[mm[ss]]]
.br
scdbackup timestamps:
 YYMMDD[.hhmm[ss]]
.br
where "A0" is year 2000, "B0" is 2010, etc.
.TP
\fB\-alter_date_r\fR type timestring iso_rr_path [***]
Like -alter_date but affecting all files below eventual directories.
.TP
\fB\-find\fR iso_rr_path [test [test ...]] [-exec action [params]] --
A very restricted substitute for shell command find in the ISO image.
It performs an action on matching file objects at or below iso_rr_path.
.br
Tests are optional. If they are omitted then action is applied to all file
objects. If tests are given then action is applied only if all of them
match the file object. Available tests are:
.br
-name pattern
.br
Pattern is not expanded but used for comparison with
the particular file names of the eventual directory tree underneath
iso_rr_path.
.br
-type type_letter
.br
matches only files 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.
.br
Only the first letter is interpreted.  E.g.: -find / -type d
.br
-damaged
.br
matches only 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.
.br
-undamaged
.br
matches only files which use data blocks outside the areas marked as damaged. 
.br
-lba_range start_lba block_count
.br
matches only files which use data blocks within the range of start_lba
and start_lba+block_count-1.
.br
-has_acl , -has_no_acl
.br
match files which have resp. have not a non-trivial ACL.
.br
-has_xattr , -has_no_xattr
.br
match files which have resp. have not xattr name-value pairs
from user namespace.
.br
-has_aaip , -has_no_aaip
.br
match files which have ACL or any xattr resp. have neither of them.
.br

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.
.br
"chown" and "chown_r" change the ownership and get the user id as param. E.g.:
.br
  -find / -exec chown thomas --
.br
"chgrp" and "chgrp_r" change the group attribute and get the group id as param.
E.g.:
.br
  -find / name 'news*' -type d -exec chgrp_r staff --
.br
"chmod" and "chmod_r" change access permissions and get a mode string as param.
E.g.:
.br
  -find / -exec chmod a-w,a+r --
.br
"alter_date" and "alter_date_r" change the timestamps.
They get a type character and a timestring as params. 
E.g.:
.br
  -find / -exec alter_date "m" "Dec 30 19:34:12 2007" --
.br
"lsdl" prints file information like shell command ls -dl.
E.g.:
.br
  -find / -exec lsdl --
.br
"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.:
.br
  -find / -exec compare /home/thomas --
.br
"update" performs command -update with the found file address as iso_rr_path.
The corresponding file address is determined like with above "compare".
.br
E.g.:
.br
  -find / -exec update /home/thomas --
.br
"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".
.br
E.g.:
.br
  -find / -name *.doc -exec rm --
.br
"rm_r" removes the found iso_rr_path from the image, including whole directory
trees.
.br
E.g.:
.br 
  -find /uh/oh -name *private* -exec rm_r --
.br
"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. 
.br
E.g.:
.br
  -find / -damaged -exec report_damage
.br
"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".
.br
E.g.:
.br
  -find / -lba_range 302000 50000 -exec report_lba
.br
"getfacl" prints access permissions in ACL text form to the result channel.
.br
E.g.:
.br
  -find / -has_acl -exec getfacl
.br
"setfacl" attaches ACLs after removing eventually exiting ones. The new
ACL is given in text form as defined with option -setfacl.
.br
E.g.:
.br
  -find /workgroup -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw
.br
"getfattr" prints eventual xattr name-value pairs to the result channel.
.br
E.g.:
.br
  -find / -has_xattr -exec getfattr
.br
"setfattr" sets or deletes xattr name value pairs.
.br
E.g.:
.br
  -find / -has_xattr -exec setfattr --remove-all ''
.br
"find" performs another run of -find on the matching file address. It accepts
the same params as -find, except iso_rr_path.
E.g.:
.br
  -find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r --
.br
If not used as last command in the line then the argument list
needs to get terminated by "--".
.TP
\fB\-mkdir\fR 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.
.TP
\fB\-rmdir\fR iso_rr_path [***]
Delete empty directories.
.TP
\fB\-rollback\fR
Discard the manipulated ISO image and reload it from -indev.
.TP
\fB\-rollback_end\fR
Discard the manipulated ISO image. End program without loading a new image.
.TP
.B Writing the result:
(see also paragraph about settings below)
.TP
\fB\-commit\fR
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.
To suppress a final write, execute -rollback_end.
To eject outdev after write without new loading of image, use -commit_eject.
.br

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 - or even the drive gets stuck and you need
to reboot - 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.
.TP
\fB\-eject\fR "in"|"out"|"all"
Eject the media in -indev, resp. -outdev, resp. both drives.
Note: It is not possible yet to effectively eject disk files.
.TP
\fB\-commit_eject\fR "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.
.TP
\fB\-blank\fR mode
Make media ready for writing from scratch (if not -dummy is activated).
.br
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
.br
"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.
.br
"fast" and "all" make CD-RW and unformatted DVD-RW re-usable,
or invalidate overwriteable ISO images.
.br
"deformat" converts overwriteable DVD-RW into unformatted ones.
.br
"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".
.br
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.
.TP
\fB\-format\fR 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.
.br
Defined modes are:
.br
  as_needed, full, fast, by_index_<num>, fast_by_index_<num> 
.br
"as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or blank
unformatted BD-R. Other media are left untouched.
.br
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank unformatted BD-R.
.br
"fast" does the same as "full" but tries to be quicker.
.br
"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".
.br
"fast_by_index_" does the same as "by_index_" but tries to be quicker.
.br
"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.
.br
"fast_by_size_" does the same as "by_size_" but tries to be quicker.
.br
The formatting action has no effect on media if -dummy is activated.
.br
Formatting is normally needed only once during the lifetime of a media,
if ever. But it is a reason for re-formatting if:
.br
 DVD-RW was deformatted by -blank,
.br
 DVD+RW has read failures (re-format before next write),
.br
 DVD-RAM or BD-RE shall change their amount of defect reserve.
.br
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.
.br
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.
.TP
\fB\-list_formats\fR
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. 
.br
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.
.br
Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve space.
.TP
.B Settings for data insertion:
.TP
\fB\-file_size_limit\fR 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:
.br
 -file_size_limit 400g -200k --
.br
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.
.br
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.
.TP
\fB\-not_mgt\fR code[:code[...]]
Control the behavior of the exclusion lists.
.br
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.
.br
Several codes are defined.
The _on/_off settings persist until they are revoked by their_off/_on
counterparts.
.br
"erase" empties the lists which were accumulated by -not_paths and -not_leaf.
.br
"reset" is like "erase" but also re-installs default behavior.
.br
"off" disables exclusion processing temporarily without invalidating
the lists and settings.
.br
"on" re-enables exclusion processing.
.br
"param_off" applies exclusion processing only to paths below disk_path
parameter of commands. I.e. explicitely given disk_paths are exempted
from exclusion processing.
.br
"param_on" applies exclusion processing to command parameters as well as
to files below such parameters.
.br
"subtree_off" with "param_on" excludes parameter paths only if they
match a -not_paths item exactly.
.br
"subtree_on" additionally excludes parameter paths which lead to a file
address below any -not_paths item.
.br
"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.
.br
"ignore_on" keeps excluded files out of -compare or -update activities.
.TP
\fB\-not_paths\fR 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.
.br
(Do not forget to end the list of disk_paths by "--")
.TP
\fB\-not_leaf\fR 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.
.TP
\fB\-not_list\fR 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.
.TP
\fB\-quoted_not_list\fR disk_path
Like -not_list but with quoted input reading rules. Each word is
handled as one argument for -not_paths resp. -not_leaf.
.TP
\fB\-follow\fR 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.
.br
There are two kinds of follow decisison to be made:
.br
"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. 
.br
"mount" is the hop from one filesystem to another subordinate filesystem.
If enabled then mountpoint directories are handled as any other directory,
else mountpoints are handled as empty directories if they are encountered in
directory tree traversals.
.br
Less general than above occasions:
.br
"pattern" is mount and link hopping, but only during -disk_pattern expansion.
.br
"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). 
.br
Occasions can be combined in a colon separated list. All occasions
mentioned in the list will then lead to a positive follow decision. 
.br
"off" prevents any positive follow decision. Use it if no other occasion
applies.
.br
Shortcuts:
.br
"default" is equivalent to "pattern:mount:limit=100".
.br
"on" always decides positive. Equivalent to "link:mount".
.br

Not an occasion but an optional setting is:
.br
"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:
.br
  \fB$\fR ln -s .. uploop
.br
Link hopping has a builtin 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.
.TP
\fB\-pathspecs\fR "on"|"off"
Control parameter interpretation with xorriso actions -add and -path_list.
.br
"on" enables pathspecs of the form
.B target=source
like with program mkisofs -graft-points.
It also disables -disk_pattern expansion for command -add.
.br
"off" disables pathspecs of the form target=source
and eventually enables -disk_pattern expansion.
.TP                
\fB\-overwrite\fR "on"|"nondir"|"off"
Allow or disallow to overwrite existing files in the
ISO image by files with the same user defined name.
.br
With setting "off", name collisions cause FAILURE events.
With setting "nondir", only directories are 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.
.br
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".
.TP
\fB\-split_size\fR 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.
See also option -cut_out for more information about file parts.
.br
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.
.TP                
.B Settings for result writing:
.TP
Rock Ridge info will be generated by the program unconditionally.
ACLs will be written according to the setting of option -acl.
.TP
\fB\-joliet\fR "on"|"off"
If enabled by "on", generate Joliet info additional to Rock Ridge info.
.TP
\fB\-compliance\fR 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 inofficial extra features.
.br
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".
.br
Rule keywords are:
.br
"omit_version" do not add versions (";1") to the file names.
.br
"deep_paths" allow ISO file paths deeper than 8 levels.
.br
"long_paths" allow ISO file paths longer than 255 characters.
.br
"long_names" allow up to 37 characters with ISO file names.
.br
"no_force_dots" do not add a dot to filenames which have none.
.br
"lowercase" allow lowercase characters in ISO file names.
.br
"full_ascii" allow all ASCII characters in ISO file names.
.br
"joliet_long_paths" allow Joliet paths longer than 240 characters.
.br
"always_gmt" store timestamps in GMT representation with timezone 0.
.br
"rec_mtime" record with ISO files the disk file's mtime and not the
creation time of the image.
.br
"new_rr" use Rock Ridge version 1.12 (suitable for 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".
.br
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".
.br
"aaip_susp_1_10" allows AAIP to be written as inofficial extension of RRIP
rather than as official extension under SUSP-1.12.
.br
Default setting is "clear:deep_paths:long_paths:always_gmt".
.br
Note: The term "ISO file" means the plain ISO 9660 names wnd attributes
which get visible if the reader ignores Rock Ridge.
.TP
\fB\-volid\fR text
Specify the volume ID. xorriso accepts any text up to 32 characters,
but according to rarely obeyed specs stricter rules apply:
.br
ECMA 119 demands ASCII characters out of [A-Z0-9_]. Like: "IMAGE_23"
.br
Joliet allows 16 UCS-2 characters. Like: "Windows name"
.br
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.
.br
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.
.br 
Consider this when setting -volid "ISOIMAGE" before executing -dev, -indev,
or -rollback.
If you insist in -volid "ISOIMAGE", set it again after those commands.
.TP
\fB\-publisher\fR text
Set the publisher string to be written with the next -commit. Permissible
are up to 128 characters.
.TP
\fB\-application_id\fR text
Set the application id string to be written with the next -commit. Permissible
are up to 128 characters.
.TP
\fB\-out_charset\fR 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 after -commit the setting of -out_charset
will be copied to -in_charset.
.TP
\fB\-uid\fR uid
User id to be used for all files when the new ISO tree gets written to media.
.TP
\fB\-gid\fR gid
Group id to be used for all files when the new ISO tree gets written to media.
.TP
\fB\-speed\fR 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.
.br
Example speeds:
.br
 706k = 706kB/s = 4c = 4xCD
.br
 5540k = 5540kB/s = 4d = 4xDVD
.br
If there is no hint about the speed unit attached, then the
media in the -outdev will decide. Default unit is CD = 176.4k.
.br
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.
.TP
\fB\-stream_recording\fR "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. 
.br
"full" tries full speed with all write operations, 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.
.br
"data" causes full speed to start when superblock and directory entries are
written and writing of file content blocks begins.
.TP
\fB\-dummy\fR "on"|"off"
If "on" then simulate burning or refuse with FAILURE event if
no simulation is possible, do neither blank nor format.
.TP
\fB-fs\fR 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).
.TP
\fB\-close\fR "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).
.br
This is the contrary of cdrecord, wodim, cdrskin option -multi,
and is one aspect of growisofs option -dvd-compat.
.TP
\fB\-padding\fR 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.
.br
For images which will never get to a CD it is safe to use -padding 0 .
.TP
.B El Torito bootable ISO images:
.PP
Contrary to published specifications many BIOSes will load an El Torito
object 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.
.br
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.
.br
If ISOLINUX 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.
.TP
\fB\-boot_image\fR "any"|"isolinux"
.br
     "discard"|"keep"|"patch"|"show_status"|bootspec
.br
Define the handling of an eventual El Torito object which has
been read from an existing ISO image or defines how to make a prepared
ISOLINUX file set bootable.
.br

All types ("any") of El Torito boot images can be discarded or kept unaltered.
The latter makes only sense if the format of the boot image is
relocatable without content changes.
.br
With any type, "show_status" will print what is known about the loaded image
and its designated fate.
.br
An existing boot image of type "isolinux" can be discarded or it can be
patched to match its relocation. In the latter case the resulting ISO image
stays bootable if the boot image was really produced by ISOLINUX.
.br
CAUTION:
This is an expert option. 
xorriso cannot recognize the inner form of boot images.
So the user has already to know about the particular needs of the
boot image which is present on the input media.
.br
Most safe is the default: -boot_image "any" "discard".
.br

A bootspec is a word of the form name=value and is used to describe the
activation of a ISOLINUX boot image by an El Torito record and eventually
a MBR. The names "dir" and "bin_path" lead to boot image activation.
.br
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.
.br
The ISOLINUX files have to be added to the ISO image by normal means
(image loading, -map, -add, ...) and 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.:
.br
 -boot_image isolinux dir=/boot/isolinux
.br
which bundles these individual settings:
.br
 -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
.br
 -boot_image isolinux cat_path=/boot/isolinux/boot.cat
.br
 -boot_image isolinux load_size=2048
.br
bin_path depicts the binary program which is to be started by the BIOS at
boot time. It is among the files produced by ISOLINUX.
.br
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.
.br
Bootspec "isohybrid=off" disables MBR generation, "isohybrid=on" prevents the
write session if not the isohybrid signature is found in the bin_path file.
Default is "isohybrid=auto" which silently omits the MBR if the signature is
missing. 
.TP
.B Character sets:
.PP
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 computers.
The meanings of byte codes are defined in \fBcharacter sets\fR which have
names. Shell command iconv -l lists them. 
.br
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.
.br
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.
.br
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.
.TP
\fB\-charset\fR 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.
.TP
\fB\-local_charset\fR 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.
.TP
.B Exception processing:
.PP
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.
.br
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:
.br
"NEVER" The upper end of the severity spectrum.
.br
"ABORT" The program is being aborted and on its way to end.
.br
"FATAL" The main purpose of the run failed
or an important resource failed unexpectedly.
.br
"FAILURE" An important part of the job could not be performed.
.br
"MISHAP" A FAILURE which can be tolerated during ISO image generation.
.br
"SORRY" A less important part of the job could not be performed.
.br
"WARNING" A situation is suspicious of being not intended by the user.
.br
"HINT" A proposal to the user how to achieve better results.
.br
"NOTE" A harmless information about noteworthy circumstances.
.br
"UPDATE" A pacifier message during long running operations.
.br
"DEBUG" A message which would only interest the program developers.
.br
"ALL" The lower end of the severity spectrum.
.TP
\fB\-abort_on\fR severity
Set the severity threshold for events to abort the program.
.br
Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY"
.br
It may become necessary to abort the program anyway, despite
the setting by this option. Expect not many "ABORT" events to
be ignorable.
.br
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.
.TP
\fB\-return_with\fR severity exit_value
Set the threshold and exit_value to be returned at program end if no abort
has happened. This is to allow xorriso to go on after problems but to get
a failure indicating exit value from the program, nevertheless.
Useful is a value lower than the -abort_on threshold, down to "WARNING".
.br
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:
.br
1=abort due to external signal
.br
2=no program arguments given
.br
3=creation of xorriso main object failed
.br
4=failure to start libburnia-project.org libraries
.br
5=program abort during argument processing
.br
6=program abort during dialog processing
.TP
\fB\-report_about\fR severity
Set the threshold for events to be reported.
.br
Useful:  "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL"
.br
Regardless what is set by -report_about, messages get always reported if they
reach the severity threshold of -abort_on .
.br
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".
.br
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.
.TP
\fB\-error_behavior\fR 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.
.br
With "image_loading" there are three behaviors available:
.br
"best_effort" goes on with reading after events with severity below FAILURE
if the threshold of option -abort_on allows this.
.br
"failure" aborts image tree reading on first event of at least SORRY.
It issues an own FAILURE event.
.br
"fatal" acts like "failure" but issues the own event as FATAL.
This is the default.
.br
With occasion "file_extraction" there are three behaviors:
.br
"keep" maintains incompletely extracted files on disk. This is the default.
.br
"delete" removes files which encountered errors during content extraction.
.br
"best_effort" starts a revovery attempt by means of -extract_cut.
.TP
.B Dialog mode control:
.TP
\fB\-dialog\fR "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.
.br
Mode "on" supports input of newline characters within quotation marks and
line continuation by trailing backslash outside quotation marks.
Mode "single_line" does not.
.TP
\fB\-page\fR length width
Describe terminal to the text pager. See also above, paragraph Result pager.
.br
If parameter length is nonzero then the user gets prompted after that
number of terminal lines. Zero length disables paging.
.br
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.
.TP
\fB\-use_readline\fR "on"|"off"
If "on" then use readline for dialog. Else use plain stdin.
.br
See also above, paragraph Dialog, Readline, Result pager.
.TP
\fB\-reassure\fR "on"|"tree"|"off"
If "on" then ask the user for "y" or "n":
.br
before deleting or overwriting any file in the ISO image,
.br
before overwriting any disk file during restore operations,
.br
before rolling back pending image changes,
.br
before committing image changes to media,
.br
before changing the input drive,
.br
before blanking or formatting media,
.br
before ending the program.
.br
With setting "tree" the reassuring prompt will appear for an eventual
directory only once and not for each file in its whole subtree.
.br
Setting "off" silently kills any kind of image file object resp. performs
above irrevocable actions.
.br
To really produce user prompts, option -dialog needs to 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.
.br
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.
.TP
.B Drive and media related inquiry actions:
.TP
\fB\-devices\fR
Show list of available MMC drives with the addresses of
their libburn standard device files.
.br
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.
.br
In order to be visible, a device has to offer rw-permissions
with its libburn standard device file. Thus it might be only the
.B superuser
who is able to see all drives.
.br
Drives which are occupied by other processes get not shown.
.TP
\fB\-toc\fR
.br
Show media specific table of content. This is the media session history,
not the ISO image directory tree.
.br
In case of overwriteable media holding a valid ISO image, a single session
gets fabricated from the ISO image size info. But if the first session on the
overwriteable media was written by xorriso then in most cases a complete
session history can be emulated.
.br
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.
.br
Some read-only drives and media show no usable session history at all.
Eventually option -rom_toc_scan might help.
.TP
\fB\-mount_cmd\fR 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 Linux and on FreeBSD.
.br
drive can be "indev" or "outdev" to indicate already aquired drives,
or it can be the path of a not yet acquired drive.
Prefix "stdio:" for non-MMC drives is not mandatory.
.br
entity must be either "sbsector" , "track" , "session" , "volid" 
or "auto". See also option -load.
.br
id gives the superblock sector address, the track number, the session number,
or a search pattern for the volume id respectively.
.br
path will be used as mount point and must already exist as a directory.
.br
The command gets printed to the result channel. See option -mount
for direct execution of this command.
.TP
\fB\-session_string\fR drive entity id format
Print to the result channel a text which gets composed according to
format and the parameters of the addressed session.
.br
Formats "linux:"path or "freebsd:"path produce the output of -mount_cmd
for the given operating systems.
.br
In other texts xorriso will substitute the following parameter names.
An optional prefix "string:" will be removed. 
.br
"%device%" will be substituted by the mountable device path of the drive
address.
.br
"%sbsector%" will be substituted by the session start sector.
.br
"%track%", "%session%", "%volid%" will be substituted by track number,
session number, resp. volume id of the depicted session.
.TP
\fB\-print_size\fR
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.
.TP
\fB\-tell_media_space\fR
Print available space on output media and the free space after
subtracting already foreseeable consumption by next -commit.
.TP
.B Navigation in ISO image and disk filesystem:
.TP
\fB\-cd\fR iso_rr_path
Change the current working directory in the emerging ISO
image as it is at the moment. This is prepended to iso_rr_paths
which do not begin with '/'.
.br
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.
.TP
\fB\-cdx\fR disk_path
Change the current working directory on filesystem.
To be prepended to disk_paths which do not begin with '/'.
.TP
\fB\-pwd\fR
.br
Tell the current working directory in the ISO image.
.TP
\fB\-pwdx\fR
.br
Tell the current working directory on local filesystem.
.TP
\fB\-ls\fR 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, the current working directory in the ISO image.
.br
Directories are listed by their content rather than as single file item.
.br
Pattern expansion may be disabled by command -iso_rr_pattern.
.TP
\fB\-lsd\fR iso_rr_pattern [***]
Like -ls but listing directories as themselves and not by their content.
This resembles shell command ls -d.
.TP
\fB\-lsl\fR iso_rr_pattern [***]
Like -ls but also list some of the file attributes. 
The output format resembles shell command ls -ln.
.TP
\fB\-lsdl\fR iso_rr_pattern [***]
Like -lsd but also list some of the file attributes. 
The output format resembles shell command ls -dln.
.TP
\fB\-lsx\fR disk_pattern [***]
List files on local filesystem which match shell patterns. Patterns which do
not begin with '/' are used relative to -cdx, the current working directory in
the local filesystem.
.br
Directories are listed by their content rather than as single file item.
.br
Pattern expansion may be disabled by command -disk_pattern.
.TP
\fB\-lsdx\fR disk_pattern [***]
Like -lsx but listing directories as themselves and not by their content.
This resembles shell command ls -d.
.TP
\fB\-lslx\fR disk_pattern [***]
Like -lsx but also listing some of the file attributes.
Output format resembles shell command ls -ln.
.TP
\fB\-lsdlx\fR disk_pattern [***]
Like -lsdx but also listing some of the file attributes.
Output format resembles shell command ls -dln.
.TP
\fB\-getfacl\fR 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".
.TP
\fB\-getfacl_r\fR iso_rr_pattern [***]
Like -gefacl but listing recursively the whole file trees underneath eventual
directories.
.TP
\fB\-getfattr\fR 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.
.TP
\fB\-getfattr_r\fR iso_rr_pattern [***]
Like -gefattr but listing recursively the whole file trees underneath eventual
directories.
.TP
\fB\-du\fR 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.
.TP
\fB\-dus\fR 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.
.TP
\fB\-dux\fR 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.
.TP
\fB\-dusx\fR disk_pattern [***]
List size of directories and files in the local filesystem
which match one of the patterns.
Similar to shell command du -sk.
.TP
\fB\-findx\fR disk_path [-name pattern] [-type t] [-exec action [params]] --
Like -find but operating on local filesystem and not on the ISO image.
This is subject to the settings of -follow.
.br
Find accepts the same -type arguments as -find. Additionally it recognizes
type "mountpoint" (or "m"). It matches subdirectories which reside on a
different device than their parent. It never matches the disk_path
given as start address for -findx.
.br
-findx accepts the -exec actions as does -find. But except the following few
actions it will allways perform action "echo".
.br
"in_iso" iso_rr_path_start reports the path if its counterpart exist in
the ISO image. For this the disk_path of the -find command gets replaced
by iso_rr_path_start.  E.g.:
.br
  -findx /home -exec in_iso /
.br
"not_in_iso" iso_rr_path_start reports the path if its counterpart does
not exist in the ISO image. The report format is the same as with command
-compare.
E.g.
.br
  -findx /home/thomas -exec not_in_iso /thomas_on_cd
.br
"add_missing" iso_rr_path_start adds the counterpart if it does not yet
exist in the ISO image. 
E.g.
.br
  -findx /home/thomas -exec add_missing /thomas_on_cd
.br
"is_full_in_iso" iso_rr_path_start reports if the counterpart in the ISO image
contains files. To be used with -type "m" to report mount points.
.br
"empty_iso_dir" iso_rr_path_start deletes all files from the counterpart
in the ISO image. To be used with -type "m" to truncate mount points.
.TP
\fB\-compare\fR 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.
.br
If iso_rr_path is empty then disk_path is used as path in the ISO image too.
.br
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.
.TP
\fB\-compare_r\fR 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.
.TP
\fB\-compare_l\fR 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.
.TP
.B Evaluation of readability and recovery:
.PP
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.
.br
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.
.TP
\fB\-check_media\fR [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.
.br
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.
.br
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 no valid data.
.br
Alternatively it is possible to report damaged files rather than blocks.
.TP
\fB\-check_media_defaults\fR [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.
.br
An option consists of a keyword, a "=" character, and a value. Options
may override each other. So their sequence matters.
.br
The default setting at program start is:
.br
use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
time_limit=28800 item_limit=100000
.br
abort_file=/var/opt/xorriso/do_abort_check_media
.br
data_to='' sector_map='' map_with_volid=off patch_lba0=off report=blocks
.br
Option "reset=now" restores these startup defaults.
.br
Non-default options are:
.br
"report=files" lists the files which use damaged blocks (not with use=outdev).
The format is like with find -exec report_damage.
.br
"report=blocks_files" first lists damaged blocks and then affected files.
.br
"use=outdev" reads from the output drive instead of the input drive. This
avoids loading the ISO image tree from media.
.br
"what=disc" scans the payload range of a media without respecting track gaps.
.br
"min_lba=" omits all blocks with addresses lower than the option value.
.br
"max_lba=" switches to what=disc and omits all blocks above its option value.
.br
"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. 
.br
"abort_file=" 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.
.br
"time_limit=" 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.
.br
"item_limit=" gives the number of report list items after which to abort.
Value -1 means unlimited item number.
.br
"data_to=" copies the valid blocks to the file which is given as option value.
.br
"sector_map=" tries to read the file given by option value 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.
.br
"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=.
.br
"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 loaded as stdio: drive. But it usually makes
the original session 1 inaccessible.
.br
"patch_lba0=force" performs "patch_lba0=on" even if xorriso believes
that the copied data are not valid.
.br
"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.
.br
"use=sector_map" does not read any media but loads the file given by option
sector_map= and processes this virtual outcome.
.TP
.B osirrox restore options:
.PP
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.
.br
Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply.
If disk file objects already exist then the settings of -overwrite and
-reassure apply. But -overwrite "on" only triggers the behavior
of -overwrite "nondir". I.e. directories cannot be deleted.
.br
Access permissions of files in the ISO image do not restrict restoring.
The directory permissions on disk have to allow rwx.
.TP
\fB\-osirrox\fR "on"|"device_files"|"off"[: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".
.br
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.
.br
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.
.br
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.
.br
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.
.TP
\fB\-extract\fR iso_rr_path disk_path
Restore the file objects at and underneath iso_rr_path to their corresponding
addresses at and underneath disk_path.
This is the inverse of -map or -update_r.
.br
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 restore operation.
Disk files get removed only if they are to be replaced
by file objects from the ISO image.
.br
As many attributes as possible are copied together with restored
file objects.
.TP
\fB\-extract_single\fR iso_rr_path disk_path
Like -extract, but if iso_rr_path is a directory then its sub tree gets not
restored.
.TP
\fB\-extract_l\fR 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.
.TP
\fB\-extract_cut\fR 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.
Two restrictions apply:
.br
The data bytes of iso_rr_path need to be already stored in the loaded ISO image
and byte_offset must be a multiple of 2048, e.g. an integer with suffix
s, m, or g.
.br
This option is implemented by a special run of -check_media and governed by
most of the options which can be set by -check_media_defaults.
Its main purpose 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.
.TP
\fB\-cpx\fR iso_rr_path [***] disk_path
Extract single leaf file objects from the ISO image and store them under
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.
.br
Missing directory components in disk_path will get created, if possible.
.br
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.
.TP
\fB\-cpax\fR 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.
.TP
\fB\-cp_rx\fR iso_rr_path [***] disk_path
Like -cpx but also extracting whole directory trees from the ISO image.
.br
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.
.TP
\fB\-cp_rax\fR 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.
.TP
\fB\-paste_in\fR 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.
.TP
\fB\-mount\fR 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.
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.
.TP
.B Command compatibility emulations:
.PP
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.
.TP
\fB\-as\fR personality option [options] --
.br
Perform the variable length option list as sparse emulation of the program
depicted by the personality word.
.br

Personality "\fBmkisofs\fR" accepts the options listed with:
.br
  -as mkisofs -help --
.br
Among them: -R (always on), -J, -o, -M, -C, -path-list, -m, -exclude-list,
-f, -print-size, -pad, -no-pad, -V, -v, -version, -graft-points,
-no-emul-boot, -b, -c, -boot-info-table, -boot-load-size, -input-charset,
-output-charset, pathspecs as with xorriso -add.
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.
.br
-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.
.br
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.
.br
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 or after -as mkisofs.
Directories and symbolic links are no valid -o targets.
.br
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.
.br
Not original mkisofs options are --quoted_path_list (see -quoted_path_list),
isolinux_mbr= (see -boot_image isolinux isohybrid=), --acl (see -acl "on"),
--xattr (see -xattr "on").
.br
Personalites "\fBxorrisofs\fR", "\fBgenisoimage\fR", and "\fBgenisofs\fR"
are aliases for "mkisofs".
.br
If xorriso is started with one of the leafnames "xorrisofs", "genisofs",
"mkisofs", or "genisoimage", then it automatically prepends -as "genisofs"
to the command line arguments. I.e. all arguments will be interpreted mkisofs
style until "--" is encountered. From then on, options are interpreted
as xorriso options.
.br

Personality "\fBcdrecord\fR" accepts the options listed with:
.br
  -as cdrecord -help --
.br
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.
.br
It ignores most other options of cdrecord and cdrskin but refuses on
-audio, -scanbus, and on blanking modes unknown to xorriso.
.br
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.
.br
An eventually aquired input drive is given up.
This is only allowed if no image changes are pending.
.br
dev= must be given as xorriso device address. Adresses like 0,0,0 or ATA:1,1,0
are not supported.
.br
If a track source is given, then an automatic -commit happens at the end of
the "cdrecord" option list.
.br
--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.
.br
A much more elaborate libburn based cdrecord emulator is the program cdrskin.
.br
Personalites  "\fBxorrecord\fR", "\fBwodim\fR", and "\fBcdrskin\fR" are aliases
for "cdrecord".
.br
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.
.TP
\fB\-pacifier\fR behavior_code
Control behavior of UPDATE pacifiers during write operations.
The following behavior codes are defined:
.br
"xorriso" is the default format:
.br
Writing: sector XXXXX of YYYYYY  [fifo active, nn% fill]
.br
"cdrecord" looks like:
.br
X of Y MB written (fifo nn%) [buf mmm%]
.br
"mkisofs" 
.br
nn% done, estimate finish Tue Jul 15 20:13:28 2008
.TP
.B Scripting, dialog and program control features:
.TP
\fB\-no_rc\fR
.br
Only if used as first command line argument this option
prevents reading and interpretation of eventual startup
files. See section FILES below.
.TP
\fB\-options_from_file\fR fileaddress
Read quoted input from fileaddress and executes it like dialog lines.
.TP
\fB\-help\fR
.br
Print helptext.
.TP
\fB\-version\fR
Print program name and version.
.TP
\fB\-history\fR textline
Copy textline into libreadline history.
.TP
\fB\-status\fR [mode|filter]
Print the current settings of xorriso.
Modes:
.br
  short... print only important or altered settings
.br
  long ... print all settings including defaults
.br
  long_history  like long plus history lines
.br
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.
.TP
\fB\-status_history_max\fR number
Set maximum number of history lines to be reported with -status "long_history".
.TP
\fB\-list_delimiter\fR 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.
.br
For brevity the list delimiter is referred as "--" throughout this text.
.TP
\fB\-backslash_codes\fR "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:
.br
 \\a=bell(007) \\b=backspace(010) \\e=Escape(033) \\f=formfeed(014)
.br
 \\n=linefeed(012) \\r=carriage_return(015) \\t=tab(011)
.br
 \\v=vtab(013) \\\\=backslash(134) \\[0-7][0-7][0-7]=octal_code
.br
 \\\\x[0-9a-f][0-9a-f]=hex_code \\cC=control-C
.br
Translations can occur with quoted input in 3 modes:
.br
 "in_double_quotes" translates only inside " quotation.
.br
 "in_quotes" translates inside " and ' quotation.
.br
 "with_quoted_input" translates inside and outside quotes.
.br
With the start program arguments there is mode:
.br
 "with_program_arguments" translates all program arguments.
.br
.br
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).
.br
Mode "off" is default and disables any translation.
Mode "on" is
"with_quoted_input:with_program_arguments:encode_output".
.TP
\fB\-temp_mem_limit\fR number["k"|"m"]
Set the maximum size of temporary memory to be used for image dependent
buffering. Currently this applies to pattern expansion only.
.br
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB.
.TP
\fB\-print\fR  text
Print a text to result channel.
.TP
\fB\-prompt\fR 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.
.TP
\fB\-errfile_log\fR mode path|channel
.br
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.
.br
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.
.br
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.
.br
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.
.br
The errfile paths are transported as messages of very low priority "ERRFILE".
This transport becomes visible with -report_about "ALL".
.TP
\fB\-session_log\fR 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.
.br
Record format is: timestamp start_lba size volume-id
.br
The first three items are single words, the rest of the line is the volume id.
.TP
\fB\-end\fR
.br
End program immediately
.TP
\fB#\fR any text
In dialog or file execution mode only and only as first
non-whitespace in line:
Do not execute the line but eventually store it in history.
.TP
.B Support for frontend programs talking into stdin and listening at stdout:
.TP
\fB\-pkt_output\fR "on"|"off"
Consolidate text output on stdout and classify each
line by a channel indicator:
.br
 'R:' for result lines,
.br
 'I:' for notes and error messages,
.br
 'M:' for -mark texts.
.br
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.
.br
Example:
.br
 I:1: enter option and arguments :
.TP
\fB\-logfile\fR channel fileaddress
Copy output of a channel to the given file.
.TP
\fB\-mark\fR text
If text is not empty it will get put out each time an
action has been completed.
.TP
\fB\-prog\fR text
Use text as this program's name in subsequent messages
.TP
\fB\-prog_help\fR text
Use text as this program's name and perform -help.
.br
.SH EXAMPLES
.SS
.B Overview of examples:
As superuser learn about available drives
.br
Blank media and compose a new ISO image as batch run
.br
A dialog session doing about the same
.br
Manipulating an existing ISO image on the same media
.br
Copy modified ISO image from one media to another
.br
Bring a prepared ISOLINUX tree onto media and make it bootable
.br
Change existing file name tree from ISO-8859-1 to UTF-8
.br
Operate on storage facilities other than optical drives
.br
Perform multi-session runs as of cdrtools traditions
.br
Let xorriso work underneath growisofs
.br
Adjust thresholds for verbosity, exit value and program abort
.br
Examples of input timestrings
.br
Incremental backup of a few directory trees
.br
Restore directory trees from a particular ISO session to disk
.br
Try to retrieve as many blocks as possible from a damaged media
.SS
.B As superuser learn about available drives
Consider to give rw permissions to those users or groups
which shall be able to use the drives with xorriso.
.br
\fB$\fR xorriso -devices
.br
0  -dev '/dev/sr0' rwrw-- :  '_NEC    ' 'DVD_RW ND-4570A'
.br
1  -dev '/dev/sr1' rwrw-- :  'HL-DT-ST' 'DVDRAM GSA-4082B' 
.br
2  -dev '/dev/sr2' rwrw-- :  'PHILIPS ' 'SPD3300L' 
.SS
.B Blank media and compose a new ISO image as batch run
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.
.br
Because no -dialog "on" is given, the program will then end by writing the
session to media.
.br
\fB$\fR xorriso -outdev /dev/sr2 \\
.br
 -blank as_needed \\
.br
 -map /home/me/sounds /sounds \\
.br
 -map /home/me/pictures /pictures
.br

.br
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.
Re-add some wanted stuff.
.br
\fB$\fR cd /home/me
.br
\fB$\fR xorriso -outdev /dev/sr2 \\
.br
 -blank as_needed \\
.br
 -map /home/me/sounds /sounds \\
.br
 -map /home/me/pictures /pictures \\
.br
 -rm_r \\
.br
   /sounds/indecent \\
.br
   '/pictures/*private*' \\
.br
   /pictures/confidential \\
.br
   -- \\
.br
 -cd / \\
.br
 -add pictures/confidential/work*
.br
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.
.SS
.B A dialog session doing about the same
.br
-pathspecs is already given as start argument. The other activities
are done as dialog input. The pager gets set to 20 lines of 80 characters.
.br
The drive is aquired 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.
.br
In order to be able to eject the media, the session needs to be committed
explicitely.
.br
.B $ xorriso -dialog on -page 20 80 -disk_pattern on
.br
enter option and arguments :
.br
.B \-dev /dev/sr2
.br
enter option and arguments :
.br
.B \-blank as_needed
.br
enter option and arguments :
.br
.B \-map /home/me/sounds /sounds -map /home/me/pictures /pictures
.br
enter option and arguments :
.br
.B \-rm_r /sounds/indecent /pictures/*private* /pictures/confidential
.br
enter option and arguments :
.br
.B \-cdx /home/me/pictures -cd /pictures
.br
enter option and arguments :
.br
.B \-add confidential/office confidential/factory
.br
enter option and arguments :
.br
.B \-du /
.br
enter option and arguments :
.br
.B \-commit -eject all -end
.br
.SS
.B Manipulating an existing ISO image on the same media
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 and eject.
.br
\fB$\fR xorriso -dev /dev/sr2 \\
.br
 -rm_r /sounds -- \\
.br
 -mv \\
.br
   /pictures/confidential \\
.br
   /pictures/restricted \\
.br
   -- \\
.br
 -chmod go-rwx /pictures/restricted -- \\
.br
 -map /home/me/prepared_for_dvd/sounds_dummy /sounds \\
.br
 -map /home/me/prepared_for_dvd/movies /movies \\
.br
 -commit -eject all
.SS
.B Copy modified ISO image from one media to another
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.
.br
\fB$\fR xorriso -indev /dev/sr2 \\
.br
 -rm_r /sounds -- \\
.br
 ...
.br
 -outdev /dev/sr0 -blank as_needed \\
.br
 -commit -eject all
.SS
.B Bring a prepared ISOLINUX tree onto media and make it bootable
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:
.br
\fB$\fR xorriso -outdev /dev/sr0 -blank as_needed \\
.br
   -map /home/me/ISOLINUX_prepared_tree / \\
.br
   -boot_image isolinux dir=/boot/isolinux
.SS
.B Change existing file name tree from ISO-8859-1 to UTF-8
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.
.br
\fB$\fR xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \\
.br
   -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \\
.br
   -alter_date m +0 / -- -commit -eject all
.SS
.B Operate on storage facilities other than optical drives
Full read-write operation is possible with regular files and block devices:
.br
\fB$\fR xorriso -dev /tmp/regular_file ...
.br
Paths underneath /dev normally need prefix "stdio:"
.br
\fB$\fR xorriso -dev stdio:/dev/sdb ...
.br
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 your disk from xorriso:
.br
  -drive_class banned   /dev/sda*
  -drive_class harmless /dev/sdb
.br
Other writeable file types are supported write-only:
.br
\fB$\fR xorriso -outdev /tmp/named_pipe ...
.br
Among the write-only drives is standard output:
.br
\fB$\fR xorriso -outdev - \\
.br
 ...
.br
 | gzip >image.iso.gz
.SS
.B Perform multi-session runs as of cdrtools traditions
Between both processes there can be performed arbitrary transportation
or filtering.
.br
The first session is written like this:
.br
\fB$\fR xorriso -as mkisofs prepared_for_iso/tree1 | \\
.br
 xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - 
.br
Follow-up sessions are written like this:
.br
\fB$\fR m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
.br
\fB$\fR xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \\
.br
 xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
.br
Always eject the drive tray between sessions. The old sessions
get read via stdio:/dev/sr0 and thus are prone to device driver
peculiarities.
.br
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.
.SS
.B 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.
.br
\fB$\fR export MKISOFS="xorrisofs"
.br
\fB$\fR growisofs -Z /dev/dvd /some/files
.br
\fB$\fR growisofs -M /dev/dvd /more/files
.br
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:
.br
\fB$\fR ln -s $(which xorriso) "$HOME/xorrisofs"
.br
\fB$\fR export MKISOFS="$HOME/xorrisofs"
.br
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:
.br
\fB$\fR growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
.br 
\fB$\fR growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
.br
growisofs has excellent burn capabilities with DVD and BD.
It does not emulate session history on overwriteable media, though.
.SS
.B Adjust thresholds for verbosity, exit value and program abort
Be quite verbous, exit 32 if severity "FAILURE" was encountered,
do not abort prematurely but forcibly go on until the end of commands.
.br
\fB$\fR xorriso ... \\
.br
 -report_about UPDATE \\
.br
 -return_with FAILURE 32 \\
.br
 -abort_on NEVER \\
.br
 ...
.SS
.B Examples of input timestrings
.br
As printed by program date:
.B 'Thu Nov  8 14:51:13 CET 2007'
.br
The same without ignored parts:
.B 'Nov 8 14:51:13 2007'
.br
The same as expected by date:
.B 110814512007.13
.br
Four weeks in the future:
.B +4w
.br
The current time:
.B +0
.br
Three hours ago:
.B \-3h
.br
Seconds since Jan 1 1970:
.B =1194531416
.SS
.B Incremental backup of a few directory trees
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.
.br
ACL and xattr 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 explicitely.
.br
\fB$\fR xorriso \\
.br
 -acl on -xattr on -disk_dev_ino on \\
.br
 -assert_volid 'PROJECTS_MAIL_*' FATAL \\
.br
 -dev /dev/sr0 \\
.br
 -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \\
.br
 -not_leaf '*.o' -not_leaf '*.swp' \\
.br
 -update_r /home/thomas/open_source_projects /open_source_projects \\
.br
 -update_r /home/thomas/personal_mail /personal_mail \\
.br
 -commit -toc -eject all
.br
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 fails due to lack of remaining space on
the old one.
.br
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.
.br
Option -disk_dev_ino depends on stable device and inode numbers on disk.
Without it, an update run will probably save no time but last longer than
a full backup. Such a slow run might produce a smaller backup, though.
.br 
With \fBmount\fR option \fB-o "sbsector="\fR on Linux resp. \fB-s\fR on FreeBSD
it is possible to access the session trees which represent the older backup
versions. With CD media, Linux mount accepts session numbers directly by
its option "session=".
.br
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):
.br
 -mount_cmd "indev" "auto" "auto" /mnt
.br
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:
.br
 \fB#\fR osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
.br
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.
.br
\fBBetter do not use your youngest backup for -update_r\fR.
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.
.SS
.B Restore directory trees from a particular ISO session to disk
This is an alternative to mounting the media and using normal file operations.
.br
First check which backup sessions are on the media:
.br
\fB$\fR xorriso -outdev /dev/sr0 -toc
.br
Then load the desired session and copy the file trees to disk.
Avoid to eventually create /home/thomas/restored without rwx-permission.
.br
\fB$\fR xorriso -acl on -xattr on \\
.br
 -load volid 'PROJECTS_MAIL_2008_06_19*' \\
.br
 -indev /dev/sr0 \\
.br
 -osirrox on:auto_chmod_on \\
.br
 -chmod u+rwx / -- \\
.br
 -extract /open_source_projects \\
.br
          /home/thomas/restored/open_source_projects \\
.br
 -extract /personal_mail /home/thomas/restored/personal_mail \\
.br
 -rollback_end
.SS
.B Try to retrieve as many blocks as possible from a damaged media
.br
\fB$\fR xorriso -abort_on NEVER -indev /dev/sr0 \\
.br
 -check_media time_limit=1800 report=blocks_files \\
.br
 data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map --
.br
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.
.br
If you want to make the newest session the default mount session, you
may add option "patch_lba0=on" to the final -check_media run.
.SH FILES
.SS 
.B Startup files:
.br
If not -no_rc is given as the first argument then xorriso attempts on startup
to read and execute lines from the following files:
.br
   /etc/default/xorriso
.br
   /etc/opt/xorriso/rc
.br
   /etc/xorriso/xorriso.conf
.br
   $HOME/.xorrisorc
.br
The files are read in the sequence given above, but none of them is required
for xorriso to function properly.
.SS
.B Runtime control files:
.br
The default setting of -check_media abort_file= is:
.br
   /var/opt/xorriso/do_abort_check_media
.br
.SH SEE ALSO
.TP
For mounting xorriso generated ISO 9660 images
.br
.BR mount(8)
.TP
Libreadline, a comfortable input line facility
.BR readline(3)
.TP
Other programs which produce ISO 9660 images
.br
.BR mkisofs(8),
.BR genisoimage(8)
.TP
Other programs which burn sessions to optical media
.BR growisofs(1),
.BR cdrecord(1),
.BR wodim(1),
.BR cdrskin(1) 
.TP
ACL and xattr
.BR getfacl(1),
.BR setfacl(1),
.BR getfattr(1),
.BR setfattr(1)
.br
.SH AUTHOR
Thomas Schmitt <scdbackup@gmx.net>
.br
for libburnia-project.org
.SH 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 emulated growing,
to Derek Foreman and Ben Jansens who once founded libburn.
.br
Compliments towards Joerg Schilling whose cdrtools served me for ten years.