libisoburn/xorriso/xorriso.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorriso.info
@settitle GNU xorriso
@c %**end of header
@c
@c man-ignore-lines begin
@dircategory Archiving
@direntry
* Xorriso: (xorriso).           Burns ISO 9660 on CD, DVD, BD.
@end direntry
@c man-ignore-lines end
@c
@c Notes about embedded man page:
@c This texinfo code contains the necessary info to produce a man page
@c which resembles much the version of xorriso.1 from which this code
@c was originally derived in march 2010.
@c One can produce the man page by applying the following rules:
@c   The first line gets discarded.
@c   Line start "@c man " will become "", the remainder is put out unaltered. 
@c   Lines "@*" will be converted to ".br"
@c   "@c man-ignore-lines N"  will discard N following lines.
@c   "@c man-ignore-lines begin" discards all following lines
@c   up to "@c man-ignore-lines end".
@c   Line blocks of "@menu" "@end menu" will be discarded.
@c   "@item -word words" becomes "\fB\-word\fR words".
@c   "@item word words" becomes "\fBword\fR words".
@c   @strong{-...} gets mapped to \fB\-...\fR .
@c   @strong{...} gets mapped to \fB...\fR .
@c   @minus{} will become "-".
@c   @@ , @{, @} will get stripped of their first @.
@c   Other lines which begin by "@" will be discarded.
@c   In lines not stemming from "@c man", "\" becomes "\\"
@c
@c
@c man .\"                                      Hey, EMACS: -*- nroff -*-
@c man .\"
@c man .\" IMPORTANT NOTE:
@c man .\"
@c man .\"        The original of this file is kept in xorriso/xorriso.texi
@c man .\"        This here was generated by program xorriso/make_xorriso_1
@c man .\"
@c man .\"
@c man .\" First parameter, NAME, should be all caps
@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
@c man .\" other parameters are allowed: see man(7), man(1)
@c man .TH XORRISO 1 "Oct 15, 2010"
@c man .\" Please adjust this date whenever revising the manpage.
@c man .\"
@c man .\" Some roff macros, for reference:
@c man .\" .nh        disable hyphenation
@c man .\" .hy        enable hyphenation
@c man .\" .ad l      left justify
@c man .\" .ad b      justify to both left and right margins
@c man .\" .nf        disable filling
@c man .\" .fi        enable filling
@c man .\" .br        insert line break
@c man .\" .sp <n>    insert n+1 empty lines
@c man .\" for manpage-specific macros, see man(7)
@c man .nh
@c man-ignore-lines begin
@copying
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions.

Copyright @copyright{} 2007 - 2010 Thomas Schmitt

@quotation
Permission is granted to distrubute this text freely.
@end quotation
@end copying
@c man-ignore-lines end
@titlepage
@title Manual of GNU xorriso
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU xorriso
@c man-ignore-lines 1

@c man .SH NAME
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions.
@end ifnottex
@menu
* Overview::            Overview
* Model::               Session model
* Media::               Media types and states
* Methods::             Creating, Growing, Modifying, Blind Growing
* Drives::              Libburn drives
* Extras::              Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
* Processing::          Command processing
* Dialog::              Dialog, Readline, Result pager
* Options::             Reference of commands
* Examples::            Examples
* Files::               Files
* Seealso::             See also
* Legal::               Author, Copyright, Credits
* CommandIdx::          Alphabetic Command List
* ConceptIdx::          Alphabetic List of Concepts and Objects
@end menu
@node Overview, Model, Top, Top
@chapter Overview
@c man .SH SYNOPSIS
@c man .B xorriso
@c man .RI [ settings | actions ]
@c man .br
@c man .SH DESCRIPTION
@c man .PP
@strong{xorriso}
is a program which copies file objects from POSIX compliant
filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows
session-wise manipulation of such filesystems. It can load the management
information of existing ISO images and it writes the session results to
optical media or to filesystem objects.
@*
Vice versa xorriso is able to copy file objects out of ISO 9660 filesystems.
@c man .PP
@sp 1
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 .
@c man .SS
@section Features
@c man .B Overview of features:
@*
Operates on an existing ISO image or creates a new one.
@*
Copies files from disk filesystem into the ISO image.
@*
Copies files from ISO image to disk filesystem (see osirrox).
@*
Renames or deletes file objects in the ISO image.
@*
Changes file properties in the ISO image.
@*
Updates ISO subtrees incrementally to match given disk subtrees.
@*
Writes result either as completely new image or as add-on session
to optical media or filesystem objects.
@*
Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
@*
Can perform multi-session tasks as emulation of mkisofs and cdrecord.
@*
Can record and restore hard links and ACL.
@*
Content may get zisofs compressed or filtered by external processes.
@*
Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
@*
Can check media for damages and copy readable blocks to disk.
@*
Can attach MD5 checksums to each data file and the whole session.
@*
Scans for optical drives, blanks re-useable optical media.
@*
Reads its instructions from command line arguments, dialog, and files.
@*
Provides navigation commands for interactive ISO image manipulation.
@*
Adjustable thresholds for abort, exit value, and problem reporting.
@c man .SS
@c man .B General information paragraphs:
@c man .br
@c man Session model
@c man .br
@c man Media types and states
@c man .br
@c man Creating, Growing, Modifying, Blind Growing
@c man .br
@c man Libburn drives
@c man .br
@c man Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
@c man .br
@c man Command processing
@c man .br
@c man Dialog, Readline, Result pager
@c man .sp 1
@c man Maybe you first want to have a look at section EXAMPLES near the end of
@c man this text before reading the next few hundred lines of background information.
@c man .SS
@node Model, Media, Overview, Top
@chapter Session model
@c man \fBSession model:\fR
@c man .br
@cindex Session, _definition
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
@strong{session}.
@*
@cindex Image, _definition
The data content of the session is called filesystem @strong{image}.
@c man .PP
@sp 1
The written image in its session can then be mounted by the operating system
for being used read-only. GNU/Linux is able to mount ISO images from block
devices, which may represent optical media, other media or via a loop device
even from regular disk files. FreeBSD mounts ISO images from devices that
represent arbitrary media or from regular disk files.
@c man .PP
@sp 1
@cindex Multi-session, _definition
This session usage model has been extended on CD media by the concept of
@strong{multi-session} ,
which allows to add information to the CD and gives the mount programs
of the operating systems the addresses of the entry points of each
session. The mount programs recognize block devices which represent
CD media and will by default mount the image in the last session.
@*
This session usually contains an updated directory tree for the whole media
which governs the data contents in all recorded sessions.
So in the view of the mount program all sessions of a particular media
together form a single filesystem image.
@*
Adding a session to an existing ISO image is in this text referred as
@strong{growing}.
@*
The multi-session model of the MMC standard does not apply to all media
types. But program growisofs by Andy Polyakov showed how to extend this
functionality to overwriteable media or disk files which carry valid ISO 9660
filesystems.
@c man .PP
@sp 1
xorriso provides growing as well as an own method named
@strong{modifying} which produces a completely new ISO image from the old
one and the modifications.
See paragraph Creating, Growing, Modifying, Blind Growing below.
@c man .PP
@sp 1
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.
@c man .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.
@c man .PP
@sp 1
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.
@c man .PP
@sp 1
Writing a session to the target is supposed to be very expensive in terms of
time and of consumed space on appendable or write-once media. Therefore all
intended manipulations of a particular ISO image should be done in a single
session. But in principle it is possible
to store intermediate states and to continue with image manipulations.
@c man .SS
@node Media, Methods, Model, top
@chapter Media types and states
@c man .B Media types and states:
There are two families of media in the MMC standard:
@*
@cindex Multi-session media, _definition
@strong{Multi-session media} are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and
unformatted DVD-RW. These media provide a table of content which
describes their existing sessions. See option @strong{-toc}.
@*
Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW.
They allow only a single session of which the size must be known in advance.
xorriso will write onto them only if option -close is set to "on".
@*
@cindex Overwriteable media, _definition
@strong{Overwriteable media} are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
They allow random write access but do not provide information about their
session history. If they contain one or more ISO 9660 sessions and if the
first session was written by xorriso, then a table of content can
be emulated. Else only a single overall session will be visible.
@*
DVD-RW media can be formatted by -format "full". 
They can be made unformatted by -blank "deformat".
@*
Regular files and block devices are handled as overwriteable media.
Pipes and other writeable file types are handled as blank multi-session media.
@c man .PP
@sp 1
These media can assume several states in which they offer different
capabilities.
@*
@sp 1
@cindex Blank media, _definition
@strong{Blank} media can be written from scratch. They contain no ISO image
suitable for xorriso.
@*
Blank is the state of newly purchased optical media.
With used CD-RW and DVD-RW it can be achieved by action -blank "as_needed".
Overwriteable media are considered blank if they are new or if they have
been marked as blank by xorriso.
Action -blank "as_needed" can be used to do this marking on overwriteable
media, or to apply eventual mandatory formatting to new media.
@*
@sp 1
@cindex Appendable media, _definition
@strong{Appendable} media accept further sessions. Either they are MMC
multi-session media in appendable state, or they are overwriteable media
which contain an ISO image suitable for xorriso.
@*
Appendable is the state after writing a session with option -close off.
@*
@sp 1
@cindex Closed media, _definition
@strong{Closed} media cannot be written. They may contain an ISO image suitable
for xorriso.
@*
Closed is the state of DVD-ROM media and of multi-session media which were
written with option -close on. If the drive is read-only hardware then it will
probably show any media as closed CD-ROM resp. DVD-ROM.
@*
Overwriteable media assume this state in such read-only drives or if they
contain unrecognizable data in the first 32 data blocks.
@*
Read-only drives may or may not show session histories of multi-session
media. Often only the first and the last session are visible. Sometimes
not even that. Option -rom_toc_scan might or might not help in such cases.
@c man .SS
@node Methods, Drives, Media, top
@chapter Creating, Growing, Modifying, Blind Growing:
@c man .B Creating, Growing, Modifying, Blind Growing:
@*
@cindex Create, new ISO image, _definiton
A new empty ISO image gets @strong{created}
if there is no input drive with a valid ISO 9660 image when the first time
an output drive is defined. This is achieved by option -dev on blank media
or by option -outdev on media in any state.
@*
The new empty image can be populated with directories and files.
Before it can be written, the media in the output drive must get into
blank state if it was not blank already.
@c man .PP
@sp 1
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.
@c man .PP
@sp 1
@cindex Growing, _definition
The method of @strong{growing} adds new data to the existing media. These
data comprise of eventual new file content and they override the existing
ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
previous sessions but they still exist on media and with many types of
optical media it is quite easy to recover them by mounting older sessions.
@*
Growing is achieved by option -dev.
@c man .PP
@sp 1
@cindex Modifying, _definition
The write method of @strong{modifying} 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,
DVD-R DL, named pipes, character devices, sockets.
On the other hand modified sessions cannot be written to appendable media
but to blank media only.
@*
So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target media.
@*
Modifying takes place if input drive and output drive are not the same and
if option -grow_blindly is set to its default "off".
This is achieved by options -indev and -outdev.
@c man .PP
@sp 1
@cindex Blind growing, _definition
If option -grow_blindly is set to a non-negative number and if -indev and
-outdev are both set to different drives, then @strong{blind growing} is
performed. It produces an add-on session which is ready for being written
to the given block address. This is the usage model of
@*
 mkisofs -M $indev -C $msc1,$msc2 -o $outdev
@*
which gives much room for wrong parameter combinations and should thus only be
employed if a strict distinction between ISO formatter xorriso and the burn
program is desired. -C $msc1,$msc2 is equivalent to:
@*
 -load sbsector $msc1 -grow_blindly $msc2
@c man .SS
@node Drives, Extras, Methods, top
@chapter Libburn drives
@c man .B Libburn drives:
@c man .br
@cindex Drive, _definiton
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.
@c man .PP
@sp 1
Output drive, i.e. target for writing, can be any libburn drive.
Some drive types do not support the method of growing but only the methods
of modifying and blind growing. They all are suitable for newly created images.
@*
All drive file objects have to offer rw-permission to the user of xorriso.
Even those which will not be useable for reading an ISO image.
@c man .PP
@sp 1
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by
the path of their block device or of their generic character device. E.g.
@*
  -dev /dev/sr0
@*
  -dev /dev/hdc
@*
  -dev /dev/sg2
@*
On FreeBSD the device files have names like
@*
  -dev /dev/cd0
@*
On OpenSolaris:
@*
  -dev /dev/rdsk/c4t0d0s2
@*
Get a list of accessible drives by command
@*
  -devices
@*
It might be necessary to do this as
@strong{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".
@c man .PP
@sp 1
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and
their path in the filesystem. E.g.:
@*
  -dev stdio:/dev/sdc
@*
The default setting of -drive_class allows to address files outside the
/dev tree without that prefix. E.g.:
@*
  -dev /tmp/pseudo_drive
@*
If path leads to a regular file or to a block device then the emulated drive
is random access readable and can be used for the method of growing if it
already contains a valid ISO 9660 image. Any other file type is not readable
via "stdio:" and can only be used as target for the method of modifying or
blind growing.
Non-existing paths in existing directories are handled as empty regular files.
@c man .PP
@sp 1
A very special kind of pseudo drive are open file descriptors. They are
depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
@*
Addresses "-" or "stdio:/dev/fd/1" depict standard output, which normally is
the output channel for result texts.
To prevent a fatal intermingling of ISO image and text messages, all result
texts get redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among
the start arguments of the program.
@*
Standard output is currently suitable for creating one session
per program run without dialog. Use in other situations is discouraged
and several restrictions apply: 
@*
It is not allowed to use standard output as pseudo drive if it was not
among the start arguments. Do not try to fool this ban via backdoor addresses
to stdout.
@*
If stdout is used as drive, then -use_readline is permanently disabled.
Use of backdoors can cause severe memory and/or tty corruption.
@c man .PP
@sp 1
Be aware that especially the superuser can write into any accessible file or
device by using its path with the "stdio:" prefix. By default any address
in the /dev tree without prefix "stdio:" will work only if it leads to a MMC
drive.
@*
One may use option
@strong{-ban_stdio_write}
to surely prevent this risk and to allow only MMC drives.
@*
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
@c man .br
By option -drive_class one may ban certain paths or allow access without
prefix "stdio:" to other paths.
@c man .SS
@node Extras, Processing, Drives, top
@chapter Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
@c man .B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
@c man .br
@cindex Rock Ridge, _definiton
@strong{Rock Ridge}
is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
@*
This is what xorriso uses for a decent representation of the disk files
within the ISO image. Rock Ridge information is produced with any xorriso
image.
@c man .PP
@sp 1
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.
@c man .PP
@sp 1
@cindex El Torito, _definiton
An @strong{El Torito}
boot record connects one or more boot images, which are binary program files
stored in the ISO image, with the bootstrapping facility of
contemporary computers.
The content of the boot image files is not in the scope of El Torito.
@*
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.
xorriso is able to create or maintain an El Torito object which makes such
an image bootable. For details see option -boot_image.
@*
@cindex MBR, _definiton
It is possible to make ISO images bootable from USB stick or other
hard-disk-like media by -boot_image argument system_area= . This installs
a Master Boot Record which may get adjusted according to the needs
of GRUB resp. ISOLINUX.
An @strong{MBR} contains boot code and a partition table. It does not hamper
CDROM booting. The new MBR of a follow-up session can get in effect
only on overwriteable media.
@*
Emulation -as mkisofs supports the example options out of the ISOLINUX wiki,
the options used in GRUB script grub-mkrescue, and the example in the
FreeBSD AvgLiveCD wiki.
@*
The support for other boot image types is sparse.
@*
@c man .PP
@sp 1
@cindex ACL, _definiton
@strong{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
@strong{-acl}.
@*
AAIP enhanced images are supposed to be mountable normally, but one cannot
expect that the mounted filesystem will show and respect the eventual ACLs.
For now, only xorriso is able to retrieve those ACLs. It can bring them into
effect when files get restored to an ACL enabled file system or it can
print them in a format suitable for tool setfacl.
@*
Files with ACL show as group permissions the setting of entry "mask::" if
that entry exists. Nevertheless the non-listed group members get handled
according to entry "group::". xorriso brings "group::" into effect before
eventually removing the ACL from a file.
@c man .PP
@sp 1
@cindex xattr, _definiton
@strong{xattr} (aka EA)
are pairs of name and value which can be attached to file objects. AAIP is
able to represent them and xorriso allows to record and restore pairs which
have names out of the user namespace. I.e. those which begin with "user.",
like "user.x" or "user.whatever". Name has to be a 0 terminated string.
Value may be any array of bytes which does not exceed the size of 4095 bytes.
xattr processing happens only if it is enabled by option
@strong{-xattr}.
@*
As with ACL, currently only xorriso is able to retrieve xattr from AAIP
enhanced images, to restore them to xattr capable file systems, or to print
them. 
@c man .SS
@node Processing, Dialog, Extras, top
@chapter Command processing
@c man .B Command processing:
@c man .br
Commands are either actions which happen immediately or settings which
influence following actions. So their sequence does matter.
@*
@cindex List delimiter, _definiton
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 @strong{list delimiter}, or the end of argument list,
or an end of an input line.
@c man .PP
@sp 1
At program start the list delimiter is the word "@minus{}@minus{}".
This may be changed by option -list_delimiter in order to allow
"@minus{}@minus{}" as argument in a list of variable length.
It is advised to reset the delimiter to "@minus{}@minus{}" immediately
afterwards.
@*
For brevity the list delimiter is referred as "@minus{}@minus{}"
throughout this text.
@*
The list delimiter is silently tolerated if it appears after the parameters of
a command with a fixed list length. It is handled as normal text if it
appears among the arguments of such a command.
@c man .PP
@sp 1
@cindex Pattern expansion, _definition
@strong{Pattern expansion}
converts a list of pattern words into a list of existing file addresses.
Eventual unmatched pattern words appear themselves in that result list, though.
@*
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]'
and respects '/' as separator which may only be matched literally.
@*
It is a property of some particular commands and not a general
feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern.
Commands which eventually use pattern expansion all have variable argument
lists which are marked in this man page by "[***]" rather than "[...]".
@*
Some other commands perform pattern matching unconditionally.
@c man .PP
@sp 1
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.
@*
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.
@c man .PP
@sp 1
@cindex Quoted input, _definiton
@strong{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.
@*
@cindex Backslash Interpretation, _definition
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
@strong{Backslash Interpretation}
which can represent all ASCII characters except NUL (0) by backslash codes
as in $'...' of bash.
@*
It is not enabled by default. See option -backslash_codes.
@c man .PP
@sp 1
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.
@c man .PP
@sp 1
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.
@c man .SS
@node Dialog, Options, Processing, top
@chapter Dialog, Readline, Result pager
@c man .B Dialog, Readline, Result pager:
@c man .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.
@c man .PP
@sp 1
Readline is an enhancement for the input line. You may know it already from
the bash shell. Whether it is available in xorriso depends on the availability
of package readline-dev at the time when xorriso was built from its sourcecode.
@*
It allows to move the cursor over the text in the line by help of the
Leftward and the Rightward arrow key.
Text may be inserted at the cursor position. The Delete key removes the
character under the cursor. Upward and Downward arrow keys navigate through
the history of previous input lines. 
@*
@c man-ignore-lines 1
See info readline
@c man See man readline
for more info about libreadline.
@c man .PP
@sp 1
Option -page activates a built-in result text pager which may be convenient in
dialog. After an action has put out the given number of terminal lines,
the pager prompts the user for a line of input.
@*
An empty line lets xorriso resume work until the next page is put out.
@*
The single character "@@" disables paging for the current action.
@*
"@@@@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress
further result output.
@*
Any other line will be interpreted as new dialog line. The current action
is urged to abort. Afterwards, the input line is executed.
@c man .PP
@sp 1
Some actions apply paging to their info output, too.
@*
The urge to abort may or may not be obeyed by the current action. All actions
try to abort as soon as possible.
@node Options, Examples, Dialog, top 
@chapter Options
@c man .br
@c man .SH OPTIONS
@c man .br
All command words are shown with a leading dash although this dash is not
mandatory for the option to be recognized. Nevertheless within option -as
the dashes of the emulated options are mandatory.
@*
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
@menu
* AqDrive::             Aquiring source and target drive
* Loading::             Influencing the behavior of image loading
* Insert::              Inserting files into ISO image
* SetInsert::           Settings for file insertion
* Manip::               File manipulations
* CmdFind::             Tree traversal command -find
* Filter::              Filters for data file content
* Writing::             Writing the result, drive control
* SetWrite::            Settings for result writing
* Bootable::            El Torito bootable ISO images
* Jigdo::               Jigdo Template Extraction
* Charset::             Character sets
* Exception::           Exception processing
* DialogCtl::           Dialog mode control
* Inquiry::             Drive and media related inquiry actions
* Navigate::            Navigation in ISO image and disk filesystem
* Verify::              Evaluation of readability and recovery
* Restore::             osirrox ISO-to-disk restore options
* Emulation::           Command compatibility emulations (cdrtools)
* Scripting::           Scripting, dialog and program control features
* Frontend::            Support for frontend programs via stdin and stdout
@end menu
@c man .TP
@node AqDrive, Loading, Options, Options
@section  Aquiring source and target drive
@c man .B Aquiring source and target drive:
@c man .PP
Before aquiring a drive one will eventually enable options which influence
the behavior of image loading. See next option group.
@table @asis
@sp 1
@c man .TP
@item -dev address
@kindex -dev   aquires one drive for input and output
@cindex Drive, for input and output, -dev
Set input and output drive to the same address and load an eventual ISO image.
If there is no ISO image then create a blank one.
Set the image expansion method to growing.
@*
This is only allowed as long as no changes are pending in the currently
loaded ISO image. Eventually  one has to perform -commit or -rollback first.
@*
Special address string "-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
@*
An empty address string "" gives up the current device
without aquiring a new one.
@c man .TP
@item -indev address
@kindex -indev   aquires a drive for input
@cindex Drive, for input, -indev
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.
@c man .TP
@item -outdev address
@kindex -outdev   aquires a drive for output
@cindex Drive, for output, -outdev
Set output drive and if it differs from the input drive then switch from
growing to modifying or to blind growing. Unlike -dev and -indev this action
does not load a new ISO image. So it can be performed even if there are pending
changes.
@*
-outdev can be performed without previous -dev or -indev. In that case an
empty ISO image with no changes pending is created. It can either be populated
by help of -map, -add et.al. or it can be discarded silently if -dev or -indev
are performed afterwards.
@*
Special address string "-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
@*
An empty address string "" gives up the current output drive
without aquiring a new one. No writing is possible without an output drive.
@c man .TP
@item -grow_blindly "off"|predicted_nwa
@kindex -grow_blindly   overides next writeable address
@cindex Next writeable address, -grow_blindly
If predicted_nwa is a non-negative number then perform blind growing rather
than modifying if -indev and -outdev are set to different drives.
"off" or "-1" switch to modifying, which is the default.
@*
predicted_nwa is the block address where the add-on session of blind
growing will finally end up. It is the responsibility of the user to ensure
this final position and the presence of the older sessions. Else the
overall ISO image will not be mountable or will produce read errors when
accessing file content. xorriso will write the session to the address
as obtained from examining -outdev and not necessarily to predicted_nwa.
@*
During a run of blind growing, the input drive is given up before output
begins. The output drive is given up when writing is done.
@end table
@c man .TP
@c man .B Influencing the behavior of image loading:
@node Loading, Insert, AqDrive, Options
@section Influencing the behavior of image loading
@c man .PP
The following options should normally be performed before loading an image
by aquiring an input drive. In rare cases it is desirable to activate
them only after image loading.
@table @asis
@sp 1
@c man .TP
@item -load entity id
@kindex -load   addresses a particular session as input
@cindex Session, select as input, -load
Load a particular (possibly outdated) ISO session from -dev or -indev.
Usually all available sessions are shown with option -toc.
@*
entity depicts the kind of addressing. id depicts the particular
address. The following entities are defined:
@*
"auto" with any id addresses the last session in -toc. This is the default.
@*
"session" with id being a number as of a line "ISO session", column "Idx".
@*
"track" with id being a number as of a line "ISO track", column "Idx".
@*
"lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector".
@*
"volid" with a search pattern for a text as of a line "ISO ...",
column "Volume Id".
@*
Adressing a non-existing entity or one which does not represent an ISO
image will either abandon -indev or at least lead to a blank image.
@*
If an input drive is set at the moment when -load is executed, then the
addressed ISO image is loaded immediately. Else, the setting will be pending
until the next -dev or -indev. After the image has been loaded once, the
setting is valid for -rollback until next -dev or -indev, where it
will be reset to "auto".
@c man .TP
@item -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern
@kindex -drive_class   controls drive accessability
@cindex Drive, accessability, -drive_class
Add a drive path pattern to one of the safety lists or make those lists empty.
There are three lists defined which get tested in the following sequence:
@*
If a drive address path matches the "harmless" list then the drive will be
accepted. If it is not a MMC device then the prefix "stdio:" will be prepended
automatically. This list is empty by default.
@*
Else if the path matches the "banned" list then the drive will not be
accepted by xorriso but rather lead to a FAILURE event. This list is empty by
default.
@*
Else if the path matches the "caution" list and if it is not a MMC device,
then its address must have the prefix "stdio:" or it will be rejected.
This list has by default one entry: "/dev".
@*
If a drive path matches no list then it is considered "harmless". By default
these are all paths which do not begin with directory "/dev".
@*
A path matches a list if one of its parent paths or itself matches a list
entry. An eventual address prefix "stdio:" or "mmc:" will be ignored when
testing for matches.
@*
By pseudo-class "clear_list" and pseudo-patterns "banned", "caution",
"harmless", or "all", the lists may be made empty.
@*
E.g.: -drive_class clear_list banned
@*
One will normally define the -drive_class lists in one of the xorriso
Startup Files.
@*
Note: This is not a security feature but rather a bumper for the superuser to
prevent inadverted mishaps. For reliably blocking access to a device file you
have to deny its rw-permissions in the filesystem.
@c man .TP
@item -assert_volid pattern severity
@kindex -assert_volid   rejects undesired images
@cindex Image, demand volume id, -assert_volid
Refuse to load ISO images with volume ids which do not match the given
search pattern. When refusing an image, give up the input drive and issue
an event of the given severity (like FAILURE, see -abort_on). An empty search
pattern accepts any image.
@*
This option does not hamper the creation of an empty image from blank
input media and does not discard an already loaded image.
@c man .TP
@item -in_charset character_set_name
@kindex -in_charset   sets input character set
@cindex Character Set, for input, -in_charset
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.
@c man .TP
@item -auto_charset "on"|"off"
@kindex -auto_charset   learns character set from image
@cindex Character set, learn from image, -auto_charset
Enable or disable recording and interpretation of the output character
set name in an xattr attribute of the image root directory. If enabled then
an eventual recorded character set name gets used as input character set
when reading an image.
@*
Note that the default output charset is the local character set of the
terminal where xorriso runs. Before attributing this local character set
to the produced ISO image, check whether the terminal properly displays
all intended filenames, especially exotic national characters.
@c man .TP
@item -hardlinks mode[:mode...]
@kindex -hardlinks   controls handling of hard links
@cindex Hard links, control handling, -hardlinks
Enable or disable loading and recording of hardlink relations.
@*
In default mode "off", iso_rr files lose their inode numbers at image load
time. Each iso_rr file object which has no inode number at image generation
time will get a new unique inode number if -compliance is set to new_rr.
@*
Mode "on" preserves eventual inode numbers from the loaded image.
When committing a session it searches for families of iso_rr files
which stem from the same disk file, have identical content filtering and have
identical properties. The family members all get the same inode number.
Whether these numbers are respected at mount time depends on the operating
system.
@*
Commands -update and -update_r track splits and fusions of hard links in
filesystems which have stable device and inode numbers. This can cause
automatic last minute changes before the session gets written. Command
-hardlinks "perform_update" may be used to do these changes earlier,
e.g. if you need to apply filters to all updated files.
@*
Mode "without_update" avoids hardlink processing during update commands.
Use this if your filesystem situation does not allow -disk_dev_ino "on".
@*
xorriso commands which extract files from an ISO image try to hardlink files
with identical inode number. The normal scope of this operation is from
image load to image load. One may give up the accumulated hard link addresses
by -hardlinks "discard_extract". 
@*
A large number of hardlink families may exhaust -temp_mem_limit
if not -osirrox "sort_lba_on" and -hardlinks "cheap_sorted_extract"
are both in effect. This restricts hard linking to other files restored by
the same single extract command. -hardlinks "normal_extract" re-enables
wide and expensive hardlink accumulation.
@*
@c B00613 : disabled because implemented faulty from beginning:
@c Hardlink processing automatically enables @strong{-compliance new_rr}.
@c This may be overridden by a following -compliance old_rr . In this case
@c the resulting image will violate the RRIP-1.10 specs for entry PX in
@c the same way as mkisofs does.
@c man .TP
@item -acl "on"|"off"
@kindex -acl   controls handling of ACLs
@cindex ACL, control handling, -acl
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.
@c man .TP
@item -xattr "on"|"off"
@kindex -xattr   controls handling of xattr (EA)
@cindex xattr, control handling, -xattr
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.
@c man .TP
@item -md5 "on"|"all"|"off"
@kindex -md5   controls handling of MD5 sums
@cindex MD5, control handling, -md5
Enable or disable processing of MD5 checksums for the overall session and for
each single data file. If enabled then images get loaded only if eventual
checksums tags of superblock and directory tree match properly. The MD5
checksums of data files and whole session get loaded from the image if there
are any.
@*
With options -compare and -update the eventually recorded MD5 of a file
will be used to avoid content reading from the image. Only the disk file
content will be read and compared with that MD5. This can save much time
if -disk_dev_ino "on" is not suitable.
@*
At image generation time they are computed for each file which gets its data
written into the new session. The checksums of files which have their data
in older sessions get copied into the new session. Superblock, tree and whole
session get a checksum tag each.
@*
Mode "all" will additionally check during image generation whether the checksum
of a data file changed between the time when its reading began and the time
when it ended. This implies reading every file twice.
@*
Checksums can be exploited via options -check_md5, -check_md5_r, via find
actions get_md5, check_md5, and via -check_media.
@c man .TP
@item -for_backup
@kindex -for_backup    -acl,-xattr,-hardlinks,-md5
@cindex Backup, enable features, -for_backup
Enable all extra features which help to produce or to restore backups with
highest fidelity of file properties.
Currently this is a shortcut for: -hardlinks on -acl on -xattr on -md5 on.
@c man .TP
@item -disk_dev_ino "on"|"ino_only"|"off"
@kindex -disk_dev_ino   fast incremental backup
@cindex Backup, enable fast incremental, -disk_dev_ino
Enable or disable processing of recorded file identification numbers
(dev_t and ino_t). They are eventually stored as xattr and allow
to substantially accelerate file comparison. The root node gets a global start
timestamp. If during comparison a file with younger timestamps is found in the
ISO image, then it is suspected to have inconsistent content.
@*
If device numbers and inode numbers of the disk filesystems are persistent
and if no irregular alterations of timestamps or system clock happen,
then potential content changes can be detected without reading that content.
File content change is assumed if any of mtime, ctime, device number or inode
number have changed.
@*
Mode "ino_only" replaces the precondition that device numbers are stable by the
precondition that mount points in the compared tree always lead to the
same filesystems. Use this if mode "on" always sees all files changed.
@*
The speed advantage appears only if the loaded session was produced with
-disk_dev_ino "on" too.
@*
Note that -disk_dev_ino "off" is totally in effect only if -hardlinks is "off",
too.
@c man .TP
@item -rom_toc_scan "on"|"force"|"off"[:"emul_on"|"emul_off"]
@kindex -rom_toc_scan   searches for sessions
@cindex Table-of-content, search sessions, -rom_toc_scan
Read-only drives do not tell the actual media type but show any media as
ROM (e.g. as DVD-ROM). The session history of MMC multi-session media might
be truncated to first and last session or even be completely false.
(The eventual emulated history of overwriteable media is not affected by this.)
@*
To have in case of failure a chance of getting the session history and
especially the address of the last session, there is a scan for ISO 9660
filesystem headers which might help but also might yield worse results
than the drive's table of content. At its end it can cause read attempts
to invalid addresses and thus ugly drive behavior.
Setting "on" enables that scan for alleged read-only media.
@*
Some operating systems are not able to mount the most recent session of
multi-session DVD or BD. If on such a system xorriso has no own MMC
capabilities then it may still find that session from a scanned table of
content. Setting "force" handles any media like a ROM media with setting "on".
@*
On the other hand the emulation of session history on overwriteable media
can hamper reading of partly damaged media. Setting "off:emul_off" disables
the elsewise trustworthy table-of-content scan for those media.
@*
To be in effect, the -rom_toc_scan setting has to be made before the -*dev
command which aquires drive and media.
@c man .TP
@item -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
@kindex -calm_drive   reduces drive activity
@cindex Drive, reduce activity, -calm_drive
Reduce drive noise until it is actually used again. Some drives stay alert
for substantial time after they have been used for reading. This reduces
the startup time for the next drive operation but can be loud and waste
energy if no i/o with the drive is expected to happen soon.
@*
Modes "in", "out", "all" immediately calm down -indev, -outdev, resp. both.
Mode "revoke" immediately alerts both.
Mode "on" causes -calm_drive to be performed automatically after each -dev,
-indev, and -outdev. Mode "off" disables this.
@c man .TP
@item -ban_stdio_write
@kindex -ban_stdio_write   demands real drive
@cindex Drive, demand real MMC, -ban_stdio_write
Allow for writing only the usage of MMC optical drives. Disallow
to write the result into files of nearly arbitrary type.
Once set, this command cannot be revoked.
@end table
@c man .TP
@c man .B Inserting files into ISO image:
@node Insert, SetInsert, Loading, Options
@section Inserting files into ISO image
@c man .PP
The following commands expect file addresses of two kinds:
@c man .br
@cindex disk_path, _definition
@strong{disk_path}
is a path to an object in the local filesystem tree.
@c man .br
@cindex iso_rr_path, _definition
@strong{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.)
@c man .PP
@sp 1
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.
@c man .PP
@sp 1
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:
@*
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
@strong{-overwrite}
decides.
@*
Renaming of files has similar collision handling, but directories can only
be replaced, not merged. Note that -mv inserts the source objects into an
eventual existing target directory rather than attempting to replace it.
@c man .PP
@sp 1
The commands in this section alter the ISO image and not the local filesystem.
@table @asis
@sp 1
@c man .TP
@item -disk_pattern "on"|"ls"|"off"
@kindex -disk_pattern   controls pattern expansion
@cindex Pattern expansion, for disk paths, -disk_pattern
Set the pattern expansion mode for the disk_path arguments of several
commands which support this feature.
@*
Setting "off" disables this feature for all commands which are marked in this
man page by "disk_path [***]" or "disk_pattern [***]".
@*