5737 lines
224 KiB
Raw Normal View History

\input texinfo @c -*-texinfo-*-
@c %**start of header
2011-09-27 13:36:10 +00:00
@settitle GNU xorriso 1.1.7
@c %**end of header
@c man-ignore-lines begin
@dircategory Archiving
* Xorriso: (xorriso). Burns ISO 9660 on CD, DVD, BD.
@end direntry
@c man-ignore-lines end
@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 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)
2011-09-27 13:36:10 +00:00
@c man .TH XORRISO 1 "Version 1.1.7, Sep 27, 2011"
@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
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions.
2011-07-08 13:24:57 +00:00
Copyright @copyright{} 2007 - 2011 Thomas Schmitt
Permission is granted to distrubute this text freely.
@end quotation
@end copying
@c man-ignore-lines end
2011-09-27 13:36:10 +00:00
@title Manual of GNU xorriso 1.1.7
@author Thomas Schmitt
@vskip 0pt plus 1filll
@end titlepage
@node Top
2011-09-27 13:36:10 +00:00
@top GNU xorriso 1.1.7
@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
* Overview:: Overview
* Model:: Session model
* Media:: Media types and states
* Methods:: Creating, Growing, Modifying, Blind Growing
* Drives:: Libburn drives
* Extras:: Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
* Processing:: Command processing
* Dialog:: Dialog, Readline, Result pager
* Options:: Reference of commands
* Examples:: Examples
* Files:: Files
* Seealso:: See also
* 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 .B xorriso
@c man .RI [ settings | actions ]
@c man .br
@c man .PP
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
@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 .
@c man .SS
@section Features
@c man .B Overview of features:
Operates on an existing ISO image or creates a new one.
Copies files from disk filesystem into the ISO image.
Copies files from ISO image to disk filesystem (see osirrox).
Renames or deletes file objects in the ISO image.
Changes file properties in the ISO image.
Updates ISO subtrees incrementally to match given disk subtrees.
Writes result either as completely new image or as add-on session
to optical media or filesystem objects.
Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
Can perform multi-session tasks as emulation of mkisofs and cdrecord.
Can record and restore hard links and ACL.
Content may get zisofs compressed or filtered by external processes.
Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
Can check media for damages and copy readable blocks to disk.
Can attach MD5 checksums to each data file and the whole session.
Scans for optical drives, blanks re-useable optical media.
Reads its instructions from command line arguments, dialog, and files.
Provides navigation commands for interactive ISO image manipulation.
Adjustable thresholds for abort, exit value, and problem reporting.
@c man .SS
@c man .B General information paragraphs:
@c man .br
@c man Session model
@c man .br
@c man Media types and states
@c man .br
@c man Creating, Growing, Modifying, Blind Growing
@c man .br
@c man Libburn drives
@c man .br
@c man Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
@c man .br
@c man Command processing
@c man .br
@c man Dialog, Readline, Result pager
@c man .sp 1
@c man Maybe you first want to have a look at section EXAMPLES near the end of
@c man this text before reading the next few hundred lines of background information.
@c man .SS
@node Model, Media, Overview, Top
@chapter Session model
@c man \fBSession model:\fR
@c man .br
@cindex Session, _definition
Unlike other filesystems, ISO 9660 is not intended for read-write operation but
rather for being generated in a single sweep and being written to media as a
@cindex Image, _definition
The data content of the session is called filesystem @strong{image}.
@c man .PP
@sp 1
The written image in its session can then be mounted by the operating system
for being used read-only. GNU/Linux is able to mount ISO images from block
devices, which may represent optical media, other media or via a loop device
even from regular disk files. FreeBSD mounts ISO images from devices that
represent arbitrary media or from regular disk files.
@c man .PP
@sp 1
@cindex Multi-session, _definition
This session usage model has been extended on CD media by the concept of
@strong{multi-session} ,
which allows to add information to the CD and gives the mount programs
of the operating systems the addresses of the entry points of each
session. The mount programs recognize block devices which represent
CD media and will by default mount the image in the last session.
This session usually contains an updated directory tree for the whole media
which governs the data contents in all recorded sessions.
So in the view of the mount program all sessions of a particular media
together form a single filesystem image.
Adding a session to an existing ISO image is in this text referred as
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
@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 media.
@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 option @strong{-toc}.
Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW.
They allow only a single session of which the size must be known in advance.
@command{xorriso} will write onto them only if option -close is set to "on".
@cindex Overwriteable media, _definition
@strong{Overwriteable media} are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
They allow random write access but do not provide information about their
session history. If they contain one or more ISO 9660 sessions and if the
first session was written by @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
@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 option -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 option -close on. If the drive is read-only hardware then it will
probably show any media as closed CD-ROM resp. DVD-ROM.
Overwriteable media assume this state in such read-only drives or if they
contain unrecognizable data in the first 32 data blocks.
Read-only drives may or may not show session histories of multi-session
media. Often only the first and the last session are visible. Sometimes
not even that. Option -rom_toc_scan might or might not help in such cases.
@c man .SS
@node Methods, Drives, Media, top
@chapter Creating, Growing, Modifying, Blind Growing:
@c man .B Creating, Growing, Modifying, Blind Growing:
@cindex Create, new ISO image, _definiton
A new empty ISO image gets @strong{created}
if there is no input drive with a valid ISO 9660 image when the first time
an output drive is defined. This is achieved by option -dev on blank media
or by option -outdev on media in any state.
The new empty image can be populated with directories and files.
Before it can be written, the media in the output drive must get into
blank state if it was not blank already.
@c man .PP
@sp 1
If there is a input drive with a valid ISO image, then this image gets loaded
as foundation for manipulations and extension. The constellation of input
and output drive determines which write method will be used.
They have quite different capabilities and constraints.
@c man .PP
@sp 1
@cindex Growing, _definition
The method of @strong{growing} adds new data to the existing media. These
data comprise of new file content and they override the existing
ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
previous sessions but they still exist on media and with many types of
optical media it is quite easy to recover them by mounting older sessions.
Growing is achieved by option -dev.
@c man .PP
@sp 1
@cindex Modifying, _definition
The write method of @strong{modifying} produces compact filesystem
images with no outdated files or directory trees. Modifying can write its
images to target media which are completely unsuitable for multi-session
operations. E.g. DVD-RW which were treated with -blank deformat_quickest,
DVD-R DL, named pipes, character devices, sockets.
On the other hand modified sessions cannot be written to appendable media
but to blank media only.
So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target media.
Modifying takes place if input drive and output drive are not the same and
if option -grow_blindly is set to its default "off".
This is achieved by options -indev and -outdev.
@c man .PP
@sp 1
@cindex Blind growing, _definition
If option -grow_blindly is set to a non-negative number and if -indev and
-outdev are both set to different drives, then @strong{blind growing} is
performed. It produces an add-on session which is ready for being written
to the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
which gives much room for wrong parameter combinations and should thus only be
employed if a strict distinction between ISO formatter @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, _definiton
Input drive, i.e. source of an existing or empty ISO image, can be any random
access readable libburn drive: optical media with readable data,
blank optical media, regular files, block devices.
@c man .PP
@sp 1
Output drive, i.e. target for writing, can be any libburn drive.
Some drive types do not support the method of growing but only the methods
of modifying and blind growing. They all are suitable for newly created images.
All drive file objects have to offer rw-permission to the user of
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
2011-07-27 21:14:49 +00:00
It might be necessary to do this as
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
One may use option
to surely prevent this risk and to allow only MMC drives.
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
@c man .br
By option -drive_class one may ban certain paths or allow access without
prefix "stdio:" to other paths.
@c man .SS
@node Extras, Processing, Drives, top
@chapter Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
@c man .B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
@c man .br
@cindex Rock Ridge, _definiton
@strong{Rock Ridge}
is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
This is what @command{xorriso} uses for a decent representation of the disk
files within the ISO image. Rock Ridge information is produced with any
@command{xorriso} image.
@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, _definiton
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 option -boot_image.
2010-04-18 15:46:12 +00:00
@cindex MBR, _definiton
It is possible to make ISO images bootable from USB stick or other
2010-04-18 15:46:12 +00:00
hard-disk-like media by -boot_image argument system_area= . This installs
a Master Boot Record which may get adjusted according to the needs
An @strong{MBR} contains boot code and a partition table. It does not hamper
CDROM booting. The new MBR of a follow-up session can get in effect
only on overwriteable media.
2010-06-25 09:59:20 +00:00
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.
There is support for boot facilities other than PC BIOS:
EFI, MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
@c man .PP
@sp 1
@cindex ACL, _definiton
are an advanced way of controlling access permissions to file objects. Neither
ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has
introduced a standard conformant extension named AAIP for that purpose.
It uses this extension if enabled by option
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.
2011-08-23 10:42:01 +00:00
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, _definiton
2011-08-23 10:42:01 +00:00
@cindex EA, _definiton
@cindex extattr, _definiton
@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 option
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.
2011-08-23 10:42:01 +00:00
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.
@cindex List delimiter, _definiton
Commands consist of a command word,
followed by zero or more parameter words. If the list of parameter words
is of variable length (indicated by "[...]" or "[***]") then it has to be
terminated by either the @strong{list delimiter}, or the end of argument list,
or an end of an input line.
@c man .PP
@sp 1
At program start the list delimiter is the word "@minus{}@minus{}".
This may be changed by option -list_delimiter in order to allow
"@minus{}@minus{}" as argument in a list of variable length.
It is advised to reset the delimiter to "@minus{}@minus{}" immediately
For brevity the list delimiter is referred as "@minus{}@minus{}"
throughout this text.
The list delimiter is silently tolerated if it appears after the parameters of
a command with a fixed list length. It is handled as normal text if it
appears among the arguments of such a command.
@c man .PP
@sp 1
@cindex Pattern expansion, _definition
@strong{Pattern expansion}
converts a list of pattern words into a list of existing file addresses.
Unmatched pattern words appear themselves in that result list, though.
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]'
and respects '/' as separator which may only be matched literally.
It is a property of some particular commands and not a general
feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern.
Commands which may use pattern expansion all have variable argument
lists which are marked in this man page by "[***]" rather than "[...]".
Some other commands perform pattern matching unconditionally.
@c man .PP
@sp 1
Command and parameter words are either read from program arguments, where one
argument is one word, or from quoted input lines where words are recognized
similar to the quotation rules of a shell parser.
@command{xorriso} is not a shell, although it might appear so on first glimpse.
Be aware that the interaction of quotation marks and pattern symbols like "*"
differs from the usual shell parsers. In @command{xorriso}, a quotation mark
does not make a pattern symbol literal.
@c man .PP
@sp 1
@cindex Quoted input, _definiton
@strong{Quoted input}
converts whitespace separated text pieces into words.
The double quotation mark " and the single quotation mark ' can be used to
enclose whitespace and make it part of words (e.g. of file names). Each mark
type can enclose the marks of the other type. A trailing backslash \ outside
quotations or an open quotation cause the next input line to be appended.
@cindex Backslash Interpretation, _definition
Quoted input accepts any ASCII character except NUL (0) as content of quotes.
Nevertheless it can be cumbersome for the user to produce those characters
at all. Therefore quoted input and program arguments allow optional
@strong{Backslash Interpretation}
which can represent all ASCII characters except NUL (0) by backslash codes
as in $'...' of bash.
It is not enabled by default. See option -backslash_codes.
@c man .PP
@sp 1
When the program 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" was executed up to then.
@c man .PP
@sp 1
The program ends either by command -end, or by the end of program arguments
if not dialog was enabled up to that moment, or by a problem
event which triggers the threshold of command -abort_on.
@c man .SS
@node Dialog, Options, Processing, top
@chapter Dialog, Readline, Result pager
@c man .B Dialog, Readline, Result pager:
@c man .br
Dialog mode prompts for a quoted input line, parses it into words, and performs
them as commands with their parameters. It provides assisting services
to make dialog more comfortable.
@c man .PP
@sp 1
Readline is an enhancement for the input line. You may know it already from
the bash shell. Whether it is available in @command{xorriso} depends on the
of package readline-dev at the time when @command{xorriso} was built from
its sourcecode.
It allows to move the cursor over the text in the line by help of the
Leftward and the Rightward arrow key.
Text may be inserted at the cursor position. The Delete key removes the
character under the cursor. Upward and Downward arrow keys navigate through
the history of previous input lines.
@c man-ignore-lines 1
See info readline
@c man See man readline
for more info about libreadline.
@c man .PP
@sp 1
Option -page activates a built-in result text pager which may be convenient in
dialog. After an action has put out the given number of terminal lines,
the pager prompts the user for a line of input.
An empty line lets @command{xorriso} resume work until the next page is put out.
The single character "@@" disables paging for the current action.
"@@@@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress
further result output.
Any other line will be interpreted as new dialog line. The current action
is urged to abort. Afterwards, the input line is executed.
@c man .PP
@sp 1
Some actions apply paging to their info output, too.
The urge to abort may or may not be obeyed by the current action. All actions
try to abort as soon as possible.
@node Options, Examples, Dialog, top
@chapter Options
@c man .br
@c man .SH OPTIONS
@c man .br
All command words are shown with a leading dash although this dash is not
mandatory for the option to be recognized. Nevertheless within option -as
the dashes of the emulated options are mandatory.
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
* AqDrive:: Aquiring source and target drive
* Loading:: Influencing the behavior of image loading
* Insert:: Inserting files into ISO image
* SetInsert:: Settings for file insertion
* Manip:: File manipulations
* CmdFind:: Tree traversal command -find
* Filter:: Filters for data file content
* Writing:: Writing the result, drive control
* SetWrite:: Settings for result writing
* Bootable:: Bootable ISO images
2010-09-29 15:28:57 +00:00
* Jigdo:: Jigdo Template Extraction
* Charset:: Character sets
* Exception:: Exception processing
* DialogCtl:: Dialog mode control
* Inquiry:: Drive and media related inquiry actions
* Navigate:: Navigation in ISO image and disk filesystem
* Verify:: Evaluation of readability and recovery
* Restore:: osirrox ISO-to-disk restore options
* Emulation:: Command compatibility emulations (cdrtools)
* Scripting:: Scripting, dialog and program control features
* Frontend:: Support for frontend programs via stdin and stdout
@end menu
@c man .TP
@node AqDrive, Loading, Options, Options
@section Aquiring source and target drive
@c man .B Aquiring source and target drive:
@c man .PP
The effect of aquiring a drive may depend on several options in the
next paragraph "Influencing the behavior of image loading".
If desired, their enabling commands have to be performed before the
commands which aquire the drive.
@table @asis
@sp 1
@c man .TP
@item -dev address
@kindex -dev aquires one drive for input and output
@cindex Drive, for input and output, -dev
Set input and output drive to the same address and load an 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 aquiring a new one.
@c man .TP
@item -indev address
@kindex -indev aquires a drive for input
@cindex Drive, for input, -indev
Set input drive and load an 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 aquires a drive for output
@cindex Drive, for output, -outdev
Set output drive and if it differs from the input drive then switch from
growing to modifying or to blind growing. Unlike -dev and -indev this action
does not load a new ISO image. So it can be performed even if there are pending
-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 or it can be discarded silently if -dev or -indev
are performed afterwards.
Special address string "-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current output drive
without aquiring a new one. No writing is possible without an output drive.
@c man .TP
@item -grow_blindly "off"|predicted_nwa
@kindex -grow_blindly overides next writeable address
@cindex Next writeable address, -grow_blindly
If predicted_nwa is a non-negative number then perform blind growing rather
than modifying if -indev and -outdev are set to different drives.
"off" or "-1" switch to modifying, which is the default.
predicted_nwa is the block address where the add-on session of blind
growing will finally end up. It is the responsibility of the user to ensure
this final position and the presence of the older sessions. Else the
overall ISO image will not be mountable or will produce read errors when
accessing file content. @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, Options
@section Influencing the behavior of image loading
@c man .PP
The following options should normally be performed before loading an image
by aquiring an input drive. In rare cases it is desirable to activate
them only after image loading.
@table @asis
@sp 1
@c man .TP
@item -load entity id
@kindex -load addresses a particular session as input
@cindex Session, select as input, -load
Load a particular (possibly outdated) ISO session from -dev or -indev.
Usually all available sessions are shown with option -toc.
entity depicts the kind of addressing. id depicts the particular
address. The following entities are defined:
"auto" with any id addresses the last session in -toc. This is the default.
"session" with id being a number as of a line "ISO session", column "Idx".
"track" with id being a number as of a line "ISO track", column "Idx".
"lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector".
"volid" with a search pattern for a text as of a line "ISO ...",
column "Volume Id".
Adressing a non-existing entity or one which does not represent an ISO
image will either abandon -indev or at least lead to a blank image.
If an input drive is set at the moment when -load is executed, then the
addressed ISO image is loaded immediately. Else, the setting will be pending
until the next -dev or -indev. After the image has been loaded once, the
setting is valid for -rollback until next -dev or -indev, where it
will be reset to "auto".
@c man .TP
2010-11-30 09:43:32 +00:00
@item -displacement [-]lba
@kindex -displacement compensate altered image start address
2010-11-30 09:43:32 +00:00
@cindex Session, altered start address, -displacement
Compensate a displacement of the image versus the start address
2010-11-30 09:43:32 +00:00
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-aquired after writing.
2010-11-30 09:43:32 +00:00
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 option does not hamper the creation of an empty image from blank
input media and does not discard an already loaded image.
@c man .TP
@item -in_charset character_set_name
@kindex -in_charset sets input character set
@cindex Character Set, for input, -in_charset
Set the character set from which to convert file names when loading an
image. 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
namoe 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
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