libisoburn/xorriso/xorriso.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename xorriso.info
@settitle GNU xorriso 1.3.0
@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.0, Mai 17, 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.0
@author Thomas Schmitt
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@contents
@ifnottex
@node Top
@top GNU xorriso 1.3.0
@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.
@*
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 acquiring 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. @command{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, Commands
@section Influencing the behavior of image loading
@c man .PP
The following commands should normally be performed before loading an image
by acquiring 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 command -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 -displacement [-]lba
@kindex -displacement   compensate altered image start address
@cindex Session, altered start address, -displacement
Compensate a displacement of the image versus the start address
for which the image was prepared. This affects only loading of ISO images
and reading of their files. The multi-session method of growing is not allowed
as long as -displacement is non-zero. I.e. -indev and -outdev must be
different. The displacement gets reset to 0 before the drive
gets re-acquired after writing.
@*
Examples:
@*
If a track of a CD starts at block 123456 and gets copied to a disk file
where it begins at block 0, then this copy can be loaded with
-displacement -123456.
@*
If an ISO image was written onto a partition with offset of 640000 blocks of
512 bytes, then it can be loaded from the base device by -displacement 160000.
@*
In both cases, the ISO sessions should be self contained, i.e. not add-on
sessions to an ISO image outside their track resp. partition.
@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 @command{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. 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 @command{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 command 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. 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 and
if a recorded character set name is found, then this name will be used as
name of the input character set when reading an image.
@*
Note that the default output charset is the local character set of the
terminal where @command{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 inode numbers from the loaded image if such numbers
were recorded.
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.
@*
Command -lsl displays hardlink counts if "lsl_count" is enabled. This can
slow down the command substantially after changes to the ISO image have
been made. Therefore the default is "no_lsl_count".
@*
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".
@*
@command{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 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 @command{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 commands -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 @command{xorriso} will handle xattr similar to ACL.
See also commands -getfattr, -setfattr and above paragraph about xattr.
@c man .TP
@item -md5 "on"|"all"|"off"|"load_check_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 with checksum tags get loaded
only if the 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 commands -compare and -update the 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.
@*
Mode "load_check_off" together with "on" or "all" will load recorded MD5 sums
but not test the recorded checksum tags of superblock and directory tree.
This is necessary if growisofs was used as burn program, because it does
not overwrite the superblock checksum tag of the first session.
Therefore load_check_off is in effect when @command{xorriso} -as mkisofs
option -M is performed.
@*
The test can be re-enabled by mode "load_check_on".
@*
Checksums can be exploited via commands -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). If enabled they are 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_off"][:"emul_wide"]
@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 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 @command{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 medium 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.
@*
The table-of-content scan on overwriteable media normally searches only up to
the end of the session that is pointed to by the superblock at block 0.
Setting "on:emul_wide" lets the scan continue up to the end of the medium.
This may be useful after copying a medium with -check_media patch_lba0=on
when not the last session was loaded.
@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.
@c man .TP
@item -early_stdio_test "on"|"appendable_wo"|"off"
@kindex -early_stdio_test   classifies stdio drives
@cindex Drive, classify stdio, -early_stdio_test
If enabled by "on" then regular files and block devices get tested for
effective access permissions. This implies to try opening those files for
writing, which otherwise will happen only later and only if actual
writing is desired.
@*
The test result is used for classifying the pseudo drives as overwriteable,
read-only, write-only, or uselessly empty. This may lead to earlier detection
of severe problems, and may avoid some less severe error events.
@*
Mode "appendable_wo" is like "on" with the additional property that
non-empty write-only files are regarded as appendable rather than blank.
@c man .TP
@item -data_cache_size number_of_tiles blocks_per_tile
@kindex -data_cache_size   adjusts read cache size
@cindex Image reading, cache size, -data_cache_size
Set the size and granularity of the data cache which is used when ISO images
are loaded and when file content is read from ISO images. The cache consists
of several tiles, which each consists of several blocks. A larger cache
reduces the need for tiles being read multiple times. Larger tiles might
additionally improve the data throughput from the drive, but can be
wasteful if the data are scattered over the medium. 
@*
Larger cache sizes help best with image loading from MMC drives. They are an
inferior alternative to -osirrox option "sort_lba_on".
@*
blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The overall cache
size must not exceed 1 GiB.
The default values can be restored by parameter "default" instead of one or
both of the numbers.
Currently the default is 32 tiles of 32 blocks = 2 MiB.
@end table
@c man .TP
@c man .B Inserting files into ISO image:
@node Insert, SetInsert, Loading, Commands
@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.
If no Rock Ridge information is recorded in the loaded ISO image, then you
will see ISO 9660 names which are of limited length and character set.
If no Rock Ridge information shall be stored in an emerging ISO image, then
their names will get mapped to such restricted ISO 9660 names.
@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 if the target directory exists, then -mv
inserts the source objects into this directory rather than attempting
to replace it. Command -move, on the other hand, would attempt 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 parameters 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 [***]
@kindex -add   inserts one or more paths
@cindex Insert, pathspecs, -add
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 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 -disk_pattern expansion applies, if enabled.
The resulting words are used as both, iso_rr_path and disk path. Relative
path words get prepended the setting of -cdx to disk_path and the setting
of -cd to iso_rr_path.
@c man .TP
@item -add_plainly mode
@kindex -add_plainly   inserts one or more paths
@cindex Insert, non-dashed arguments, -add_plainly
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.
If enabled, -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
@kindex -path_list   inserts paths from disk file
@cindex Insert, paths from disk file, -path_list
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
@kindex -quoted_path_list   inserts paths from disk file
@cindex Insert, paths from disk file, -quoted_path_list
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
@kindex -map   inserts path
@cindex Insert, path, -map
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
@kindex -map_single   inserts path
@cindex Insert, path, -map_single
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 [***]
@kindex -map_l   inserts paths from disk file
@cindex Insert, paths from disk file, -map_l
Perform -map with each of the disk_path parameters. 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
@kindex -update   inserts path if different
@cindex Insert, if different, -update
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. Commands -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
@kindex -update_r   inserts paths if different
@cindex Insert, if different, -update_r
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 command -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 [***]
@kindex -update_l   inserts paths if different
@cindex Insert, if different, -update_l
Perform -update_r with each of the disk_path parameters. 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
@kindex -cut_out   inserts piece of data file
@cindex Insert, piece of data file, -cut_out
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 medium, 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 command -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 commands -compare*, -update*, and overwrite
situations.
See command -split_size for details.
@c man .TP
@item -cpr disk_path [***] iso_rr_path
@kindex -cpr   inserts like with cp -r
@cindex Insert, paths, -cpr
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 -mkdir iso_rr_path [...]
@kindex -mkdir   creates ISO directory
@cindex Directory, create, -mkdir
Create empty directories if they do not exist yet.
Existence as directory generates a WARNING event, existence as
other file causes a FAILURE event.
@c man .TP
@item -lns target_text iso_rr_path
@kindex -lns   creates ISO symbolic link
@cindex Symbolic link, create, -lns
Create a symbolic link with address iso_rr_path which points to target_text.
iso_rr_path may not exist yet.
@*
Hint: Command -clone produces the ISO equivalent of a hard link.
@c man .TP
@item -clone iso_rr_path_original iso_rr_path_copy
@kindex -clone   copies ISO directory tree
@cindex Directory, copy, -clone
Create a copy of the ISO file object iso_rr_path_original with the new
address iso_rr_path_copy. If the original is a directory then copy all
files and directories underneath. If iso_rr_path_original is a boot catalog
file, then it gets not copied but is silently ignored.
@*
The copied ISO file objects have the same attributes. Copied data files
refer to the same content source as their originals.
The copies may then be manipulated independendly of their originals.
@*
This command will refuse execution if the address iso_rr_path_copy
already exists in the ISO tree.
@c man .TP
@item -cp_clone iso_rr_path_original [***] iso_rr_path_dest
@kindex -cp_clone   copies ISO directory tree
@cindex Directories, copy, -cp_clone
Create copies of one or more ISO file objects as with command -clone.
In case of collision merge directories with existing ones, but do not overwrite
existing ISO file objects.
@*
The rules for generating the copy addresses are the same as with
command -cpr (see above) resp. shell command cp -r. Other than with -cpr,
relative iso_rr_path_original will get prepended the -cd path and not
the -cdx path. Consider to -mkdir iso_rr_path_dest before -cp_clone
so the copy address does not depend on the number of iso_rr_path_original
parameters.
@end table
@c man .TP
@c man .B Settings for file insertion:
@node SetInsert, Manip, Insert, Commands
@section Settings for file insertion
@c man .TP
@table @asis
@item -file_size_limit value [value [...]] @minus{}@minus{}
@kindex -file_size_limit   limits data file size
@cindex Insert, limit data file size, -file_size_limit
Set the maximum permissible size for a single data file. The values get
summed up for the actual limit. If the only value is "off" then the file
size is not limited by @command{xorriso}.
Default is a limit of 100 extents, 4g -2k each:
@*
 -file_size_limit 400g -200k @minus{}@minus{}
@*
When mounting ISO 9660 filesystems, old operating systems can handle only files
up to 2g -1 @minus{}@minus{}. Newer ones are good up to 4g -1 @minus{}@minus{}.
You need quite a new Linux kernel to read correctly the final bytes
of a file >= 4g if its size is not aligned to 2048 byte blocks.
@*
@command{xorriso}'s own data read capabilities are not affected by
operating system size limits. Such limits apply to mounting only. Nevertheless,
the target filesystem of an -extract must be able to take the file size.
@c man .TP
@item -not_mgt code[:code[...]]
@kindex -not_mgt   controls file exclusion
@cindex Insert, file exclusion, -not_mgt
Control the behavior of the exclusion lists.
@*
Exclusion processing happens before disk_paths get mapped to the ISO image
and before disk files get compared with image files.
The absolute disk path of the source is matched against the -not_paths list.
The leafname of the disk path is matched against the patterns in the -not_leaf
list. If a match is detected then the disk path will not be regarded as an
existing file and not be added to the ISO image.
@*
Several codes are defined.
The _on/_off settings persist until they are revoked by their_off/_on
counterparts.
@*
"erase" empties the lists which were accumulated by -not_paths and -not_leaf.
@*
"reset" is like "erase" but also re-installs default behavior.
@*
"off" disables exclusion processing temporarily without invalidating
the lists and settings.
@*
"on" re-enables exclusion processing.
@*
"param_off" applies exclusion processing only to paths below disk_path
parameter of commands. I.e. explicitly given disk_paths are exempted
from exclusion processing.
@*
"param_on" applies exclusion processing to command parameters as well as
to files below such parameters.
@*
"subtree_off" with "param_on" excludes parameter paths only if they
match a -not_paths item exactly.
@*
"subtree_on" additionally excludes parameter paths which lead to a file
address below any -not_paths item.
@*
"ignore_off" treats excluded disk files as if they were missing. I.e. they
get reported with -compare and deleted from the image with -update.
@*
"ignore_on" keeps excluded files out of -compare or -update activities.
@c man .TP
@item -not_paths disk_path [***]
@kindex -not_paths   sets absolute exclusion paths
@cindex Insert, file exclusion absolute, -not_paths
Add the given paths to the list of excluded absolute disk paths. If a given
path is relative, then the current -cdx is prepended to form an absolute path.
Pattern matching, if enabled, happens at definition time and not when exclusion
checks are made.
@*
(Do not forget to end the list of disk_paths by "@minus{}@minus{}")
@c man .TP
@item -not_leaf pattern
@kindex -not_leaf   sets exclusion pattern
@cindex Insert, file exclusion pattern, -not_leaf
Add a single shell parser style pattern to the list of exclusions for
disk leafnames. These patterns are evaluated when the exclusion checks are
made.
@c man .TP
@item -not_list disk_path
@kindex -not_list   sets exclusions from disk file
@cindex Insert, file exclusion from file, -not_list
Read lines from disk_path and use each of them either as -not_paths parameter,
if they contain a / character, or as -not_leaf pattern.
@c man .TP
@item -quoted_not_list disk_path
@kindex -quoted_not_list   sets exclusions
@cindex Insert, file exclusion, -quoted_not_list
Like -not_list but with quoted input reading rules. Each word is
handled as one parameter for -not_paths resp. -not_leaf.
@c man .TP
@item -follow occasion[:occasion[...]]
@kindex -follow   softlinks and mount points
@cindex Insert, links or mount points, -follow
Enable or disable resolution of symbolic links and mountpoints under
disk_paths. This applies to actions -add, -du*x, -ls*x, -findx,
and to -disk_pattern expansion.
@*
There are two kinds of follow decisison to be made:
@*
"link" is the hop from a symbolic link to its target file object.
If enabled then symbolic links are handled as their target file objects,
else symbolic links are handled as themselves. 
@*
"mount" is the hop from one filesystem to another subordinate filesystem.
If enabled then mountpoint directories are handled as any other directory,
else mountpoints are handled as empty directories if they are encountered in
directory tree traversals.
@*
Less general than above occasions:
@*
"pattern" is mount and link hopping, but only during -disk_pattern expansion.
@*
"param" is link hopping for parameter words (after eventual pattern expansion).
If enabled then -ls*x will show the link targets rather than the links
themselves. -du*x, -findx, and -add will process the link targets but not
follow links in an eventual directory tree below the targets (unless "link"
is enabled). 
@*
Occasions can be combined in a colon separated list. All occasions
mentioned in the list will then lead to a positive follow decision. 
@*
"off" prevents any positive follow decision. Use it if no other occasion
applies.
@*
Shortcuts:
@*
"default" is equivalent to "pattern:mount:limit=100".
@*
"on" always decides positive. Equivalent to "link:mount".
@*
@sp 1

Not an occasion but an optional setting is:
@*
"limit="<number> which sets the maximum number of link hops.
A link hop consists of a sequence of symbolic links and a final target
of different type. Nevertheless those hops can loop. Example:
@*
  $ ln -s .. uploop
@*
Link hopping has a built-in loop detection which stops hopping at the first
repetition of a link target. Then the repeated link is handled as itself
and not as its target.
Regrettably one can construct link networks which
cause exponential workload before their loops get detected.
The number given with "limit=" can curb this workload at the risk of truncating
an intentional sequence of link hops.
@c man .TP
@item -pathspecs "on"|"off"
@kindex -pathspecs   sets meaning of = with -add
@cindex Insert, meaning of = with -add, -pathspecs
Control parameter interpretation with @command{xorriso}
actions -add and -path_list.
@*
@cindex Pathspec, _definition
"on" enables pathspecs of the form
@strong{target=source}
like with program mkisofs -graft-points.
It also disables -disk_pattern expansion for command -add.
@*
"off" disables pathspecs of the form target=source
and re-enables -disk_pattern expansion.
@c man .TP                
@item -overwrite "on"|"nondir"|"off"
@kindex -overwrite   enables overwriting in ISO
@cindex Insert, enable overwriting, -overwrite
Allow or disallow to overwrite existing files in the
ISO image by files with the same name.
@*
With setting "off", name collisions cause FAILURE events.
With setting "nondir", only directories are protected by such events, other
existing file types get treated with -rm before the new file gets added.
Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an
existing directory and all its subordinates.
@*
If restoring of files is enabled, then the overwrite rule applies to the
target file objects on disk as well, but "on" is downgraded to "nondir".
@c man .TP
@item -split_size number["k"|"m"]
@kindex -split_size   enables large file splitting
@cindex Insert, large file splitting, -split_size
Set the threshold for automatic splitting of regular files. Such splitting
maps a large disk file onto a ISO directory with several part files in it.
This is necessary if the size of the disk file exceeds -file_size_limit.
Older operating systems can handle files in mounted ISO 9660 filesystems
only if they are smaller than 2 GiB resp. 4 GiB.
@*
Default is 0 which will exclude files larger than -file_size_limit by a
FAILURE event.
A well tested -split_size is 2047m. Sizes above -file_size_limit are not
permissible.
@*
While command -split_size is set larger than 0 such a directory with split
file pieces will be recognized and handled like a regular file by commands
-compare* , -update*, and in overwrite situations. There are -ossirox
parameters "concat_split_on" and "concat_split_off" which control the handling
when files get restored to disk.
@*
In order to be recognizable, the names of the part files have to
describe the splitting by 5 numbers:
@*
 part_number,total_parts,byte_offset,byte_count,disk_file_size
@*
which are embedded in the following text form:
@*
 part_#_of_#_at_#_with_#_of_#
@*
Scaling characters like "m" or "k" are taken into respect.
All digits are interpreted as decimal, even if leading zeros are present.
@*
E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
@*
No other files are allowed in the directory. All parts have to be present and
their numbers have to be plausible. E.g. byte_count must be valid as -cut_out
parameter and their contents may not overlap.
@end table
@c man .TP
@c man .B File manipulations:
@node Manip, CmdFind, SetInsert, Commands
@section File manipulations
@c man .PP
The following commands manipulate files in the ISO image, regardless whether
they stem from the loaded image or were newly inserted.
@c man .PP
@table @asis
@sp 1
@c man .TP
@item -iso_rr_pattern "on"|"ls"|"off"
@kindex -iso_rr_pattern   controls pattern expansion
@cindex Pattern expansion, for ISO paths, -iso_rr_pattern
Set the pattern expansion mode for the iso_rr_path parameters of several
commands which support this feature.
@*
Setting "off" disables pattern expansion 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 -rm iso_rr_path [***]
@kindex -rm   deletes files from ISO image
@cindex Delete, from ISO image, -rm
Delete the given files from the ISO image.
@*
Note: This does not free any space on the -indev medium, even if
the deletion is committed to that same medium.
@*
The image size will shrink if the image is written to a different
medium in modification mode.
@c man .TP
@item -rm_r iso_rr_path [***]
@kindex -rm_r   deletes trees from ISO image
@cindex Delete, from ISO image, -rm_r
Delete the given files or directory trees from the ISO image.
See also the note with command -rm.
@c man .TP
@item -rmdir iso_rr_path [***]
@kindex -rmdir   deletes ISO directory
@cindex Delete, ISO directory, -rmdir
@cindex Directory, delete, -rmdir
Delete empty directories.
@c man .TP
@item -move iso_rr_path iso_rr_path
@kindex -mv   renames single file in ISO image
@cindex Rename, in ISO image, -move
Rename the file given by the first (origin) iso_rr_path to the second
(destination) iso_rr_path.
Deviate from rules of shell command mv by not moving the origin file underneath
an existing destination directory. The origin file will rather replace such a
directory, if this is allowed by command -overwrite.
@c man .TP
@item -mv iso_rr_path [***] iso_rr_path
@kindex -mv   renames files in ISO image
@cindex Rename, in ISO image, -mv
Rename the given file objects in the ISO tree to the last
parameter in the list. Use the same rules as with shell command mv.
@*
If pattern expansion is enabled and if the last parameter 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 [***]
@kindex -chown   sets ownership in ISO image
@cindex Ownership, in ISO image, -chown
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 [***]
@kindex -chown_r   sets ownership in ISO image
@cindex Ownership, in ISO image, -chown_r
Like -chown but affecting all files below eventual directories.
@c man .TP
@item -chgrp gid iso_rr_path [***]
@kindex -chgrp   sets group in ISO image
@cindex Group, in ISO image, -chgrp
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 [***]
@kindex -chgrp_r   sets group in ISO image
@cindex Group, in ISO image, -chgrp_r
Like -chgrp but affecting all files below eventual directories.
@c man .TP
@item -chmod mode iso_rr_path [***]
@kindex -chmod   sets permissions in ISO image
@cindex Permissions, in ISO image, -chmod
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 [***]
@kindex -chmod_r   sets permissions in ISO image
@cindex Permissions, in ISO image, -chmod_r
Like -chmod but affecting all files below eventual directories.
@c man .TP
@item -setfacl acl_text iso_rr_path [***]
@kindex -setfacl   sets ACL in ISO image
@cindex ACL, set in ISO image, -setfacl
Attach the given ACL to the given iso_rr_paths. If the files already have
ACLs, then those get deleted before the new ones get into effect.
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 [***]
@kindex -setfacl_r   sets ACL in ISO image
@cindex ACL, set in ISO image, -setfacl_r
Like -setfacl but affecting all files below eventual directories.
@c man .TP
@item -setfacl_list disk_path
@kindex -setfacl_list   sets ACL in ISO image
@cindex ACL, set in ISO image, -setfacl_list
Read the output of -getfacl_r or shell command getfacl -R and apply it to the
iso_rr_paths as given in lines beginning with "# file:". This will change
ownership, group and ACL of the given files.
If disk_path is "-" then lines are read from standard input. Line "@@" ends the
list, "@@@@@@" aborts without changing the pending iso_rr_path.
@*
Since -getfacl and getfacl -R strip leading "/" from file paths, the setting of
-cd does always matter.
@c man .TP
@item -setfattr [-]name value iso_rr_path [***]
@kindex -setfattr   sets xattr in ISO image
@cindex xattr, set in ISO image, -setfattr
Attach the given xattr pair of name and value to the given iso_rr_paths.
If the given name is prefixed by "-", then the pair with that name gets
removed from the xattr list. If name is "@minus{}@minus{}remove@minus{}all"
then all user namespace
xattr of the given iso_rr_paths get deleted. In case of deletion, value must
be an empty text.
@*
Only names from the user namespace are allowed. I.e. a name has to begin with
"user.", like "user.x" or "user.whatever".
@*
Values and names undergo the normal input processing of @command{xorriso}.
See also command -backslash_codes. Other than with command -setfattr_list,
the byte value 0 cannot be expressed via -setfattr.
@c man .TP
@item -setfattr_r [-]name value iso_rr_path [***]
@kindex -setfattr_r   sets xattr in ISO image
@cindex xattr, set in ISO image, -setfattr_r
Like -setfattr but affecting all files below eventual directories.
@c man .TP
@item -setfattr_list disk_path
@kindex -setfattr_list   sets xattr in ISO image
@cindex xattr, set in ISO image, -setfattr_list
Read the output of -getfattr_r or shell command getfattr -Rd and apply it to
the iso_rr_paths as given in lines beginning with "# file:". All previously
existing user space xattr of the given iso_rr_paths will be deleted.
If disk_path is "-" then lines are read from standard input.
@*
Since -getfattr and getfattr -Rd strip leading "/" from file paths, the setting
of -cd does always matter.
@*
Empty input lines and lines which begin by "#" will be ignored
(except "# file:"). Line "@@" ends the list, "@@@@@@" aborts without changing
the pending iso_rr_path. Other input lines must have the form
@*
  name="value"
@*
Name must be from user namespace. I.e. user.xyz where xyz should consist of
printable characters only. The separator "=" is not allowed in names.
Value may contain any kind of bytes. It must be in quotes. Trailing
whitespace after the end quote will be ignored. Non-printables bytes and quotes
must be represented as \XYZ by their octal 8-bit code XYZ.
Use code \000 for 0-bytes.
@c man .TP
@item -alter_date type timestring iso_rr_path [***]
@kindex -alter_date   sets timestamps in ISO image
@cindex Timestamps, set in ISO image, -alter_date
Alter the date entries of a file in the ISO image. type is
one of "a", "m", "b" for access time, modification time,
both times.
@*
timestring may be in the following formats
(see also section EXAMPLES):
@*
As expected by program date:
 MMDDhhmm[[CC]YY][.ss]]
@*
As produced by program date:
@*
 [Day] MMM DD hh:mm:ss [TZON] YYYY
@*
Relative times counted from current clock time:
@*
 +|-Number["s"|"h"|"d"|"w"|"m"|"y"]
@*
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d,
"y"=365.25d plus 1d added to multiplication result.
@*
Absolute seconds counted from Jan 1 1970:
@*
 =Number
@*
@command{xorriso}'s own timestamps:
@*
 YYYY.MM.DD[.hh[mm[ss]]]
@*
scdbackup timestamps:
@*
 YYMMDD[.hhmm[ss]]
@*
where "A0" is year 2000, "B0" is 2010, etc.
@*
ECMA-119 volume timestamps:
@*
 YYYYMMDDhhmmsscc
@*
These are normally given as GMT. The suffix "LOC" causes local timezone
conversion. E.g. 2013010720574700, 2013010720574700LOC.
The last two digits cc (centiseconds) will be ignored, but must be present
in order to make the format recognizable.
@c man .TP
@item -alter_date_r type timestring iso_rr_path [***]
@kindex -alter_date_r   sets timestamps in ISO image
@cindex Timestamps, set in ISO image, -alter_date_r
Like -alter_date but affecting all files below eventual directories.
@c man .TP
@item -hide hide_state iso_rr_path [***]
@kindex -hide   excludes file names from directory trees
@cindex hidden, set in ISO image, -hide
Prevent the names of the given files from showing up in the directory trees
of ISO 9660 and/or Joliet and/or HFS+ when the image gets written.
The data content of such hidden files will be included in the
resulting image, even if they do not show up in any directory.
But you will need own means to find nameless data in the image.
@*
Warning: Data which are hidden from the ISO 9660 tree will not be copied
by the write method of modifying.
@*
Possible values of hide_state are: "iso_rr" for hiding from ISO 9660 tree,
"joliet" for Joliet tree, "hfsplus" for HFS+, "on" for them all.
"off" means visibility in all directory trees.
@*
These values may be combined.
E.g.: joliet:hfsplus
@*
This command does not apply to the boot catalog.
Rather use: -boot_image "any" "cat_hidden=on"
@end table
@c man .TP
@c man .B Tree traversal command -find:
@node CmdFind, Filter, Manip, Commands
@section Tree traversal command -find
@c man .PP
@table @asis
@c man .TP
@item -find iso_rr_path [test [op] [test ...]] [-exec action [params]] @minus{}@minus{}
@kindex -find   traverses and alters ISO tree
@cindex Tree, ISO, traverse and alter, -find
A restricted substitute for shell command find in the ISO image.
It performs an action on matching file objects at or below iso_rr_path.
@*
If not used as last command in the line then the parameter list
needs to get terminated by "@minus{}@minus{}".
@*
Tests are optional. If they are omitted then action is applied to all file
objects. If tests are given then they form together an expression.
The action is applied only if the expression matches the file object. Default
expression operator between tests is -and, i.e. the expression matches only
if all its tests match.
@*
Available tests are:
@*
@table @asis
@sp 1
@item -name pattern :
Matches if pattern matches the file leaf name.
@*
@item -wholename pattern :
Matches if pattern matches the file path as it would be printed by action
"echo". Character '/' is not special but can be matched by wildcards.
@*
@item -disk_name pattern :
Like -name but testing the leaf name of the file source on disk.
Can match only data files which do not stem from the loaded image,
or for directories above such data files. With directories the result can
change between -find runs if their content stems from multiple sources.
@*
@item -disk_path disk_path :
Matches if the given disk_path is equal to the path of the file source
on disk. The same restrictions apply as with -disk_name.
@*
@item -type type_letter :
Matches files of the given type:
"block", "char", "dir", "pipe", "file", "link", "socket", "eltorito",
and "Xotic" which matches what is not matched by the other types.
@*
Only the first letter is interpreted.  E.g.: -find / -type d
@*
@item -damaged :
Matches files which use data blocks marked as damaged by a previous
run of -check_media. The damage info vanishes when a new ISO image gets
loaded.
@*
Note that a MD5 session mismatch marks all files of the session as damaged.
If finer distinction is desired, perform -md5 off before -check_media.
@*
@item -pending_data :
Matches files which get their content from outside the loaded ISO image.
@*
@item -lba_range start_lba block_count :
Matches files which use data blocks within the range of start_lba
and start_lba+block_count-1.
@*
@item -has_acl :
Matches files which have a non-trivial ACL.
@*
@item -has_xattr :
Matches files which have xattr name-value pairs from user namespace.
@*
@item -has_aaip :
Matches files which have ACL or any xattr.
@*
@item -has_any_xattr :
Matches files which have any xattr other than ACL.
@*
@item -has_md5 :
Matches data files which have MD5 checksums.
@*
@item -has_hfs_crtp creator type :
Matches files which have the given HFS+ creator and type attached.
These are codes of 4 characters which get stored if -hfsplus is
enabled. Use a single dash '-' as wildcard that matches any such code.
E.g:.
@*
 -has_hfs_crtp YYDN TEXT
@*
 -has_hfs_crtp - -
@*
@item -has_hfs_bless blessing :
Matches files which bear the given HFS+ blessing. It may be one of :
"ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx_folder",
"any". See also action set_hfs_bless.
@*
@item -has_filter :
Matches files which are filtered by -set_filter.
@*
@item -hidden hide_state :
Matches files which are hidden in "iso_rr" tree, in "joliet" tree,
in "hfsplus" tree, in all trees ("on"), or not hidden in any tree ("off").
@*
Those which are hidden in some tree match -not -hidden "off".
@*
@item -prune :
If this test is reached and the tested file is a directory then -find will not
dive into that directory. This test itself does always match. 
@*
@item -decision "yes"|"no" :
If this test is reached then the evaluation ends immediately and action
is performed if the decision is "yes" or "true". See operator -if.
@*
@c man \fB\-true\fR and \fB\-false\fR :
@c man-ignore-lines 1
@item -true and -false :
Always match resp. match not. Evaluation goes on.
@*
@item -sort_lba :
Always match. This causes -find to perform its action in a sequence sorted by
the ISO image block addresses of the files. It may improve throughput with
actions which read data from optical drives. Action will always get the
absolute path as parameter.
@*
Available operators are:
@*
@item -not :
Matches if the next test or sub expression does not match.
Several tests do this specifically:
@*
-undamaged, -lba_range with negative start_lba, -has_no_acl, -has_no_xattr,
-has_no_aaip, -has_no_filter .
@*
@item -and :
Matches if both neighboring tests or expressions match.
@*
@item -or :
Matches if at least one of both neighboring tests or expressions matches.
@*
@c man \fB\-sub\fR ... \fB\-subend\fR or \fB(\fR ... \fB)\fR :
@c man-ignore-lines 1
@item -sub ... -subend or ( ... ) :
Enclose a sub expression which gets evaluated first before it
is processed by neighboring operators.
Normal precedence is: -not, -or , -and.
@*
@c man \fB\-if\fR ... \fB\-then\fR\ ... \fB\-elseif\fR ... \fB\-then\fR ...
@c man \fB\-else\fR ... \fB\-endif\fR :
@c man-ignore-lines 1
@item -if ... -then ... -elseif ... -then ... -else ... -endif :
Enclose one or more sub expressions. If the -if expression matches, then
the -then expression is evaluated as the result of the whole expression
up to -endif. Else the next -elseif expression is evaluated and if it matches,
its -then expression. Finally in case of no match, the -else expression
is evaluated.
There may be more than one -elseif. Neither -else nor -elseif are mandatory.
If -else is missing and would be hit, then the result is a non-match.
@*
-if-expressions are the main use case for above test -decision.
@end table
@sp 1

Default action is @strong{echo},
i.e. to print the address of the found file. Other actions are certain
@command{xorriso} commands which get performed on the found files.
These commands
may have specific parameters. See also their particular descriptions.
@c man .br
@table @asis
@sp 1
@c man \fBchown\fR and \fBchown_r\fR
@c man-ignore-lines 1
@item chown and chown_r
change the ownership and get the user id
as parameter. E.g.: -exec chown thomas @minus{}@minus{}
@*
@c man \fBchgrp\fR and \fBchgrp_r\fR
@c man-ignore-lines 1
@item chgrp and Bchgrp_r
change the group attribute and get the group id
as parameter. E.g.: -exec chgrp_r staff @minus{}@minus{}
@*
@c man \fBchmod\fR and \fBchmod_r\fR
@c man-ignore-lines 1
@item chmod and chmod_r
change access permissions and get a mode string
as parameter.  E.g.: -exec chmod a-w,a+r @minus{}@minus{}
@*
@c man \fBalter_date\fR and \fBalter_date_r\fR
@c man-ignore-lines 1
@item Balter_date and Balter_date_r
change the timestamps. They get a type
character and a timestring as parameters.
@*
E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" @minus{}@minus{}
@*
@item lsdl
prints file information like shell command ls -dl.
@*
@item compare
performs command -compare with the found file address as
iso_rr_path and the corresponding file address below its parameter
disk_path_start. For this the iso_rr_path of the -find command gets
replaced by the disk_path_start.
@*
E.g.: -find /thomas -exec compare /home/thomas @minus{}@minus{}
@*
@item update
performs command -update with the found file address as
iso_rr_path. The corresponding file address is determined like with above
action "compare".
@*
@item update_merge
is like update but does not delete the found file if it is missing on disk.
It may be run several times and records with all visited files whether their
counterpart on disk has already been seen by one of the update_merge runs.
Finally, a -find run with action "rm_merge" may remove all files that
saw no counterpart on disk.
@*
Up to the next "rm_merge" or "clear_merge" all newly inserted files will
get marked as having a disk counterpart.
@*
@item rm
removes the found iso_rr_path from the image if it is not a directory
with files in it. I.e. this "rm" includes "rmdir".
@*
@item rm_r
removes the found iso_rr_path from the image, including whole
directory trees.
@*
@item rm_merge
removes the found iso_rr_path if it was visited by one or more previous actions
"update_merge" and saw no counterpart on disk in any of them. The marking from
the update actions is removed in any case.
@*
@item clear_merge
removes an eventual marking from action "update_merge".
@*
@item report_damage
classifies files whether they hit a data block that is
marked as damaged. The result is printed together with the address
of the first damaged byte, the maximum span of damages, file size, and the
path of the file. 
@*
@item report_lba
prints files which are associated to image data blocks.
It tells the logical block address, the block number, the byte size,
and the path of each file. There may be reported more than one
line per file if the file is very large. In this case each line has a
different extent number in column "xt".
@*
@item getfacl
prints access permissions in ACL text form to the result channel.
@*
@item setfacl
attaches ACLs after removing existing ones. The new
ACL is given in text form as defined with command -setfacl.
@*
E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::@minus{},m::rw @minus{}@minus{}
@*
@item getfattr
prints xattr name-value pairs from user namespace
to the result channel.
@*
@item get_any_xattr
prints xattr name-value pairs from any namespace
except ACL to the result channel. This is mostly for debugging of
namespace "isofs".
@*
@item list_extattr mode
prints a script to the result channel, which would use FreeBSD command
setextattr to set the file's xattr name-value pairs of user namespace.
Parameter mode controls the form of the output of names and values.
Default mode "e" prints harmless characters in shell quotation marks,
but represents texts with octal 001 to 037 and 0177 to 0377 by an embedded
echo -e command.
Mode "q" prints any characters in shell quotation marks. This might not be
terminal-safe but should work in script files.
Mode "r" uses no quotation marks. Not safe.
Mode "b" prints backslash encoding. Not suitable for shell parsing.
@*
E.g. -exec list_extattr e --
@*
Command -backslash_codes does not affect the output.
@*
@item get_md5
prints the MD5 sum, if recorded, together with file path.
@*
@item check_md5
compares the MD5 sum, if recorded, with the file content
and reports if mismatch.
@*
E.g.: -find / -not -pending_data -exec check_md5 FAILURE @minus{}@minus{}
@*
@item make_md5
equips a data file with an MD5 sum of its content. Useful to
upgrade the files in the loaded image to full MD5 coverage by the next
commit with -md5 "on".
@*
E.g.: -find / -type f -not -has_md5 -exec make_md5 @minus{}@minus{}
@*
@item setfattr
sets or deletes xattr name value pairs.
@*
E.g.: -find / -has_xattr -exec setfattr @minus{}@minus{}remove-all '' @minus{}@minus{}
@*
@item set_hfs_crtp
adds, changes, or removes HFS+ creator and type attributes.
@*
E.g.: -exec set_hfs_crtp YYDN TEXT
@*
E.g.: -find /my/dir -prune -exec set_hfs_crtp --delete -
@*
@item get_hfs_crtp
prints the HFS+ creator and type attributes together with the iso_rr_path,
if the file has such attributes at all.
@*
E.g.: -exec get_hfs_crtp
@*
@item set_hfs_bless
applies or removes HFS+ blessings. They are roles which can be attributed to
up to four directories and a data file:
@*
"ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx_folder".
@*
They may be abbreviated as "p", "i", "s", "9", and "x".
@*
Each such role can be attributed to at most one file object. "intel_bootfile"
is the one that would apply to a data file. All others apply to directories.
The -find run will end as soon as the first blessing is issued. The previous
bearer of the blessing will lose it then.
No file object can bear more than one blessing.
@*
E.g.: -find /my/blessed/directory -exec set_hfs_bless p
@*
Further there is blessing "none" or "n" which revokes any blessing from
the found files. This -find run will not stop when the first match is reached.
@*
E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none
@*
@item get_hfs_bless
prints the HFS+ blessing role and the iso_rr_path, if the file is blessed
at all.
@*
E.g.: -exec get_hfs_bless
@*
@item set_filter
applies or removes filters.
@*
E.g.: -exec set_filter @minus{}@minus{}zisofs @minus{}@minus{}
@*
@item mkisofs_r
applies the rules of mkisofs -r to the file object:
@*
user id and group id become 0, all r-permissions get granted, all w denied.
If there is any x-permission, then all three x get granted.
s- and t-bits get removed.
@*
@item sort_weight
attributes a LBA weight number to regular files.
@*
The number may range from -2147483648 to 2147483647. The higher it is, the
lower will be the block address of the file data in the emerging ISO image.
Currently the boot catalog has a hardcoded weight of 1 billion.
Normally it should occupy the block with the lowest possible address.
Data files get added or loaded with initial weight 0.
@*
E.g.: -exec sort_weight 3 @minus{}@minus{}
@*
@item show_stream
shows the content stream chain of a data file.
@*
@item hide
brings the file into one of the hide states "on", "iso_rr", "joliet",
"hfsplus", "off". They may be combined. E.g.: joliet:hfsplus
@*
E.g.:
@*
  -find / -disk_name *_secret -exec hide on
@*
@item estimate_size
prints a lower and an upper estimation of the number of blocks which the
found files together will occupy in the emerging ISO image.
This does not account for the superblock,
for the directories in the -find path, or for image padding.
@*
@item find
performs another run of -find on the matching file address.
It accepts the same params as -find, except iso_rr_path.
@*
E.g.:
@*
  -find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r @minus{}@minus{}
@end table
@end table
@c man .TP
@c man .B Filters for data file content:
@c man .PP
@node Filter, Writing, CmdFind, Commands
@section Filters for data file content
@cindex Filter, _definition
@strong{Filters} may be installed between data files in the ISO image and their
content source outside the image. They may also be used vice versa between
data content in the image and target files on disk.
@*
@sp 1
Built-in filters are "@minus{}@minus{}zisofs" and
"@minus{}@minus{}zisofs-decode". The former is to be
applied via -set_filter, the latter is automatically applied if zisofs
compressed content is detected with a file when loading the ISO image.
@*
Another built-in filter pair is "@minus{}@minus{}gzip"
and "@minus{}@minus{}gunzip" with suffix ".gz".
They behave about like external gzip and gunzip but avoid forking a process
for each single file. So they are much faster if there are many small files.
@c man .PP
@table @asis
@sp 1
@c man .TP
@item -external_filter name option[:option] program_path [arguments] @minus{}@minus{}
@kindex -external_filter   registers data filter
@cindex Filter, register, -external_filter
Register a content filter by associating a name with a program path,
program arguments, and some behavioral options. Once registered it can be
applied to multiple data files in the ISO image, regardless whether their
content resides in the loaded ISO image or in the local filesystem.
External filter processes may produce synthetic file content by reading the
original content from stdin and writing to stdout whatever they want.
They must deliver the same output on the same input in repeated runs.
@*
Options are:
@*
 "default" means that no other option is intended.
@*
 "suffix=..." sets a file name suffix. If it is not empty then it will be
appended to the file name or removed from it.
@*
 "remove_suffix" will remove a file name suffix
rather than appending it.
@*
 "if_nonempty" will leave 0-sized files unfiltered.
@*
 "if_reduction" will try filtering and revoke it if the content size does not
shrink.
@*
 "if_block_reduction" will revoke if the number of 2 kB blocks does not shrink.
@*
 "used=..." is ignored. Command -status shows it with the number of
files which currently have the filter applied.
@*
Examples:
@*
 -external_filter bzip2 suffix=.bz2:if_block_reduction \
@*
                  /usr/bin/bzip2 @minus{}@minus{}
@*
 -external_filter bunzip2 suffix=.bz2:remove_suffix \
@*
                  /usr/bin/bunzip2 @minus{}@minus{}
@c man .TP
@item -unregister_filter name
@kindex -external_filter   unregisters data filter
@cindex Filter, unregister, -unregister_filter
Remove an -external_filter registration. This is only possible if the filter
is not applied to any file in the ISO image.
@c man .TP
@item -close_filter_list
@kindex -close_filter_list   bans filter registration
@cindex Filter, ban registration, -close_filter_list
Irrevocably ban commands -external_filter and -unregister_filter,
but not -set_filter. Use this to prevent external filtering in general or
when all intended filters are registered.
External filters may also be banned totally at compile time of
@command{xorriso}.
By default they are banned if @command{xorriso} runs under setuid permission.
@c man .TP
@item -set_filter name iso_rr_path [***]
@kindex -set_filter   applies filter to file
@cindex Filter, apply to file, -set_filter
Apply an -external_filter or a built-in filter to the given data files in the
ISO image.
If the filter suffix is not empty , then it will be applied to the file name.
Renaming only happens if the filter really gets attached and is not revoked by
its options.
By default files which already bear the suffix will not get filtered. The
others will get the suffix appended to their names.
If the filter has option "remove_suffix", then the filter will only be
applied if the suffix is present and can be removed.
Name oversize or collision caused by suffix change will prevent filtering.
@*
With most filter types this command will immediately run the filter once for
each file in order to determine the output size.
Content reading operations like -extract , -compare and image generation will
perform further filter runs and deliver filtered content.
@*
At image generation time the filter output must still be the same as the
output from the first run. Filtering for image generation does not happen
with files from the loaded ISO image if the write method of growing is in
effect (i.e -indev and -outdev are identical).
@*
The reserved filter name "@minus{}@minus{}remove-all-filters" revokes
filtering. This will revoke suffix renamings as well.
Use "@minus{}@minus{}remove-all-filters+" to
prevent any suffix renaming.
@*
Attaching or detaching filters will not alter the state of -changes_pending.
If the filter manipulations shall be the only changes in a write run, then
explicitely execute -changes_pending "yes".
@c man .TP
@item -set_filter_r name iso_rr_path [***]
@kindex -set_filter_r   applies filter to file tree
@cindex Filter, apply to file tree, -set_filter_r
Like -set_filter but affecting all data files below eventual directories.
@end table
@c man .TP
@c man .B Writing the result, drive control:
@node Writing, SetWrite, Filter, Commands
@section Writing the result, drive control
@c man .PP
(see also paragraph about settings below)
@table @asis
@sp 1
@c man .TP
@item -rollback
@kindex -rollback   discards pending changes
@cindex Image, discard pending changes, -rollback
Discard the manipulated ISO image and reload it from -indev.
(Use -rollback_end if immediate program end is desired.)
@c man .TP
@item -changes_pending "no"|"yes"|"mkisofs_printed"|"show_status"
@kindex -changes_pending   overrides change status
@cindex Image, override change status, -changes_pending
Write runs are performed only if a change of the image has been made 
since the image was loaded or created blank. Vice versa the program will
start a write run for pending changes when it ends normally (i.e. not by abort
and not by command -rollback_end).
@*
The command -changes_pending can be used to override the automatically
determined state. This is mainly useful for setting state "yes" despite
no real changes were made. The sequence -changes_pending "no" -end
is equivalent to the command -rollback_end. State "mkisofs_printed"
is caused by emulation command -as mkisofs if option -print-size is present.
@*
The pseudo-state "show_status" can be used to print the current state to result
channel.
@*
Image loading or manipulations which happen after this command will again
update automatically the change status of the image.
@c man .TP
@item -commit
@kindex -commit   writes pending ISO image
@cindex Write, pending ISO image, -commit
Perform the write operation. Afterwards, if -outdev is readable, make it
the new -dev and load the image from there.
Switch to growing mode.
(A subsequent -outdev will activate modification mode or blind growing.)
-commit is performed automatically at end of program if there
are uncommitted manipulations pending.
@*
So, to perform a final write operation with no new -dev
and no new loading of image, rather execute command -end.
If you want to go on without image loading, execute -commit_eject "none".
To eject after write without image loading, use -commit_eject "all".
@*
To suppress a final write, execute -rollback_end.
@*

Writing can last quite a while. It is not unnormal with several
types of media that there is no progress visible for the first
few minutes or that the drive gnaws on the medium for a few
minutes after all data have been transmitted.
@command{xorriso} and the drives are in a client-server relationship.
The drives have much freedom about what to do with the media.
Some combinations of drives and media simply do not work,
despite the promises by their vendors.
If writing fails then try other media or another drive. The reason
for such failure is hardly ever in the code of the various
burn programs but you may well try some of those listed below
under SEE ALSO.
@c man .TP
@item -eject "in"|"out"|"all"
@kindex -eject    ejects drive tray
@cindex Drive, eject tray, -eject
Eject the medium in -indev, resp. -outdev, resp. both drives.
Note: It is not possible yet to effectively eject disk files.
@c man .TP
@item -commit_eject "in"|"out"|"all"|"none"
@kindex -commit_eject    writes and ejects
@cindex Drive, write and eject, -commit_eject
Combined -commit and -eject. When writing has finished do not make
-outdev the new -dev, and load no ISO image. Rather eject
-indev and/or -outdev. Give up any non-ejected drive.
@c man .TP
@item -blank mode
@kindex -blank   erases media
@cindex Media, erase, -blank
Make media ready for writing from scratch (if not -dummy is activated).
@*
This affects only the -outdev not the -indev.
If both drives are the same and if the ISO image was altered
then this command leads to a FAILURE event.
Defined modes are:
  as_needed, fast, all, deformat, deformat_quickest
@*
"as_needed" cares for used CD-RW, DVD-RW and for used overwriteable media
by applying -blank "fast". It applies -format "full" to  yet unformatted
DVD-RAM and BD-RE. Other media in blank state are gracefully ignored.
Media which cannot be made ready for writing from scratch cause a FAILURE
event.
@*
"fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates
overwriteable ISO images. "all" might work more thoroughly and need more time.
@*
"deformat" converts overwriteable DVD-RW into unformatted ones.
@*
"deformat_quickest" is a faster way to deformat or blank DVD-RW
but produces media which are only suitable for a single session.
Some drives announce this state by not offering feature 21h,
but some drives offer it anyway.
If feature 21h is missing, then @command{xorriso}
will refuse to write on DVD-RW if not command -close is set to "on".
@*
The progress reports issued by some drives while blanking are
quite unrealistic. Do not conclude success or failure from the
reported percentages. Blanking was successful if no SORRY event or
worse occured.
@*
Mode may be prepended by "force:" in order to override the evaluation
of the medium state by libburn. E.g. "force:fast".
Blanking will nevertheless only succeed if the drive is willing to do it.
@*
@c man .TP
@item -format mode
@kindex -format   formats media
@cindex Media, format, -format
Convert unformatted DVD-RW into overwriteable ones, "de-ice" DVD+RW, format
newly purchased BD-RE or BD-R, re-format DVD-RAM or BD-RE.
@*
Defined modes are:
@*
  as_needed, full, fast, by_index_<num>, fast_by_index_<num> 
@*
"as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or blank
unformatted BD-R. Other media are left untouched.
@*
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank unformatted BD-R.
@*
"fast" does the same as "full" but tries to be quicker.
@*
"by_index_" selects a format out of the descriptor list issued by command
-list_formats. The index number from that list is to be appended to the
mode word. E.g: "by_index_3".
@*
"fast_by_index_" does the same as "by_index_" but tries to be quicker.
@*
"by_size_" selects a format out of the descriptor list which provides at
least the given size. That size is to be appended to the mode word.
E.g: "by_size_4100m". This applies to media with Defect Management.
@*
"fast_by_size_" does the same as "by_size_" but tries to be quicker.
@*
The formatting action has no effect on media if -dummy is activated.
@*
Formatting is normally needed only once during the lifetime of a medium,
if ever. But it is a reason for re-formatting if:
@*
 DVD-RW was deformatted by -blank,
@*
 DVD+RW has read failures (re-format before next write),
@*
 DVD-RAM or BD-RE shall change their amount of defect reserve.
@*
BD-R may be written unformatted or may be formatted before first use.
Formatting activates Defect Management which tries to catch and repair
bad spots on media during the write process at the expense of half speed
even with flawless media.
@*
The progress reports issued by some drives while formatting are
quite unrealistic. Do not conclude success or failure from the
reported percentages. Formatting was successful if no SORRY event
or worse occured. Be patient with apparently frozen progress.
@c man .TP
@item -list_formats
@kindex -list_formats   lists available formats
@cindex Media, list formats, -list_formats
Put out a list of format descriptors as reported by the output drive for
the current medium. The list gives the index number after "Format idx",
a MMC format code, the announced size in blocks (like "2236704s")
and the same size in MiB. 
@*
MMC format codes are manifold. Most important are:
"00h" general formatting, "01h" increases reserve space for DVD-RAM,
"26h" for DVD+RW, "30h" for BD-RE with reserve space,
"31h" for BD-RE without reserve space, "32h" for BD-R.
@*
Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve space.
@c man .TP
@item -list_speeds
@kindex -list_speeds   lists available write speeds
@cindex Media, list write speeds, -list_speeds
Put out a list of speed values as reported by the output drive with
the loaded medium. This does not necessarily mean that the medium is writable
or that these speeds are actually achievable. Especially the
lists reported with empty drive or with ROM media obviously advertise
speeds for other media.
@*
It is not mandatory to use speed values out of the listed range.
The drive is supposed to choose a safe speed that is as near to the desired
speed as possible.
@*
At the end of the list, "Write speed L" and "Write speed H"
are the best guesses for lower and upper speed limit.
"Write speed l" and "Write speed h" may appear only with CD
and eventually override the list of other speed offers.
@*
Only if the drive reports contradicting speed information there will appear
"Write speed 0", which tells the outcome of speed selection by command
-speed 0, if it deviates from "Write speed H".
@c man .TP
@item -close_damaged "as_needed"|"force"
@kindex -close_damaged   closes damaged track and session
@cindex Damaged track and session, close, -close_damaged
Try to close the upcomming track and session if the drive reported the medium
as damaged. This may apply to CD-R, CD-RW, DVD-R, DVD-RW, DVD+R, DVD+R DL,
or BD-R media. It is indicated by warning messages when the drive gets
acquired, and by a remark "but next track is damaged" with the line
"Media status :" of command -toc.
@*
The setting of command -close determines whether the medium stays appendable.
@*
Mode "as_needed" gracefully refuses on media which are not reported as
damaged. Mode "force" attempts the close operation even with media which
appear undamaged.
@*
No image changes are allowed to be pending before this command is performed.
After closing was attempted, both drives are given up.
@c man .TP
@item -list_profiles "in"|"out"|"all"
@kindex -list_profiles   lists supported media
@cindex Drive, list supported media, -list_profiles
Put out a list of media types supported by -indev, resp. -outdev, resp. both.
The currently recognized type is marked by text "(current)".
@end table
@c man .TP
@c man .B Settings for result writing:
@node SetWrite, Bootable, Writing, Commands
@section Settings for result writing
@c man .PP
Rock Ridge info will be generated by default.
ACLs will be written according to the setting of command -acl.
@table @asis
@sp 1
@c man .TP
@item -joliet "on"|"off"
@kindex -joliet   enables production of Joliet tree
@cindex Write, enable Joliet, -joliet
If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge
tree.
@sp 1
@c man .TP
@item -hfsplus "on"|"off"
@kindex -hfsplus   enables production of HFS+ partition
@cindex Write, enable HFS+, -hfsplus
If enabled by "on", generate a HFS+ filesystem inside the ISO 9660 image
and mark it by Apple Partition Map (APM) entries in the System Area,
the first 32 KiB of the image.
@*
This may collide with data submitted by -boot_image system_area=.
The first 8 bytes of the System Area get overwritten by
@{ 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff @}
which can be executed as x86 machine code without negative effects.
So if an MBR gets combined with this feature, then its first 8 bytes
should contain no essential commands.
@*
The next blocks of 2 KiB in the System Area will be occupied by APM entries.
The first one covers the part of the ISO image before the HFS+ filesystem
metadata. The second one marks the range from HFS+ metadata to the end
of file content data. If more ISO image data follow, then a third partition
entry gets produced. Other features of xorriso might cause the need for
more APM entries.
@*
The HFS+ filesystem is not suitable for add-on sessions produced by the
multi-session method of growing. An existing ISO image may nevertheless
be the base for a new image produced by the method of modifying.
If -hfsplus is enabled when -indev or -dev gets executed, then AAIP
attributes get loaded from the input image and checked for information about
HFS creator, filetype, or blessing. If found, then they get enabled as
settings for the next image production.
Therefore it is advisable to perform -hfsplus "on" before -indev or -dev.
@*
Information about HFS creator, type, and blessings gets stored by xorriso
if -hfsplus is enabled at -commit time. It is stored as copy outside the
HFS+ partition, but rather along with the Rock Ridge information.
xorriso does not read any information from the HFS+ meta data.
@*
Be aware that HFS+ is case-insensitive although it can record file names
with upper-case and lower-case letters. Therefore, file names from the iso_rr
name tree may collide in the HFS+ name tree. In this case they get changed
by adding underscore characters and counting numbers. In case of very long
names, it might be necessary to map them to "MANGLED_...".
@sp 1
@c man .TP
@item -rockridge "on"|"off"
@kindex -rockridge   disables production of Rock Ridge info
@cindex Write, disable Rock Ridge, -rockridge
Mode "off" disables production of Rock Ridge information for the ISO 9660 file
objects. The multi-session capabilities of xorriso depend much on the naming
fidelity of Rock Ridge. So it is strongly discouraged to deviate from
default setting "on".
@c man .TP
@item -compliance rule[:rule...]
@kindex -compliance   controls standard compliance
@cindex Write, compliance to specs, -compliance
Adjust the compliance to specifications of ISO 9660/ECMA-119 and its
contemporary extensions. In some
cases it is worth to deviate a bit in order to circumvent bugs of the intended
reader system or to get unofficial extra features.
@*
There are several adjustable rules which have a keyword each. If they
are mentioned with this command then their rule gets added to the relaxation
list. This list can be erased by rules "strict" or "clear". It can be reset
to its start setting by "default". All of the following relaxation rules
can be revoked individually by appending "_off". Like "deep_paths_off".
@*
Rule keywords are:
@*
"iso_9660_level="number chooses level 1 with ECMA-119 names of the form 8.3
and -file_size_limit <= 4g - 1, or level 2 with ECMA-119 names up to
length 32 and the same -file_size_limit, or level 3 with ECMA-119 names up to
length 32 and -file_size_limit >= 400g -200k. If necessary -file_size_limit
gets adjusted.
@*
"allow_dir_id_ext" allows ECMA-119 names of directories to have a name extension
as with other file types. It does not force dots and it omits the version
number, though. This is a bad tradition of mkisofs which violates ECMA-119.
Especially ISO level 1 only allows 8 characters in a directory name and
not 8.3.
@*
"omit_version" does not add versions (";1") to ECMA-119 and Joliet file names.
@*
"only_iso_version" does not add versions (";1") to Joliet file names.
@*
"deep_paths" allows ECMA-119 file paths deeper than 8 levels.
@*
"long_paths" allows ECMA-119 file paths longer than 255 characters.
@*
"long_names" allows up to 37 characters with ECMA-119 file names.
@*
"no_force_dots" does not add a dot to ECMA-119 file names which have none.
@*
"no_j_force_dots" does not add a dot to Joliet file names which have none.
@*
"lowercase" allows lowercase characters in ECMA-119 file names.
@*
"7bit_ascii" allows nearly all 7-bit characters in ECMA-119 file names.
Not allowed are 0x0 and '/'. If not "lowercase" is enabled, then lowercase
letters get converted to uppercase.
@*
"full_ascii" allows all 8-bit characters except 0x0 and '/'
in ECMA-119 file names.
@*
"untranslated_names" might be dangerous for inadverted reader programs
which rely on the restriction to at most 37 characters in ECMA-119 file names.
This rule allows ECMA-119 file names up to 96 characters with no character
conversion. If a file name has more characters, then image production will
fail deliberately.
@*
"untranslated_name_len="number enables untranslated_names with a smaller limit
for the length of file names. 0 disables this feature, -1 chooses maximum
length limit, numbers larger than 0 give the desired length limit.
@*
"joliet_long_names" allows Joliet leaf names up to 103 characters rather
than 64.
@*
"joliet_long_paths" allows Joliet paths longer than 240 characters.
@*
"always_gmt" stores timestamps in GMT representation with timezone 0.
@*
"rec_mtime" records with non-RockRidge directory entries the disk file's
mtime and not the creation time of the image. This applies to the ECMA-119
tree (plain ISO 9660), to Joliet, and to ISO 9660:1999. "rec_time" is
default. If disabled, it gets automatically re-enabled by -as mkisofs emulation
when a pathspec is encountered.
@*
"new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux but not for older
FreeBSD or for Solaris). This implies "aaip_susp_1_10_off" which may be changed
by subsequent "aaip_susp_1_10".
@*
Default is "old_rr" which uses Rock Ridge version 1.10. This implies also 
"aaip_susp_1_10" which may be changed by subsequent "aaip_susp_1_10_off".
@*
"aaip_susp_1_10" allows AAIP to be written as unofficial extension of RRIP
rather than as official extension under SUSP-1.12.
@*
"no_emul_toc" saves 64 kB with the first session on overwriteable media
but makes the image incapable of displaying its session history.
@*
"iso_9660_1999" causes the production of an additional directory tree
compliant to ISO 9660:1999. It can record long filenames for readers which
do not understand Rock Ridge.
@*
"old_empty" uses the old way of of giving block addresses in the range
of [0,31] to files with no own data content. The new way is to have
a dedicated block to which all such files will point.
@*
Default setting is
@*
 "clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
@*
 always_gmt:old_rr".
@*
Note: The term "ECMA-119 name" means the plain ISO 9660 names and attributes
which get visible if the reader ignores Rock Ridge.
@c man .TP
@item -rr_reloc_dir name
@kindex -rr_reloc_dir   sets name of relocation directory
@cindex Relocation directory, set name, -rr_reloc_dir
Specify the name of the relocation directory in which deep directory subtrees
shall be placed if -compliance is set to "deep_paths_off" or "long_paths_off".
A deep directory is one that has a chain of 8 parent directories (including
root) above itself, or one that contains a file with an ECMA-119 path of more
than 255 characters.
@*
The overall directory tree will appear originally deep when interpreted
as Rock Ridge tree. It will appear as re-arranged if only ECMA-119
information is considered.
@*
The default relocation directory is the root directory. By giving a non-empty
name with -rr_reloc_dir, a directory in the root directory may get this role.
If that directory does not already exist at -commit time, then it will get
created and marked for Rock Ridge as relocation artefact. At least on
GNU/Linux it will not be displayed in mounted Rock Ridge images.
@*
The name must not contain a '/' character and must not be longer than
255 bytes.
@c man .TP
@item -volid text
@kindex -volid   sets volume id
@cindex Image, set volume id, -volid
Specify the volume ID, which most operating systems will consider to be
the volume name of the image or medium.
@*
@command{xorriso} accepts any text up to 32 characters,
but according to rarely obeyed specs stricter rules apply:
@*
ECMA-119 demands ASCII characters out of [A-Z0-9_]. Like:
@*
  "IMAGE_23"
@*
Joliet allows 16 UCS-2 characters. Like:
@*
  "Windows name"
@*
Be aware that the volume id might get used automatically as the name of the
mount point when the medium is inserted into a playful computer system.
@*
If an ISO image gets loaded while the volume ID is set to default "ISOIMAGE"
or to "", then the volume ID of the loaded image will become the effective
volume id for the next write run. But as soon as command -volid is performed
afterwards, this pending ID is overridden by the new setting.
@*
Consider this when setting -volid "ISOIMAGE" before executing -dev, -indev,
or -rollback.
If you insist in -volid "ISOIMAGE", set it again after those commands.
@c man .TP
@item -volset_id text
@kindex -volset_id   sets volume set id
@cindex Image, set volume set id, -volset_id
Set the volume set ID string to be written with the next -commit.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
@c man .TP
@item -publisher text
@kindex -publisher   sets publisher id
@cindex Image, set publisher id, -publisher
Set the publisher ID string to be written with the next -commit. This may
identify the person or organisation who specified what shall be recorded.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
@c man .TP
@item -application_id text
@kindex -application_id   sets application id
@cindex Image, set application id, -application_id
Set the application ID string to be written with the next -commit. This may
identify the specification of how the data are recorded.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
@*
The special text "@@xorriso@@" gets converted to the ID string of
@command{xorriso}
which is normally written as -preparer_id. It is a wrong tradition to write
the program ID as -application_id.
@c man .TP
@item -system_id text
@kindex -system_id   sets system id
@cindex Image, set system id, -system_id
Set the system ID string to be written with the next -commit. This may
identify the system which can recognize and act upon the content of the
System Area in image blocks 0 to 15.
Permissible are up to 32 characters. This setting gets overridden by
image loading.
@c man .TP
@item -volume_date type timestring
@kindex -volume_date   sets volume timestamp
@cindex Image, set volume timestamp, -volume_date
Set one of the four overall timestamps for subsequent image writing.
Available types are:
@*
"c"  time when the volume was created.
@*
"m"  time when volume was last modified.
@*
"x"  time when the information in the volume expires.
@*
"f"  time since when the volume is effectively valid.
@*
"uuid"  sets a timestring that overrides "c" and "m" times literally.
It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc, with
YYYY between 1970 and 2999. Time zone is GMT.
It is supposed to match this GRUB line:
@*
 search @minus{}@minus{}fs-uuid @minus{}@minus{}set YYYY-MM-DD-hh-mm-ss-cc
@*
E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
@*
Timestrings for the other types may be given as with command -alter_date.
Some of them are prone to timezone computations. The timestrings "default" or
"overridden" cause default settings: "c" and "m" will show the current time
of image creation. "x" and "f" will be marked as insignificant.
"uuid" will be deactivated.
@c man .TP
@item -copyright_file text
@kindex -copyright_file   sets copyright file name
@cindex Image, set copyright file name, -copyright_file
Set the copyright file name to be written with the next -commit. This should
be the ISO 9660 path of a file in the image which contains a copyright
statement.
Permissible are up to 37 characters. This setting gets overridden by
image loading.
@c man .TP
@item -abstract_file text
@kindex -abstract_file   sets abstract file name
@cindex Image, set abstract file name, -abstract_file
Set the abstract file name to be written with the next -commit. This should
be the ISO 9660 path of a file in the image which contains an abstract
statement about the image content.
Permissible are up to 37 characters. This setting gets overridden by
image loading.
@c man .TP
@item -biblio_file text
@kindex -biblio_file   sets biblio file name
@cindex Image, set biblio file name, -biblio_file
Set the biblio file name to be written with the next -commit. This should
be the ISO 9660 path of a file in the image which contains bibliographic
records.
Permissible are up to 37 characters. This setting gets overridden by
image loading.
@c man .TP
@item -preparer_id
@kindex -preparer_id   sets preparer id
@cindex Image, set preparer id, -preparer_id
Set the preparer ID string to be written with the next -commit. This may
identify the person or other entity which controls the preparation of the data
which shall be recorded. Normally this should be the ID of @command{xorriso}
and not of the person or program which operates @command{xorriso}.
Please avoid to change it.  Permissible are up to 128 characters.
@*
The special text "@@xorriso@@" gets converted to the ID string of
@command{xorriso} which is default at program startup.
@*
Unlike other ID strings, this setting is not influenced by image loading.
@c man .TP
@item -out_charset character_set_name
@kindex -out_charset   sets output character set
@cindex Character Set, for output, -out_charset
Set the character set to which file names get converted when writing an
image. See paragraph "Character sets" for more explanations.
When loading the written image after -commit the setting of -out_charset
will be copied to -in_charset.
@c man .TP
@item -uid uid
@kindex -uid   sets global ownership
@cindex Ownership, global in ISO image, -uid
User id to be used for all files when the new ISO tree gets written to media.
@c man .TP
@item -gid gid
@kindex -gid   sets global ownership
@cindex Group, global in ISO image, -gid
Group id to be used for all files when the new ISO tree gets written to media.
@c man .TP
@item -zisofs option[:options]
@kindex -zisofs   controls zisofs production
@cindex Filter, zisofs parameters, -zisofs
Set global parameters for zisofs compression. This data format is recognized
and transparently uncompressed by some Linux kernels. It is to be applied
via command -set_filter with built-in filter "@minus{}@minus{}zisofs".
Parameters are:
@*
 "level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
@*
 "block_size="32k|64k|128k size of compression blocks
@*
 "by_magic=on" enables an expensive test at image generation time which checks
files from disk whether they already are zisofs compressed, e.g. by program
mkzftree.
@*
 "default" same as "level=6:block_size=32k:by_magic=off"
@c man .TP
@item -speed number[k|m|c|d|b]
@kindex -speed   set write speed
@cindex Write, set speed, -speed
Set the burn speed. Default is 0 = maximum speed.
Speed can be given in media dependent numbers or as a
desired throughput per second in MMC compliant kB (= 1000)
or MB (= 1000 kB). Media x-speed factor can be set explicity
by "c" for CD, "d" for DVD, "b" for BD, "x" is optional.
@*
Example speeds:
@*
 706k = 706kB/s = 4c = 4xCD
@*
 5540k = 5540kB/s = 4d = 4xDVD
@*
If there is no hint about the speed unit attached, then the
medium in the -outdev will decide. Default unit is CD = 176.4k.
@*
MMC drives usually activate their own idea of speed and take
the speed value given by the burn program only as upper limit
for their own decision.
@c man .TP
@item -stream_recording "on"|"off"|"full"|"data"|number
@kindex -stream_recording   controls defect management
@cindex Write, defect management, -stream_recording
Setting "on" tries to circumvent the management of defects on DVD-RAM, BD-RE,
or BD-R. Defect management keeps partly damaged media usable. But it reduces
write speed to half nominal speed even if the medium is in perfect shape.
For the case of flawless media, one may use -stream_recording "on" to get
full speed. 
@*
"full" tries full speed with all write operations, whereas "on" does this
only above byte address 32s. One may give a number of at least 16s
in order to set an own address limit.
@*
"data" causes full speed to start when superblock and directory entries are
written and writing of file content blocks begins.
@c man .TP
@item -dvd_obs "default"|"32k"|"64k"
@kindex -dvd_obs   set write block size
@cindex Write, block size, -dvd_obs
GNU/Linux specific:
Set the number of bytes to be transmitted with each write operation to DVD
or BD media. A number of 64 KB may improve throughput with bus systems which
show latency problems. The default depends on media type, on command
-stream_recording , and on compile time options.
@c man .TP
@item -stdio_sync "on"|"off"|number
@kindex -stdio_sync   controls stdio buffer
@cindex Write, buffer syncing, -stdio_sync
Set the number of bytes after which to force output to stdio: pseudo drives.
This forcing keeps the memory from being clogged with lots of
pending data for slow devices. Default "on" is the same as "16m".
Forced output can be disabled by "off".
@c man .TP
@item -dummy "on"|"off"
@kindex -dummy   controls write simulation
@cindex Write, simulation, -dummy
If "on" then simulate burning or refuse with FAILURE event if
no simulation is possible, do neither blank nor format.
@c man .TP
@item -fs number["k"|"m"]
@kindex -fs   sets size of fifo
@cindex Write, fifo size, -fs
Set the size of the fifo buffer which smoothens the data
stream from ISO image generation to media burning. Default
is 4 MiB, minimum 64 kiB, maximum 1 GiB.
The number may be followed by letter "k" or "m"
which means unit is kiB (= 1024) or MiB (= 1024 kiB).
@c man .TP
@item -close "on"|"off"
@kindex -close   controls media closing
@cindex Write, close media, -close
If "on" then mark the written medium as not appendable
any more (if possible at all with the given type of target media).
@*
This is the contrary of cdrecord, wodim, cdrskin command -multi,
and is one aspect of growisofs option -dvd-compat.
@c man .TP
@item -write_type "auto"|"tao"|"sao/dao"
@kindex -write_type   chooses TAO or SAO/DAO
@cindex Write, TAO or SAO/DAO, -write_type
Set the write type for the next burn run. "auto" will select SAO with blank
CD media, DAO with blank DVD-R[W] if -close is "on", and elsewise CD TAO or the
equivalent write type of the particular DVD/BD media.
Choosing TAO or SAO/DAO explicitely might cause the burn run to fail if the
desired write type is not possible with the given media state.
@c man .TP
@item -padding number["k"|"m"]|"included"|"appended"
@kindex -padding   sets amount or mode of image padding
@cindex Write, padding image, -padding
Append the given number of extra bytes to the image stream.
This is a traditional remedy for a traditional bug in block
device read drivers. Needed only for CD recordings in TAO mode.
Since one can hardly predict on what media an image might end up,
@command{xorriso} adds the traditional 300k of padding by default to
all images.
@*
For images which will never get to a CD it is safe to use -padding 0 .
@*
Normally padding is not written as part of the ISO image but appended
after the image end. This is -padding mode "appended".
@*
Emulation command -as "mkisofs" and command -jigdo cause padding to be
written as part of the image.
The same effect is achieved by -padding mode "included".
@end table
@c man .TP
@c man .B Bootable ISO images:
@node Bootable, Jigdo, SetWrite, Commands
@section Bootable ISO images
@c man .PP
Contrary to published specifications many BIOSes will load an El Torito
record from the first session on media and not from the last one, which
gets mounted by default. This makes no problems with overwriteable media,
because they appear to inadverted readers as one single session.
@*
But with multi-session media CD-R[W], DVD-R[W], DVD+R, it implies that the
whole bootable system has to reside already in the first session and that
the last session still has to bear all files which the booted system expects
after mounting the ISO image.
@*
If a boot image from ISOLINUX or GRUB is known to be present on media then
it is advised to patch it
when a follow-up session gets written. But one should not rely on the
capability to influence the bootability of the existing sessions, unless one
can assume overwriteable media.
@*
There are booting mechanisms which do not use an El Torito record but rather
start at the first bytes of the image: PC-BIOS MBR for hard-disk-like devices,
MIPS Volume Header for old SGI computers, DEC Boot Block for old DECstation,
SUN Disk Label for SPARC machines.
@*
The boot firmware EFI may use programs which are located in a FAT filesystem
and announced by an MBR partition table entry.
@*
@table @asis
@sp 1
@c man .TP
@item -boot_image "any"|"isolinux"|"grub"
@kindex -boot_image   controls bootability
@cindex Write, bootability, -boot_image
@cindex Bootability, control, -boot_image
@*
     "discard"|"keep"|"patch"|"show_status"|bootspec|"next"
@*
@sp 1
Define the handling of a set of El Torito boot images which
has been read from an existing ISO image or define how to make a prepared
boot image file set bootable. Such file sets get produced by ISOLINUX or GRUB.
@*
Each -boot_image command has two parameters: type and setting. More than one
-boot_image command may be used to define the handling of one or more boot
images. Sequence matters.
@*
Types @strong{isolinux} and @strong{grub} care for known peculiarities.
Type @strong{any} makes
no assumptions about the origin of the boot images.
@*
@sp 1

El Torito boot images of any type can be newly inserted, or discarded,
or patched, or kept unaltered.
Whether to patch or to keep depends on whether
the boot images contain boot info tables.
@*
A boot info table needs to be patched when the boot image gets newly
introduced into the ISO image or if an existing image gets relocated.
This is automatically done if type "isolinux" or "grub"
is given, but not with "any".
@*
If patching is enabled, then boot images from previous sessions will
be checked whether they seem to bear a boot info table. If not,
then they stay unpatched. This check is not infallible. So if
you do know that the images need no patching, use "any" "keep".
"grub" "patch" will not patch EFI images (platform_id=0xef).
@*
Most safe is the default: -boot_image "any" "discard".
@*
Advised for GRUB :  -boot_image "grub" "patch"
@*
For ISOLINUX :  -boot_image "isolinux" "patch"
@*
@strong{show_status} will print what is known about the loaded boot images
and their designated fate.
@*
@sp 1

A @strong{bootspec} is a word of the form name=value. It is used to describe
the parameters of a boot image by an El Torito record or a MBR.
The names "dir", "bin_path", "efi_path" lead to El Torito bootable images.
Name "system_area" activates a given file as MBR.
@*
On all media types this is possible within the first session. In further
sessions an existing boot image can get replaced by a new one, but depending
on the media type this may have few effect at boot time. See above.
@*
The boot image and its supporting files have to be added to the ISO image by
normal means (image loading, -map, -add, ...). In case of ISOLINUX the files
should reside either in ISO image directory /isolinux or in /boot/isolinux .
In that case it suffices to use as bootspec the text "dir=/isolinux" or
"dir=/boot/isolinux". E.g.:
@*
 -boot_image isolinux dir=/boot/isolinux
@*
which bundles these individual settings:
@*
 -boot_image isolinux bin_path=/boot/isolinux/isolinux.bin
@*
 -boot_image isolinux cat_path=/boot/isolinux/boot.cat
@*
 -boot_image isolinux load_size=2048
@*
 -boot_image any boot_info_table=on
@*
An El Torito boot catalog file gets inserted into the ISO image with address
@strong{cat_path=} at -commit time.
It is subject to normal -overwrite and -reassure processing if there is already
a file with the same name.
The catalog lists the boot images and is read by the boot facility to choose
one of the boot images. But it is not necessary that it appears in the
directory tree at all. One may hide it in all trees by @strong{cat_hidden=on}.
Other possible values are "iso_rr", "joliet", "hfsplus", and the default "off".
@*
@strong{bin_path=} depicts a boot image file, a binary program which is to be
started by the hardware boot facility (e.g. the BIOS) at boot time.
@*
@strong{efi_path=} depicts a boot image file that is ready for EFI booting.
Its load_size is determined automatically, no boot info table gets
written, no boot medium gets emulated, platform_id is 0xef.
@*
@strong{emul_type=} can be one of "no_emulation", "hard_disk", "diskette".
It controls the boot medium emulation code of a boot image.
The default "no_emulation" is suitable for ISOLINUX, GRUB, FreeBSD cdboot.
@*
@strong{load_size=} is a value which depends on the boot image.
Default 2048 should be overridden only if a better value is known.
@*
@strong{boot_info_table=on} causes address patching to bytes 8 to 63
of the boot image which is given by "any" "bin_path=".
"boot_info_table=off" disables this patching.
@*
@strong{grub2_boot_info=on} causes address patching to byte 2548
of the boot image which is given by "any" "bin_path=".
The address is written as 64 bit little-endian number. It is the
2KB block address of the boot image content, multiplied by 4,
and then incremented by 5.
"grub2_boot_info=off" disables this patching.
@*
@strong{platform_id=} defines by two hex digits the Platform ID of the
boot image. "00" is 80x86 PC-BIOS, "01" is PowerPC, "02" is Mac, "ef" is EFI.
@*
@strong{id_string=}text|56_hexdigits defines the ID string of the boot catalog
section where the boot image will be listed. If the value consists of 56
characters [0-9A-Fa-f] then it is converted into 28 bytes, else the first
28 characters become the ID string.
The ID string of the first boot image becomes the overall catalog ID.
It is limited to 24 characters. Other id_strings become section IDs.
@*
@strong{sel_crit=}hexdigits defines the Selection Criteria of the boot image.
Up to 20 bytes get read from the given characters [0-9A-Fa-f].
They get attributed to the boot image entry in the catalog.
@*
@strong{next} ends the definition of a boot image and starts a new one.
Any following -bootimage bootspecs will affect the new image.
The first "next" discards loaded boot images and their catalog.
@*
@strong{discard} gives up an existing boot catalog and its boot images.
@*
@strong{keep} keeps or copies boot images unaltered and writes a new catalog.
@*
@strong{patch} applies patching to existing boot images
if they seem to bear a boot info table.
@*
@cindex System area, _definition
@cindex MBR, set, -boot_image system_area=
@strong{system_area=}disk_path copies at most 32768 bytes from the given
disk file to the very start of the ISO image.
This System Area is reserved for system dependent boot software, e.g. an MBR
which can be used to boot from USB stick or hard disk.
@*
Other than a El Torito boot image, the file disk_path needs not to be added
to the ISO image.
@*
-boot_image isolinux system_area= implies "partition_table=on".
@*
@strong{grub2_mbr=}disk_path works like "any" system_area= with additional
patching for modern GRUB MBRs. The content start address of the first boot
image is converted to a count of 512 byte blocks, and an offset of 4 is added.
The result is written as 64 bit little-endian number to byte address 0x1b0.
@*
@cindex Partition table, _definition
@strong{partition_table=on} causes a simple partition table to be written
into bytes 446 to 511 of the System Area.
@*
With type "isolinux" it shows a partition that begins at byte 0 and it causes
the LBA of the first boot image to be written into the MBR. For the first
session this works only if also "system_area=" and "bin_path=" or "dir="
is given.
@*
With types "any" and "grub" it shows a single
partition which starts at byte 512 and ends where the ISO image ends.
This works with or without system_area= or boot image.
@*
Bootspecs chrp_boot_part=, prep_boot_part=, and efi_boot_part= overwrite
this entry in the MBR partition table. 
@*
In follow-up sessions the existing System Area is preserved by default.
If types "isolinux" or "grub" are set to "patch", then "partition_table=on"
is activated without new boot image.
In this case the existing System Area gets checked whether it bears addresses
and sizes as if it had been processed by "partition_table=on". If so,
then those parameters get updated when the new System Area is written.
@*
Special "system_area=/dev/zero" causes 32k of NUL-bytes.
Use this to discard an MBR which was loaded with the ISO image.
@*
@cindex CHRP partition, _definition
@strong{chrp_boot_part=on} causes a single partition in MBR which covers
the whole ISO image and has type 0x41. This is not compatible with any
other feature that produces MBR partition entries. It makes GPT unrecognizable.
@*
@cindex PReP partition, _definition
@strong{prep_boot_part=} inserts the content of a data file into the image and
marks it by an MBR partition of type 0x96. The parts of the ISO image before
and after this partition will be covered by further MBR partitions.
The data file is supposed to contain ELF executable code.
@*
@cindex EFI system partition, _definition
@strong{efi_boot_part=} inserts the content of a data file into the image and
marks it by a GPT partition. If not chrp_boot_part=on, then the first partition
in MBR will have type 0xee to announce the presence of GPT.
The data file is supposed to contain a FAT filesystem.
@*
Instead of a disk_path, the word @minus{}@minus{}efi-boot-image may be given.
It exposes in GPT the content of the first El Torito EFI boot image as
EFI system partition. EFI boot images are introduced by bootspec efi_path=.
The affected EFI boot image cannot show up in HFS+ because it is stored
outside the HFS+ partition.
@*
@cindex Partition offset, _definition
@strong{partition_offset=}2kb_block_adr causes a partition table with a single
partition that begins at the given block address. This is counted in 2048 byte
blocks, not in 512 byte blocks. If the block address is non-zero then it must
be at least 16. A non-zero partition offset causes two superblocks to be
generated and two sets of directory trees. The image is then mountable from its
absolute start as well as from the partition start.
@*
The offset value of an ISO image gets preserved when a new session is added.
So the value defined here is only in effect if a new ISO image gets written.
@*
@cindex Cylinder size, _definition
@strong{partition_hd_cyl=}number gives the number of heads per cylinder for
the partition table. 0 chooses a default value. Maximum is 255.
@*
@strong{partition_sec_hd=}number gives the number of sectors per head for
the partition table. 0 chooses a default value. Maximum is 63.
@*
The product partition_sec_hd * partition_hd_cyl * 512 is the cylinder size.
It should be divisible by 2048 in order to allow exact alignment.
If it is too small to describe the image size by at most 1024 cylinders,
then appropriate values of partition_hd_cyl are chosen with
partition_sec_hd 32 or 63. If the image is larger than 8,422,686,720 bytes,
then the cylinder size constraints cannot be fulfilled.
@*
@cindex Cylinder alignment, _definition
@strong{partition_cyl_align=}mode controls image size alignment to an integer
number of cylinders. It is prescribed by isohybrid specs and it seems to
please program fdisk. Cylinder size must be divisible by 2048.
Images larger than 8,323,596,288 bytes cannot be aligned.
@*
Mode "auto" is default. Alignment by padding happens only with 
"isolinux" "partition_table=on".
@*
Mode "on" causes alignment by padding with "partition_table=on" for any type.
Mode "all" is like "on" but also pads up partitions from -append_partition
to an aligned size.
@*
Mode "off" disables alignment for any type.
@*
@cindex MIPS boot file, activation
@strong{mips_path=}iso_rr_path declares a data file in the image to be a
MIPS Big Endian boot file and causes production of a MIPS Big Endian Volume
Header. This is mutually exclusive with production of other boot blocks
like MBR.
It will overwrite the first 512 bytes of any data provided by system_area=.
Up to 15 boot files can be declared by mips_path=.
@*
@strong{mipsel_path=}iso_rr_path declares a data file in the image to be the
MIPS Little Endian boot file. This is mutually exclusive with other boot
blocks.
It will overwrite the first 512 bytes of any data provided by system_area=.
Only a single boot file can be declared by mipsel_path=.
@*
@cindex SUN Disk Label, production
@strong{sparc_label=}text causes the production of a SUN Disk Label with the
given text as ASCII label. This boot block format allows to append images
for partitions 2 to 8. Partition 1 will always be the ISO image.
See command -append_partition.
The first 512 bytes of any data provided by system_area= will be overwritten.
@*
@strong{grub2_sparc_core=}iso_rr_path causes the content address and size
of the given file to be written after the SUN Disk Label. Both numbers are
counted in bytes. The address is written as 64 bit big-endian number to
byte 0x228. The size is written as 32 bit big-endian number to byte 0x230.
@*
@strong{mips_discard} and @strong{sparc_discard} revoke any boot file
declarations made by mips_path= or mipsel_path=. They also disable production
of SUN Disk Label.
This removes the ban on production of other boot blocks.
@*
@cindex HFS+ serial number
@strong{hfsplus_serial=}hexstring sets a string of 16 digits "0" to "9"
and letters "a" to "f", which will be used as unique serial number of
an emerging HFS+ filesystem.
@*
@cindex HFS+ allocation block size
@strong{hfsplus_block_size=}number sets the allocation block size to
be used when producing HFS+ filesystems. Permissible are 512, 2048, or 0.
The latter lets the program decide.
@*
@cindex APM block size
@strong{apm_block_size=}number sets the block size to be used when
describing partitions by an Apple Partition Map. Permissible are 512, 2048,
or 0. The latter lets the program decide.
@*
Note that size 512 is not compatible with production of GPT, and that
size 2048 will not be mountable -t hfsplus at least by older Linux kernels.
@end table
@*
@table @asis
@sp 1
@c man .TP
@item -append_partition partition_number type_code disk_path
@kindex -append_partition   adds arbitrary file after image end
@cindex Appended Filesystem Image, -append_partition
Cause a prepared filesystem image to be appended to the ISO image and to be
described by a partition table entry in a boot block at the start of the
emerging ISO image. The partition entry will bear the size of the submitted
file rounded up to the next multiple of 2048 bytes or to the next multiple
of the cylinder size.
@*
Beware of subsequent multi-session runs. The appended partition will get
overwritten.
@*
Partitions may be appended with boot block type MBR and with SUN Disk Label.
@*
With MBR:
@*
partition_number may be 1 to 4. Number 1 will put the whole ISO image into
the unclaimed space before partition 1. So together with most @command{xorriso}
MBR features, number 2 would be the most natural choice.
@*
The type_code may be "FAT12", "FAT16", "Linux",
or a hexadecimal number between 0x00 and 0xff. Not all those numbers will
yield usable results. For a list of codes search the Internet for
"Partition Types" or run fdisk command "L".
@*
The disk_path must provide the necessary data bytes at commit time.
An empty disk_path disables this feature for the given partition number.
@*
@cindex SUN SPARC boot images, activation
With SUN Disk Label (selected by -boot_image any sparc_label=):
@*
partition_number may be 2 to 8. Number 1 will always be the ISO image.
Partition start addresses are aligned to 320 KiB. The type_code does not
matter. Submit 0x0.
@*
Partition image name "." causes the partition to become a copy of the next
lower valid one.
@end table
@c man .TP
@c man .B Jigdo Template Extraction:
@node Jigdo, Charset, Bootable, Commands
@section Jigdo Template Extraction
@c man .PP
@cindex Jigdo Template Extraction, _definition
From man genisoimage:
"Jigdo is a tool to help in the distribution of large files like CD and
DVD images; see http://atterer.net/jigdo/ for more details. Debian CDs
and DVD ISO images are published on the web in jigdo format to allow
end users to download them more efficiently."
@*
@command{xorriso} can produce a .jigdo and a .template file together with a
single-session ISO image.
The .jigdo file contains checksums and symbolic file addresses.
The .template file contains the compressed ISO image with reference tags
instead of the content bytes of the listed files.
@*
Input for this process are the normal arguments for a @command{xorriso} session
on a blank -outdev, and a .md5 file which lists those data files which may be
listed in the .jigdo file and externally referenced in the .template file.
Each designated file is represented in the .md5 file by a single text line:
@*
MD5 as 32 hex digits, 2 blanks, size as 12 decimal digits or blanks, 2 blanks,
symbolic file address
@*
The file address in an .md5 line has to bear the same basename as the
disk_path of the file which it shall match. The directory path of
the file address is decisive for To=From mapping, not for file recognition.
After To=From mapping, the file address gets written into the .jigdo
file. Jigdo restore tools will convert these addresses into really
reachable data source addresses from which they can read.
@*
If the list of jigdo parameters is not empty, then @command{xorriso} will
refuse to
write to non-blank targets, it will disable multi-session emulation, and
padding will be counted as part of the ISO image.
@*
@table @asis
@sp 1
@c man .TP
@item -jigdo parameter_name value
@kindex -jigdo   clears JTE or or adds parameter to JTE
@cindex Jigdo Template Extraction, -jigdo
Clear Jigdo Template Extraction parameter list or add a parameter to that list.
The alias names are the corresponding genisoimage options. They are accepted
as parameter names as well. Especially they are recognized by the -as mkisofs
emulation command.
@*
Parameter @strong{clear} with any value empties the whole list.
No .jigdo and .template file will be produced.
@*
@strong{template_path} sets the disk_path for the .template file with the
holed and compressed ISO image copy.
@*
Alias: -jigdo-template
@*
@strong{jigdo_path} sets the disk_path for the .jigdo file with the checksums
and download addresses for filling the holes in .template.
@*
Alias: -jigdo-jigdo
@*
@strong{md5_path} sets the disk_path where to find the .md5 input file.
@*
Alias: -md5-list
@*
@strong{min_size} sets the minimum size for a data file to be listed
in the .jigdo file and being a hole in the .template file.
@*
Alias: -jigdo-min-file-size
@*
@strong{exclude} adds a regular expression pattern which will get compared
with the absolute disk_path of any data file. A match causes the file to
stay in .template in any case.
@*
Alias: -jigdo-exclude
@*
@strong{demand_md5} adds a regular expression pattern which will get compared
with the absolute disk_path of any data file that was not found in the .md5
list. A match causes a MISHAP event.
@*
Alias: -jigdo-force-md5
@*
@strong{mapping} adds a string pair of the form To=From to the parameter list.
If a data file gets listed in the .jigdo file, then it is referred by the
file address from its line in the .md5 file. This file address gets checked
whether it begins with the From string. If so, then this string will be
replaced by the To string and a ':' character, before it goes into the .jigdo
file. The From string should end by a '/' character.
@*
Alias: -jigdo-map
@*
@strong{compression} chooses one of "bzip2" or "gzip" for the compression of
the template file. The jigdo file is put out uncompressed.
@*
Alias: -jigdo-template-compress
@*
@strong{checksum_iso} chooses one or more of "md5", "sha1", "sha256", "sha512"
for the auxiliary "# Image Hex" checksums in the jigdo file. The value may e.g.
look like "md5,sha1,sha512". Value "all" chooses all available algorithms.
Note that MD5 stays always enabled.
@*
Alias: -checksum_algorithm_iso
@*
@strong{checksum_template} is like checksum_iso but for "# Template Hex".
@*
Alias: -checksum_algorithm_template
@end table
@c man .TP
@c man .B Character sets:
@node Charset, Exception, Jigdo, Commands
@section Character sets
@c man .PP
@cindex Character Set, _definition
File names are strings of non-zero bytes with 8 bit each. Unfortunately
the same byte string may appear as different peculiar national characters
on differently nationalized terminals.
The meanings of byte codes are defined in @strong{character sets} which have
names. Shell command iconv -l lists them. 
@*
Character sets should not matter as long as only english alphanumeric
characters are used for file names or as long as all writers and readers
of the media use the same character set.
Outside these constraints it may be necessary to let @command{xorriso}
convert byte codes.
@*
There is an input conversion from input character set to the local character
set which applies when an ISO image gets loaded. A conversion from local
character set to the output character set is performed when an
image tree gets written. The sets can be defined independently by commands
-in_charset and -out_charset. Normally one will have both identical, if ever.
@*
If conversions are desired then @command{xorriso} needs to know the name of the
local character set. @command{xorriso} can inquire the same info as
shell command
"locale" with argument "charmap". This may be influenced by environment
variables LC_ALL, LC_CTYPE, or LANG and should match the expectations of
the terminal.
@*
The default output charset is the local character set of the terminal where
@command{xorriso} runs. So by default no conversion happens between local
filesystem
names and emerging names in the image. The situation stays ambigous and the
reader has to riddle what character set was used.
@*
By command -auto_charset it is possible to attribute the output charset name
to the image. This makes the situation unambigous. But if your terminal
character set does not match the character set of the local file names,
then this attribute can become plainly wrong and cause problems at read time.
To prevent this it is necessary to check whether the terminal properly
displays all intended filenames. Check especially the exotic national
characters.
@*
To enforce recording of a particular character set name without any conversion
at image generation time, set -charset and -local_charset to the desired name,
and enable -backslash_codes to avoid evil character display on your terminal.
@table @asis
@sp 1
@c man .TP
@item -charset character_set_name
@kindex -charset   sets input/output character set
@cindex Character Set, for input/output, -charset
Set the character set from which to convert file names when loading an
image and to which to convert when writing an image.
@c man .TP
@item -local_charset character_set_name
@kindex -local_charset   sets terminal character set
@cindex Character Set, of terminal, -local_charset
Override the system assumption of the local character set name.
If this appears necessary, one should consider to set -backslash_codes to
"on" in order to avoid dangerous binary codes being sent to the terminal.
@end table
@c man .TP
@c man .B Exception processing:
@node Exception, DialogCtl, Charset, Commands
@section Exception processing
@c man .PP
Since the tasks of @command{xorriso} are manifold and prone to external
influence, there
may arise the need for @command{xorriso} to report and handle problem events.
@*
Those events get classified when they are detected by one of the software
modules and forwarded to reporting and evaluation modules which decide about
reactions. Event classes are sorted by severity:
@*
"NEVER" The upper end of the severity spectrum.
@*
"ABORT" The program is being aborted and on its way to end.
@*
"FATAL" The main purpose of the run failed
or an important resource failed unexpectedly.
@*
"FAILURE" An important part of the job could not be performed.
@*
"MISHAP" A FAILURE which can be tolerated during ISO image generation.
@*
"SORRY" A less important part of the job could not be performed.
@*
"WARNING" A situation is suspicious of being not intended by the user.
@*
"HINT" A proposal to the user how to achieve better results.
@*
"NOTE" A harmless information about noteworthy circumstances.
@*
"UPDATE" A pacifier message during long running operations.
@*
"DEBUG" A message which would only interest the program developers.
@*
"ALL" The lower end of the severity spectrum.
@table @asis
@sp 1
@c man .TP
@item -abort_on severity
@kindex -abort_on   controls abort on error
@cindex Process, control abort on error, -abort_on
Set the severity threshold for events to abort the program.
@*
Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY"
@*
It may become necessary to abort the program anyway, despite
the setting by this command. Expect not many "ABORT" events to
be ignorable.
@*
A special property of this command is that it works preemptive if given as
program start argument. I.e. the first -abort_on setting among the
start arguments is in effect already when the first operations of
@command{xorriso} begin. Only "-abort_on" with dash "-" is recognized that way.
@c man .TP
@item -return_with severity exit_value
@kindex -return_with   controls exit value
@cindex Process, control exit value, -return_with
Set the threshold and exit_value to be returned at program end if no abort
has happened. This is to allow @command{xorriso} to go on after problems
but to get a failure indicating exit value from the program, nevertheless.
Useful is a value lower than the -abort_on threshold, down to "WARNING".
@*
exit_value may be either 0 (indicating success to the starter of the program)
or a number between 32 and 63. Some other exit_values are used by
@command{xorriso} if it decides to abort the program run:
@*
1=abort due to external signal
@*
2=no program arguments given
@*
3=creation of @command{xorriso} main object failed
@*
4=failure to start libburnia-project.org libraries
@*
5=program abort during argument processing
@*
6=program abort during dialog processing
@c man .TP
@item -report_about severity
@kindex -report_about   controls verbosity
@cindex Process, control verbosity, -report_about
Set the threshold for events to be reported.
@*
Useful:  "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL"
@*
Regardless what is set by -report_about, messages get always reported if they
reach the severity threshold of -abort_on .
@*
Event messages are sent to the info channel "I" which is usually stderr
but may be influenced by command -pkt_output.
Info messages which belong to no event get attributed severity "NOTE".
@*
A special property of this command is that the first -report_about setting
among the start arguments is in effect already when the first operations
of @command{xorriso} begin. Only "-report_about" with dash "-" is
recognized that way.
@c man .TP
@item -signal_handling mode
@kindex -signal_handling   controls handling of system signals
@cindex Control, signal handling, -signal_handling
Control the installation of a signal handler which shall react on external
signals (e.g. from program "kill" or from keys Ctrl+C) or on signals
caused by severe program errors.
@*
Mode "on" is the default. It uses the signal handler of libburn which produces
ugly messages but puts much effort in releasing optical drives
before @command{xorriso} ends.
@*
Mode "off" as first -signal_handling among the start arguments prevents all
own signal precautions of @command{xorriso}. Inherited signal
handler settings stay as they are.
@*
It works like "sig_dfl" if given after other signal handling was already
established at program start.
@*
Mode "sig_dfl" uses the system provided default handling of signals, which is
normally a sudden abort of the program. To prevent stuck drives, the
libburn handler is used during burning, blanking, and formatting on MMC drives.
@*
Mode "sig_ign" tries to ignore as many signal types as possible. This imposes
the risk that @command{xorriso} refuses to end until externally kill -9
if performed.
kill -9 then imposes the risk that the drive is left in unusable state and
needs poweroff to be reset. So during burning, blanking, and formatting
wait for at least their normal run time before killing externally.
@*
A special property of this command is that the first -signal_handling setting
among the start arguments is in effect already when the first operations
of @command{xorriso} begin. Only "-signal_handling" with dash "-" is
recognized that way.
@c man .TP
@item -error_behavior occasion behavior
@kindex -error_behavior   controls error workarounds
@cindex Process, error workarounds, -error_behavior
Control the program behavior at problem event occasions.
For now this applies to occasions "image_loading" which is given while
an image tree is read from the input device, and to "file_extraction" which
is given with osirrox commands like -extract.
@*
With "image_loading" there are three behaviors available:
@*
"best_effort" goes on with reading after events with severity below FAILURE
if the threshold of command -abort_on allows this.
@*
"failure" aborts image tree reading on first event of at least SORRY.
It issues an own FAILURE event.
This is the default.
@*
"fatal" acts like "failure" but issues the own event as FATAL.
@*
With occasion "file_extraction" there are three behaviors:
@*
"keep" maintains incompletely extracted files on disk. This is the default.
@*
"delete" removes files which encountered errors during content extraction.
@*
"best_effort" starts a revovery attempt by means of -extract_cut if the
file content stems from the loaded ISO image and is not filtered.
@end table
@c man .TP
@c man .B Dialog mode control:
@node DialogCtl, Inquiry, Exception, Commands
@section Dialog mode control
@table @asis
@c man .TP
@item -dialog "on"|"off"|"single_line"
@kindex -dialog   enables dialog mode
@cindex Dialog, enable dialog mode, -dialog
Enable or disable to enter dialog mode after all program arguments are
processed.
In dialog mode input lines get prompted via readline or from stdin.
@*
If no -abort_on severity was set when dialog starts, then "NEVER" is set
to avoid abort in most cases of wrong input or other problems. Before dialog
begins, the default is "FAILURE" which e.g. aborts on unknown commands.
@*
Mode "on" supports input of newline characters within quotation marks and
line continuation by trailing backslash outside quotation marks.
Mode "single_line" does not.
@c man .TP
@item -page length width
@kindex -page   set terminal geometry
@cindex Dialog, terminal geometry, -page
Describe terminal to the text pager. See also above, paragraph Result pager.
@*
If parameter length is nonzero then the user gets prompted after that
number of terminal lines. Zero length disables paging.
@*
Parameter width is the number of characters per terminal line. It is used
to compute the number of terminal lines which get occupied by an output line.
A usual terminal width is 80.
@c man .TP
@item -use_readline "on"|"off"
@kindex -use_readline   enables readline for dialog
@cindex Dialog, line editing, -use_readline
If "on" then use readline for dialog. Else use plain stdin.
@*
See also above, paragraph Dialog, Readline, Result pager.
@c man .TP
@item -reassure "on"|"tree"|"off"
@kindex -reassure   enables confirmation question
@cindex Dialog, confirmation question, -reassure
If "on" then ask the user for "y" or "n":
@*
before deleting or overwriting any file in the ISO image,
@*
before overwriting any disk file during restore operations,
@*
before rolling back pending image changes,
@*
before committing image changes to media,
@*
before changing the input drive,
@*
before blanking or formatting media,
@*
before ending the program.
@*
With setting "tree" the reassuring prompt will appear for an eventual
directory only once and not for each file in its whole subtree.
@*
Setting "off" silently kills any kind of image file object resp. performs
above irrevocable actions.
@*
To really produce user prompts, command -dialog needs to be set to "on".
Note that the prompt does not appear in situations where file removal
is forbidden by command -overwrite. -reassure only imposes an additional
curb for removing existing file objects.
@*
Be aware that file objects get deleted from the ISO image immediately
after confirmation. They are gone even if the running command gets aborted 
and its desired effect gets revoked. In case of severe mess-up, consider to
use -rollback to revoke the whole session.
@end table
@c man .TP
@c man .B Drive and media related inquiry actions:
@node Inquiry, Navigate, DialogCtl, Commands
@section Drive and media related inquiry actions
@table @asis
@c man .TP
@item -devices
@kindex -devices   gets list of drives
@cindex Drive, get drive list, -devices
Show list of available MMC drives with the addresses of
their libburn standard device files.
@*
This is only possible when no ISO image changes are pending.
After this command was executed, there is no drive current
and no image loaded.
@*
In order to be visible, a device has to offer rw-permissions
with its libburn standard device file. Thus it might be only the
@strong{superuser}
who is able to see all drives.
@*
Drives which are occupied by other processes get not shown.
@c man .TP
@item -device_links
@kindex -device_links   gets list of drives
@cindex Drive, get drive list, -device_links
Like -devices, but presenting the drives with addresses of symbolic links
which point to the actual device files.
@*
Modern GNU/Linux systems may shuffle drive addresses from boot to boot.
The udev daemon is supposed to create links which always point to the
same drive, regardless of its system address.
The command -device_links shows the addresses of such links if they begin
by "/dev/dvd" or "/dev/cd".
Precedence is: "dvdrw", "cdrw", "dvd", "cdrom", "cd".
@c man .TP
@item -toc
@*
@kindex -toc   shows list of sessions
@cindex Table-of-content, show, -toc
Show media specific tables of content. This is the session history
of the medium, not the ISO image directory tree.
@*
In case of overwriteable media holding a valid ISO image, it may happen that
only a single session gets shown. But if the first session on the
overwriteable media was written by @command{xorriso} then a complete
session history can be emulated.
@*
A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM
with only one or two sessions on it. The last of these sessions is supposed
to be the most recent real session then.
@*
Some read-only drives and media show no usable session history at all.
Command -rom_toc_scan might help.
@*
If input device and output device are both aquired and not the same,
then both tables-of-content get shown.
@c man .TP
@item -toc_of "in"|"out"|"all"[":short"]
@kindex -toc_of   shows list of sessions
Like command -toc but explicitely choosing which drive's table-of-content
to show. "in" shows -indev or -dev, "out" shows -outdev or -dev,
"all" shows the same as -toc.
@*
If ":short" is appended to the drive choosing word, then only a short
summary of drive state and medium content is printed.
@*
As further difference to -toc, this command does not emit FAILURE events
if the desired drive is not aquired.
@c man .TP
@item -mount_cmd drive entity id path
@kindex -mount_cmd   composes mount command line
@cindex Session, mount command line, -mount_cmd
Emit an appropriate command line for mounting the ISO session
indicated by drive, entity and id.
The result will be different on GNU/Linux and on FreeBSD.
@*
drive can be "indev" or "outdev" to indicate already acquired drives,
or it can be the path of a not yet acquired drive.
Prefix "stdio:" for non-MMC drives is not mandatory.
@*
entity must be either "sbsector" with the superblock sector address as id,
or "track" with a track number as id, or "session" with a session number,
or "volid" with a search pattern for the volume id, or "auto" with any text
as id. 
@*
path will be used as mount point and must already exist as a directory on disk.
@*
The command gets printed to the result channel. See command -mount
for direct execution of this command.
@c man .TP
@item -mount_opts option[:option...]
@kindex -mount_cmd   controls mount command
@cindex Session, mount parameters, -mount_opts
Set options which influence -mount and -mount_cmd. Currently there is only
option "exclusive" which is default and its counterpart "shared". The latter
causes @command{xorriso} not to give up the affected drive with command -mount.
On GNU/Linux it adds mount option "loop" which may allow to mount several
sessions of the same block device at the same time. One should not write
to a mounted optical medium, of course. Take care to umount all sessions
before ejecting.
@c man .TP
@item -session_string drive entity id format
@kindex -session_string   composes session info line
@cindex Session, info string, -session_string
Print to the result channel a text which gets composed according to
format and the parameters of the addressed session.
@*
Formats "linux:"path or "freebsd:"path produce the output of -mount_cmd
for the given operating systems.
@*
In other texts @command{xorriso} will substitute the following parameter names.
An optional prefix "string:" will be removed. 
@*
"%device%" will be substituted by the mountable device path of the drive
address.
@*
"%sbsector%" will be substituted by the session start sector.
@*
"%track%", "%session%", "%volid%" will be substituted by track number,
session number, resp. volume id of the depicted session.
@c man .TP
@item -print_size
@kindex -print_size   predicts image size
@cindex Write, predict image size, -print_size
Print the foreseeable consumption of 2048 byte blocks
by next -commit. This can last a while as a -commit gets
prepared and only in last moment is revoked by this command.
The result depends on several settings and also on the kind of output device.
If no -jidgo options are set and not command -as "mkisofs" was used,
then -padding (300 kB by default) is not counted as part of the image size.
@*
If an El Torito boot image file is already depicted, then command -print_size
automatically executes -boot_image "any" "next".
This means that the properties of that boot image cannot be edited by
subsequent commands.
@c man .TP
@item -tell_media_space
@kindex -tell_media_space   reports free space
@cindex Write, free space, -tell_media_space
Print available space on the output medium and the free space after
subtracting already foreseeable consumption by next -commit.
@*
Note that the title of the prediction "After commit :" is misleading.
It is rather the space that may still be filled in this session without
making the next -commit fail from medium overflow.
@*
The free space after the next -commit might be smaller by several MB.
This depends on medium type, number of recorded sessions, and drive habits.
@c man .TP
@item -pvd_info 
@kindex -pvd_info   shows image id strings
@cindex Image, show id strings, -pvd_info
Print various ID strings and timestamps which can be found in loaded ISO
images. Some of the IDs may be changed by commands like -volid or -publisher.
For these IDs -pvd_info reports what would be written with the next -commit.
The timestamps get not automatically propagated from loaded image to newly
written image. The ones for new images may be set by command -volume_date.
See there for the meaning of the particular timestamps.
@end table
@c man .TP
@c man .B Navigation in ISO image and disk filesystem:
@node Navigate, Verify, Inquiry, Commands
@section Navigation in ISO image and disk filesystem
@table @asis
@c man .TP
@item -cd iso_rr_path
@kindex -cd   sets working directory in ISO
@cindex Navigate, set ISO working directory, -cd
Change the current working directory in the ISO image.
This is prepended to iso_rr_paths which do not begin with '/'.
@*
It is possible to set the working directory to a path which does not exist
yet in the ISO image. The necessary parent directories will be created when
the first file object is inserted into that virtual directory.
Use -mkdir if you want to enforce the existence of the directory already at
first insertion.
@c man .TP
@item -cdx disk_path
@kindex -cdx   sets working directory on disk
@cindex Navigate, set disk working directory, -cdx
Change the current working directory in the local filesystem.
To be prepended to disk_paths which do not begin with '/'.
@c man .TP
@item -pwd
@*
@kindex -pwd   tells working directory in ISO
@cindex Navigate, tell ISO working directory, -pwd
Tell the current working directory in the ISO image.
@c man .TP
@item -pwdx
@kindex -pwdx   tells working directory on disk
@cindex Navigate, tell disk working directory, -pwdx
@*
Tell the current working directory in the local filesystem.
@c man .TP
@item -ls iso_rr_pattern [***]
@kindex -ls   lists files in ISO image
@cindex Navigate, list ISO files, -ls
List files in the ISO image which match shell patterns
(i.e. with wildcards '*' '?' '[a-z]').
If a pattern does not begin with '/' then it is compared with addresses
relative to -cd.
@*
Directories are listed by their content rather than as single file item.
@*
Pattern expansion may be disabled by command -iso_rr_pattern.
@c man .TP
@item -lsd iso_rr_pattern [***]
@kindex -lsd   lists files in ISO image
@cindex Navigate, list ISO files, -lsd
Like -ls but listing directories as themselves and not by their content.
This resembles shell command ls -d.
@c man .TP
@item -lsl iso_rr_pattern [***]
@kindex -lsl   lists files in ISO image
@cindex Navigate, list ISO files, -lsl
Like -ls but also list some of the file attributes. 
The output format resembles shell command ls -ln.
@*
File type 'e' indicates the El Torito boot catalog.
@*
If the file has non-trivial ACL, then a '+' is appended to the permission info.
If the file is hidden, then 'I' for "iso_rr", 'J' for "joliet", 'A'
for "hfsplus", resp. 'H' for multiple hiding gets appended.
Together with ACL it is 'i', 'j', 'a', resp. 'h'.
@c man .TP
@item -lsdl iso_rr_pattern [***]
@kindex -lsdl   lists files in ISO image
@cindex Navigate, list ISO files, -lsdl
Like -lsd but also list some of the file attributes. 
The output format resembles shell command ls -dln.
@c man .TP
@item -lsx disk_pattern [***]
@kindex -lsx   lists files on disk
@cindex Navigate, list disk files, -lsx
List files in the local filesystem which match shell patterns. Patterns which
do not begin with '/' are used relative to -cdx.
@*
Directories are listed by their content rather than as single file item.
@*
Pattern expansion may be disabled by command -disk_pattern.
@c man .TP
@item -lsdx disk_pattern [***]
@kindex -lsdx   lists files on disk
@cindex Navigate, list disk files, -lsdx
Like -lsx but listing directories as themselves and not by their content.
This resembles shell command ls -d.
@c man .TP
@item -lslx disk_pattern [***]
@kindex -lslx   lists files on disk
@cindex Navigate, list disk files, -lslx
Like -lsx but also listing some of the file attributes.
Output format resembles shell command ls -ln.
@c man .TP
@item -lsdlx disk_pattern [***]
@kindex -lsdlx   lists files on disk
@cindex Navigate, list disk files, -lsdlx
Like -lsdx but also listing some of the file attributes.
Output format resembles shell command ls -dln.
@c man .TP
@item -getfacl iso_rr_pattern [***]
@kindex -getfacl   shows ACL in ISO image
@cindex ACL, show in ISO image, -getfacl
Print the access permissions of the given files in the ISO image using the
format of shell command getfacl. If a file has no ACL then it gets fabricated
from the -chmod settings. A file may have a real ACL if it was introduced into
the ISO image while command -acl was set to "on".
@c man .TP
@item -getfacl_r iso_rr_pattern [***]
@kindex -getfacl_r   shows ACL in ISO image
@cindex ACL, show in ISO image, -getfacl_r
Like -gefacl but listing recursively the whole file trees underneath eventual
directories.
@c man .TP
@item -getfattr iso_rr_pattern [***]
@kindex -getfattr   shows xattr in ISO image
@cindex xattr, show in ISO image, -getfattr
Print the xattr of the given files in the ISO image.
If a file has no such xattr then noting is printed for it.
@c man .TP
@item -getfattr_r iso_rr_pattern [***]
@kindex -getfattr_r   shows xattr in ISO image
@cindex xattr, show in ISO image, -getfattr_r
Like -gefattr but listing recursively the whole file trees underneath eventual
directories.
@c man .TP
@item -du iso_rr_pattern [***]
@kindex -du   show directory size in ISO image
@cindex Navigate, directory size in ISO image, -du
Recursively list size of directories and files in the ISO image
which match one of the patterns.
similar to shell command du -k.
@c man .TP
@item -dus iso_rr_pattern [***]
@kindex -dus   show directory size in ISO image
@cindex Navigate, directory size in ISO image, -dus
List size of directories and files in the ISO image 
which match one of the patterns.
Similar to shell command du -sk.
@c man .TP
@item -dux disk_pattern [***]
@kindex -dux   show directory size on disk
@cindex Navigate, directory size in on disk, -dux
Recursively list size of directories and files in the local filesystem
which match one of the patterns. Similar to shell command du -k.
@c man .TP
@item -dusx disk_pattern [***]
@kindex -dusx   show directory size on disk
@cindex Navigate, directory size in on disk, -dusx
List size of directories and files in the local filesystem
which match one of the patterns.
Similar to shell command du -sk.
@c man .TP
@item -findx disk_path [-name pattern] [-type t] [-exec action [params]] @minus{}@minus{}
@kindex -findx   traverses disk tree
@cindex Tree, disk, traverse, -findx
Like -find but operating on local filesystem and not on the ISO image.
This is subject to the settings of -follow.
@*
-findx accepts the same -type parameters as -find. Additionally it recognizes
type "mountpoint" (or "m") which matches subdirectories which reside on a
different device than their parent. It never matches the disk_path
given as start address for -findx.
@*
-findx accepts the -exec actions as does -find. But except the following few
actions it will always perform action "echo".
@*
@table @asis
@sp 1
@item in_iso
reports the path if its counterpart exists in the ISO image.
For this the disk_path of the -findx command gets replaced
by the iso_rr_path given as parameter.
@*
E.g.: -findx /home/thomas -exec in_iso /thomas_on_cd @minus{}@minus{}
@*
@item not_in_iso
reports the path if its counterpart does
not exist in the ISO image. The report format is the same as with command
-compare.
@*
@item add_missing iso_rr_path_start
adds the counterpart if it does not yet
exist in the ISO image and marks it for "rm_merge" as non-removable. 
@*
E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd @minus{}@minus{}
@*
@item is_full_in_iso
reports if the counterpart in the ISO image
contains files. To be used with -type "m" to report mount points.
@*
@item empty_iso_dir
deletes all files from the counterpart
in the ISO image. To be used with -type "m" to truncate mount points.
@*
@item estimate_size
prints a lower and an upper estimation of the number of blocks which the
found files together will occupy in the emerging ISO image.
This does not account for the superblock,
for the directories in the -findx path, or for image padding.
@*
@item list_extattr mode
prints a script to the result channel, which would use FreeBSD command
setextattr to set the file's xattr name-value pairs of user namespace.
See -find for a description of parameter mode.
@*
E.g. -exec list_extattr e --
@end table
@c man .TP
@item -compare disk_path iso_rr_path
@kindex -compare   reports ISO/disk differences
@cindex Verify, compare ISO and disk file, -compare
Compare attributes and eventual data file content of a fileobject in the
local filesystem with a file object in the ISO image. The iso_rr_path may
well point to an image file object which is not yet committed, i.e. of which
the data content still resides in the local filesystem. Such data content is
prone to externally caused changes.
@*
If iso_rr_path is empty then disk_path is used as path in the ISO image too.
@*
Differing attributes are reported in detail, differing content is summarized.
Both to the result channel. In case of no differences no result lines are
emitted.
@c man .TP
@item -compare_r disk_path iso_rr_path
@kindex -compare_r   reports ISO/disk differences
@cindex Verify, compare ISO and disk tree, -compare_r
Like -compare but working recursively. I.e. all file objects below both
addresses get compared whether they have counterparts below the other address
and whether both counterparts match.
@c man .TP
@item -compare_l disk_prefix iso_rr_prefix disk_path [***]
@kindex -compare_l   reports ISO/disk differences
@cindex Verify, compare ISO and disk, -compare_l
Perform -compare_r with each of the disk_path parameters. iso_rr_path will be
composed from disk_path by replacing disk_prefix by iso_rr_prefix.
@c man .TP
@item -show_stream iso_rr_path [***]
@kindex -show_stream   shows data source and filters
@cindex Filter, show chain, -show_stream
Display the content stream chain of data files in the ISO image. The chain
consists of the iso_rr_name and one or more streams, separated by " < " marks.
A stream description consists of one or more texts, separated by ":"
characters.
The first text tells the stream type, the following ones, if ever, describe its
individual properties.
Frequently used types are:
@*
 disk:'disk_path'  for local filesystem objects.
@*
 image:'iso_rr_path'  for ISO image file objects.
@*
 cout:'disk_path offset count'  for -cut_out files.
@*
 extf:'filter_name' for external filters.
@*
Example:
@*
 '/abc/xyz.gz' < extf:'gzip' < disk:'/home/me/x'
@c man .TP
@item -show_stream_r iso_rr_path [***]
@kindex -show_stream_r   shows data source and filters
@cindex Filter, show chains of tree, -show_stream_r
Like -show_stream but working recursively.
@end table
@c man .TP
@c man .B Evaluation of readability and recovery:
@node Verify, Restore, Navigate, Commands
@section Evaluation of readability and recovery
@c man .PP
It is not uncommon that optical media produce read errors. The reasons may be
various and get obscured by error correction which is performed by the drives
and based on extra data on the media. If a drive returns data then one can
quite trust that they are valid. But at some degree of read problems the
correction will fail and the drive is supposed to indicate error.
@*
@command{xorriso} can scan a medium for readable data blocks, classify them
according
to their read speed, save them to a file, and keep track of successfuly saved
blocks for further tries on the same medium.
@*
By command -md5 checksums may get recorded with data files and whole
sessions. These checksums are reachable only via indev and a loaded image.
They work independently of the media type and can detect transmission errors.
@table @asis
@sp 1
@c man .TP
@item -check_media [option [option ...]] @minus{}@minus{}
@kindex -check_media   reads media block by block
@cindex Verify, check blocks, -check_media
@cindex Recovery, retrieve blocks, -check_media
Try to read data blocks from the indev drive, optionally copy them to a
disk file, and finally report about the encountered quality. Several options
may be used to modify the default behavior.
@*
The parameters given with this command override the default settings which
may have been changed by command -check_media_defaults. See there for a
description of available options.
@*
The result list tells intervals of 2 KiB blocks with start address, number
of blocks and quality. Qualities which begin with "+" are
supposed to be valid readable data. Qualities with "-" are unreadable or
corrupted data.
"0" indicates qualities which are not covered by the check run or are regularly
allowed to be unreadable (e.g. gaps between tracks).
@*
Alternatively it is possible to report damaged files rather than blocks.
@*
If -md5 is "on" then the default mode what=tracks looks out for libisofs
checksum tags for the ISO session data and checks them
against the checksums computed from the data stream.
@c man .TP
@item -check_media_defaults [option [option ...]] @minus{}@minus{}
@kindex -check_media_defaults   sets -check_media options
@cindex Verify, preset -check_media, -check_media_defaults
Preset options for runs of -check_media, -extract_cut and best_effort
file extraction. Options given with -check_media will override the
preset options. -extract_cut will override some options automatically.
@*
An option consists of a keyword, a "=" character, and a value. Options
may override each other. So their sequence matters.
@*
The default setting at program start is:
@*
use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
@*
time_limit=28800 item_limit=100000 data_to='' event=ALL
@*
abort_file=/var/opt/xorriso/do_abort_check_media
@*
sector_map='' map_with_volid=off patch_lba0=off report=blocks
@*
bad_limit=valid slow_limit=1.0 chunk_size=0s async_chunks=0
@*
Option "reset=now" restores these startup defaults.
@*
Non-default options are:
@*
@table @asis
@sp 1
@item report="files"
lists the files which use damaged blocks (not with use=outdev).
The format is like with find -exec report_damage.
Note that a MD5 session mismatch marks all files of the session as damaged.
If finer distinction is desired, perform -md5 off before -check_media.
@*
@item report="blocks_files"
first lists damaged blocks and then affected files.
@*
@item use="outdev"
reads from the output drive instead of the input drive. This
avoids loading the ISO image tree from media.
@*
@item use="sector_map"
does not read any media but loads the file given by option
sector_map= and processes this virtual outcome.
@*
@item what="disc"
scans the payload range of a medium without respecting track gaps.
@*
@item what="image"
similar to "disc", but restricts scanning to the range of the ISO 9660 image,
if present.
@*
@item min_lba=limit
omits all blocks with addresses lower than limit.
@*
@item max_lba=limit
switches to what=disc and omits all blocks above limit.
@*
@item retry="on"
forces read retries with single blocks when the normal read
chunk produces a read error. By default, retries are only enabled with CD
media. "retry=off" forbits retries for all media types. 
@*
@item abort_file=disk_path
gives the path of the file which may abort a scan run. Abort
happens if the file exists and its mtime is not older than the start time
of the run. Use shell command "touch" to trigger this.
Other than an aborted program run, this will report the tested and untested
blocks and go on with running @command{xorriso}.
@*
@item time_limit=seconds
gives the number of seconds after which the scan shall be
aborted. This is useful for unattended scanning of media which may else
overwork the drive in its effort to squeeze out some readable blocks.
Abort may be delayed by the drive gnawing on the last single read operation.
Value -1 means unlimited time.
@*
@item item_limit=number
gives the number of report list items after which to abort.
Value -1 means unlimited item number.
@*
@item data_to=disk_path
copies the valid blocks to the given file.
@*
@item event=severity
sets the given severity for a problem event which shall be issued at
the end of a check run if data blocks were unreadable or failed to match
recorded MD5 checksums. Severity "ALL" disables this event.
@*
@item sector_map=disk_path
tries to read the file given by disk_path as
sector bitmap and to store such a map file after the scan run.
The bitmap tells which blocks have been read successfully in previous runs.
It allows to do several scans on the same medium, even with intermediate
eject, in order to collect readable blocks whenever the drive is lucky enough
to produce them. The stored file contains a human readable TOC of tracks
and their start block addresses, followed by binary bitmap data.
@*
@item map_with_volid="on"
examines tracks whether they are ISO images and
prints their volume IDs into the human readable TOC of sector_map=.
@*
@item patch_lba0="on"
transfers within the data_to= file a copy of the currently
loaded session head to the start of that file and patches it to be valid
at that position.
This makes the loaded session the last valid session of the image file
when it gets mounted or loaded as stdio: drive. New sessions will be appended
after this last session and will overwrite any sessions which have followed it.
@*
@item patch_lba0="force"
performs patch_lba0="on" even if @command{xorriso} believes
that the copied data are not valid.
@*
patch_lba0= may also bear a number. If it is 32 or higher it is taken as
start address of the session to be copied. In this case it is not necessary to
have an -indev and a loaded image. ":force" may be appended after the number.
@*
@item bad_limit=threshold
sets the highest quality which shall be considered as damage.
Choose one of "good", "md5_match", "slow", "partial", "valid", "untested",
"invalid", "tao_end", "off_track", "md5_mismatch", "unreadable".
@*
@item slow_limit=threshold
sets the time threshold for a single read chunk to be considered
slow. This may be a fractional number like 0.1 or 1.5.
@*
@item chunk_size=size
sets the number of bytes to be read in one read operation.
This gets rounded down to full blocks of 2048 bytes. 0 means automatic size.
@*
@item async_chunks=number
enables asynchronous MD5 processing if number is 2 or larger.
In this case the given number of read chunks is allocated as fifo buffer.
On very fast MMC drives try: chunk_size=64s async_chunks=16.
@end table
@c man .TP
@kindex -check_md5   verifies file checksum
@cindex Verify, file checksum, -check_md5
@item -check_md5 severity iso_rr_path [***]
Compare the data content of the given files in the loaded image with their
recorded MD5 checksums, if there are any. In case of any mismatch an event of
the given severity is issued. It may then be handled by appropriate settings of
commands -abort_on or -return_with which both can cause non-zero exit values
of the program run. Severity ALL suppresses that event.
@*
This command reports match and mismatch of data files to the result channel.
Non-data files cause NOTE events. There will also be UPDATE events from
data reading.
@*
If no iso_rr_path is given then the whole loaded session is compared with its
MD5 sum. Be aware that this covers only one session and not the whole image
if there are older sessions.
@c man .TP
@item -check_md5_r severity iso_rr_path [***]
@kindex -check_md5_r   verifies file tree checksums
@cindex Verify, file tree checksums, -check_md5_r
Like -check_md5 but checking all data files underneath the given paths.
Only mismatching data files will be reported.
@end table
@c man .TP
@c man .B osirrox ISO-to-disk restore commands:
@node Restore, Emulation, Verify, Commands
@section osirrox ISO-to-disk restore commands
@c man .PP
Normally @command{xorriso} only writes to disk files which were given as stdio:
pseudo-drives or as log files.
But its alter ego osirrox is able to extract file objects
from ISO images and to create, overwrite, or delete file objects on disk.
@*
Disk file exclusions by -not_mgt, -not_leaf, -not_paths apply.
If disk file objects already exist then the settings of -overwrite and
-reassure apply. But -overwrite "on" only triggers the behavior
of -overwrite "nondir". I.e. directories cannot be deleted.
@*
Access permissions of files in the ISO image do not restrict restoring.
The directory permissions on disk have to allow rwx.
@table @asis
@sp 1
@c man .TP
@item -osirrox setting[:option:...]
@kindex -osirrox   enables ISO-to-disk copying
@cindex Restore, enable ISO-to-disk, -osirrox
Setting "off" disables disk filesystem manipulations. This is the default
unless the program was started with leafname "osirrox". Elsewise
the capability to restore files can be enabled explicitly by -osirrox "on".
It can be irrevocably disabled by -osirrox "banned".
@*
The setting "blocked" is like "off". But it can only be revoked by
setting "unblock", which elsewise is like "on". This can be used to curb
command scripts which might use "on" undesiredly.
@*
To enable restoring of special files by "device_files" is potentially
dangerous.
The meaning of the number st_rdev (see man 2 stat) depends much on the
operating system. Best is to restore device files only to the same system
from where they were copied. If not enabled, device files in the ISO image
are ignored during restore operations.
@*
Due to a bug of previous versions, device files from previous sessions might
have been altered to major=0, minor=1. So this combination does not get
restored.
@*
Option "concat_split_on" is default. It enables restoring of split file
directories as data files if the directory contains a complete collection
of -cut_out part files. With option "concat_split_off" such directories are
handled like any other ISO image directory.
@*
Option "auto_chmod_off" is default. If "auto_chmod_on" is set then access
restrictions for disk directories get circumvented if those directories
are owned by the effective user who runs @command{xorriso}. This happens
by temporarily granting rwx permission to the owner.
@*
Option "sort_lba_on" may improve read performance with optical drives. It
allows to restore large numbers of hard links without exhausting
-temp_mem_limit. It does not preserve directory mtime and it needs
-osirrox option auto_chmod_on in order to extract directories which offer no
write permission. Default is "sort_lba_off".
@*
Option "o_excl_on" is the default unless the program was started with leafname
"osirrox". On GNU/Linux it tries to avoid using drives which are mounted or in
use by other libburn programs.
Option "o_excl_off" allows on GNU/Linux to access such drives. Drives which
get acquired while "o_excl_off" will refuse to get blanked, formatted, 
written, or ejected. But be aware that even harmless inquiries can spoil
ongoing burns of CD-R[W] and DVD-R[W].
@*
Option "strict_acl_off" is default. It tolerates on FreeBSD the presence of
directory "default" ACLs in the ISO image. With "strict_acl_on" these
GNU/Linux ACLs cause on FreeBSD a FAILURE event during restore with -acl "on".
@c man .TP
@item -extract iso_rr_path disk_path
@kindex -extract   copies file tree to disk
@cindex Restore, copy file tree to disk, -extract
Copy the file objects at and underneath iso_rr_path to their corresponding
addresses at and underneath disk_path.
This is the inverse of -map or -update_r.
@*
If iso_rr_path is a directory and disk_path is an existing directory then
both trees will be merged. Directory attributes get extracted only if the disk
directory is newly created by the copy operation.
Disk files get removed only if they are to be replaced
by file objects from the ISO image.
@*
As many attributes as possible are copied together with restored
file objects.
@c man .TP
@item -extract_single iso_rr_path disk_path
@kindex -extract_single   copies file to disk
@cindex Restore, copy file to disk, -extract_single
Like -extract, but if iso_rr_path is a directory then its sub tree gets not
restored.
@c man .TP
@item -extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
@kindex -extract_l   copies files to disk
@cindex Restore, copy files to disk, -extract_l
Perform -extract with each of the iso_rr_path parameters. disk_path will be
composed from iso_rr_path by replacing iso_rr_prefix by disk_prefix.
@c man .TP
@item -extract_cut iso_rr_path byte_offset byte_count disk_path
@kindex -extract_cut   copies file piece to disk
@cindex Restore, copy file piece to disk, -extract_cut
Copy a byte interval from a data file out of an ISO image into a newly created
disk file.
The main purpose for this is to allow handling of large files if they
are not supported by mount -t iso9660 and if the reading system is unable
to buffer them as a whole.
@*
If the data bytes of iso_rr_path are stored in the loaded ISO image,
and no filter is applied,
and byte_offset is a multiple of 2048, then a special run of -check_media
is performed. It may be quicker and more rugged than the general reading
method.
@c man .TP
@item -cpx iso_rr_path [***] disk_path
@kindex -cpx   copies files to disk
@cindex Restore, copy files to disk, -cpx
Copy single leaf file objects from the ISO image to the address given by
disk_path. If more then one iso_rr_path is given then
disk_path must be a directory or non-existent. In the latter case it gets
created and the extracted files get installed in it with the same leafnames.
@*
Missing directory components in disk_path will get created, if possible.
@*
Directories are allowed as iso_rr_path only with -osirrox "concat_split_on"
and only if they actually represent a complete collection of -cut_out split
file parts.
@c man .TP
@item -cpax iso_rr_path [***] disk_path
@kindex -cpax   copies files to disk
@cindex Restore, copy files to disk, -cpax
Like -cpx but restoring mtime, atime as in ISO image and trying to set
ownership and group as in ISO image.
@c man .TP
@item -cp_rx iso_rr_path [***] disk_path
@kindex -cp_rx   copies file trees to disk
@cindex Restore, copy file trees to disk, -cp_rx
Like -cpx but also extracting whole directory trees from the ISO image.
@*
The resulting disk paths are determined as with shell command cp -r :
If disk_path is an existing directory then the trees will be inserted or merged
underneath this directory and will keep their leaf names. The ISO directory "/"
has no leaf name and thus gets mapped directly to disk_path.
@c man .TP
@item -cp_rax iso_rr_path [***] disk_path
@kindex -cp_rx   copies file trees to disk
@cindex Restore, copy file trees to disk, -cp_rx
Like -cp_rx but restoring mtime, atime as in ISO image and trying to set
ownership and group as in ISO image.
@c man .TP
@item -paste_in iso_rr_path disk_path byte_offset byte_count
@kindex -paste_in   copies file into disk file
@cindex Restore, copy file into disk file, -paste_in
Read the content of a ISO data file and write it into a data file on disk
beginning at the byte_offset. Write at most byte_count bytes.
This is the inverse of command -cut_out.
@c man .TP
@item -mount drive entity id path
@kindex -mount   issues mount command for ISO session
@cindex Session, issue mount command, -mount
Produce the same line as -mount_cmd and then execute it as external program run
after giving up the depicted drive. See also -mount_opts.
This demands -osirrox to be enabled and normally will succeed only for the
superuser. For safety reasons the mount program is only executed if it is 
reachable as /bin/mount or /sbin/mount.
@end table
@c man .TP
@c man .B Command compatibility emulations:
@node Emulation, Scripting, Restore, Commands
@section Command compatibility emulations (cdrtools)
@c man .PP
Writing of ISO 9660 on CD is traditionally done by program mkisofs
as ISO 9660 image producer and cdrecord as burn program.
@command{xorriso} does not strive for their comprehensive emulation.
Nevertheless it is ready to perform some of its core tasks under control
of commands which in said programs trigger comparable actions.
@table @asis
@sp 1
@c man .TP
@item -as personality option [options] @minus{}@minus{}
@kindex -as   emulates mkisofs or cdrecord
@cindex Emulation, -as
@*
Perform the variable length option list as sparse emulation of the program
depicted by the personality word.
@*
@sp 1

@cindex Emulation, mkisofs, -as
@cindex mkisofs, Emulation
Personality "@strong{mkisofs}" accepts the options listed with:
@*
  -as mkisofs -help @minus{}@minus{}
@*
Among them: -R (always on), -r, -J, -o, -M, -C, -dir-mode, -file-mode,
-path-list, -m, -exclude-list,
-f, -print-size, -pad, -no-pad, -V, -v, -version, -graft-points, -z,
-no-emul-boot, -b, -c, -boot-info-table, -boot-load-size, -input-charset, -G,
-output-charset, -U, -hide, -hide-joliet, -hide-list, -hide-joliet-list,
file paths and pathspecs.
A lot of options are not supported and lead to failure of the mkisofs
emulation. Some are ignored, but better do not rely on this tolerance.
@*
The supported options are documented in detail in xorrisofs.info
and in man xorrisofs. The description here is focused on the effect
of mkisofs emulation in the context of a @command{xorriso} run.
@*
Other than with the "cdrecord" personality there is no automatic -commit at
the end of a "mkisofs" option list. Verbosity settings -v (= "UPDATE") and
-quiet (= "SORRY") persist. The output file
persists until things happen like -commit, -rollback, -dev, or end of
@command{xorriso}.
@*
Options which affect all file objects in the ISO image, like -r or -dir-mode,
will be applied only to files which are present in the ISO image when
the command -as ends. If you use several -as mkisofs commands in the same
run, then consider to put such options into the last -as command.
@*
-pacifier gets set to "mkisofs" if files are added to the image.
@*
-graft-points is equivalent to -pathspecs on. Note that pathspecs without "="
are interpreted differently than with @command{xorriso} command -add.
Directories get
merged with the root directory of the ISO image, other filetypes get mapped
into that root directory.
@*
If pathspecs are given and if no output file was chosen before or during the
"mkisofs" option list, then standard output (-outdev "-") will get into effect.
If -o points to a regular file, then it will be truncated to 0 bytes
when finally writing begins. This truncation does not happen if the drive
is chosen by @command{xorriso} commands before -as mkisofs or after its
list delimiter. Directories and symbolic links are no valid -o targets.
@*
Writing to stdout is possible only if -as "mkisofs" was among the start
arguments or if other start arguments pointed the output drive to
standard output.
@*
-print-size inhibits automatic image production at program end. This ban is
lifted only if the pending image changes get discarded.
@*
Padding is counted as part of the ISO image if not option --emul-toc
is given.
@*
If no -iso-level is given, then level 1 is chosen when the first file or
directory is added to the image. At the same occasion directory names get
allowed to violate the standard by -compliance option allow_dir_id_ext.
This may be avoided by option -disallow_dir_id_ext.
@*
Option -root is supported. Option -old-root is implemented by @command{xorriso}
commands -mkdir, -cp_clone, -find update_merge, and -find rm_merge.
-root and -old-root set command -disk_dev_ino to "ino_only" and -md5 to "on",
by default.
@minus{}disk_dev_ino can be set to "off" by @minus{}@minus{}old-root-no-ino
resp. to "on" by @minus{}@minus{}old-root-devno .
@minus{}md5 can be set to "off" by @minus{}@minus{}old-root-no-md5 .
@*
Not original mkisofs options are @minus{}@minus{}quoted_path_list ,
@minus{}@minus{}hardlinks , @minus{}@minus{}acl ,
@minus{}@minus{}xattr , @minus{}@minus{}md5 , @minus{}@minus{}stdio_sync .
They work like the @command{xorriso} commands with the
same name and hardcoded parameter "on", e.g. -acl "on".
Explicit parameters are expected by @minus{}@minus{}stdio_sync
and @minus{}@minus{}scdbackup_tag.
@*
The capability to preserve multi-session history on overwriteable media
gets disabled by default. It can be enabled by using @minus{}@minus{}emul-toc
with the first session. See -compliance no_emul_toc.
@*
@minus{}@minus{}sort-weight gets as parameters a number and an iso_rr_path.
The number becomes the LBA sorting weight of regular file iso_rr_path or
of all regular files underneath directory iso_rr_path.
(See -find -exec sort_weight).
@*
Adopted from grub-mkisofs are @minus{}@minus{}protective-msdos-label 
(see -boot_image grub partition_table=on) and 
@minus{}@minus{}modification-date=YYYYMMDDhhmmsscc
(see -volume_date uuid). For EFI bootable GRUB boot images use
@minus{}@minus{}efi-boot.
It performs @minus{}boot_image grub efi_path= surrounded by two
@minus{}boot_image "any" "next". 
Alternative option @minus{}e from Fedora genisoimage sets bin_path and
platform_id for EFI, but performs no "next". 
@*
For MBR bootable ISOLINUX images there is -isohybrid-mbr FILE, where
FILE is one of the Syslinux files mbr/isohdp[fp]x*.bin . Use this
instead of -G to apply the effect of -boot_image isolinux partition_table=on.
@*
@minus{}@minus{}boot-catalog-hide is -boot_image any cat_hidden=on.
@*
@minus{}mips-boot is the same as -boot_image any mips_path= .
@*
@minus{}mipsel-boot leads to mipsel_path= .
@*
@minus{}partition_offset number is
@minus{}boot_image any partition_offset=number.
@*
Command @minus{}append_partition is supported.
@*
@minus{}untranslated_name_len number is
@minus{}compliance untranslated_name_len=number.
@*
@minus{}@minus{}old-empty is -compliance old_empty.
@*
The options of genisoimage Jigdo Template Extraction are recognized and
performed via @command{xorriso} command -jigdo. See the "Alias:" names there
for the meaning of the genisoimage options.
@*
@sp 1

Personalities "@strong{xorrisofs}", "@strong{genisoimage}",
and "@strong{genisofs}" are aliases for "mkisofs".
@*
If @command{xorriso} is started with one of the leafnames "xorrisofs",
"genisofs",
"mkisofs", or "genisoimage", then it performs -read_mkisofsrc and prepends
-as "genisofs" to the program arguments.
I.e. all arguments will be interpreted mkisofs style until "@minus{}@minus{}"
is encountered. 
From then on, arguments are interpreted as @command{xorriso} commands.
@*
@minus{}@minus{}no_rc as first argument of such a program start
prevents interpretation of startup files. See section FILES below.
@*
@sp 1

@cindex Emulation, cdrecord, -as
@cindex cdrecord, Emulation
Personality "@strong{cdrecord}" accepts the options listed with:
@*
  -as cdrecord -help @minus{}@minus{}
@*
Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=, tsize=,
-isosize, -multi, -msinfo, @minus{}@minus{}grow_overwriteable_iso,
write_start_address=,
track source file path or "-" for standard input as track source.
@*
It ignores most other options of cdrecord and cdrskin but refuses on
-audio, -scanbus, and on blanking modes unknown to @command{xorriso}.
@*
The scope is only a single data track per session to be written
to blank, overwriteable, or appendable media. The medium gets closed if 
closing is applicable and not option -multi is present.
@*
If an input drive was acquired, then it is given up.
This is only allowed if no image changes are pending.
@*
dev= must be given as @command{xorriso} device address. Addresses like 0,0,0
or ATA:1,1,0 are not supported.
@*
If a track source is given, then an automatic -commit happens at the end of
the "cdrecord" option list.
@*
@minus{}@minus{}grow_overwriteable_iso
enables emulation of multi-session on overwriteable
media.  To enable emulation of a TOC, the first session needs -C 0,32 with
-as mkisofs (but no -M) and @minus{}@minus{}grow_overwriteable_iso
write_start_address=32s with -as cdrecord.
@*
A much more elaborate libburn based cdrecord emulator is the program cdrskin.
@*
Personalites "@strong{xorrecord}", "@strong{wodim}", and "@strong{cdrskin}"
are aliases for "cdrecord".
@*
If @command{xorriso} is started with one of the leafnames "xorrecord",
"cdrskin", "cdrecord", or "wodim", then it automatically prepends -as "cdrskin"
to the program arguments. I.e. all arguments will be interpreted cdrecord
style until "@minus{}@minus{}" is encountered.
From then on, arguments are interpreted as @command{xorriso} commands.
@*
@minus{}@minus{}no_rc as first argument of such a program start
prevents interpretation of @command{xorriso} startup files.
See section FILES below.
@c man .TP
@item -read_mkisofsrc
@kindex -read_mkisofsrc   searches and reads .mkisofsrc file
@cindex Emulation, .mkisofsrc, -read_mkisofsrc
Try one by one to open for reading:
 ./.mkisofsrc , $MKISOFSRC , $HOME/.mkisofsrc , $(dirname $0)/.mkisofsrc 
@*
On success interpret the file content as of man mkisofs CONFIGURATION,
and end this command. Do not try further files.
The last address is used only if start argument 0 has a non-trivial dirname.
@*
The reader currently interprets the following NAME=VALUE pairs:
APPI (-application_id) , PUBL (-publisher) , SYSI (-system_id) ,
VOLI (-volid) , VOLS (-volset_id)
@*
Any other lines will be silently ignored.
@c man .TP
@item -pacifier behavior_code
@kindex -pacifier   controls pacifier text form
@cindex Emulation, pacifier form, -pacifier
Control behavior of UPDATE pacifiers during write operations.
The following behavior codes are defined:
@*
"xorriso" is the default format:
@*
Writing: sector XXXXX of YYYYYY  [fifo active, nn% fill]
@*
"cdrecord" looks like:
@*
X of Y MB written (fifo nn%) [buf mmm%]
@*
"mkisofs" 
@*
nn% done, estimate finish Tue Jul 15 20:13:28 2008
@c man .TP
@item -scdbackup_tag list_path record_name
@kindex -scdbackup_tag   enables scdbackup checksum tag
@cindex Backup, scdbackup checksum tag, -scdbackup
Set the parameter "name" for a scdbackup checksum record.
It will be appended in an scdbackup checksum tag to the -md5 session tag if
the image starts at LBA 0. This is the case if it gets written as first
session onto a sequential medium, or piped into a program, named pipe or
character device.
@*
If list_path is not empty then the record will also be appended to the
data file given by this path.
@*
Program scdbackup_verify will recognize and verify tag resp. record.
@end table
@c man .TP
@c man .B Scripting, dialog and program control features:
@node Scripting, Frontend, Emulation, Commands
@section Scripting, dialog and program control features
@table @asis
@c man .TP
@item -no_rc
@kindex -no_rc   disables startup files
@cindex Process, disable startup files, -no_rc
@*
Only if used as first program argument this command
prevents reading and interpretation of startup files. See section FILES below.
@c man .TP
@item -options_from_file fileaddress
@kindex -options_from_file   reads commands from file
@cindex Process, read command file, -options_from_file
Read quoted input from fileaddress and execute it like dialog lines.
Empty lines and lines which begin by # are ignored. Normally one line
should hold one @command{xorriso} command and all its parameters.
Nevertheless lines may be concatenated by a trailing backslash.
@*
See also section "Command processing", paragraph "Quoted input".
@c man .TP
@item -help
@kindex -help   prints help text
@cindex Program, print help text, -help
@*
Print helptext.
@c man .TP
@item -version
@kindex -version   prints help text
@cindex Program, print version, -version
Print program name and version, component versions, license.
@c man .TP
@item -list_extras code
@kindex -list_extras   lists compile time extra features
@cindex Program, list extra features, -list_extras
Tell whether certain extra features were enabled at compile time.
Code "all" lists all features and a headline.
Other codes pick a single feature.
Code "codes" lists them. They share names with related commands
(see also there):
@*
"acl" tells whether xorriso has an adapter for local filesystems ACLs.
@*
"xattr" tells whether xorriso has an adapter for local filesystems EA.
@*
"jigdo" tells whether production of Jigdo files is possible.
@*
"zisofs" tells whether zisofs and built-in gzip filters are enabled.
@*
"external_filter" tells whether external filter processes are allowed
and whether they are allowed if real user id and effective user id differ.
@*
"dvd_obs" tells whether 64 kB output to DVD media is default.
@*
"use_readline" tells whether readline may be enabled in dialog mode.
@*
@c man .TP
@item -history textline
@kindex -history   brings text into readline history
@cindex Dialog, bring text into history, -history
Copy textline into libreadline history.
@c man .TP
@item -status mode|filter
@kindex -status   shows current settings
@cindex Program, show current settings, -status
Print the current settings of @command{xorriso}.
Modes:
@*
  short... print only important or altered settings
@*
  long ... print all settings including defaults
@*
  long_history  like long plus history lines
@*
Filters begin with '-' and are compared literally against the
output lines of -status:long_history. A line is put out only
if its start matches the filter text. No wildcards.
@c man .TP
@item -status_history_max number
@kindex -status_history_max   curbs -status history
@cindex Program, status history, -status_history_max
Set maximum number of history lines to be reported with -status "long_history".
@c man .TP
@item -list_delimiter word
@kindex -list_delimiter   replaces '@minus{}@minus{}'
@cindex Program, replace @minus{}@minus{}, -list_delimiter
Set the list delimiter to be used instead of "@minus{}@minus{}".
It has to be a single word,
must not be empty, not longer than 80 characters, and must not contain
quotation marks.
@*
For brevity the list delimiter is referred as "@minus{}@minus{}"
throughout this text.
@c man .TP
@item -backslash_codes "on"|"off"|mode[:mode]
@kindex -backslash_codes   enables backslash conversion
@cindex Program, backslash conversion, -backslash_codes
Enable or disable the interpretation of symbolic representations of special
characters with quoted input, or with program arguments, or with program
text output. If enabled the following translations apply:
@*
 \a=bell(007) \b=backspace(010) \e=Escape(033) \f=formfeed(014)
@*
 \n=linefeed(012) \r=carriage_return(015) \t=tab(011)
@*
 \v=vtab(013) \\=backslash(134) \[0-7][0-7][0-7]=octal_code
@*
 \x[0-9a-f][0-9a-f]=hex_code \cC=control-C
@*
Translations can occur with quoted input in 3 modes:
@*
 "in_double_quotes" translates only inside " quotation.
@*
 "in_quotes" translates inside " and ' quotation.
@*
 "with_quoted_input" translates inside and outside quotes.
@*
With the start program arguments there is mode:
@*
 "with_program_arguments" translates all program arguments.
@*
@*
Mode "encode_output" encodes output characters. It combines "encode_results"
with "encode_infos". Inside single or double quotation marks encoding applies
to 8-bit characters octal 001 to 037 , 177 to 377 and to backslash(134).
Outside quotation marks some harmless ASCII control characters stay unencoded:
bell(007), backspace(010), tab(011), linefeed(012), formfeed(014),
carriage_return(015).
@*
Mode "off" is default and disables any translation.
Mode "on" is
"with_quoted_input:with_program_arguments:encode_output".
@c man .TP
@item -temp_mem_limit number["k"|"m"]
@kindex -temp_mem_limit   curbs memory consumption
@cindex Program, curb memory, -temp_mem_limit
Set the maximum size of temporary memory to be used for image dependent
buffering. Currently this applies to pattern expansion, LBA sorting,
restoring of hard links.
@*
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB.
@c man .TP
@item -print  text
@kindex -print   prints result text line
@cindex Program, print result text line, -print
Print a text line to the result channel which is by default stdout. 
@c man .TP
@item -print_info  text
@kindex -print_info   prints message text line
@cindex Program, print message text line, -print_info
Print a text line to the info channel which is by default stderr.
@c man .TP
@item -print_mark  text
@kindex -print_mark   prints synchronizing text line
@cindex Program, print synchronizing text line, -print_mark
Print a text line to the mark channel which is by default directed to both,
result and info channel. An empty text will cause no output at all.
@c man .TP
@item -prompt text
@kindex -prompt   prompts for enter key
@cindex Program, prompt for enter key, -prompt
Show text at beginning of output line and
wait for the user to hit the Enter key
resp. to send a line via stdin.
@c man .TP
@item -sleep seconds
@kindex -sleep   waits for a given time span
@cindex Program, wait a time span, -sleep
Wait for the given number of seconds before perfoming the next command.
Expect coarse granularity no better than 1/100 seconds.
@c man .TP
@item -errfile_log mode path|channel
@kindex -errfile_log   logs problematic disk files
@cindex Write, log problematic disk files, -errfile_log
@*
If problem events are related to input files from the filesystem, then their
disk_paths can be logged to a file or to output channels R or I.
@*
Mode can either be "plain" or "marked". The latter causes marker lines which
give the time of log start, burn session start, burn session end, log end
or program end. In mode "plain", only the file paths are logged.
@*
If path is "-" or "-R" then the log is directed to the result channel.
Path "-I" directs it to the info message channel. Any text that does not
begin with "-" is used as path for a file to append the log lines.
@*
Problematic files can be recorded multiple times during one program run.
If the program run aborts then the list might not be complete because
some input files might not have been processed at all.
@*
The errfile paths are transported as messages of very low severity "ERRFILE".
This transport becomes visible with -report_about "ALL".
@c man .TP
@item -session_log path
@kindex -session_log   logs written sessions
@cindex Write, log written sessions, -session_log 
@cindex Session, log when written, -session_log 
If path is not empty it gives the address of a plain text file where
a log record gets appended after each session. This log can be used to
determine the start_lba of a session for mount options -o sbsector=
resp. -s from date or volume ID.
@*
Record format is: timestamp start_lba size volume-id
@*
The first three items are single words, the rest of the line is the volume ID.
@c man .TP
@item -scsi_log "on"|"off"
@kindex -scsi_log   reports SCSI commands
@cindex Drive, report SCSI commands, -scsi_log
Mode "on" enables very verbous logging of SCSI commands and drive replies.
Logging messages get printed to stderr, not to any of the @command{xorriso}
output channels.
@*
A special property of this command is that the first -scsi_log setting
among the start arguments is in effect already when the first operations
of @command{xorriso} begin.
Only "-scsi_log" with dash "-" is recognized that way.
@c man .TP
@item -end
@kindex -end   writes pending session and ends program
@cindex Process, end program and write, -end
@cindex Program, end and write, -end
@*
End program after writing pending changes.
@c man .TP
@item -rollback_end
@kindex -rollback_end   ends program without writing
@cindex Program, end without writing, -rollback_end
@cindex Process, end program, no writing, -rollback_end
Discard pending changes. End program immediately.
@c man .TP
@item # any text
@kindex #   starts a comment line
@cindex Comment, #
Only in dialog or file execution mode, and only as first
non-whitespace in line:
Do not execute the line but store it in readline history.
@end table
@c man .TP
@c man .B Support for frontend programs via stdin and stdout:
@node Frontend, ExDevices, Scripting, Commands
@section Support for frontend programs via stdin and stdout
@table @asis
@c man .TP
@item -pkt_output "on"|"off"
@kindex -pkt_output   consolidates text output
@cindex Process, consolidate text output, -pkt_output
Consolidate text output on stdout and classify each
line by a channel indicator:
@*
 'R:' for result lines,
@*
 'I:' for notes and error messages,
@*
 'M:' for -mark texts.
@*
Next is a decimal number of which only bit 0 has a meaning for now.
0 means no newline at end of payload, 1 means that the newline character at
the end of the output line belongs to the payload. After another colon and
a blank follows the payload text.
@*
Example:
@*
 I:1: enter option and parameters :
@c man .TP
@item -logfile channel fileaddress
@kindex -logfile   logs output channels to file
@cindex Process, log output channels to file, -logfile
Copy output of a channel to the given file. Channel may be one of: "." for all
channels, "I" for info messages, "R" for result lines, "M" for -mark texts.
@c man .TP
@item -mark text
@kindex -mark   sets synchronizing message
@cindex Process, set synchronizing message, -mark
If text is not empty it will get put out on "M" channel each time
@command{xorriso} is ready for the next dialog line or before
@command{xorriso} performs a command that was entered to the pager prompt.
@c man .TP
@item -msg_op opcode parameter_text
@kindex -msg_op   perform operations on program messages
@cindex Program messages, perform operations, -msg_op
This command shall facilitate extraction of particular information from
the message output of other commands. It gives access to the C API function
Xorriso_parse_line() and to the message sieve that is provided by the C API.
Please refer to their descriptions in file xorriso.h.
Further it helps to interpret the severity codes of info messages.
@*
Intended users are frontend programs which operate xorriso in dialog mode.
@*
The result output of this command is not caught by the message sieve.
@*
The following opcodes are defined:
@*
@strong{start_sieve}
@*
Install the message sieve as of Xorriso_sieve_big() and start watching
program messages. The parameter_text has no meaning.
@*
@strong{show_sieve}
@*
Show a list of filter rule names. The parameter_text has no meaning.
The list begins by a line with the return value of Xorriso_sieve_get_result()
with flag bit3. If this value is larger than 0, then the next line tells
the number of names. The following lines show one name each.
@*
@strong{read_sieve}
@*
Use the parameter_text as name of a filter rule and inquire its next
recorded result.
See Xorriso_sieve_big() for a list of names and reply strings.
@*
The recorded strings are put out on result channel. They get wrapped
into lines which tell their structure.
The first line tells the return value of Xorriso_sieve_get_result().
The next line tells the number of strings. Each string begins by a line that
tells the number of lines of the string. Then follow these lines. They are to
be concatenated with a newline character inbetween each of them.
Finally the number of still available recorded results of the given name
is put out.
@*
@strong{clear_sieve}
@*
Dispose all recorded strings and continue watching program messages.
The parameter_text has no meaning.
@*
@strong{end_sieve}
@*
Dispose the sieve with its filter rules and stop watching program messages.
The parameter_text has no meaning.
@*
@strong{parse}
@*
Read a text from dialog input and submit it to Xorriso_parse_line().
The parameter_text word shall consist of several words separated by blanks.
It will be necessary to use both kinds of quotation marks.
@*
E.g. "'ISO session  :' '' 0 0 1"
@*
The five parameter words are: prefix, separators, max_words, flag,
number_of_input_lines.
The former four are handed over to Xorriso_parse_line(). The number of
input lines minus one tells xorriso how many newline characters are
part of the input text.
@*
The announced number of text lines will be read from dialog input,
concatenated with a newline character inbetween each of them,
and submitted to Xorriso_parse_line() as parameter line.
Note that newlines outside of quotation marks are
interpreted as separators if the separators parameter is empty.
@*
The parsed strings are put out on result channel. They get wrapped
into lines which tell their structure.
The first line tells the return value of Xorriso_parse_line().
The next line tells the number of strings. Each string begins by a line that
tells the number of lines of the string. Then follow these lines. They are to 
be concatenated with a newline character inbetween each of them.
@*
If -backslash_codes "encode_output" is enabled, then the strings undergo
encoding as if they were enclosed in quotes. Escpecially each string
will be put out as a single result line.
@*
@strong{parse_bulk}
@*
Like "parse", but with the fifth parameter word being number_of_input_texts
rather than number_of_input_lines. Each input text has to be preceded by
a line that tells number_of_input_lines as with "parse".
Then come the announced number of text lines.
@*
All input texts will be read before printing of result lines begins.
This consumes memory in xorriso. So the number_of_input_texts should not
be extremely high. On the other hand, large transactions of command,
input texts, and results are desirable if connection latency is an
issue. 
@*
@strong{compare_sev}
@*
The parameter_text should contain two comma separated severity texts as
issued by this program. Like "SORRY,UPDATE". See also paragraph
"Exception processing".
@*
These two severity texts get compared and a number gets printed
to the result channel. This number is 0 if both severities are equal.
It is -1 if the first severity is lower than the second one.
It is 1 is the first severity is higher than the second one.
@*
Above example "SORRY,UPDATE" will yield 1.
@*
@strong{list_sev}
@*
Print to the result channel a blank separated list of all severity names.
Sorted from low to high severity.
@*
@c man .TP
@item -launch_frontend program [arguments ...] @minus{}@minus{}
@kindex -launch_frontend   starts frontend program at pipes
@cindex Frontend program, start at pipes, -launch_frontend
Start the program that is given as first parameter. Submit the other
parameters as program arguments. Enable xorriso dialog mode.
@*
Two nameless pipe objects are created. xorriso standard input gets
connected to the standard output of the started program.
xorriso standard output and standard error get connected to the
standard input of that program.
@*
xorriso will abort when the started program ends or if it cannot
be started at all. In both cases it will return a non-zero exit value.
The exit value will be zero if the frontend sends -end or -rollback_end
before ending itself.
@*
This command may be totaly banned at compile time. It is banned
by default if xorriso runs under setuid permissions.
@*
The program name will not be searched in the $PATH directories.
To make this clear, it must contain at least one /-character.
Best is an absolute path.
@*
Example:
@*
  xorriso -launch_frontend "$(which xorriso-tcltk)" -stdio --
@*
The frontend program should first send via its standard output:
@*
  -mark 0 -pkt_output on -msg_op start_sieve - -reassure off
@*
It should be ready to decode -pkt_output and to react on -mark messages.
Best is to increment the -mark number after each sent command sequence
and then to wait for the new number to show up in a mark message:
@*
  ...some...commands... -mark <incremented_number>
@*
Further are advised:
@*
  -report_about UPDATE -abort_on NEVER
@*
  -iso_rr_pattern off -disk_pattern off
@*
A check of the xorriso version should be done, in order to make sure
that all desired features are present.
@*
Command -launch_frontend will only work once per xorriso run.
If no command parameters are submitted or if program is an empty text,
then no program will be started but nevertheless -launch_frontend will
be irrevocably disabled.
@c man .TP
@item -prog text
@kindex -prog   sets program name
@cindex Program, set name, -prog
Use text as name of this program in subsequent messages
@c man .TP
@item -prog_help text
@kindex -prog_help   prints help text
@cindex Program, print help text, -prog_help
Use text as name of this program and perform -help.
@end table
@c man .br
@node Examples, Files, Commands, Top
@chapter Examples
@c man .SH EXAMPLES
@c man .SS
@c man .B Overview of examples:
@c man As superuser learn about available drives
@c man .br
@c man Blank medium and compose a new ISO image as batch run
@c man .br
@c man A dialog session doing about the same
@c man .br
@c man Manipulate an existing ISO image on the same medium
@c man .br
@c man Copy modified ISO image from one medium to another
@c man .br
@c man Bring a prepared ISOLINUX tree onto medium and make it bootable
@c man .br
@c man Change existing file name tree from ISO-8859-1 to UTF-8
@c man .br
@c man Operate on storage facilities other than optical drives
@c man .br
@c man Burn an existing ISO image file to medium
@c man .br
@c man Perform multi-session runs as of cdrtools traditions
@c man .br
@c man Let xorriso work underneath growisofs
@c man .br
@c man Adjust thresholds for verbosity, exit value and program abort
@c man .br
@c man Examples of input timestrings
@c man .br
@c man Incremental backup of a few directory trees
@c man .br
@c man Restore directory trees from a particular ISO session to disk
@c man .br
@c man Try to retrieve blocks from a damaged medium
@cindex Examples
@menu
* ExDevices::    As superuser learn about available drives
* ExCreate::     Blank medium and compose a new ISO image as batch run
* ExDialog::     A dialog session doing about the same
* ExGrowing::    Manipulate an existing ISO image on the same medium
* ExModifying::  Copy modified ISO image from one medium to another
* ExBootable::   Bring a prepared ISOLINUX tree onto medium and make it bootable
* ExCharset::    Change existing file name tree from ISO-8859-1 to UTF-8
* ExPseudo::     Operate on storage facilities other than optical drives
* ExCdrecord::   Burn an existing ISO image file to medium
* ExMkisofs::    Perform multi-session runs as of cdrtools traditions
* ExGrowisofs::  Let @command{xorriso} work underneath growisofs
* ExException::  Adjust thresholds for verbosity, exit value and program abort
* ExTime::       Examples of input timestrings
* ExIncBackup::  Incremental backup of a few directory trees
* ExRestore::    Restore directory trees from a particular ISO session to disk
* ExRecovery::   Try to retrieve blocks from a damaged medium
@end menu
@c man .SS
@c man .B As superuser learn about available drives
@node ExDevices, ExCreate, Frontend, Examples
@section As superuser learn about available drives
On Linux or FreeBSD consider to give rw-permissions to those users or groups
which shall be able to use the drives with @command{xorriso}.
On Solaris use pfexec. Consider to restrict privileges of @command{xorriso} to
"base,sys_devices" and to give r-permission to user or group.
@*
@sp 1
$ xorriso -device_links
@*
1  -dev '/dev/cdrom1' rwrw@minus{}@minus{} :  'TSSTcorp' 'DVD-ROM SH-D162C
@*
1  -dev '/dev/cdrw'   rwrw@minus{}@minus{} :  'TSSTcorp' 'CDDVDW SH-S223B'
@*
2  -dev '/dev/cdrw3'  rwrw@minus{}@minus{} :  'HL-DT-ST' 'BDDVDRW_GGC-H20L'
@c man .SS
@c man .B Blank medium and compose a new ISO image as batch run
@node ExCreate, ExDialog, ExDevices, Examples
@section Blank medium and compose a new ISO image as batch run
Acquire drive /dev/sr2, make medium ready for writing a new image,
fill the image with the files from hard disk directories /home/me/sounds
and /home/me/pictures.
@*
Because no -dialog "on" is given, the program will then end by writing the
session to the medium.
@*
@sp 1
$ xorriso -outdev /dev/sr2 \
@*
 -blank as_needed \
@*
 -map /home/me/sounds /sounds \
@*
 -map /home/me/pictures /pictures
@*
@sp 1

@*
The ISO image may be shaped in a more elaborate way like the following:
Omit some unwanted stuff by removing it from the image directory tree.
Reintroduce some wanted stuff.
@*
@sp 1
$ cd /home/me
@*
$ xorriso -outdev /dev/sr2 \
@*
 -blank as_needed \
@*
 -map /home/me/sounds /sounds \
@*
 -map /home/me/pictures /pictures \
@*
 -rm_r \
@*
   /sounds/indecent \
@*
   '/pictures/*private*' \
@*
   /pictures/confidential \
@*
   @minus{}@minus{} \
@*
 -cd / \
@*
 -add pictures/confidential/work* @minus{}@minus{}
@*
@sp 1
Note that '/pictures/*private*' is a pattern for iso_rr_paths
while pictures/confidential/work* gets expanded by the shell
with addresses from the hard disk. Commands -add and -map have different
parameter rules but finally the same effect: they put files into the image.
@c man .SS
@c man .B A dialog session doing about the same
@c man .br
@node ExDialog, ExGrowing, ExCreate, Examples
@section A dialog session doing about the same as the previous example
Some settings are already given as start argument. The other activities
are done as dialog input. The pager gets set to 20 lines of 80 characters.
@*
The drive is acquired by command -dev rather than -outdev in order to see
the message about its current content. By command -blank this content is
made ready for being overwritten and the loaded ISO image is made empty.
@*
In order to be able to eject the medium, the session needs to be committed
explicitly.
@*
@c man .B $ xorriso -dialog on -page 20 80 -disk_pattern on
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-dev /dev/sr2
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-blank as_needed
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-map /home/me/sounds /sounds -map /home/me/pictures /pictures
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-rm_r /sounds/indecent /pictures/*private* /pictures/confidential
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-cdx /home/me/pictures -cd /pictures
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-add confidential/office confidential/factory
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-du /
@c man .br
@c man enter option and arguments :
@c man .br
@c man .B \-commit_eject all -end
@c man .br
@sp 1
@c man-ignore-lines begin
$ xorriso -dialog on -page 20 80 -disk_pattern on
@sp 1
enter option and arguments :
@*
-dev /dev/sr2
@sp 1
enter option and arguments :
@*
-blank as_needed
@sp 1
enter option and arguments :
@*
-map /home/me/sounds /sounds -map /home/me/pictures /pictures
@sp 1
enter option and arguments :
@*
-rm_r /sounds/indecent /pictures/*private* /pictures/confidential
@sp 1
enter option and arguments :
@*
-cdx /home/me/pictures -cd /pictures
@sp 1
enter option and arguments :
@*
-add confidential/office confidential/factory
@sp 1
enter option and arguments :
@*
-du /
@sp 1
enter option and arguments :
@*
-commit_eject all -end
@c man-ignore-lines end
@c man .SS
@c man .B Manipulate an existing ISO image on the same medium
@node ExGrowing, ExModifying, ExDialog, Examples
@section Manipulate an existing ISO image on the same medium
Load image from drive.
Remove (i.e. hide) directory /sounds and its subordinates.
Rename directory /pictures/confidential to /pictures/restricted.
Change access permissions of directory /pictures/restricted.
Add new directory trees /sounds and /movies.
Burn to the same medium, check whether the tree can be loaded, and eject.
@*
@sp 1
$ xorriso -dev /dev/sr2 \
@*
 -rm_r /sounds @minus{}@minus{} \
@*
 -mv \
@*
   /pictures/confidential \
@*
   /pictures/restricted \
@*
   @minus{}@minus{} \
@*
 -chmod go-rwx /pictures/restricted @minus{}@minus{} \
@*
 -map /home/me/prepared_for_dvd/sounds_dummy /sounds \
@*
 -map /home/me/prepared_for_dvd/movies /movies \
@*
 -commit -eject all
@c man .SS
@c man .B Copy modified ISO image from one medium to another
@node ExModifying, ExBootable, ExGrowing, Examples
@section Copy modified ISO image from one medium to another
Load image from input drive. Do the same manipulations as in the previous
example. Acquire output drive and blank it. Burn the modified image as
first and only session to the output drive.
@*
@sp 1
$ xorriso -indev /dev/sr2 \
@*
 -rm_r /sounds @minus{}@minus{} \
@*
 ...
@*
 -outdev /dev/sr0 -blank as_needed \
@*
 -commit -eject all
@c man .SS
@c man .B Bring a prepared ISOLINUX tree onto medium and make it bootable
@node ExBootable, ExCharset, ExModifying, Examples
@section Bring a prepared ISOLINUX tree onto medium and make it bootable
The user has already created a suitable file tree on disk and copied the
ISOLINUX files into subdirectory ./boot/isolinux of that tree.
Now @command{xorriso} can burn an El Torito bootable medium:
@*
@sp 1
$ xorriso -outdev /dev/sr0 -blank as_needed \
@*
   -map /home/me/ISOLINUX_prepared_tree / \
@*
   -boot_image isolinux dir=/boot/isolinux
@c man .SS
@c man .B Change existing file name tree from ISO-8859-1 to UTF-8
@node ExCharset, ExPseudo, ExBootable, Examples
@section Change existing file name tree from ISO-8859-1 to UTF-8
This example assumes that the existing ISO image was written with character
set ISO-8859-1 but that the readers expected UTF-8. Now a new session with
the same files gets added with converted file names.
In order to avoid any weaknesses of the local character set, this command
pretends that it uses already the final target set UTF-8.
Therefore strange file names may appear in messages, which
will be made terminal-safe by command -backslash_codes.
@*
@sp 1
$ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
@*
   -out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
@*
   -alter_date m +0 / @minus{}@minus{} -commit -eject all
@c man .SS
@c man .B Operate on storage facilities other than optical drives
@node ExPseudo, ExCdrecord, ExCharset, Examples
@section Operate on storage facilities other than optical drives
Full read-write operation is possible with regular files and block devices:
@*
@sp 1
$ xorriso -dev /tmp/regular_file ...
@*
@sp 1
Paths underneath /dev normally need prefix "stdio:"
@*
@sp 1
$ xorriso -dev stdio:/dev/sdb ...
@*
@sp 1
If /dev/sdb is to be used frequently and /dev/sda is the system disk,
then consider to place the following lines in a @command{xorriso} Startup File.
They allow to use /dev/sdb without prefix and protect disk /dev/sda
from @command{xorriso}:
@*
@sp 1
  -drive_class banned   /dev/sda*
@*
  -drive_class harmless /dev/sdb
@*
@sp 1
Other writeable file types are supported write-only:
@*
@sp 1
$ xorriso -outdev /tmp/named_pipe ...
@*
@sp 1
Among the write-only drives is standard output:
@*
@sp 1
$ xorriso -outdev - \
@*
 ...
@*
 | gzip >image.iso.gz
@c man .SS
@c man .B Burn an existing ISO image file to medium
@node ExCdrecord, ExMkisofs, ExPseudo, Examples
@section Burn an existing ISO image file to medium
Actually this works with any kind of data, not only ISO images:
@*
@sp 1
$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso
@c man .SS
@c man .B Perform multi-session runs as of cdrtools traditions
@node ExMkisofs, ExGrowisofs, ExCdrecord, Examples
@section Perform multi-session runs as of cdrtools traditions
Between both processes there can be performed arbitrary transportation
or filtering.
@*
The first session is written like this:
@*
@sp 1
$ xorriso -as mkisofs prepared_for_iso/tree1 | \
@*
 xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject - 
@*
@sp 1
Follow-up sessions are written like this:
@*
@sp 1
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
@*
$ m=$(xorriso -as cdrecord dev=/dev/sr0 -msinfo)
@*
$ xorriso -as mkisofs -M /dev/sr0 -C $m prepared_for_iso/tree2 | \
@*
 xorriso -as cdrecord -v dev=/dev/sr0 -waiti -multi -eject -
@*
@sp 1
Always eject the drive tray between sessions. The old sessions
get read via /dev/sr0. Its device driver might not be aware
of the changed content before it loads the medium again.
In this case the previous session would not be loaded and the
new session would contain only the newly added files.
@*
For the same reason do not let @command{xorriso} -as cdrecord load the medium,
but rather do this manually or by a program that reads from /dev/sr0.
@*
@sp 1
This example works for multi-session media only.
Add cdrskin option @minus{}@minus{}grow_overwriteable_iso
to all -as cdrecord runs
in order to enable multi-session emulation on overwriteable media.
@c man .SS
@c man .B Let xorriso work underneath growisofs
@node ExGrowisofs, ExException, ExMkisofs, Examples
@section Let @command{xorriso} work underneath growisofs
growisofs expects an ISO formatter program which understands options -C and
-M. If @command{xorriso} gets started by name "xorrisofs" then it is suitable
for that.
@*
@sp 1
$ export MKISOFS="xorrisofs"
@*
$ growisofs -Z /dev/dvd /some/files
@*
$ growisofs -M /dev/dvd /more/files
@*
@sp 1
If no "xorrisofs" is available on your system, then you will have to create
a link pointing to the @command{xorriso} binary and tell growisofs to use it.
E.g. by:
@*
@sp 1
$ ln -s $(which xorriso) "$HOME/xorrisofs"
@*
$ export MKISOFS="$HOME/xorrisofs"
@*
@sp 1
One may quit mkisofs emulation by argument "@minus{}@minus{}" and make
use of all @command{xorriso} commands. growisofs dislikes options which
start with "-o" but -outdev must be set to "-".
So use "outdev" instead:
@*
@sp 1
$ growisofs -Z /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
@*
$ growisofs -M /dev/dvd @minus{}@minus{} outdev - -update_r /my/files /files
@*
@sp 1
growisofs has excellent burn capabilities with DVD and BD.
It does not emulate session history on overwriteable media, though.
@c man .SS
@c man .B Adjust thresholds for verbosity, exit value and program abort
@node ExException, ExTime, ExGrowisofs, Examples
@section Adjust thresholds for verbosity, exit value and program abort
Be quite verbous, exit 32 if severity "FAILURE" was encountered,
do not abort prematurely but forcibly go on until the end of commands.
@*
@sp 1
$ xorriso ... \
@*
 -report_about UPDATE \
@*
 -return_with FAILURE 32 \
@*
 -abort_on NEVER \
@*
 ...
@c man .SS
@c man .B Examples of input timestrings
@node ExTime, ExIncBackup, ExException, Examples
@section Examples of input timestrings
@c man .br
@c man As printed by program date:
@c man .B 'Thu Nov  8 14:51:13 CET 2007'
@c man .br
@c man The same without ignored parts:
@c man .B 'Nov 8 14:51:13 2007'
@c man .br
@c man The same as expected by date:
@c man .B 110814512007.13
@c man .br
@c man Four weeks in the future:
@c man .B +4w
@c man .br
@c man The current time:
@c man .B +0
@c man .br
@c man Three hours ago:
@c man .B \-3h
@c man .br
@c man Seconds since Jan 1 1970:
@c man .B =1194531416
@c man-ignore-lines begin
As printed by program date:
@*
'Thu Nov  8 14:51:13 CET 2007'
@sp 1
The same without ignored parts:
@*
'Nov 8 14:51:13 2007'
@sp 1
The same as expected by date:
@*
110814512007.13
@sp 1
Four weeks in the future:
@*
+4w
@sp 1
The current time:
@*
+0
@sp 1
Three hours ago:
@*
-3h
@sp 1
Seconds since Jan 1 1970:
@*
=1194531416
@c man-ignore-lines end
@c man .SS
@c man .B Incremental backup of a few directory trees
@node ExIncBackup, ExRestore, ExTime, Examples
@section Incremental backup of a few directory trees
This changes the directory trees /projects and /personal_mail
in the ISO image so that they become exact copies of their disk counterparts.
ISO file objects get created, deleted or get their attributes adjusted
accordingly.
@*
ACL, xattr, hard links and MD5 checksums will be recorded.
Accelerated comparison is enabled at the expense of potentially larger backup
size. Only media with the expected volume ID or blank media are accepted.
Files with names matching *.o or *.swp get excluded explicitly.
@*
When done with writing the new session gets checked by its recorded MD5.
@*
@sp 1
$ xorriso \
@*
 -abort_on FATAL \
@*
 -for_backup -disk_dev_ino on \
@*
 -assert_volid 'PROJECTS_MAIL_*' FATAL \
@*
 -dev /dev/sr0 \
@*
 -volid PROJECTS_MAIL_"$(date '+%Y_%m_%d_%H%M%S')" \
@*
 -not_leaf '*.o' -not_leaf '*.swp' \
@*
 -update_r /home/thomas/projects /projects \
@*
 -update_r /home/thomas/personal_mail /personal_mail \
@*
 -commit -toc -check_md5 FAILURE @minus{}@minus{} -eject all
@*
@sp 1
To be used several times on the same medium, whenever an update of
the two disk trees to the medium is desired. Begin with a blank medium and
update it until the run fails gracefully due to lack of remaining space on
the old one.
@*
This makes sense if the full backup leaves substantial remaining capacity
on media and if the expected changes are much smaller than the full backup.
To apply zisofs compression to those data files which get newly copied from
the local filesystem, insert these commands immediately before -commit :
@*
@sp 1
 -hardlinks perform_update \
@*
 -find / -type f -pending_data -exec set_filter @minus{}@minus{}zisofs @minus{}@minus{} \
@*
@sp 1
Commands -disk_dev_ino and -for_backup depend on stable device and inode numbers
on disk. Without them, an update run may use -md5 "on" to match recorded MD5
sums against the current file content on hard disk. This is usually much faster
than the default which compares both contents directly.
@*
With @strong{mount} option @strong{-o "sbsector="} on GNU/Linux
resp. @strong{-s} on FreeBSD
it is possible to access the session trees which represent the older backup
versions. With CD media, GNU/Linux mount accepts session numbers directly by
its option "session=".
@*
Multi-session media and most overwriteable media written by @command{xorriso}
can tell the sbsectors of their sessions by @command{xorriso} command -toc.
Used after -commit the following command prints the matching mount command for
the newly written session (here for mount point /mnt):
@*
@sp 1
 -mount_cmd "indev" "auto" "auto" /mnt
@*
@sp 1
Commands -mount_cmd and -mount are also able to produce the mount commands for
older sessions in the table-of-content. E.g. as superuser:
@*
@sp 1
 # osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
@*
@sp 1
@c man .sp 1
Above example produces a result similar to  -root / -old-root / with mkisofs.
For getting the session trees accumulated in the new sessions, let all -update
commands use a common parent directory and clone it after updating is done:
@*
 -update_r /home/thomas/projects /current/projects \
@*
 -update_r /home/thomas/personal_mail /current/personal_mail \
@*
 -clone /current /"$(date '+%Y_%m_%d_%H%M%S')" \
@*
The cloned tree will have a name like /2011_02_12_155700.
@*
@sp 1
@c man .sp 1
Sessions on multi-session media are separated by several MB of unused blocks.
So with small sessions the payload capacity can become substantially lower
than the overall media capacity. If the remaining space on a medium does not
suffice for the next gap, the drive is supposed to close the medium
automatically.
@*
@sp 1
@c man .sp 1
@strong{Better do not use your youngest backup for -update_r}.
Have at least two media which you use alternatingly. So only older backups
get endangered by the new write operation, while the newest backup is
stored safely on a different medium.
@*
Always have a blank medium ready to perform a full backup in case the update
attempt fails due to insufficient remaining capacity. This failure will
not spoil the old medium, of course.
@c man .SS
@c man .B Restore directory trees from a particular ISO session to disk
@node ExRestore, ExRecovery, ExIncBackup, Examples
@section Restore directory trees from a particular ISO session to disk
This is an alternative to mounting the medium and using normal file operations.
@*
First check which backup sessions are on the medium:
@*
@sp 1
$ xorriso -outdev /dev/sr0 -toc
@*
@sp 1
Then enable restoring of ACL, xattr and hard links. Load the desired session
and copy the file trees to disk.
Avoid to create /home/thomas/restored without rwx-permission.
@*
@sp 1
$ xorriso -for_backup \
@*
 -load volid 'PROJECTS_MAIL_2008_06_19*' \
@*
 -indev /dev/sr0 \
@*
 -osirrox on:auto_chmod_on \
@*
 -chmod u+rwx / @minus{}@minus{} \
@*
 -extract /projects /home/thomas/restored/projects \
@*
 -extract /personal_mail /home/thomas/restored/personal_mail \
@*
 -rollback_end
@*
@sp 1
The final command -rollback_end prevents an error message about the altered
image being discarded.
@c man .SS
@c man .B Try to retrieve blocks from a damaged medium
@node ExRecovery,, ExRestore, Examples
@section Try to retrieve blocks from a damaged medium
@*
@sp 1
$ xorriso -abort_on NEVER -indev /dev/sr0 \
@*
 -check_media time_limit=1800 report=blocks_files \
@*
 data_to="$HOME"/dvd_copy sector_map="$HOME"/dvd_copy.map @minus{}@minus{}
@*
@sp 1
This can be repeated several times, if necessary with -eject or with other
-indev drives. See the human readable part of "$HOME"/dvd_copy.map for
addresses which can be used on "$HOME"/dvd_copy with mount option -o sbsector=
resp. -s.
@c man .SH FILES
@node Files, Seealso, Examples, Top 
@chapter Files
@c man .SS 
@c man .B Program alias names:
@*
@section Program Alias Names
Normal installation of @command{xorriso} creates three links or copies which by their
program name pre-select certain settings:
@*
@sp 1
@strong{xorrisofs} starts @command{xorriso} with -as mkisofs emulation.
@*
@strong{xorrecord} starts @command{xorriso} with -as cdrecord emulation.
@*
@strong{osirrox} starts with -osirrox "on:o_excl_off" which allows
to copy files from ISO image to disk and to apply command -mount to
one or more of the existing ISO sessions.
@c man .SS 
@c man .B Startup files:
@section Startup Files
@*
If not -no_rc is given as the first argument then @command{xorriso} attempts on startup
to read and execute lines from the following files:
@*
@sp 1
   /etc/default/xorriso
@*
   /etc/opt/xorriso/rc
@*
   /etc/xorriso/xorriso.conf
@*
   $HOME/.xorrisorc
@*
@sp 1
The files are read in the sequence given above, but none of them is required
to exist. The line format is described with command -options_from_file.
@*
If mkisofs emulation was enabled by program name "xorrisofs", "mkisofs",
"genisoimage", or "genisofs", then afterwards -read_mkisofsrc is performed,
which reads .mkisofsrc files. See there.
@c man .SS
@c man .B Runtime control files:
@section Runtime control files
@*
The default setting of -check_media abort_file= is:
@*
@sp 1
   /var/opt/xorriso/do_abort_check_media
@*
@c man .SH SEE ALSO
@c man .TP
@c man For the mkisofs emulation of xorriso
@c man .BR xorrisofs(1) 
@c man .TP
@c man For the cdrecord emulation of xorriso
@c man .BR xorrecord(1)
@c man .TP 
@c man For mounting xorriso generated ISO 9660 images (-t iso9660)
@c man .BR mount(8)
@c man .TP
@c man Libreadline, a comfortable input line facility
@c man .BR readline(3)
@c man .TP
@c man Other programs which produce ISO 9660 images
@c man .BR mkisofs(8),
@c man .BR genisoimage(8)
@c man .TP
@c man Other programs which burn sessions to optical media
@c man .BR growisofs(1),
@c man .BR cdrecord(1),
@c man .BR wodim(1),
@c man .BR cdrskin(1)
@c man .TP
@c man ACL and xattr
@c man .BR getfacl(1),
@c man .BR setfacl(1),
@c man .BR getfattr(1),
@c man .BR setfattr(1)
@c man .TP
@c man MD5 checksums
@c man .BR md5sum(1)
@c man .TP
@c man On FreeBSD the commands for xattr and MD5 differ
@c man .BR getextattr(8),
@c man .BR setextattr(8),
@c man .BR md5(1)
@c man-ignore-lines begin
@node Seealso, Bugreport, Files, Top 
@chapter See also
@table @asis
@item For the mkisofs emulation of @command{xorriso}
xorrisofs(1) 
@item For the cdrecord emulation of @command{xorriso}
xorrecord(1) 
@item For mounting @command{xorriso} generated ISO 9660 images (-t iso9660)
mount(8)
@item Libreadline, a comfortable input line facility
readline(3)
@item Other programs which produce ISO 9660 images
mkisofs(8),
genisoimage(8)
@item Other programs which burn sessions to optical media
growisofs(1),
cdrecord(1),
wodim(1),
cdrskin(1)
@item ACL and xattr
getfacl(1),
setfacl(1),
getfattr(1),
setfattr(1)
@item MD5 checksums
md5sum(1)
@item On FreeBSD some commands differ:
getextattr(8),
setextattr(8),
md5(1)
@end table
@c man-ignore-lines end
@c man .SH BUGS
@node Bugreport, Legal, Seealso, Top
@chapter Reporting bugs
@cindex Bugs, reporting
@cindex Problems, reporting
To report bugs, request help, or suggest enhancements for @command{xorriso},
please send electronic mail to the public list @email{bug-xorriso@@gnu.org}.
If more privacy is desired, mail to @email{scdbackup@@gmx.net}.
@*
@sp 1
Please describe what you expect @command{xorriso} to do,
the program arguments resp. commands by which you tried to achieve it,
the messages of @command{xorriso}, and the undesirable outcome of your
program run.
@*
@sp 1
Expect to get asked more questions before solutions can be proposed. 
@c man .SH AUTHOR
@node Legal, CommandIdx, Bugreport, Top
@chapter Author, Copyright, Credits
@section Author
Thomas Schmitt <scdbackup@@gmx.net>
@*
for libburnia-project.org
@c man .SH COPYRIGHT
@section Copyright
Copyright (c) 2007 - 2013 Thomas Schmitt
@*
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of @command{xorriso}.
If you make use of the license to derive modified versions of
@command{xorriso} then you are entitled to modify this text under that
same license.
@c man .SH CREDITS
@section Credits
@command{xorriso} is in part based on work by Vreixo Formoso who provides
libisofs together with Mario Danic who also leads the libburnia team.
Vladimir Serbinenko contributed the HFS+ filesystem code and related knowledge.
Thanks to Andy Polyakov who invented emulated growing,
to Derek Foreman and Ben Jansens who once founded libburn.
@*
Compliments towards Joerg Schilling whose cdrtools served me for ten years.
@c man-ignore-lines begin

@node CommandIdx, ConceptIdx, Legal, Top
@chapter Alphabetic Command List
@printindex ky

@node ConceptIdx,, CommandIdx, top
@chapter Alphabetic List of Concepts and Objects
@printindex cp

@c man-ignore-lines end
@bye