libisoburn/xorriso/xorriso.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorriso.info
@settitle GNU xorriso 1.3.3
@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 "\fBword\fR words".
@c   @b{...}, @command{...}, @dfn{...}, @emph{...}, @strong{...}
@c     get mapped to \fB...\fR .
@c   @abbr{...}, @code{...}, @file{...}, @i{...}, @option{...}, @r{...},
@c     @ref{...}, @samp{...},@var{...}, get mapped to ... .
@c   @ref{...}, @xref{...} get mapped to empty text.
@c   @email{...} gets mapped to <...> .
@c   Mapped {...} content is subject to the rules except {...} mapping.
@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   "-" which are not preceded by an uneven number of "\" will get
@c     prepended one "\".
@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 "Version 1.3.3, Aug 07, 2013"
@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 - 2013 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 1.3.3
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU xorriso 1.3.3
@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
* Commands::            Reference of commands
* Examples::            Examples
* Files::               Files
* Seealso::             See also
* Bugreport::           Reporting bugs
* 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
@command{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 @command{xorriso} is able to copy file objects out of ISO 9660
filesystems.
@c man .PP
@sp 1
A special property of @command{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.
@*
@sp 1
@c man .sp 1
Note that @command{xorriso} does not write audio CDs and that it does not
produce UDF filesystems which are specified for official video DVD or BD.
@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
@cindex ISO 9660, _definition
@cindex ECMA-119, _definition
Unlike other filesystems, @strong{ISO 9660} (aka @strong{ECMA-119})
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 medium
which governs the data contents in all recorded sessions.
So in the view of the mount program all sessions of a particular medium
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
@command{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
@command{xorriso} adopts the concept of multi-session by loading an
image directory tree if present,
by allowing to manipulate it by several actions,
and by writing the new image to the target medium.
@c man .br
The first session of a @command{xorriso} run begins by the definition of
the input drive with the 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 command @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.
@command{xorriso} will write onto them only if command -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 @command{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 @command{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 @command{xorriso}.
Action -blank "as_needed" can be used to do this marking on overwriteable
media, or to apply mandatory formatting to new media if necessary.
@*
@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 @command{xorriso}.
@*
Appendable is the state after writing a session with command -close off.
@*
@sp 1
@cindex Closed media, _definition
@strong{Closed} media cannot be written. They may contain an ISO image suitable
for @command{xorriso}.
@*
Closed is the state of DVD-ROM media and of multi-session media which were
written with command -close on. If the drive is read-only hardware then it will
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. Command -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, _definition
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 command -dev on blank media
or by command -outdev on media in any state.
@*
The new empty image can be populated with directories and files.
Before it can be written, the medium 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 data on the
medium. These data comprise of 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 the medium and with many types of
optical media it is quite easy to recover them by mounting older sessions.
@*
Growing is achieved by command -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 medium.
@*
Modifying takes place if input drive and output drive are not the same and
if command -grow_blindly is set to its default "off".
This is achieved by commands -indev and -outdev.
@c man .PP
@sp 1
@cindex Blind growing, _definition
If command -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 @command{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, _definition
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
@command{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
@*
  -device_links
@*
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 command
@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 command -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, _definition
@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 @command{xorriso} uses for a decent representation of the disk
files within the ISO image. @command{xorriso} produces Rock Ridge information
by default. It is strongly discouraged to disable this feature.
@c man .PP
@sp 1
@command{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, _definition
An @strong{El Torito}
boot record points the BIOS bootstrapping facility to one or more boot
images, which are binary program files stored in the ISO image.
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.
@command{xorriso} is able to create or maintain an El Torito object which
makes such an image bootable. For details see command -boot_image.
@*
@cindex MBR, _definition
It is possible to make ISO images bootable from USB stick or other
hard-disk-like media. Several options install a @strong{MBR}
(Master Boot Record), It may get adjusted according to the needs of the
intended boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX.
A MBR contains boot code and a partition table.
The new MBR of a follow-up session can get in effect
only on overwriteable media.
@*
MBR is read by PC-BIOS when booting from USB stick or hard disk,
and by PowerPC CHRP or PReP when booting.
An MBR partiton with type 0xee indicates the presence of GPT.
@*
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.
@*
@cindex GPT, _definition
A @strong{GPT} (GUID Partition Table) marks partitions in a more modern way.
It is read by EFI when booting from USB stick or hard disk, and may be used
for finding and mounting a HFS+ partition inside the ISO image.
@*
@cindex APM, _definition
An @strong{APM} (Apple Partition Map) marks the HFS+ partition.
It is read by Macs for booting and for mounting.
@*
MBR, GPT and APM are combinable. APM occupies the first 8 bytes of
MBR boot code. All three do not hamper El Torito booting from CDROM.
@*
There is support for further facilities:
MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
Those are mutually not combinable and also not combinable with MBR, GPT,
or APM.
@*
@c man .PP
@sp 1
@cindex ACL, _definition
@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 command
@strong{-acl}.
@*
AAIP enhanced images are supposed to be mountable normally, but one cannot
expect that the mounted filesystem will show and respect the ACLs.
For now, only @command{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::". When removing ACL from a file,
@command{xorriso} brings "group::" into effect.
@*
Recording and restoring of ACLs from and to local files works currently
only on GNU/Linux and FreeBSD.
@c man .PP
@sp 1
@cindex xattr, _definition
@cindex EA, _definition
@cindex extattr, _definition
@strong{xattr} (aka EA, or extattr)
are pairs of name and value which can be attached to file objects. AAIP is
able to represent them and @command{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 command
@strong{-xattr}.
@*
As with ACL, currently only @command{xorriso} is able to retrieve xattr
from AAIP enhanced images, to restore them to xattr capable file systems,
or to print them. 
@*
Recording and restoring of xattr from and to local files works currently
only on GNU/Linux and FreeBSD, where they are known as extattr. 
@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, unless they are
given as program arguments and command
@strong{-x}
is among them.
@*
@cindex List delimiter, _definition
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 must be
terminated by either the @strong{list delimiter}, occur at the end of
the argument list, or occur at the end of an input line.
@c man .PP
@sp 1
At program start the list delimiter is the string "@minus{}@minus{}".
This may be changed with the -list_delimiter command in order to allow
"@minus{}@minus{}" as parameter in a variable length list.
However, 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 ignored 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 parameters 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.
Unmatched pattern words will appear unaltered in that result list.
@*
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]'
and respects '/' as the path separator, which may only be matched literally.
@*
Pattern expansion is a property of some particular commands and not a general
feature. It is controlled by commands -iso_rr_pattern and -disk_pattern.
Commands which use pattern expansion all have variable parameter
lists which are specified in this text by "[***]" rather than "[...]".
@*
Some other commands perform pattern matching unconditionally.
@c man .PP
@sp 1
Command and parameter words are either read from the 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.
@*
@command{xorriso} is not a shell, although it might appear so at first glimpse.
Be aware that the interaction of quotation marks and pattern symbols like "*"
differs from the usual shell parsers. In @command{xorriso}, a quotation mark
does not make a pattern symbol literal.
@c man .PP
@sp 1
@cindex Quoted input, _definition
@strong{Quoted input}
converts whitespace-separated text 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 8-bit character except NUL (0) as the content of
the quotes.
Nevertheless it can be cumbersome for the user to produce those characters
directly. Therefore quoted input and program arguments allow optional
@strong{Backslash Interpretation}
which can represent all 8-bit characters except NUL (0) via backslash codes
as in $'...' of bash.
@*
This is not enabled by default. See command -backslash_codes.
@c man .PP
@sp 1
When the program starts then it first looks for argument -no_rc. If this is
not present then it looks for its startup files and
reads their content as command input lines. Then it interprets
the program arguments as commands and parameters. Finally it enters
dialog mode if command -dialog "on" has been executed by this point.
@c man .PP
@sp 1
The program ends either by command -end, or by the end of program arguments
if dialog mode has not been enabled at that point, or by a problem
event which triggers the threshold of command -abort_on.
@c man .SS
@node Dialog, Commands, 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 already know it from
the bash shell. Whether it is available in @command{xorriso} depends on the
availability
of package readline-dev at the time when @command{xorriso} was built from
its sourcecode.
@*
Readline allows to move the cursor over the text in the line by help of the
Left and the Right arrow keys.
Text may be inserted at the cursor position. The Delete key removes the
character under the cursor. Up and Down 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
Command -page activates a built-in result text pager which may be convenient in
dialog mode. After an action has output the given number of terminal lines,
the pager prompts the user for a line of input.
@*
An empty line lets @command{xorriso} resume work until the next page is output.
@*
The single character "@@" disables paging for the current action.
@*
"@@@@@@", "x", "q", "X", or "Q" request that the current action aborts and
suppress further result output.
@*
Any other line input will be interpreted as new dialog line. The current action
is requested to abort. Afterwards, the input line is executed.
@c man .PP
@sp 1
Some actions apply paging to their info output, too.
@*
The request to abort may or may not be obeyed by the current action.
All actions try to abort as soon as possible.
@node Commands, Examples, Dialog, top 
@chapter Commands
@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 command to be recognized. Nevertheless within command -as
the dashes of the emulated commands are mandatory.
@*
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
@menu
* ArgSort::             Execution order of program arguments
* AqDrive::             Acquiring 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::            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 commands
* 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 ArgSort, AqDrive, Commands, Commands
@section  Execution order of program arguments
@c man .B Execution order of program arguments:
@c man .PP
By default the program arguments of a xorriso run are interpreted as a
sequence of commands which get performed exactly in the given order.
This requires the user to write commands for desired settings before the
commands which shall be influenced by those settings.
@*
Many other programs support program arguments in an arbitrary ordering
and perform settings and actions in a sequence at their own discretion.
xorriso provides an option to enable such a behavior
at the cost of loss of expressivity.
@table @asis
@sp 1
@c man .TP
@item -x
@kindex -x   enables automatic execution order of arguments
@cindex Automatic execution order, of arguments, -x
Enable automatic sorting of program arguments into a sequence that
(most likely) is sensible.
This command may be given at any position among the commands
which are handed over as program arguments.
@*
Note: It works only if it is given as program argument and
with a single dash (i.e. "-x"). It will not work in startup files, nor with
-options_from_file, nor in dialog mode, nor as "x" and finally not as
"@minus{}@minus{}x".
It affects only the commands given as program arguments.
@c man .TP
@item -list_arg_sorting
@kindex -list_arg_sorting   prints sorting order of -x
@cindex Sorting order, for -x, -list_arg_sorting
List all xorriso commands in the order which applies if command -x is in
effect.
@*
This list may also be helpful without -x for a user who ponders over the
sequence in which to put commands. Deviations from the listed sorting order may
well make sense, though.
@end table
@c man .PP
@c man .TP
@node AqDrive, Loading, ArgSort, Commands
@section  Acquiring source and target drive
@c man .B Acquiring source and target drive:
@c man .PP
The effect of acquiring a drive may depend on several commands in the
next paragraph "Influencing the behavior of image loading".
If desired, their enabling commands have to be performed before the
commands which acquire the drive.
@table @asis
@sp 1
@c man .TP
@item -dev address
@kindex -dev   acquires 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 ISO image if it
is present.
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. If changes are pending, then 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 acquiring a new one.
@c man .TP
@item -indev address
@kindex -indev   acquires a drive for input
@cindex Drive, for input, -indev
Set input drive and load an ISO image if present.
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   acquires 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.
@*