|
|
|
.\" Hey, EMACS: -*- nroff -*-
|
|
|
|
.\"
|
|
|
|
.\" IMPORTANT NOTE:
|
|
|
|
.\"
|
|
|
|
.\" The original of this file is kept in xorriso/xorriso.texi
|
|
|
|
.\" This here was generated by program xorriso/make_xorriso_1
|
|
|
|
.\"
|
|
|
|
.\"
|
|
|
|
.\" First parameter, NAME, should be all caps
|
|
|
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
|
|
|
|
.\" other parameters are allowed: see man(7), man(1)
|
|
|
|
.TH XORRISO 1 "Mar 09, 2011"
|
|
|
|
.\" Please adjust this date whenever revising the manpage.
|
|
|
|
.\"
|
|
|
|
.\" Some roff macros, for reference:
|
|
|
|
.\" .nh disable hyphenation
|
|
|
|
.\" .hy enable hyphenation
|
|
|
|
.\" .ad l left justify
|
|
|
|
.\" .ad b justify to both left and right margins
|
|
|
|
.\" .nf disable filling
|
|
|
|
.\" .fi enable filling
|
|
|
|
.\" .br insert line break
|
|
|
|
.\" .sp <n> insert n+1 empty lines
|
|
|
|
.\" for manpage-specific macros, see man(7)
|
|
|
|
.nh
|
|
|
|
.SH NAME
|
|
|
|
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
|
|
|
|
with Rock Ridge extensions.
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B xorriso
|
|
|
|
.RI [ settings | actions ]
|
|
|
|
.br
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.PP
|
|
|
|
\fBxorriso\fR
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Vice versa xorriso is able to copy file objects out of ISO 9660 filesystems.
|
|
|
|
.PP
|
|
|
|
A special property of xorriso is that it needs neither an external ISO 9660
|
|
|
|
formatter program nor an external burn program for CD, DVD or BD but rather
|
|
|
|
incorporates the libraries of libburnia-project.org .
|
|
|
|
.SS
|
|
|
|
.B Overview of features:
|
|
|
|
.br
|
|
|
|
Operates on an existing ISO image or creates a new one.
|
|
|
|
.br
|
|
|
|
Copies files from disk filesystem into the ISO image.
|
|
|
|
.br
|
|
|
|
Copies files from ISO image to disk filesystem (see osirrox).
|
|
|
|
.br
|
|
|
|
Renames or deletes file objects in the ISO image.
|
|
|
|
.br
|
|
|
|
Changes file properties in the ISO image.
|
|
|
|
.br
|
|
|
|
Updates ISO subtrees incrementally to match given disk subtrees.
|
|
|
|
.br
|
|
|
|
Writes result either as completely new image or as add-on session
|
|
|
|
to optical media or filesystem objects.
|
|
|
|
.br
|
|
|
|
Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
|
|
|
|
.br
|
|
|
|
Can perform multi-session tasks as emulation of mkisofs and cdrecord.
|
|
|
|
.br
|
|
|
|
Can record and restore hard links and ACL.
|
|
|
|
.br
|
|
|
|
Content may get zisofs compressed or filtered by external processes.
|
|
|
|
.br
|
|
|
|
Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
|
|
|
|
.br
|
|
|
|
Can check media for damages and copy readable blocks to disk.
|
|
|
|
.br
|
|
|
|
Can attach MD5 checksums to each data file and the whole session.
|
|
|
|
.br
|
|
|
|
Scans for optical drives, blanks re-useable optical media.
|
|
|
|
.br
|
|
|
|
Reads its instructions from command line arguments, dialog, and files.
|
|
|
|
.br
|
|
|
|
Provides navigation commands for interactive ISO image manipulation.
|
|
|
|
.br
|
|
|
|
Adjustable thresholds for abort, exit value, and problem reporting.
|
|
|
|
.SS
|
|
|
|
.B General information paragraphs:
|
|
|
|
.br
|
|
|
|
Session model
|
|
|
|
.br
|
|
|
|
Media types and states
|
|
|
|
.br
|
|
|
|
Creating, Growing, Modifying, Blind Growing
|
|
|
|
.br
|
|
|
|
Libburn drives
|
|
|
|
.br
|
|
|
|
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
|
|
|
|
.br
|
|
|
|
Command processing
|
|
|
|
.br
|
|
|
|
Dialog, Readline, Result pager
|
|
|
|
.sp 1
|
|
|
|
Maybe you first want to have a look at section EXAMPLES near the end of
|
|
|
|
this text before reading the next few hundred lines of background information.
|
|
|
|
.SS
|
|
|
|
\fBSession model:\fR
|
|
|
|
.br
|
|
|
|
Unlike other filesystems, ISO 9660 is not intended for read-write operation but
|
|
|
|
rather for being generated in a single sweep and being written to media as a
|
|
|
|
\fBsession\fR.
|
|
|
|
.br
|
|
|
|
The data content of the session is called filesystem \fBimage\fR.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
This session usage model has been extended on CD media by the concept of
|
|
|
|
\fBmulti-session\fR ,
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Adding a session to an existing ISO image is in this text referred as
|
|
|
|
\fBgrowing\fR.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
xorriso provides growing as well as an own method named
|
|
|
|
\fBmodifying\fR which produces a completely new ISO image from the old
|
|
|
|
one and the modifications.
|
|
|
|
See paragraph Creating, Growing, Modifying, Blind Growing below.
|
|
|
|
.PP
|
|
|
|
xorriso adopts the concept of multi-session by loading an eventual image
|
|
|
|
directory tree, allowing to manipulate it by several actions, and to write
|
|
|
|
the new image to the target media.
|
|
|
|
.br
|
|
|
|
The first session of a xorriso run begins by the definition of the input
|
|
|
|
drive with the eventual ISO image or by the definition of an output drive.
|
|
|
|
The session ends by command -commit which triggers writing. A -commit is
|
|
|
|
done automatically when the program ends regularly.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.SS
|
|
|
|
.B Media types and states:
|
|
|
|
There are two families of media in the MMC standard:
|
|
|
|
.br
|
|
|
|
\fBMulti-session media\fR 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 \fB\-toc\fR.
|
|
|
|
.br
|
|
|
|
Similar to multi-session media are DVD-R DL and minimally blanked DVD-RW.
|
|
|
|
They allow only a single session of which the size must be known in advance.
|
|
|
|
xorriso will write onto them only if option -close is set to "on".
|
|
|
|
.br
|
|
|
|
\fBOverwriteable media\fR are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
|
|
|
|
They allow random write access but do not provide information about their
|
|
|
|
session history. If they contain one or more ISO 9660 sessions and if the
|
|
|
|
first session was written by xorriso, then a table of content can
|
|
|
|
be emulated. Else only a single overall session will be visible.
|
|
|
|
.br
|
|
|
|
DVD-RW media can be formatted by -format "full".
|
|
|
|
They can be made unformatted by -blank "deformat".
|
|
|
|
.br
|
|
|
|
Regular files and block devices are handled as overwriteable media.
|
|
|
|
Pipes and other writeable file types are handled as blank multi-session media.
|
|
|
|
.PP
|
|
|
|
These media can assume several states in which they offer different
|
|
|
|
capabilities.
|
|
|
|
.br
|
|
|
|
\fBBlank\fR media can be written from scratch. They contain no ISO image
|
|
|
|
suitable for xorriso.
|
|
|
|
.br
|
|
|
|
Blank is the state of newly purchased optical media.
|
|
|
|
With used CD-RW and DVD-RW it can be achieved by action -blank "as_needed".
|
|
|
|
Overwriteable media are considered blank if they are new or if they have
|
|
|
|
been marked as blank by xorriso.
|
|
|
|
Action -blank "as_needed" can be used to do this marking on overwriteable
|
|
|
|
media, or to apply eventual mandatory formatting to new media.
|
|
|
|
.br
|
|
|
|
\fBAppendable\fR media accept further sessions. Either they are MMC
|
|
|
|
multi-session media in appendable state, or they are overwriteable media
|
|
|
|
which contain an ISO image suitable for xorriso.
|
|
|
|
.br
|
|
|
|
Appendable is the state after writing a session with option -close off.
|
|
|
|
.br
|
|
|
|
\fBClosed\fR media cannot be written. They may contain an ISO image suitable
|
|
|
|
for xorriso.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Overwriteable media assume this state in such read-only drives or if they
|
|
|
|
contain unrecognizable data in the first 32 data blocks.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.SS
|
|
|
|
.B Creating, Growing, Modifying, Blind Growing:
|
|
|
|
.br
|
|
|
|
A new empty ISO image gets \fBcreated\fR
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
The method of \fBgrowing\fR adds new data to the existing media. These
|
|
|
|
data comprise of eventual new file content and they override the existing
|
|
|
|
ISO 9660 + Rock Ridge directory tree. It is possible to hide files from
|
|
|
|
previous sessions but they still exist on media and with many types of
|
|
|
|
optical media it is quite easy to recover them by mounting older sessions.
|
|
|
|
.br
|
|
|
|
Growing is achieved by option -dev.
|
|
|
|
.PP
|
|
|
|
The write method of \fBmodifying\fR 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.
|
|
|
|
.br
|
|
|
|
So for this method one needs either two optical drives or has to work with
|
|
|
|
filesystem objects as source and/or target media.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
If option -grow_blindly is set to a non-negative number and if -indev and
|
|
|
|
-outdev are both set to different drives, then \fBblind growing\fR 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
|
|
|
|
.br
|
|
|
|
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
|
|
|
|
.br
|
|
|
|
which gives much room for wrong parameter combinations and should thus only be
|
|
|
|
employed if a strict distinction between ISO formatter xorriso and the burn
|
|
|
|
program is desired. -C $msc1,$msc2 is equivalent to:
|
|
|
|
.br
|
|
|
|
-load sbsector $msc1 -grow_blindly $msc2
|
|
|
|
.SS
|
|
|
|
.B Libburn drives:
|
|
|
|
.br
|
|
|
|
Input drive, i.e. source of an existing or empty ISO image, can be any random
|
|
|
|
access readable libburn drive: optical media with readable data,
|
|
|
|
blank optical media, regular files, block devices.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
All drive file objects have to offer rw-permission to the user of xorriso.
|
|
|
|
Even those which will not be useable for reading an ISO image.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
-dev /dev/sr0
|
|
|
|
.br
|
|
|
|
-dev /dev/hdc
|
|
|
|
.br
|
|
|
|
-dev /dev/sg2
|
|
|
|
.br
|
|
|
|
On FreeBSD the device files have names like
|
|
|
|
.br
|
|
|
|
-dev /dev/cd0
|
|
|
|
.br
|
|
|
|
On OpenSolaris:
|
|
|
|
.br
|
|
|
|
-dev /dev/rdsk/c4t0d0s2
|
|
|
|
.br
|
|
|
|
Get a list of accessible drives by command
|
|
|
|
.br
|
|
|
|
-devices
|
|
|
|
.br
|
|
|
|
It might be necessary to do this as
|
|
|
|
\fBsuperuser\fR
|
|
|
|
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".
|
|
|
|
.PP
|
|
|
|
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and
|
|
|
|
their path in the filesystem. E.g.:
|
|
|
|
.br
|
|
|
|
-dev stdio:/dev/sdc
|
|
|
|
.br
|
|
|
|
The default setting of -drive_class allows to address files outside the
|
|
|
|
/dev tree without that prefix. E.g.:
|
|
|
|
.br
|
|
|
|
-dev /tmp/pseudo_drive
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
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).
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Standard output is currently suitable for creating one session
|
|
|
|
per program run without dialog. Use in other situations is discouraged
|
|
|
|
and several restrictions apply:
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
If stdout is used as drive, then -use_readline is permanently disabled.
|
|
|
|
Use of backdoors can cause severe memory and/or tty corruption.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
One may use option
|
|
|
|
\fB\-ban_stdio_write\fR
|
|
|
|
to surely prevent this risk and to allow only MMC drives.
|
|
|
|
.br
|
|
|
|
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
|
|
|
|
.br
|
|
|
|
By option -drive_class one may ban certain paths or allow access without
|
|
|
|
prefix "stdio:" to other paths.
|
|
|
|
.SS
|
|
|
|
.B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
|
|
|
|
.br
|
|
|
|
\fBRock Ridge\fR
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
This is what xorriso uses for a decent representation of the disk files
|
|
|
|
within the ISO image. Rock Ridge information is produced with any xorriso
|
|
|
|
image.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
An \fBEl Torito\fR
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.
|
|
|
|
xorriso is able to create or maintain an El Torito object which makes such
|
|
|
|
an image bootable. For details see option -boot_image.
|
|
|
|
.br
|
|
|
|
It is possible to make ISO images bootable from USB stick or other
|
|
|
|
hard-disk-like media by -boot_image argument system_area= . This installs
|
|
|
|
a Master Boot Record which may get adjusted according to the needs
|
|
|
|
of GRUB resp. ISOLINUX.
|
|
|
|
An \fBMBR\fR 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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
There is support for boot facilities other than PC BIOS:
|
|
|
|
EFI, MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
|
|
|
|
.br
|
|
|
|
.PP
|
|
|
|
\fBACL\fR
|
|
|
|
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
|
|
|
|
\fB\-acl\fR.
|
|
|
|
.br
|
|
|
|
AAIP enhanced images are supposed to be mountable normally, but one cannot
|
|
|
|
expect that the mounted filesystem will show and respect the eventual ACLs.
|
|
|
|
For now, only xorriso is able to retrieve those ACLs. It can bring them into
|
|
|
|
effect when files get restored to an ACL enabled file system or it can
|
|
|
|
print them in a format suitable for tool setfacl.
|
|
|
|
.br
|
|
|
|
Files with ACL show as group permissions the setting of entry "mask::" if
|
|
|
|
that entry exists. Nevertheless the non-listed group members get handled
|
|
|
|
according to entry "group::". xorriso brings "group::" into effect before
|
|
|
|
eventually removing the ACL from a file.
|
|
|
|
.PP
|
|
|
|
\fBxattr\fR (aka EA)
|
|
|
|
are pairs of name and value which can be attached to file objects. AAIP is
|
|
|
|
able to represent them and xorriso allows to record and restore pairs which
|
|
|
|
have names out of the user namespace. I.e. those which begin with "user.",
|
|
|
|
like "user.x" or "user.whatever". Name has to be a 0 terminated string.
|
|
|
|
Value may be any array of bytes which does not exceed the size of 4095 bytes.
|
|
|
|
xattr processing happens only if it is enabled by option
|
|
|
|
\fB\-xattr\fR.
|
|
|
|
.br
|
|
|
|
As with ACL, currently only xorriso is able to retrieve xattr from AAIP
|
|
|
|
enhanced images, to restore them to xattr capable file systems, or to print
|
|
|
|
them.
|
|
|
|
.SS
|
|
|
|
.B Command processing:
|
|
|
|
.br
|
|
|
|
Commands are either actions which happen immediately or settings which
|
|
|
|
influence following actions. So their sequence does matter.
|
|
|
|
.br
|
|
|
|
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 \fBlist delimiter\fR, or the end of argument list,
|
|
|
|
or an end of an input line.
|
|
|
|
.PP
|
|
|
|
At program start the list delimiter is the word "--".
|
|
|
|
This may be changed by option -list_delimiter in order to allow
|
|
|
|
"--" as argument in a list of variable length.
|
|
|
|
It is advised to reset the delimiter to "--" immediately
|
|
|
|
afterwards.
|
|
|
|
.br
|
|
|
|
For brevity the list delimiter is referred as "--"
|
|
|
|
throughout this text.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.PP
|
|
|
|
\fBPattern expansion\fR
|
|
|
|
converts a list of pattern words into a list of existing file addresses.
|
|
|
|
Eventual unmatched pattern words appear themselves in that result list, though.
|
|
|
|
.br
|
|
|
|
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]'
|
|
|
|
and respects '/' as separator which may only be matched literally.
|
|
|
|
.br
|
|
|
|
It is a property of some particular commands and not a general
|
|
|
|
feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern.
|
|
|
|
Commands which eventually use pattern expansion all have variable argument
|
|
|
|
lists which are marked in this man page by "[***]" rather than "[...]".
|
|
|
|
.br
|
|
|
|
Some other commands perform pattern matching unconditionally.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
xorriso is not a shell, although it might appear so on first glimpse.
|
|
|
|
Be aware that the interaction of quotation marks and pattern symbols like "*"
|
|
|
|
differs from the usual shell parsers. In xorriso, a quotation mark does not
|
|
|
|
make a pattern symbol literal.
|
|
|
|
.PP
|
|
|
|
\fBQuoted input\fR
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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
|
|
|
|
\fBBackslash Interpretation\fR
|
|
|
|
which can represent all ASCII characters except NUL (0) by backslash codes
|
|
|
|
as in $'...' of bash.
|
|
|
|
.br
|
|
|
|
It is not enabled by default. See option -backslash_codes.
|
|
|
|
.PP
|
|
|
|
When the program begins then it first looks for argument -no_rc. If this is
|
|
|
|
not present then it looks for its startup files and
|
|
|
|
eventually reads their content as command input lines. Then it interprets
|
|
|
|
the program arguments as commands and parameters and finally it enters
|
|
|
|
dialog mode if command -dialog "on" was executed up to then.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.SS
|
|
|
|
.B Dialog, Readline, Result pager:
|
|
|
|
.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.
|
|
|
|
.PP
|
|
|
|
Readline is an enhancement for the input line. You may know it already from
|
|
|
|
the bash shell. Whether it is available in xorriso depends on the availability
|
|
|
|
of package readline-dev at the time when xorriso was built from its sourcecode.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
See man readline
|
|
|
|
for more info about libreadline.
|
|
|
|
.PP
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
An empty line lets xorriso resume work until the next page is put out.
|
|
|
|
.br
|
|
|
|
The single character "@" disables paging for the current action.
|
|
|
|
.br
|
|
|
|
"@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress
|
|
|
|
further result output.
|
|
|
|
.br
|
|
|
|
Any other line will be interpreted as new dialog line. The current action
|
|
|
|
is urged to abort. Afterwards, the input line is executed.
|
|
|
|
.PP
|
|
|
|
Some actions apply paging to their info output, too.
|
|
|
|
.br
|
|
|
|
The urge to abort may or may not be obeyed by the current action. All actions
|
|
|
|
try to abort as soon as possible.
|
|
|
|
.br
|
|
|
|
.SH OPTIONS
|
|
|
|
.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.
|
|
|
|
.br
|
|
|
|
Normally any number of leading dashes is ignored with command words and
|
|
|
|
inner dashes are interpreted as underscores.
|
|
|
|
.TP
|
|
|
|
.B Aquiring source and target drive:
|
|
|
|
.PP
|
|
|
|
Before aquiring a drive one will eventually enable options which influence
|
|
|
|
the behavior of image loading. See next option group.
|
|
|
|
.TP
|
|
|
|
\fB\-dev\fR address
|
|
|
|
Set input and output drive to the same address and load an eventual ISO image.
|
|
|
|
If there is no ISO image then create a blank one.
|
|
|
|
Set the image expansion method to growing.
|
|
|
|
.br
|
|
|
|
This is only allowed as long as no changes are pending in the currently
|
|
|
|
loaded ISO image. Eventually one has to perform -commit or -rollback first.
|
|
|
|
.br
|
|
|
|
Special address string "-" means standard output, to which several restrictions
|
|
|
|
apply. See above paragraph "Libburn drives".
|
|
|
|
.br
|
|
|
|
An empty address string "" gives up the current device
|
|
|
|
without aquiring a new one.
|
|
|
|
.TP
|
|
|
|
\fB\-indev\fR address
|
|
|
|
Set input drive and load an eventual ISO image. If the new input drive differs
|
|
|
|
from -outdev then switch from growing to modifying or to blind growing.
|
|
|
|
It depends on the setting of -grow_blindly which of both gets activated.
|
|
|
|
The same rules and restrictions apply as with -dev.
|
|
|
|
.TP
|
|
|
|
\fB\-outdev\fR address
|
|
|
|
Set output drive and if it differs from the input drive then switch from
|
|
|
|
growing to modifying or to blind growing. Unlike -dev and -indev this action
|
|
|
|
does not load a new ISO image. So it can be performed even if there are pending
|
|
|
|
changes.
|
|
|
|
.br
|
|
|
|
-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.
|
|
|
|
.br
|
|
|
|
Special address string "-" means standard output, to which several restrictions
|
|
|
|
apply. See above paragraph "Libburn drives".
|
|
|
|
.br
|
|
|
|
An empty address string "" gives up the current output drive
|
|
|
|
without aquiring a new one. No writing is possible without an output drive.
|
|
|
|
.TP
|
|
|
|
\fB\-grow_blindly\fR "off"|predicted_nwa
|
|
|
|
If predicted_nwa is a non-negative number then perform blind growing rather
|
|
|
|
than modifying if -indev and -outdev are set to different drives.
|
|
|
|
"off" or "-1" switch to modifying, which is the default.
|
|
|
|
.br
|
|
|
|
predicted_nwa is the block address where the add-on session of blind
|
|
|
|
growing will finally end up. It is the responsibility of the user to ensure
|
|
|
|
this final position and the presence of the older sessions. Else the
|
|
|
|
overall ISO image will not be mountable or will produce read errors when
|
|
|
|
accessing file content. xorriso will write the session to the address
|
|
|
|
as obtained from examining -outdev and not necessarily to predicted_nwa.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.TP
|
|
|
|
.B Influencing the behavior of image loading:
|
|
|
|
.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.
|
|
|
|
.TP
|
|
|
|
\fB\-load\fR entity id
|
|
|
|
Load a particular (possibly outdated) ISO session from -dev or -indev.
|
|
|
|
Usually all available sessions are shown with option -toc.
|
|
|
|
.br
|
|
|
|
entity depicts the kind of addressing. id depicts the particular
|
|
|
|
address. The following entities are defined:
|
|
|
|
.br
|
|
|
|
"auto" with any id addresses the last session in -toc. This is the default.
|
|
|
|
.br
|
|
|
|
"session" with id being a number as of a line "ISO session", column "Idx".
|
|
|
|
.br
|
|
|
|
"track" with id being a number as of a line "ISO track", column "Idx".
|
|
|
|
.br
|
|
|
|
"lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector".
|
|
|
|
.br
|
|
|
|
"volid" with a search pattern for a text as of a line "ISO ...",
|
|
|
|
column "Volume Id".
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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".
|
|
|
|
.TP
|
|
|
|
\fB\-displacement\fR [-]lba
|
|
|
|
Compensate an eventual 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. Eventually the displacement is reset to 0 before the drive
|
|
|
|
gets re-aquired after writing.
|
|
|
|
.br
|
|
|
|
Examples:
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.TP
|
|
|
|
\fB\-drive_class\fR "harmless"|"banned"|"caution"|"clear_list" disk_pattern
|
|
|
|
Add a drive path pattern to one of the safety lists or make those lists empty.
|
|
|
|
There are three lists defined which get tested in the following sequence:
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Else if the path matches the "banned" list then the drive will not be
|
|
|
|
accepted by xorriso but rather lead to a FAILURE event. This list is empty by
|
|
|
|
default.
|
|
|
|
.br
|
|
|
|
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".
|
|
|
|
.br
|
|
|
|
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".
|
|
|
|
.br
|
|
|
|
A path matches a list if one of its parent paths or itself matches a list
|
|
|
|
entry. An eventual address prefix "stdio:" or "mmc:" will be ignored when
|
|
|
|
testing for matches.
|
|
|
|
.br
|
|
|
|
By pseudo-class "clear_list" and pseudo-patterns "banned", "caution",
|
|
|
|
"harmless", or "all", the lists may be made empty.
|
|
|
|
.br
|
|
|
|
E.g.: -drive_class clear_list banned
|
|
|
|
.br
|
|
|
|
One will normally define the -drive_class lists in one of the xorriso
|
|
|
|
Startup Files.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.TP
|
|
|
|
\fB\-assert_volid\fR pattern severity
|
|
|
|
Refuse to load ISO images with volume ids which do not match the given
|
|
|
|
search pattern. When refusing an image, give up the input drive and issue
|
|
|
|
an event of the given severity (like FAILURE, see -abort_on). An empty search
|
|
|
|
pattern accepts any image.
|
|
|
|
.br
|
|
|
|
This option does not hamper the creation of an empty image from blank
|
|
|
|
input media and does not discard an already loaded image.
|
|
|
|
.TP
|
|
|
|
\fB\-in_charset\fR character_set_name
|
|
|
|
Set the character set from which to convert file names when loading an
|
|
|
|
image. This has eventually to be done before specifying -dev , -indev or
|
|
|
|
-rollback. See paragraph "Character sets" for more explanations.
|
|
|
|
When loading the written image after -commit the setting of -out_charset
|
|
|
|
will be copied to -in_charset.
|
|
|
|
.TP
|
|
|
|
\fB\-auto_charset\fR "on"|"off"
|
|
|
|
Enable or disable recording and interpretation of the output character
|
|
|
|
set name in an xattr attribute of the image root directory. If enabled then
|
|
|
|
an eventual recorded character set name gets used as input character set
|
|
|
|
when reading an image.
|
|
|
|
.br
|
|
|
|
Note that the default output charset is the local character set of the
|
|
|
|
terminal where xorriso runs. Before attributing this local character set
|
|
|
|
to the produced ISO image, check whether the terminal properly displays
|
|
|
|
all intended filenames, especially exotic national characters.
|
|
|
|
.TP
|
|
|
|
\fB\-hardlinks\fR mode[:mode...]
|
|
|
|
Enable or disable loading and recording of hardlink relations.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Mode "on" preserves eventual inode numbers from the loaded image.
|
|
|
|
When committing a session it searches for families of iso_rr files
|
|
|
|
which stem from the same disk file, have identical content filtering and have
|
|
|
|
identical properties. The family members all get the same inode number.
|
|
|
|
Whether these numbers are respected at mount time depends on the operating
|
|
|
|
system.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Mode "without_update" avoids hardlink processing during update commands.
|
|
|
|
Use this if your filesystem situation does not allow -disk_dev_ino "on".
|
|
|
|
.br
|
|
|
|
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".
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
.TP
|
|
|
|
\fB\-acl\fR "on"|"off"
|
|
|
|
Enable or disable processing of ACLs.
|
|
|
|
If enabled, then xorriso will obtain ACLs from disk file objects,
|
|
|
|
store ACLs in the ISO image using the libisofs specific AAIP format,
|
|
|
|
load AAIP data from ISO images, test ACL during file comparison,
|
|
|
|
and restore ACLs to disk files when extracting them from ISO images.
|
|
|
|
See also options -getfacl, -setfacl.
|
|
|
|
.TP
|
|
|
|
\fB\-xattr\fR "on"|"off"
|
|
|
|
Enable or disable processing of xattr attributes in user namespace.
|
|
|
|
If enabled, then xorriso will handle xattr similar to ACL.
|
|
|
|
See also options -getfattr, -setfattr and above paragraph about xattr.
|
|
|
|
.TP
|
|
|
|
\fB\-md5\fR "on"|"all"|"off"|"load_check_off"
|
|
|
|
Enable or disable processing of MD5 checksums for the overall session and for
|
|
|
|
each single data file. If enabled then images get loaded only if eventual
|
|
|
|
checksums tags of superblock and directory tree match properly. The MD5
|
|
|
|
checksums of data files and whole session get loaded from the image if there
|
|
|
|
are any.
|
|
|
|
.br
|
|
|
|
With options -compare and -update the eventually recorded MD5 of a file
|
|
|
|
will be used to avoid content reading from the image. Only the disk file
|
|
|
|
content will be read and compared with that MD5. This can save much time
|
|
|
|
if -disk_dev_ino "on" is not suitable.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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 xorriso -as mkisofs option -M
|
|
|
|
is performed.
|
|
|
|
.br
|
|
|
|
The test can be re-enabled by mode "load_check_on".
|
|
|
|
.br
|
|
|
|
Checksums can be exploited via options -check_md5, -check_md5_r, via find
|
|
|
|
actions get_md5, check_md5, and via -check_media.
|
|
|
|
.TP
|
|
|
|
\fB\-for_backup\fR
|
|
|
|
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.
|
|
|
|
.TP
|
|
|
|
\fB\-disk_dev_ino\fR "on"|"ino_only"|"off"
|
|
|
|
Enable or disable processing of recorded file identification numbers
|
|
|
|
(dev_t and ino_t). They are eventually stored as xattr and allow
|
|
|
|
to substantially accelerate file comparison. The root node gets a global start
|
|
|
|
timestamp. If during comparison a file with younger timestamps is found in the
|
|
|
|
ISO image, then it is suspected to have inconsistent content.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
The speed advantage appears only if the loaded session was produced with
|
|
|
|
-disk_dev_ino "on" too.
|
|
|
|
.br
|
|
|
|
Note that -disk_dev_ino "off" is totally in effect only if -hardlinks is "off",
|
|
|
|
too.
|
|
|
|
.TP
|
|
|
|
\fB\-rom_toc_scan\fR "on"|"force"|"off"[:"emul_on"|"emul_off"]
|
|
|
|
Read-only drives do not tell the actual media type but show any media as
|
|
|
|
ROM (e.g. as DVD-ROM). The session history of MMC multi-session media might
|
|
|
|
be truncated to first and last session or even be completely false.
|
|
|
|
(The eventual emulated history of overwriteable media is not affected by this.)
|
|
|
|
.br
|
|
|
|
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.
|
|
|
|
.br
|
|
|
|
Some operating systems are not able to mount the most recent session of
|
|
|
|
multi-session DVD or BD. If on such a system xorriso has no own MMC
|
|
|
|
capabilities then it may still find that session from a scanned table of
|
|
|
|
content. Setting "force" handles any media like a ROM media with setting "on".
|
|
|
|
.br
|
|
|
|
On the other hand the emulation of session history on overwriteable media
|
|
|
|
can hamper reading of partly damaged media. Setting "off:emul_off" disables
|
|
|