libisoburn/xorriso/xorriso.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorriso.info
@settitle GNU xorriso
@c %**end of header
@c
@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 "Mar 17, 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
* Index::               Index
@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
@unnumberedsec Overview of 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 boot images via El Torito.
@*
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
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}.
@*
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
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:
@*
@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}.
@*
@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.
@*
@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.
@*
@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.
@*
@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:
@*
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
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
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,
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
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
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
@*
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
@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
An @strong{El Torito}
boot record connects a boot image, which is a binary program plus some
other files stored in the ISO image, with the bootstrapping facility of
contemporary computers.
The content of the boot image files is not in the scope of El Torito.
@*
Most bootable GNU/Linux CDs are equipped with ISOLINUX boot images. xorriso is
able to create or maintain an El Torito object which makes such an image
bootable. For details see option -boot_image.
Emulation -as mkisofs supports the example options out of the ISOLINUX wiki.
@*
The support for other boot image types is sparse.
@*
An MBR is generated together with the El Torito boot record if the boot image
bears the isohybrid signature of ISOLINUX 3.72 or later. It will occupy the
first 512 bytes of the emerging ISO image and enable booting from media which
appear as hard disk rather than as CDROM. An MBR does not hamper CDROM booting.
The MBR of a follow-up session can get in effect only on overwriteable media.
@c man .PP
@sp 1
@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
@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.
@*
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
@strong{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 "[...]".
@*
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
@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.
@*
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
* Manipulation::        File manipulations
* Writing::             Writing the result, drive control
* SetInsert::           Settings for file insertion
* SetWrite::            Settings for result writing
* Bootable::            El Torito bootable ISO images
* 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
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
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
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
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, Manipulation, 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
Load a particular (possibly outdated) ISO image 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
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
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
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"
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...]
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.
@*
Hardlink processing automatically enables @strong{-compliance new_rr}.
This may be overridden by a following -compliance old_rr . In this case
the resulting image will violate the RRIP-1.10 specs for entry PX in
the same way as mkisofs does.
@c man .TP
@item -acl "on"|"off"
Enable or disable processing of ACLs.
If enabled, then xorriso will obtain ACLs from disk file objects,
store ACLs in the ISO image using the libisofs specific AAIP format,
load AAIP data from ISO images, test ACL during file comparison,
and restore ACLs to disk files when extracting them from ISO images.
See also options -getfacl, -setfacl.
@c man .TP
@item -xattr "on"|"off"
Enable or disable processing of xattr attributes in user namespace.
If enabled, then xorriso will handle xattr similar to ACL.
See also options -getfattr, -setfattr and above paragraph about xattr.
@c man .TP
@item -md5 "on"|"all"|"off"
Enable or disable processing of MD5 checksums for the overall session and for
each single data file. If enabled then images get loaded only if eventual
checksums tags of superblock and directory tree match properly. The MD5
checksums of data files and whole session get loaded from the image if there
are any.
@*
With options -compare and -update the eventually recorded MD5 of a file
will be used to avoid content reading from the image. Only the disk file
content will be read and compared with that MD5. This can save much time
if -disk_dev_ino "on" is not suitable.
@*
At image generation time they are computed for each file which gets its data
written into the new session. The checksums of files which have their data
in older sessions get copied into the new session. Superblock, tree and whole
session get a checksum tag each.
@*
Mode "all" will additionally check during image 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
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"
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"]
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"
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
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 File manipulations:
@node Manipulation, Writing, Loading, Options
@section File manipulations
@c man .PP
The following commands expect file addresses of two kinds:
@c man .br
@strong{disk_path}
is a path to an object in the local filesystem tree.
@c man .br
@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 -iso_rr_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the iso_rr_path arguments of several
commands which support this feature.
@*
@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.
@*
Setting "off" disables this feature for all commands which are marked in this
man page by "iso_rr_path [***]" or "iso_rr_pattern [***]".
@*
Setting "on" enables it for all those commands.
@*
Setting "ls" enables it only for those which are marked by
"iso_rr_pattern [***]".
@*
Default is "on".
@c man .TP
@item -disk_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the disk_path arguments of several
commands which support this feature.
@*
Setting "off" disables this feature for all commands which are marked in this
man page by "disk_path [***]" or "disk_pattern [***]".
@*
Setting "on" enables it for all those commands.
@*
Setting "ls" enables it only for those which are marked by
"disk_pattern [***]".
@*
Default is "ls".
@c man .TP
@item -add pathspec [...] | disk_path [***]
Insert the given files or directory trees from filesystem
into the ISO image.
@*
If -pathspecs is set to "on" then pattern expansion is always disabled and
character '=' has a special meaning. It eventually separates the ISO image path
from the disk path:
@*
iso_rr_path=disk_path
@*
The separator '=' can be escaped by '\'.
If iso_rr_path does not begin with '/' then -cd is prepended.
If disk_path does not begin with '/' then -cdx is prepended.
@*
If no '=' is given then the word is used as both, iso_rr_path and disk path.
If in this case the word does not begin with '/' then -cdx is prepended to
the disk_path and -cd is prepended to the iso_rr_path.
@*
If -pathspecs is set to "off" then eventual -disk_pattern expansion applies.
The resulting words are used as both, iso_rr_path and disk path. Eventually
-cdx gets prepended to disk_path and -cd to iso_rr_path.
@c man .TP
@item -add_plainly mode
If set to mode "unknown" then any command word that does not begin with "-" and
is not recognized as known command will be subject to a virtual -add command.
I.e. it will be used as pathspec or as disk_path and added to the image.
Eventually -disk_pattern expansion applies to disk_paths.
@*
Mode "dashed" is similar to "unknown" but also adds unrecognized command
words even if they begin with "-".
@*
Mode "any" announces that all further words are to be added as pathspecs
or disk_paths. This does not work in dialog mode.
@*
Mode "none" is the default. It prevents any words from being understood
as files to add, if they are not parameters to appropriate commands.
@c man .TP
@item -path_list disk_path
Like -add but read the parameter words from file disk_path
or standard input if disk_path is "-". 
The list must contain exactly one pathspec resp. disk_path pattern per line. 
@c man .TP
@item -quoted_path_list disk_path
Like -path_list but with quoted input reading rules. Lines get split into
parameter words for -add. Whitespace outside quotes is discarded.
@c man .TP
@item -map disk_path iso_rr_path
Insert file object disk_path into the ISO image as iso_rr_path. If disk_path
is a directory then its whole sub tree is inserted into the ISO image.
@c man .TP
@item -map_single disk_path iso_rr_path
Like -map, but if disk_path is a directory then its sub tree is not inserted.
@c man .TP
@item -map_l disk_prefix iso_rr_prefix disk_path [***]
Perform -map with each of the disk_path arguments. iso_rr_path will be
composed from disk_path by replacing disk_prefix by iso_rr_prefix.
@c man .TP
@item -update disk_path iso_rr_path
Compare file object disk_path with file object iso_rr_path. If they do not
match, then perform the necessary image manipulations to make iso_rr_path
a matching copy of disk_path. By default this comparison will imply lengthy
content reading before a decision is made. Options -disk_dev_ino or -md5 may
accelerate comparison if they were already in effect when the loaded session
was recorded.
@*
If disk_path is a directory and iso_rr_path does not exist yet, then the
whole subtree will be inserted. Else only directory attributes will be
updated.
@c man .TP
@item -update_r disk_path iso_rr_path
Like -update but working recursively. I.e. all file objects below both
addresses get compared whether they have counterparts below the other address
and whether both counterparts match. If there is a mismatch then the necessary
update manipulation is done.
@*
Note that the comparison result may depend on option -follow. Its setting
should always be the same as with the first adding of disk_path as iso_rr_path.
@*
If iso_rr_path does not exist yet, then it gets added. If disk_path does not
exist, then iso_rr_path gets deleted.
@c man .TP
@item -update_l disk_prefix iso_rr_prefix disk_path [***]
Perform -update_r with each of the disk_path arguments. iso_rr_path will be
composed from disk_path by replacing disk_prefix by iso_rr_prefix.
@c man .TP
@item -cut_out disk_path byte_offset byte_count iso_rr_path
Map a byte interval of a regular disk file into a regular file in the ISO
image.
This may be necessary if the disk file is larger than a single media, or if
it exceeds the traditional limit of 2 GiB - 1 for old operating systems,
or the limit of 4 GiB - 1 for newer ones. Only the newest Linux kernels
seem to read properly files >= 4 GiB - 1.
@*
A clumsy remedy for this limit is to backup file pieces and to concatenate
them at restore time. A well tested chopping size is 2047m.
It is permissible to request a higher byte_count than available. The
resulting file will be truncated to the correct size of a final piece.
To request a byte_offset higher than available yields no file in
the ISO image but a SORRY event.
E.g:
@*
 -cut_out /my/disk/file 0 2047m \
@*
 /file/part_1_of_3_at_0_with_2047m_of_5753194821 \
@*
 -cut_out /my/disk/file 2047m 2047m \
@*
 /file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
@*
 -cut_out /my/disk/file 4094m 2047m \
@*
 /file/part_3_of_3_at_4094m_with_2047m_of_5753194821
@*
While option -split_size is set larger than 0, and if all pieces of a file
reside in the same ISO directory with no other files, and if the names look
like above, then their ISO directory will be recognized and handled like a
regular file. This affects options -compare*, -update*, and overwrite
situations.
See option -split_size for details.
@c man .TP
@item -cpr disk_path [***] iso_rr_path
Insert the given files or directory trees from filesystem 
into the ISO image.
@*
The rules for generating the ISO addresses are similar as with
shell command cp -r. Nevertheless, directories of the iso_rr_path
are created if necessary. Especially a not yet existing iso_rr_path
will be handled as directory if multiple disk_paths are present.
The leafnames of the multiple disk_paths will be grafted under that
directory as would be done with an existing directory.
@*
If a single disk_path is present then a non-existing iso_rr_path will
get the same type as the disk_path.
@*
If a disk_path does not begin with '/' then -cdx is prepended.
If the iso_rr_path does not begin with '/' then -cd is prepended. 
@c man .TP
@item -rm iso_rr_path [***]
Delete the given files from the ISO image.
@*
Note: This does not free any space on the -indev media, even if
the deletion is committed to that same media.
@*
The image size will shrink if the image is written to a different
media in modification mode.
@c man .TP
@item -rm_r iso_rr_path [***]
Delete the given files or directory trees from the ISO image.
See also the note with option -rm.
@c man .TP
@item -mv iso_rr_path [***] iso_rr_path
Rename the given file objects in the ISO tree to the last
argument in the list. Use the same rules as with shell command mv.
@*
If pattern expansion is enabled and if the last argument contains wildcard
characters then it must match exactly one existing file address, or else the
command fails with a FAILURE event.
@c man .TP
@item -chown uid iso_rr_path [***]
Set ownership of file objects in the ISO image. uid may either be a decimal
number or the name of a user known to the operating system.
@c man .TP
@item -chown_r uid iso_rr_path [***]
Like -chown but affecting all files below eventual directories.
@c man .TP
@item -chgrp gid iso_rr_path [***]
Set group attribute of file objects in the ISO image. gid  may either be a
decimal number or the name of a group known to the operating system.
@c man .TP
@item -chgrp_r gid iso_rr_path [***]
Like -chgrp but affecting all files below eventual directories.
@c man .TP
@item -chmod mode iso_rr_path [***]
Equivalent to shell command chmod in the ISO image.
mode is either an octal number beginning with "0" or a comma separated
list of statements of the form [ugoa]*[+-=][rwxst]* .
@*
Like: go-rwx,u+rwx .
@*
@strong{Personalities}:
u=user, g=group, o=others, a=all
@*
@strong{Operators}:
+ adds given permissions, - revokes given permissions,
= revokes all old permissions and then adds the given ones.
@*
@strong{Permissions}:
r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit
@*
For octal numbers see man 2 stat.
@c man .TP
@item -chmod_r mode iso_rr_path [***]
Like -chmod but affecting all files below eventual directories.
@c man .TP
@item -setfacl acl_text iso_rr_path [***]
Attach the given ACL to the given iso_rr_paths after deleting their eventually
existing ACLs.
If acl_text is empty, or contains the text "clear" or the text
"@minus{}@minus{}remove-all",
then the existing ACLs will be removed and no new ones will be
attached. Any other content of acl_text will be interpreted as a list of
ACL entries. It may be in the long multi-line format as put out by -getfacl
but may also be abbreviated as follows:
@*
ACL entries are separated by comma or newline. If an entry is empty text or
begins with "#" then it will be ignored. A valid entry has to begin
by a letter out of @{ugom@} for "user", "group", "other", "mask". It has to
contain two colons ":". A non-empty text between those ":" gives a user id
resp. group id. After the second ":" there may be letters out of @{rwx- #@}.
The first three give read, write resp.  execute permission.
Letters "-", " " and TAB are ignored. "#" causes the rest of the entry to
be ignored. Letter "X" or any other letters are not supported. Examples:
@*
  g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
@*
  group:toolies:rw@minus{},user::rw@minus{},group::r@minus{}@minus{},other::r@minus{}@minus{},mask::rw@minus{}
@*
A valid entry may be prefixed by "d", some following characters and ":".
This indicates that the entry goes to the "default" ACL rather than to the
"access" ACL. Example:
@*
  u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
@c man .TP
@item -setfacl_r acl_text iso_rr_path [***]
Like -setfacl but affecting all files below eventual directories.
@c man .TP
@item -setfacl_list disk_path
Read the output of -getfacl_r or shell command getfacl -R and apply it to the
iso_rr_paths as given in lines beginning with "# file:". This will change
ownership, group and ACL of the given files.
If disk_path is "-" then lines are read from standard input. Line "@@" ends the