libisoburn/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 "Jun, 14, 2008"
.\" 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 or DVD 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
Can write result as completely new image to optical media or
filesystem objects.
.br
Can write result as add-on session to appendable multi-session media, 
to overwriteable media, to regular files, and to block devices.
.br
Can restore files from ISO image to disk filesystem (see osirrox).
.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
.br
Libburn drives
.br
Rock Ridge, POSIX, X/Open
.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.
.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 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\fR media 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\fR media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
They allow random write access but do not provide information about their
session history. If they contain one or more ISO 9660 sessions and if the
first session was written by xorriso, then a table of content can
be emulated. Else only a single overall session will be visible.
.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 unless they contain an ISO image
suitable for xorriso. Action -blank "as_needed" can be used to invalidate the
image on overwriteable media, or to apply eventual mandatory formatting.
.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
\fBRead-only\fR 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:
.br
A new empty ISO image gets \fBcreated\fR
if there is no input drive with a valid
ISO 9660 image plus Rock Ridge extensions 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 of two write methods 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
Modifying takes place whenever input drive and output drive are not the same.
This is achieved by options -indev and -outdev.
.br
So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target media.
.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.
.br
Rock Ridge info must be present in existing ISO images and it will be generated
by the program unconditionally.
.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 method
of modifying. 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
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:/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.
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 a single new 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. Addresses without prefix
"stdio:" will only work if they lead to a MMC drive.
.br
One may use option
.B -ban_stdio_write
to surely prevent this risk and to allow only MMC drives.
.SS
.B Rock Ridge, POSIX, X/Open:
.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 and xorriso will load for manipulation only Rock Ridge enhanced images.
.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.
.SS
.B Command processing:
.br
Commands are either actions or settings. They 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 word "--" or the end of argument list or an end of
an input line.
It is not an error if "--" appears after the parameters of a command
with a fixed list length.
.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 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
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 an 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
of 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. 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. 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 -add 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\-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 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\-rom_toc_scan\fR "on"|"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.
.br
To be in effect, -rom_toc_scan has to be enabled by "on" 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. Directories can hardly collide on renaming because
of the shell-like behavior of -mv: if a file object hits an existing directory
then it gets inserted rather than trying to replace that directory.
Nevertheless, the overwriting rules apply if an operation of xorriso
ever attempts to do such a replacement.
.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\-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\-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.
.br
-update_r is also a convenient compromise between -add addressing and -cpr
addressing: Its semantics is similar to -add and thus avoids the pitfalls
inherited from cp -r behavior. Its syntax resembles cp, though.
.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.
.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\-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 [-name pattern] [-type t] [-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
Optional -name pattern is not expanded but used for comparison with
the particular file names of the eventual directory tree underneath
iso_rr_path. If no -name pattern is given, then any file name matches.
.br
The optional -type test restricts matching to files of the given type:
"block", "char", "dir", "pipe", "file", "link", "socket",
"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
If a file matches then the action is performed. 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
"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\-\-\fR
.br
Mark end of particular action argument list.
.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 from eventual modifiying mode to growing mode.
(A subsequent -outdev will activate modification mode.)
-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 or BD-RE.
.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, 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. Other media
are left untouched.
.br
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE.
.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
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-formatting might help or not),
.br
 DVD-RAM or BD-RE shall change their amount of defect reserve.
.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