| Current File : //usr/share/info/xorriso.info |
This is xorriso.info, produced by makeinfo version 4.8 from
./xorriso.texi.
INFO-DIR-SECTION Archiving
START-INFO-DIR-ENTRY
* Xorriso: (xorriso). Burns ISO 9660 on CD, DVD, BD.
END-INFO-DIR-ENTRY
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem
images with Rock Ridge extensions.
Copyright (C) 2007 - 2010 Thomas Schmitt
Permission is granted to distrubute this text freely.
File: xorriso.info, Node: Top, Next: Overview, Up: (dir)
GNU xorriso
***********
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem
images with Rock Ridge extensions.
* Menu:
* Overview:: Overview
* Model:: Session model
* Media:: Media types and states
* Methods:: Creating, Growing, Modifying, Blind Growing
* Drives:: Libburn drives
* Extras:: Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
* Processing:: Command processing
* Dialog:: Dialog, Readline, Result pager
* Options:: Reference of commands
* Examples:: Examples
* Files:: Files
* Seealso:: See also
* Legal:: Author, Copyright, Credits
* CommandIdx:: Alphabetic Command List
* ConceptIdx:: Alphabetic List of Concepts and Objects
File: xorriso.info, Node: Overview, Next: Model, Prev: Top, Up: Top
1 Overview
**********
*xorriso* is a program which copies file objects from POSIX compliant
filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows
session-wise manipulation of such filesystems. It can load the
management information of existing ISO images and it writes the session
results to optical media or to filesystem objects.
Vice versa xorriso is able to copy file objects out of ISO 9660
filesystems.
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 .
1.1 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.
File: xorriso.info, Node: Model, Next: Media, Prev: Overview, Up: Top
2 Session model
***************
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 *session*.
The data content of the session is called filesystem *image*.
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.
This session usage model has been extended on CD media by the
concept of *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
*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.
xorriso provides growing as well as an own method named *modifying*
which produces a completely new ISO image from the old one and the
modifications. See paragraph Creating, Growing, Modifying, Blind
Growing below.
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. 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.
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.
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.
File: xorriso.info, Node: Media, Next: Methods, Prev: Model, Up: Top
3 Media types and states
************************
There are two families of media in the MMC standard:
*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 *-toc*.
*Overwriteable media* are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
They allow random write access but do not provide information about
their session history. If they contain one or more ISO 9660 sessions
and if the first session was written by xorriso, then a table of
content can be emulated. Else only a single overall session will be
visible.
DVD-RW media can be formatted by -format "full". They can be made
unformatted by -blank "deformat".
Regular files and block devices are handled as overwriteable media.
Pipes and other writeable file types are handled as blank multi-session
media.
These media can assume several states in which they offer different
capabilities.
*Blank* media can be written from scratch. They contain no ISO image
suitable for xorriso.
Blank is the state of newly purchased optical media. With used CD-RW
and DVD-RW it can be achieved by action -blank "as_needed".
Overwriteable media are considered blank if they are new or if they have
been marked as blank by xorriso. Action -blank "as_needed" can be used
to do this marking on overwriteable media, or to apply eventual
mandatory formatting to new media.
*Appendable* media accept further sessions. Either they are MMC
multi-session media in appendable state, or they are overwriteable media
which contain an ISO image suitable for xorriso.
Appendable is the state after writing a session with option -close off.
*Closed* media cannot be written. They may contain an ISO image suitable
for xorriso.
Closed is the state of DVD-ROM media and of multi-session media which
were written with option -close on. If the drive is read-only hardware
then it will probably show any media as closed CD-ROM resp. DVD-ROM.
Overwriteable media assume this state in such read-only drives or if
they contain unrecognizable data in the first 32 data blocks.
Read-only drives may or may not show session histories of multi-session
media. Often only the first and the last session are visible. Sometimes
not even that. Option -rom_toc_scan might or might not help in such
cases.
File: xorriso.info, Node: Methods, Next: Drives, Prev: Media, Up: Top
4 Creating, Growing, Modifying, Blind Growing:
**********************************************
A new empty ISO image gets *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.
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.
The method of *growing* adds new data to the existing media. These
data comprise of eventual new file content and they override the
existing ISO 9660 + Rock Ridge directory tree. It is possible to hide
files from previous sessions but they still exist on media and with
many types of optical media it is quite easy to recover them by
mounting older sessions.
Growing is achieved by option -dev.
The write method of *modifying* produces compact filesystem images
with no outdated files or directory trees. Modifying can write its
images to target media which are completely unsuitable for multi-session
operations. E.g. DVD-RW which were treated with -blank
deformat_quickest, named pipes, character devices, sockets. On the
other hand modified sessions cannot be written to appendable media but
to blank media only.
So for this method one needs either two optical drives or has to work
with filesystem objects as source and/or target media.
Modifying takes place if input drive and output drive are not the same
and if option -grow_blindly is set to its default "off". This is
achieved by options -indev and -outdev.
If option -grow_blindly is set to a non-negative number and if
-indev and -outdev are both set to different drives, then *blind
growing* is performed. It produces an add-on session which is ready for
being written to the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
which gives much room for wrong parameter combinations and should thus
only be employed if a strict distinction between ISO formatter xorriso
and the burn program is desired. -C $msc1,$msc2 is equivalent to:
-load sbsector $msc1 -grow_blindly $msc2
File: xorriso.info, Node: Drives, Next: Extras, Prev: Methods, Up: Top
5 Libburn drives
****************
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.
Output drive, i.e. target for writing, can be any libburn drive.
Some drive types do not support the method of growing but only the
methods of modifying and blind growing. They all are suitable for newly
created images.
All drive file objects have to offer rw-permission to the user of
xorriso. Even those which will not be useable for reading an ISO image.
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
-devices
It might be necessary to do this as *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".
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.
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.
Be aware that especially the superuser can write into any accessible
file or device by using its path with the "stdio:" prefix. By default
any address in the /dev tree without prefix "stdio:" will work only if
it leads to a MMC drive.
One may use option *-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:". By option -drive_class one may ban certain paths or allow
access without prefix "stdio:" to other paths.
File: xorriso.info, Node: Extras, Next: Processing, Prev: Drives, Up: Top
6 Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
**************************************************
*Rock Ridge* is the name of a set of additional information which
enhance an ISO 9660 filesystem so that it can represent a POSIX
compliant filesystem with ownership, access permissions, symbolic
links, and other attributes.
This is what xorriso uses for a decent representation of the disk files
within the ISO image. Rock Ridge information is produced with any
xorriso image.
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.
An *El Torito* boot record connects one or more boot images, which
are binary program files stored in the ISO image, with the
bootstrapping facility of contemporary computers. The content of the
boot image files is not in the scope of El Torito.
Most bootable GNU/Linux CDs are equipped with ISOLINUX 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.
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 *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.
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.
The support for other boot image types is sparse.
*ACL* are an advanced way of controlling access permissions to file
objects. Neither ISO 9660 nor Rock Ridge specify a way to record ACLs.
So libisofs has introduced a standard conformant extension named AAIP
for that purpose. It uses this extension if enabled by option *-acl*.
AAIP enhanced images are supposed to be mountable normally, but one
cannot expect that the mounted filesystem will show and respect the
eventual ACLs. For now, only xorriso is able to retrieve those ACLs.
It can bring them into effect when files get restored to an ACL enabled
file system or it can print them in a format suitable for tool setfacl.
Files with ACL show as group permissions the setting of entry "mask::"
if that entry exists. Nevertheless the non-listed group members get
handled according to entry "group::". xorriso brings "group::" into
effect before eventually removing the ACL from a file.
*xattr* (aka EA) are pairs of name and value which can be attached
to file objects. AAIP is able to represent them and xorriso allows to
record and restore pairs which have names out of the user namespace.
I.e. those which begin with "user.", like "user.x" or "user.whatever".
Name has to be a 0 terminated string. Value may be any array of bytes
which does not exceed the size of 4095 bytes. xattr processing happens
only if it is enabled by option *-xattr*.
As with ACL, currently only xorriso is able to retrieve xattr from AAIP
enhanced images, to restore them to xattr capable file systems, or to
print them.
File: xorriso.info, Node: Processing, Next: Dialog, Prev: Extras, Up: Top
7 Command processing
********************
Commands are either actions which happen immediately or settings which
influence following actions. So their sequence does matter.
Commands consist of a command word, followed by zero or more parameter
words. If the list of parameter words is of variable length (indicated
by "[...]" or "[***]") then it has to be terminated by either the *list
delimiter*, or the end of argument list, or an end of an input line.
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.
For brevity the list delimiter is referred as "--" 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.
*Pattern expansion* converts a list of pattern words into a list of
existing file addresses. Eventual unmatched pattern words appear
themselves in that result list, though.
Pattern matching supports the usual shell parser wildcards '*' '?'
'[xyz]' and respects '/' as separator which may only be matched
literally.
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
"[...]".
Some other commands perform pattern matching unconditionally.
Command and parameter words are either read from program arguments,
where one argument is one word, or from quoted input lines where words
are recognized similar to the quotation rules of a shell parser.
xorriso is not a shell, although it might appear so on first glimpse.
Be aware that the interaction of quotation marks and pattern symbols
like "*" differs from the usual shell parsers. In xorriso, a quotation
mark does not make a pattern symbol literal.
*Quoted input* converts whitespace separated text pieces into words.
The double quotation mark " and the single quotation mark ' can be used
to enclose whitespace and make it part of words (e.g. of file names).
Each mark type can enclose the marks of the other type. A trailing
backslash \ outside quotations or an open quotation cause the next
input line to be appended.
Quoted input accepts any ASCII character except NUL (0) as content of
quotes. Nevertheless it can be cumbersome for the user to produce
those characters at all. Therefore quoted input and program arguments
allow optional *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.
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.
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.
File: xorriso.info, Node: Dialog, Next: Options, Prev: Processing, Up: Top
8 Dialog, Readline, Result pager
********************************
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.
Readline is an enhancement for the input line. You may know it
already from the bash shell. Whether it is available in xorriso depends
on the availability of package readline-dev at the time when xorriso
was built from its sourcecode.
It allows to move the cursor over the text in the line by help of the
Leftward and the Rightward arrow key. Text may be inserted at the
cursor position. The Delete key removes the character under the cursor.
Upward and Downward arrow keys navigate through the history of previous
input lines.
See info readline for more info about libreadline.
Option -page activates a built-in result text pager which may be
convenient in dialog. After an action has put out the given number of
terminal lines, the pager prompts the user for a line of input.
An empty line lets xorriso resume work until the next page is put out.
The single character "@" disables paging for the current action.
"@@@", "x", "q", "X", or "Q" urge the current action to abort and
suppress further result output.
Any other line will be interpreted as new dialog line. The current
action is urged to abort. Afterwards, the input line is executed.
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.
File: xorriso.info, Node: Options, Next: Examples, Prev: Dialog, Up: Top
9 Options
*********
All command words are shown with a leading dash although this dash is
not mandatory for the option to be recognized. Nevertheless within
option -as the dashes of the emulated options are mandatory.
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
* Menu:
* AqDrive:: Aquiring source and target drive
* Loading:: Influencing the behavior of image loading
* 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:: El Torito bootable ISO images
* Charset:: Character sets
* Exception:: Exception processing
* DialogCtl:: Dialog mode control
* Inquiry:: Drive and media related inquiry actions
* Navigate:: Navigation in ISO image and disk filesystem
* Verify:: Evaluation of readability and recovery
* Restore:: osirrox ISO-to-disk restore options
* Emulation:: Command compatibility emulations (cdrtools)
* Scripting:: Scripting, dialog and program control features
* Frontend:: Support for frontend programs via stdin and stdout
File: xorriso.info, Node: AqDrive, Next: Loading, Prev: Options, Up: Options
9.1 Aquiring source and target drive
====================================
Before aquiring a drive one will eventually enable options which
influence the behavior of image loading. See next option group.
-dev address
Set input and output drive to the same address and load an
eventual ISO image. If there is no ISO image then create a blank
one. Set the image expansion method to growing.
This is only allowed as long as no changes are pending in the
currently loaded ISO image. Eventually one has to perform -commit
or -rollback first.
Special address string "-" means standard output, to which several
restrictions apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current device without
aquiring a new one.
-indev address
Set input drive and load an eventual ISO image. If the new input
drive differs from -outdev then switch from growing to modifying
or to blind growing. It depends on the setting of -grow_blindly
which of both gets activated. The same rules and restrictions
apply as with -dev.
-outdev address
Set output drive and if it differs from the input drive then
switch from growing to modifying or to blind growing. Unlike -dev
and -indev this action does not load a new ISO image. So it can be
performed even if there are pending changes.
-outdev can be performed without previous -dev or -indev. In that
case an empty ISO image with no changes pending is created. It can
either be populated by help of -map, -add et.al. or it can be
discarded silently if -dev or -indev are performed afterwards.
Special address string "-" means standard output, to which several
restrictions apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current output drive
without aquiring a new one. No writing is possible without an
output drive.
-grow_blindly "off"|predicted_nwa
If predicted_nwa is a non-negative number then perform blind
growing rather than modifying if -indev and -outdev are set to
different drives. "off" or "-1" switch to modifying, which is the
default.
predicted_nwa is the block address where the add-on session of
blind growing will finally end up. It is the responsibility of the
user to ensure this final position and the presence of the older
sessions. Else the overall ISO image will not be mountable or will
produce read errors when accessing file content. xorriso will
write the session to the address as obtained from examining
-outdev and not necessarily to predicted_nwa.
During a run of blind growing, the input drive is given up before
output begins. The output drive is given up when writing is done.
File: xorriso.info, Node: Loading, Next: Insert, Prev: AqDrive, Up: Options
9.2 Influencing the behavior of image loading
=============================================
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.
-load entity id
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".
-drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern
Add a drive path pattern to one of the safety lists or make those
lists empty. There are three lists defined which get tested in
the following sequence:
If a drive address path matches the "harmless" list then the drive
will be accepted. If it is not a MMC device then the prefix
"stdio:" will be prepended automatically. This list is empty by
default.
Else if the path matches the "banned" list then the drive will not
be accepted by xorriso but rather lead to a FAILURE event. This
list is empty by default.
Else if the path matches the "caution" list and if it is not a MMC
device, then its address must have the prefix "stdio:" or it will
be rejected. This list has by default one entry: "/dev".
If a drive path matches no list then it is considered "harmless".
By default these are all paths which do not begin with directory
"/dev".
A path matches a list if one of its parent paths or itself matches
a list entry. An eventual address prefix "stdio:" or "mmc:" will
be ignored when testing for matches.
By pseudo-class "clear_list" and pseudo-patterns "banned",
"caution", "harmless", or "all", the lists may be made empty.
E.g.: -drive_class clear_list banned
One will normally define the -drive_class lists in one of the
xorriso Startup Files.
Note: This is not a security feature but rather a bumper for the
superuser to prevent inadverted mishaps. For reliably blocking
access to a device file you have to deny its rw-permissions in the
filesystem.
-assert_volid pattern severity
Refuse to load ISO images with volume ids which do not match the
given search pattern. When refusing an image, give up the input
drive and issue an event of the given severity (like FAILURE, see
-abort_on). An empty search pattern accepts any image.
This option does not hamper the creation of an empty image from
blank input media and does not discard an already loaded image.
-in_charset character_set_name
Set the character set from which to convert file names when
loading an image. This has eventually to be done before specifying
-dev , -indev or -rollback. See paragraph "Character sets" for
more explanations. When loading the written image after -commit
the setting of -out_charset will be copied to -in_charset.
-auto_charset "on"|"off"
Enable or disable recording and interpretation of the output
character set name in an xattr attribute of the image root
directory. If enabled then an eventual recorded character set name
gets used as input character set when reading an image.
Note that the default output charset is the local character set of
the terminal where xorriso runs. Before attributing this local
character set to the produced ISO image, check whether the
terminal properly displays all intended filenames, especially
exotic national characters.
-hardlinks mode[:mode...]
Enable or disable loading and recording of hardlink relations.
In default mode "off", iso_rr files lose their inode numbers at
image load time. Each iso_rr file object which has no inode number
at image generation time will get a new unique inode number if
-compliance is set to new_rr.
Mode "on" preserves eventual inode numbers from the loaded image.
When committing a session it searches for families of iso_rr files
which stem from the same disk file, have identical content
filtering and have identical properties. The family members all
get the same inode number. Whether these numbers are respected at
mount time depends on the operating system.
Commands -update and -update_r track splits and fusions of hard
links in filesystems which have stable device and inode numbers.
This can cause automatic last minute changes before the session
gets written. Command -hardlinks "perform_update" may be used to
do these changes earlier, e.g. if you need to apply filters to all
updated files.
Mode "without_update" avoids hardlink processing during update
commands. Use this if your filesystem situation does not allow
-disk_dev_ino "on".
xorriso commands which extract files from an ISO image try to
hardlink files with identical inode number. The normal scope of
this operation is from image load to image load. One may give up
the accumulated hard link addresses by -hardlinks
"discard_extract".
A large number of hardlink families may exhaust -temp_mem_limit if
not -osirrox "sort_lba_on" and -hardlinks "cheap_sorted_extract"
are both in effect. This restricts hard linking to other files
restored by the same single extract command. -hardlinks
"normal_extract" re-enables wide and expensive hardlink
accumulation.
-acl "on"|"off"
Enable or disable processing of ACLs. If enabled, then xorriso
will obtain ACLs from disk file objects, store ACLs in the ISO
image using the libisofs specific AAIP format, load AAIP data from
ISO images, test ACL during file comparison, and restore ACLs to
disk files when extracting them from ISO images. See also options
-getfacl, -setfacl.
-xattr "on"|"off"
Enable or disable processing of xattr attributes in user namespace.
If enabled, then xorriso will handle xattr similar to ACL. See
also options -getfattr, -setfattr and above paragraph about xattr.
-md5 "on"|"all"|"off"
Enable or disable processing of MD5 checksums for the overall
session and for each single data file. If enabled then images get
loaded only if eventual checksums tags of superblock and directory
tree match properly. The MD5 checksums of data files and whole
session get loaded from the image if there are any.
With options -compare and -update the eventually recorded MD5 of a
file will be used to avoid content reading from the image. Only
the disk file content will be read and compared with that MD5.
This can save much time if -disk_dev_ino "on" is not suitable.
At image generation time they are computed for each file which
gets its data written into the new session. The checksums of files
which have their data in older sessions get copied into the new
session. Superblock, tree and whole session get a checksum tag
each.
Mode "all" will additionally check during image generation whether
the checksum of a data file changed between the time when its
reading began and the time when it ended. This implies reading
every file twice.
Checksums can be exploited via options -check_md5, -check_md5_r,
via find actions get_md5, check_md5, and via -check_media.
-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.
-disk_dev_ino "on"|"ino_only"|"off"
Enable or disable processing of recorded file identification
numbers (dev_t and ino_t). They are eventually stored as xattr and
allow to substantially accelerate file comparison. The root node
gets a global start timestamp. If during comparison a file with
younger timestamps is found in the ISO image, then it is suspected
to have inconsistent content.
If device numbers and inode numbers of the disk filesystems are
persistent and if no irregular alterations of timestamps or system
clock happen, then potential content changes can be detected
without reading that content. File content change is assumed if
any of mtime, ctime, device number or inode number have changed.
Mode "ino_only" replaces the precondition that device numbers are
stable by the precondition that mount points in the compared tree
always lead to the same filesystems. Use this if mode "on" always
sees all files changed.
The speed advantage appears only if the loaded session was
produced with -disk_dev_ino "on" too.
Note that -disk_dev_ino "off" is totally in effect only if
-hardlinks is "off", too.
-rom_toc_scan "on"|"force"|"off"[:"emul_on"|"emul_off"]
Read-only drives do not tell the actual media type but show any
media as ROM (e.g. as DVD-ROM). The session history of MMC
multi-session media might be truncated to first and last session
or even be completely false. (The eventual emulated history of
overwriteable media is not affected by this.)
To have in case of failure a chance of getting the session history
and especially the address of the last session, there is a scan
for ISO 9660 filesystem headers which might help but also might
yield worse results than the drive's table of content. At its end
it can cause read attempts to invalid addresses and thus ugly
drive behavior. Setting "on" enables that scan for alleged
read-only media.
Some operating systems are not able to mount the most recent
session of multi-session DVD or BD. If on such a system xorriso
has no own MMC capabilities then it may still find that session
from a scanned table of content. Setting "force" handles any media
like a ROM media with setting "on".
On the other hand the emulation of session history on
overwriteable media can hamper reading of partly damaged media.
Setting "off:emul_off" disables the elsewise trustworthy
table-of-content scan for those media.
To be in effect, the -rom_toc_scan setting has to be made before
the -*dev command which aquires drive and media.
-calm_drive "in"|"out"|"all"|"revoke"|"on"|"off"
Reduce drive noise until it is actually used again. Some drives
stay alert for substantial time after they have been used for
reading. This reduces the startup time for the next drive
operation but can be loud and waste energy if no i/o with the
drive is expected to happen soon.
Modes "in", "out", "all" immediately calm down -indev, -outdev,
resp. both. Mode "revoke" immediately alerts both. Mode "on"
causes -calm_drive to be performed automatically after each -dev,
-indev, and -outdev. Mode "off" disables this.
-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.
File: xorriso.info, Node: Insert, Next: SetInsert, Prev: Loading, Up: Options
9.3 Inserting files into ISO image
==================================
The following commands expect file addresses of two kinds: *disk_path*
is a path to an object in the local filesystem tree. *iso_rr_path* is
the Rock Ridge name of a file object in the ISO image. (Do not confuse
with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.)
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.
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 *-overwrite* decides.
Renaming of files has similar collision handling, but directories can
only be replaced, not merged. Note that -mv inserts the source objects
into an eventual existing target directory rather than attempting to
replace it.
The commands in this section alter the ISO image and not the local
filesystem.
-disk_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the disk_path arguments of
several commands which support this feature.
Setting "off" disables this feature for all commands which are
marked in this man page by "disk_path [***]" or "disk_pattern
[***]".
Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked by
"disk_pattern [***]".
Default is "ls".
-add pathspec [...] | disk_path [***]
Insert the given files or directory trees from filesystem into the
ISO image.
If -pathspecs is set to "on" then pattern expansion is always
disabled and character '=' has a special meaning. It eventually
separates the ISO image path from the disk path:
iso_rr_path=disk_path
The separator '=' can be escaped by '\'. If iso_rr_path does not
begin with '/' then -cd is prepended. If disk_path does not begin
with '/' then -cdx is prepended.
If no '=' is given then the word is used as both, iso_rr_path and
disk path. If in this case the word does not begin with '/' then
-cdx is prepended to the disk_path and -cd is prepended to the
iso_rr_path.
If -pathspecs is set to "off" then eventual -disk_pattern
expansion applies. The resulting words are used as both,
iso_rr_path and disk path. Eventually -cdx gets prepended to
disk_path and -cd to iso_rr_path.
-add_plainly mode
If set to mode "unknown" then any command word that does not begin
with "-" and is not recognized as known command will be subject to
a virtual -add command. I.e. it will be used as pathspec or as
disk_path and added to the image. Eventually -disk_pattern
expansion applies to disk_paths.
Mode "dashed" is similar to "unknown" but also adds unrecognized
command words even if they begin with "-".
Mode "any" announces that all further words are to be added as
pathspecs or disk_paths. This does not work in dialog mode.
Mode "none" is the default. It prevents any words from being
understood as files to add, if they are not parameters to
appropriate commands.
-path_list disk_path
Like -add but read the parameter words from file disk_path or
standard input if disk_path is "-". The list must contain exactly
one pathspec resp. disk_path pattern per line.
-quoted_path_list disk_path
Like -path_list but with quoted input reading rules. Lines get
split into parameter words for -add. Whitespace outside quotes is
discarded.
-map disk_path iso_rr_path
Insert file object disk_path into the ISO image as iso_rr_path. If
disk_path is a directory then its whole sub tree is inserted into
the ISO image.
-map_single disk_path iso_rr_path
Like -map, but if disk_path is a directory then its sub tree is
not inserted.
-map_l disk_prefix iso_rr_prefix disk_path [***]
Perform -map with each of the disk_path arguments. iso_rr_path
will be composed from disk_path by replacing disk_prefix by
iso_rr_prefix.
-update disk_path iso_rr_path
Compare file object disk_path with file object iso_rr_path. If
they do not match, then perform the necessary image manipulations
to make iso_rr_path a matching copy of disk_path. By default this
comparison will imply lengthy content reading before a decision is
made. Options -disk_dev_ino or -md5 may accelerate comparison if
they were already in effect when the loaded session was recorded.
If disk_path is a directory and iso_rr_path does not exist yet,
then the whole subtree will be inserted. Else only directory
attributes will be updated.
-update_r disk_path iso_rr_path
Like -update but working recursively. I.e. all file objects below
both addresses get compared whether they have counterparts below
the other address and whether both counterparts match. If there is
a mismatch then the necessary update manipulation is done.
Note that the comparison result may depend on option -follow. Its
setting should always be the same as with the first adding of
disk_path as iso_rr_path.
If iso_rr_path does not exist yet, then it gets added. If
disk_path does not exist, then iso_rr_path gets deleted.
-update_l disk_prefix iso_rr_prefix disk_path [***]
Perform -update_r with each of the disk_path arguments.
iso_rr_path will be composed from disk_path by replacing
disk_prefix by iso_rr_prefix.
-cut_out disk_path byte_offset byte_count iso_rr_path
Map a byte interval of a regular disk file into a regular file in
the ISO image. This may be necessary if the disk file is larger
than a single media, or if it exceeds the traditional limit of 2
GiB - 1 for old operating systems, or the limit of 4 GiB - 1 for
newer ones. Only the newest Linux kernels seem to read properly
files >= 4 GiB - 1.
A clumsy remedy for this limit is to backup file pieces and to
concatenate them at restore time. A well tested chopping size is
2047m. It is permissible to request a higher byte_count than
available. The resulting file will be truncated to the correct
size of a final piece. To request a byte_offset higher than
available yields no file in the ISO image but a SORRY event. E.g:
-cut_out /my/disk/file 0 2047m \
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \
-cut_out /my/disk/file 2047m 2047m \
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
-cut_out /my/disk/file 4094m 2047m \
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821
While option -split_size is set larger than 0, and if all pieces
of a file reside in the same ISO directory with no other files,
and if the names look like above, then their ISO directory will be
recognized and handled like a regular file. This affects options
-compare*, -update*, and overwrite situations. See option
-split_size for details.
-cpr disk_path [***] iso_rr_path
Insert the given files or directory trees from filesystem into the
ISO image.
The rules for generating the ISO addresses are similar as with
shell command cp -r. Nevertheless, directories of the iso_rr_path
are created if necessary. Especially a not yet existing iso_rr_path
will be handled as directory if multiple disk_paths are present.
The leafnames of the multiple disk_paths will be grafted under that
directory as would be done with an existing directory.
If a single disk_path is present then a non-existing iso_rr_path
will get the same type as the disk_path.
If a disk_path does not begin with '/' then -cdx is prepended. If
the iso_rr_path does not begin with '/' then -cd is prepended.
-mkdir iso_rr_path [...]
Create empty directories if they do not exist yet. Existence as
directory generates a WARNING event, existence as other file
causes a FAILURE event.
File: xorriso.info, Node: SetInsert, Next: Manip, Prev: Insert, Up: Options
9.4 Settings for file insertion
===============================
-file_size_limit value [value [...]] --
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 xorriso. Default is a
limit of 100 extents, 4g -2k each:
-file_size_limit 400g -200k --
When mounting ISO 9660 filesystems, old operating systems can
handle only files up to 2g -1 --. Newer ones are good up to 4g -1
--. 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.
xorriso's own data read capabilities are not affected by eventual
operating system size limits. They apply to mounting only.
Nevertheless, the target filesystem of an -extract must be able to
take the file size.
-not_mgt code[:code[...]]
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.
-not_paths disk_path [***]
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. Eventual pattern matching happens at
definition time and not when exclusion checks are made.
(Do not forget to end the list of disk_paths by "--")
-not_leaf pattern
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.
-not_list disk_path
Read lines from disk_path and use each of them either as
-not_paths argument, if they contain a / character, or as
-not_leaf pattern.
-quoted_not_list disk_path
Like -not_list but with quoted input reading rules. Each word is
handled as one argument for -not_paths resp. -not_leaf.
-follow occasion[:occasion[...]]
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".
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.
-pathspecs "on"|"off"
Control parameter interpretation with xorriso actions -add and
-path_list.
"on" enables pathspecs of the form *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 eventually
enables -disk_pattern expansion.
-overwrite "on"|"nondir"|"off"
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".
-split_size number["k"|"m"]
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 option -split_size is set larger than 0 such a directory
with split file pieces will be recognized and handled like a
regular file by options -compare* , -update*, and in overwrite
situations. There are -ossirox options "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 argument and their contents may not
overlap.
File: xorriso.info, Node: Manip, Next: CmdFind, Prev: SetInsert, Up: Options
9.5 File manipulations
======================
The following commands manipulate files in the ISO image, regardless
whether they stem from the loaded image or were newly inserted.
-iso_rr_pattern "on"|"ls"|"off"
Set the pattern expansion mode for the iso_rr_path arguments 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".
-rm iso_rr_path [***]
Delete the given files from the ISO image.
Note: This does not free any space on the -indev media, even if
the deletion is committed to that same media.
The image size will shrink if the image is written to a different
media in modification mode.
-rm_r iso_rr_path [***]
Delete the given files or directory trees from the ISO image. See
also the note with option -rm.
-rmdir iso_rr_path [***]
Delete empty directories.
-mv iso_rr_path [***] iso_rr_path
Rename the given file objects in the ISO tree to the last argument
in the list. Use the same rules as with shell command mv.
If pattern expansion is enabled and if the last argument contains
wildcard characters then it must match exactly one existing file
address, or else the command fails with a FAILURE event.
-chown uid iso_rr_path [***]
Set ownership of file objects in the ISO image. uid may either be
a decimal number or the name of a user known to the operating
system.
-chown_r uid iso_rr_path [***]
Like -chown but affecting all files below eventual directories.
-chgrp gid iso_rr_path [***]
Set group attribute of file objects in the ISO image. gid may
either be a decimal number or the name of a group known to the
operating system.
-chgrp_r gid iso_rr_path [***]
Like -chgrp but affecting all files below eventual directories.
-chmod mode iso_rr_path [***]
Equivalent to shell command chmod in the ISO image. mode is
either an octal number beginning with "0" or a comma separated
list of statements of the form [ugoa]*[+-=][rwxst]* .
Like: go-rwx,u+rwx .
*Personalities*: u=user, g=group, o=others, a=all
*Operators*: + adds given permissions, - revokes given permissions,
= revokes all old permissions and then adds the given ones.
*Permissions*: r=read, w=write, x=execute|inspect,
s=setuid|setgid, t=sticky bit
For octal numbers see man 2 stat.
-chmod_r mode iso_rr_path [***]
Like -chmod but affecting all files below eventual directories.
-setfacl acl_text iso_rr_path [***]
Attach the given ACL to the given iso_rr_paths after deleting
their eventually existing ACLs. If acl_text is empty, or contains
the text "clear" or the text "--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-,user::rw-,group::r--,other::r--,mask::rw-
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
-setfacl_r acl_text iso_rr_path [***]
Like -setfacl but affecting all files below eventual directories.
-setfacl_list disk_path
Read the output of -getfacl_r or shell command getfacl -R and
apply it to the iso_rr_paths as given in lines beginning with "#
file:". This will change ownership, group and ACL of the given
files. If disk_path is "-" then lines are read from standard
input. Line "@" ends the 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.
-setfattr [-]name value iso_rr_path [***]
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
"--remove-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 xorriso.
See also option -backslash_codes. Other than with option
-setfattr_list, the byte value 0 cannot be expressed via -setfattr.
-setfattr_r [-]name value iso_rr_path [***]
Like -setfattr but affecting all files below eventual directories.
-setfattr_list disk_path
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 ASCII code XYZ. Use code \000 for 0-bytes.
-alter_date type timestring iso_rr_path [***]
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
xorriso's own timestamps:
YYYY.MM.DD[.hh[mm[ss]]]
scdbackup timestamps:
YYMMDD[.hhmm[ss]]
where "A0" is year 2000, "B0" is 2010, etc.
-alter_date_r type timestring iso_rr_path [***]
Like -alter_date but affecting all files below eventual
directories.
-hide hide_state iso_rr_path [***]
Prevent the names of the given files from showing up in the
directory trees of ISO 9660 and/or Joliet when the image gets
written. The eventual 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, "on" for both trees. "off"
means visibility in both directory trees.
This command does not apply to the boot catalog. Rather use:
-boot_image "any" "cat_hidden=on"
File: xorriso.info, Node: CmdFind, Next: Filter, Prev: Manip, Up: Options
9.6 Tree traversal command -find
================================
-find iso_rr_path [test [op] [test ...]] [-exec action [params]] --
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 argument list
needs to get terminated by "--".
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:
-name pattern :
Matches if pattern matches the file leaf name.
-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.
-disk_name pattern :
Like -name but testing the leaf name of the file source on
disk. Can be true only for data files which stem not from
the loaded image.
-type type_letter :
Matches files of the given type: "block", "char", "dir",
"pipe", "file", "link", "socket", "eltorito", "Xotic" which
eventually matches what is not matched by the other types.
Only the first letter is interpreted. E.g.: -find / -type d
-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.
-pending_data :
Matches files which get their content from outside the loaded
ISO image.
-lba_range start_lba block_count :
Matches files which use data blocks within the range of
start_lba and start_lba+block_count-1.
-has_acl :
Matches files which have a non-trivial ACL.
-has_xattr :
Matches files which have xattr name-value pairs from user
namespace.
-has_aaip :
Matches files which have ACL or any xattr.
-has_any_xattr :
Matches files which have any xattr other than ACL.
-has_md5 :
Matches data files which have MD5 checksums.
-has_filter :
Matches files which are filtered by -set_filter.
-hidden hide_state :
Matches files which are hidden in "iso_rr" tree, in "joliet"
tree, in both trees ("on"), or not hidden in any tree ("off").
Those which are hidden in some tree match -not -hidden "off".
-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.
-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.
-true and -false :
Always match resp. match not. Evaluation goes on.
-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:
-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 .
-and :
Matches if both neighboring tests or expressions match.
-or :
Matches if at least one of both neighboring tests or
expressions matches.
-sub ... -subend or ( ... ) :
Enclose a sub expression which gets evaluated first before it
is processed by neighboring operators. Normal precedence is:
-not, -or , -and.
-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 eventually 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.
Default action is *echo*, i.e. to print the address of the found
file. Other actions are certain xorriso commands which get
performed on the found files. These commands may have specific
parameters. See also their particular descriptions.
chown and chown_r
change the ownership and get the user id as parameter. E.g.:
-exec chown thomas --
chgrp and Bchgrp_r
change the group attribute and get the group id as parameter.
E.g.: -exec chgrp_r staff --
chmod and chmod_r
change access permissions and get a mode string as parameter.
E.g.: -exec chmod a-w,a+r --
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" --
lsdl
prints file information like shell command ls -dl.
compare
performs command -compare with the found file address as
iso_rr_path and the corresponding file address below its
argument 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 --
update
performs command -update with the found file address as
iso_rr_path. The corresponding file address is determined
like with above action "compare".
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".
rm_r
removes the found iso_rr_path from the image, including whole
directory trees.
report_damage
classifies files whether they hit a data block that is marked
as damaged. The result is printed together with the eventual
address of the first damaged byte, the maximum span of
damages, file size, and the path of the file.
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".
getfacl
prints access permissions in ACL text form to the result
channel.
setfacl
attaches ACLs after removing eventually exiting ones. The new
ACL is given in text form as defined with option -setfacl.
E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
getfattr
prints eventual xattr name-value pairs from user namespace to
the result channel.
get_any_xattr
prints eventual xattr name-value pairs from any namespace
except ACL to the result channel. This is mostly for
debugging of namespace "isofs".
get_md5
prints eventual recorded MD5 sum together with file path.
check_md5
compares eventual recorded MD5 sum with the file content and
reports if mismatch.
E.g.: -find / -not -pending_data -exec check_md5 FAILURE --
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 --
setfattr
sets or deletes xattr name value pairs.
E.g.: -find / -has_xattr -exec setfattr --remove-all " --
set_filter
applies or removes filters.
E.g.: -exec set_filter --zisofs --
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.
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 --
show_stream
shows the content stream chain of a data file.
hide
brings the file into one of the hide states "on", "iso_rr",
"joliet", "off".
E.g.:
-find / -disk_name *_secret -exec hide on
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 --
File: xorriso.info, Node: Filter, Next: Writing, Prev: CmdFind, Up: Options
9.7 Filters for data file content
=================================
*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.
Built-in filters are "--zisofs" and "--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 "--gzip" and "--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.
-external_filter name option[:option] program_path [arguments] --
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 an eventual 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 --
-external_filter bunzip2 suffix=.bz2:remove_suffix \
/usr/bin/bunzip2 --
-unregister_filter name
Remove an -external_filter registration. This is only possible if
the filter is not applied to any file in the ISO image.
-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 xorriso. By
default they are banned if xorriso runs under setuid permission.
-set_filter name iso_rr_path [***]
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 "--remove-all-filters" revokes filtering.
This will revoke eventual suffix renamings as well. Use
"--remove-all-filters+" to prevent any suffix renaming.
-set_filter_r name iso_rr_path [***]
Like -set_filter but affecting all data files below eventual
directories.
File: xorriso.info, Node: Writing, Next: SetWrite, Prev: Filter, Up: Options
9.8 Writing the result, drive control
=====================================
(see also paragraph about settings below)
-rollback
Discard the manipulated ISO image and reload it from -indev. (Use
-rollback_end if immediate program end is desired.)
-commit
Perform the write operation. Afterwards eventually make the
-outdev 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 option -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 media for a few minutes
after all data have been transmitted. 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.
-eject "in"|"out"|"all"
Eject the media in -indev, resp. -outdev, resp. both drives.
Note: It is not possible yet to effectively eject disk files.
-commit_eject "in"|"out"|"all"|"none"
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. Eventually give up any non-ejected drive.
-blank mode
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.
xorriso will write onto them only if option -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.
-format mode
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
option -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
media, 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.
-list_formats
Put out a list of format descriptors as reported by the output
drive for the current media. 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.
-list_profiles "in"|"out"|"all"
Put out a list of media types supported by -indev, resp. -outdev,
resp. both. The currently recognized type is marked by text
"(current)".
File: xorriso.info, Node: SetWrite, Next: Bootable, Prev: Writing, Up: Options
9.9 Settings for result writing
===============================
Rock Ridge info will be generated by the program unconditionally. ACLs
will be written according to the setting of option -acl.
-joliet "on"|"off"
If enabled by "on", generate Joliet tree additional to ISO 9660 +
Rock Ridge tree.
-compliance rule[:rule...]
Adjust the compliance to specifications of ISO 9660 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 option 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:
"omit_version" do not add versions (";1") to ISO and Joliet file
names.
"only_iso_version" do not add versions (";1") to Joliet file names.
"deep_paths" allow ISO file paths deeper than 8 levels.
"long_paths" allow ISO file paths longer than 255 characters.
"long_names" allow up to 37 characters with ISO file names.
"no_force_dots" do not add a dot to ISO file names which have none.
"no_j_force_dots" do not add a dot to Joliet file names which have
none.
"lowercase" allow lowercase characters in ISO file names.
"full_ascii" allow all ASCII characters in ISO file names.
"joliet_long_paths" allow Joliet paths longer than 240 characters.
"always_gmt" store timestamps in GMT representation with timezone
0.
"rec_mtime" record with ISO files the disk file's mtime and not the
creation time of the image.
"new_rr" use 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.
Default setting is
"clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
always_gmt:old_rr".
Note: The term "ISO file" means the plain ISO 9660 names and
attributes which get visible if the reader ignores Rock Ridge.
-volid text
Specify the volume ID. 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 name
of the mount point when the media 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.
-volset_id text
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.
-publisher text
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.
-application_id text
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.
-system_id text
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.
-volume_date type timestring
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 -fs-uuid -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 option
-alter_date. They 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.
-copyright_file text
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.
-abstract_file text
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.
-biblio_file text
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.
-out_charset character_set_name
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.
-uid uid
User id to be used for all files when the new ISO tree gets
written to media.
-gid gid
Group id to be used for all files when the new ISO tree gets
written to media.
-zisofs option[:options]
Set global parameters for zisofs compression. This data format is
recognized and transparently uncompressed by some Linux kernels.
It is to be applied via option -set_filter with built-in filter
"--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"
-speed number[k|m|c|d|b]
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 media
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.
-stream_recording "on"|"off"|"full"|"data"|number
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 media 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.
-dvd_obs "default"|"32k"|"64k"
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 option -stream_recording ,
and on compile time options.
-stdio_sync "on"|"off"|number
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".
-dummy "on"|"off"
If "on" then simulate burning or refuse with FAILURE event if no
simulation is possible, do neither blank nor format.
-fs number["k"|"m"]
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).
-close "on"|"off"
If "on" then mark the written media as not appendable any more (if
possible at all with the given type of target media).
This is the contrary of cdrecord, wodim, cdrskin option -multi,
and is one aspect of growisofs option -dvd-compat.
-padding number["k"|"m"]
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, 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 .
File: xorriso.info, Node: Bootable, Next: Charset, Prev: SetWrite, Up: Options
9.10 El Torito bootable ISO images
==================================
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 eventually 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.
-boot_image "any"|"isolinux"|"grub"
"discard"|"keep"|"patch"|"show_status"|bootspec|"next"
Define the handling of an eventual 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 arguments: 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 *isolinux* and *grub* care for known peculiarities. Type
*any* makes no assumptions about the origin of the boot images.
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"
*show_status* will print what is known about the loaded boot images
and their designated fate.
A *bootspec* is a word of the form name=value and is used to
describe the parameters of a boot image by an El Torito record and
eventually 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
*bin_path=* depicts the boot image file, a binary program which is
to be started by the hardware boot facility (e.g. the BIOS) at
boot time.
*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, platform_id is 0xef.
An El Torito boot catalog file gets inserted into the ISO image
with address *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 *cat_hidden=on*. Other possible
values are "iso_rr", "joliet", and the default "off".
*load_size=* is a value which depends on the boot image. Default
2048 should be overridden only if a better value is known.
*boot_info_table=on* may be used to apply patching to a boot image
which is given by "any" "bin_path=". "boot_info_table=off"
disables patching.
*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.
*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.
*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.
*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 eventually loaded boot images and their
catalog.
*discard* gives up an existing boot catalog and its boot images.
*keep* keeps or copies boot images unaltered and writes a new
catalog.
*patch* applies patching to existing boot images if they seem to
bear a boot info table.
*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".
*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 partiton which
starts at byte 512 and ends where the ISO image ends. This works
with or without system_area= or boot image.
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 eventually was loaded with the ISO image.
File: xorriso.info, Node: Charset, Next: Exception, Prev: Bootable, Up: Options
9.11 Character sets
===================
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 *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 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
options -in_charset and -out_charset. Normally one will have both
identical, if ever.
If conversions are desired then xorriso needs to know the name of the
local character set. 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 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 option -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.
-charset character_set_name
Set the character set from which to convert file names when
loading an image and to which to convert when writing an image.
-local_charset character_set_name
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.
File: xorriso.info, Node: Exception, Next: DialogCtl, Prev: Charset, Up: Options
9.12 Exception processing
=========================
Since the tasks of xorriso are manifold and prone to external
influence, there may arise the need for 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.
-abort_on severity
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 option. Expect not many "ABORT" events to be
ignorable.
A special property of this option 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 xorriso begin. Only "-abort_on" with dash "-" is
recognized that way.
-return_with severity exit_value
Set the threshold and exit_value to be returned at program end if
no abort has happened. This is to allow 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 xorriso if it decides to abort the program run:
1=abort due to external signal
2=no program arguments given
3=creation of xorriso main object failed
4=failure to start libburnia-project.org libraries
5=program abort during argument processing
6=program abort during dialog processing
-report_about severity
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 option is that the first -report_about
setting among the start arguments is in effect already when the
first operations of xorriso begin. Only "-report_about" with dash
"-" is recognized that way.
-error_behavior occasion 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 options 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 option -abort_on allows this.
"failure" aborts image tree reading on first event of at least
SORRY. It issues an own FAILURE event.
"fatal" acts like "failure" but issues the own event as FATAL.
This is the default.
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.
File: xorriso.info, Node: DialogCtl, Next: Inquiry, Prev: Exception, Up: Options
9.13 Dialog mode control
========================
-dialog "on"|"off"|"single_line"
Enable or disable to enter dialog mode after all arguments are
processed. In dialog mode input lines get prompted via readline
or from stdin.
Mode "on" supports input of newline characters within quotation
marks and line continuation by trailing backslash outside
quotation marks. Mode "single_line" does not.
-page length width
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.
-use_readline "on"|"off"
If "on" then use readline for dialog. Else use plain stdin.
See also above, paragraph Dialog, Readline, Result pager.
-reassure "on"|"tree"|"off"
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, option -dialog needs to be set to
"on". Note that the prompt does not appear in situations where
file removal is forbidden by option -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.
File: xorriso.info, Node: Inquiry, Next: Navigate, Prev: DialogCtl, Up: Options
9.14 Drive and media related inquiry actions
============================================
-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 option was executed, there is no drive current and no
image loaded. Eventually one has to aquire a drive again.
In order to be visible, a device has to offer rw-permissions with
its libburn standard device file. Thus it might be only the
*superuser* who is able to see all drives.
Drives which are occupied by other processes get not shown.
-toc
Show media specific table of content. This is the media session
history, 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 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. Eventually option -rom_toc_scan might help.
-mount_cmd drive entity id path
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 option -mount
for direct execution of this command.
-mount_opts option[:option...]
Set options which influence -mount and -mount_cmd. Currently there
is only option "exclusive" which is default and its counterpart
"shared". The latter causes 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
media, of course. Take care to umount all sessions before ejecting.
-session_string drive entity id format
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 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.
-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 option.
-tell_media_space
Print available space on output media and the free space after
subtracting already foreseeable consumption by next -commit.
-pvd_info
Print various id strings which can be found in loaded ISO images.
Some of them may be changed by options like -volid or -publisher.
For these ids -pvd_info reports what would be written with the
next -commit.
File: xorriso.info, Node: Navigate, Next: Verify, Prev: Inquiry, Up: Options
9.15 Navigation in ISO image and disk filesystem
================================================
-cd iso_rr_path
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.
-cdx disk_path
Change the current working directory in the local filesystem. To
be prepended to disk_paths which do not begin with '/'.
-pwd
Tell the current working directory in the ISO image.
-pwdx
Tell the current working directory in the local filesystem.
-ls iso_rr_pattern [***]
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.
-lsd iso_rr_pattern [***]
Like -ls but listing directories as themselves and not by their
content. This resembles shell command ls -d.
-lsl iso_rr_pattern [***]
Like -ls but also list some of the file attributes. The output
format resembles shell command ls -ln.
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", resp. 'H' for "on" gets appended. Together with
ACL it is 'i', 'j', resp. 'h'.
-lsdl iso_rr_pattern [***]
Like -lsd but also list some of the file attributes. The output
format resembles shell command ls -dln.
-lsx disk_pattern [***]
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.
-lsdx disk_pattern [***]
Like -lsx but listing directories as themselves and not by their
content. This resembles shell command ls -d.
-lslx disk_pattern [***]
Like -lsx but also listing some of the file attributes. Output
format resembles shell command ls -ln.
-lsdlx disk_pattern [***]
Like -lsdx but also listing some of the file attributes. Output
format resembles shell command ls -dln.
-getfacl iso_rr_pattern [***]
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 option
-acl was set to "on".
-getfacl_r iso_rr_pattern [***]
Like -gefacl but listing recursively the whole file trees
underneath eventual directories.
-getfattr iso_rr_pattern [***]
Print the xattr of the given files in the ISO image. If a file
has no such xattr then noting is printed for it.
-getfattr_r iso_rr_pattern [***]
Like -gefattr but listing recursively the whole file trees
underneath eventual directories.
-du iso_rr_pattern [***]
Recursively list size of directories and files in the ISO image
which match one of the patterns. similar to shell command du -k.
-dus iso_rr_pattern [***]
List size of directories and files in the ISO image which match
one of the patterns. Similar to shell command du -sk.
-dux disk_pattern [***]
Recursively list size of directories and files in the local
filesystem which match one of the patterns. Similar to shell
command du -k.
-dusx disk_pattern [***]
List size of directories and files in the local filesystem which
match one of the patterns. Similar to shell command du -sk.
-findx disk_path [-name pattern] [-type t] [-exec action [params]] --
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 arguments 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".
in_iso
reports the path if its counterpart exist 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 --
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.
add_missing iso_rr_path_start
adds the counterpart if it does not yet exist in the ISO
image.
E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd --
is_full_in_iso
reports if the counterpart in the ISO image contains files.
To be used with -type "m" to report mount points.
empty_iso_dir
deletes all files from the counterpart in the ISO image. To
be used with -type "m" to truncate mount points.
-compare disk_path iso_rr_path
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.
-compare_r disk_path iso_rr_path
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.
-compare_l disk_prefix iso_rr_prefix disk_path [***]
Perform -compare_r with each of the disk_path arguments.
iso_rr_path will be composed from disk_path by replacing
disk_prefix by iso_rr_prefix.
-show_stream iso_rr_path [***]
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 consists of one or more texts
eventually in "-quotation marks, eventually separated by ":"
characters. The first text describes the stream type, the
following ones 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'
-show_stream_r iso_rr_path [***]
Like -show_stream but working recursively.
File: xorriso.info, Node: Verify, Next: Restore, Prev: Navigate, Up: Options
9.16 Evaluation of readability and recovery
===========================================
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.
xorriso can scan the media 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 media.
By option -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.
-check_media [option [option ...]] --
Try to read data blocks from the indev drive, eventually copy them
to a disk file, and finally report about the encountered quality.
Several options may be used to modify the default behavior.
The options given with this command override the default settings
which may have been changed by option -check_media_defaults. See
there for a description of 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 eventually
checks them against the checksums computed from the data stream.
-check_media_defaults [option [option ...]] --
Preset options for runs of -check_media, -extract_cut and
best_effort file extraction. Eventual 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
Option "reset=now" restores these startup defaults.
Non-default options are:
report="files"
lists the files which use damaged blocks (not with
use=outdev). The format is like with find -exec
report_damage.
report="blocks_files"
first lists damaged blocks and then affected files.
use="outdev"
reads from the output drive instead of the input drive. This
avoids loading the ISO image tree from media.
use="sector_map"
does not read any media but loads the file given by option
sector_map= and processes this virtual outcome.
what="disc"
scans the payload range of a media without respecting track
gaps.
min_lba=limit
omits all blocks with addresses lower than limit.
max_lba=limit
switches to what=disc and omits all blocks above limit.
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.
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
xorriso.
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_limit=number
gives the number of report list items after which to abort.
Value -1 means unlimited item number.
data_to=disk_path
copies the valid blocks to the given file.
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.
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 media,
eventually 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.
map_with_volid="on"
examines tracks whether they are ISO images and eventually
prints their volume ids into the human readable TOC of
sector_map=.
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 default session of the image file when it gets mounted or
loaded as stdio: drive. But it usually makes the original
session 1 inaccessible.
patch_lba0="force"
performs patch_lba0="on" even if 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.
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".
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.
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.
-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 options -abort_on or
-return_with which both can cause non-zero exit values of the
program run. Severity ALL suppresses that event.
This option 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.
-check_md5_r severity iso_rr_path [***]
Like -check_md5 but checking all data files underneath the given
paths. Only mismatching data files will be reported.
File: xorriso.info, Node: Restore, Next: Emulation, Prev: Verify, Up: Options
9.17 osirrox ISO-to-disk restore options
========================================
Normally 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.
-osirrox "on"|"device_files"|"off"|"banned"|[:option:...]
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".
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 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].
-extract iso_rr_path disk_path
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.
-extract_single iso_rr_path disk_path
Like -extract, but if iso_rr_path is a directory then its sub tree
gets not restored.
-extract_l iso_rr_prefix disk_prefix iso_rr_path [***]
Perform -extract with each of the iso_rr_path arguments. disk_path
will be composed from iso_rr_path by replacing iso_rr_prefix by
disk_prefix.
-extract_cut iso_rr_path byte_offset byte_count disk_path
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.
-cpx iso_rr_path [***] disk_path
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.
-cpax iso_rr_path [***] disk_path
Like -cpx but restoring mtime, atime as in ISO image and trying to
set ownership and group as in ISO image.
-cp_rx iso_rr_path [***] disk_path
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.
-cp_rax iso_rr_path [***] disk_path
Like -cp_rx but restoring mtime, atime as in ISO image and trying
to set ownership and group as in ISO image.
-paste_in iso_rr_path disk_path byte_offset byte_count
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 option -cut_out.
-mount drive entity id path
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.
File: xorriso.info, Node: Emulation, Next: Scripting, Prev: Restore, Up: Options
9.18 Command compatibility emulations (cdrtools)
================================================
Writing of ISO 9660 on CD is traditionally done by program mkisofs as
ISO 9660 image producer and cdrecord as burn program. 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.
-as personality option [options] --
Perform the variable length option list as sparse emulation of the
program depicted by the personality word.
Personality "*mkisofs*" accepts the options listed with:
-as mkisofs -help --
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.
-graft-points is equivalent to -pathspecs on. Note that pathspecs
without "=" are interpreted differently than with xorriso option
-add. Directories get merged with the root directory of the ISO
image, other filetypes get mapped into that root directory.
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,
eventually chosen with -o, persists until things happen like
-commit, -rollback, -dev, or end of xorriso. -pacifier gets set
to "mkisofs" if files are added to the image.
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 xorriso
options 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.
Not original mkisofs options are --quoted_path_list , --hardlinks
, --acl , --xattr , --md5 , --stdio_sync . They work like the
xorriso options with the same name and hardcoded argument "on",
e.g. -acl "on". Explicit arguments are expected by --stdio_sync
and --scdbackup_tag. --no-emul-toc is -compliance no_emul_toc.
--sort-weight gets as arguments 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 --protective-msdos-label (see
-boot_image grub partition_table=on) and
--modification-date=YYYYMMDDhhmmsscc (see -volume_date uuid). For
EFI bootable GRUB boot images use -efi-boot. It performs
-boot_image grub efi_path= surrounded by two -boot_image any 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.
-boot-catalog-hide is -boot_image any cat_hidden=on.
Personalites "*xorrisofs*", "*genisoimage*", and "*genisofs*" are
aliases for "mkisofs".
If xorriso is started with one of the leafnames "xorrisofs",
"genisofs", "mkisofs", or "genisoimage", then it performs
-read_mkisofsrc and prepends -as "genisofs" to the command line
arguments. I.e. all arguments will be interpreted mkisofs style
until "--" is encountered. From then on, options are interpreted
as xorriso options.
Personality "*cdrecord*" accepts the options listed with:
-as cdrecord -help --
Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip,
padsize=, tsize=, -isosize, -multi, -msinfo,
--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 xorriso.
The scope is only a single data track per session to be written to
blank, overwriteable, or appendable media. The media gets closed if
closing is applicable and not option -multi is present.
An eventually acquired input drive is given up. This is only
allowed if no image changes are pending.
dev= must be given as 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.
--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
--grow_overwriteable_iso write_start_address=32s with -as cdrecord.
A much more elaborate libburn based cdrecord emulator is the
program cdrskin.
Personalites "*xorrecord*", "*wodim*", and "*cdrskin*" are aliases
for "cdrecord".
If xorriso is started with one of the leafnames "xorrecord",
"cdrskin", "cdrecord", or "wodim", then it automatically prepends
-as "cdrskin" to the command line arguments. I.e. all arguments
will be interpreted cdrecord style until "--" is encountered and
an eventual commit happens. From then on, options are interpreted
as xorriso options.
-read_mkisofsrc
Try one by one to open for reading: ./.mkisofsrc , $MKISOFSRC ,
$HOME/.mkisofsrc , $(basename $0)/.mkisofs
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 basename.
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.
-pacifier behavior_code
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
-scdbackup_tag list_path record_name
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 media, 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.
File: xorriso.info, Node: Scripting, Next: Frontend, Prev: Emulation, Up: Options
9.19 Scripting, dialog and program control features
===================================================
-no_rc
Only if used as first command line argument this option prevents
reading and interpretation of eventual startup files. See section
FILES below.
-options_from_file fileaddress
Read quoted input from fileaddress and executes it like dialog
lines.
-help
Print helptext.
-version
Print program name and version, component versions, license.
-history textline
Copy textline into libreadline history.
-status mode|filter
Print the current settings of 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.
-status_history_max number
Set maximum number of history lines to be reported with -status
"long_history".
-list_delimiter word
Set the list delimiter to be used instead of "--". 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 "--" throughout this
text.
-backslash_codes "on"|"off"|mode[:mode]
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 ASCII characters octal 001 to
037 , 177 to 377 and to backslash(134). Outside quotation marks
some harmless 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".
-temp_mem_limit number["k"|"m"]
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.
-print text
Print a text to result channel.
-prompt text
Show text at beginning of output line and wait for the user to hit
the Enter key resp. to send a line via stdin.
-errfile_log mode path|channel
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 file arguments 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".
-session_log path
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.
-scsi_log "on"|"off"
Mode "on" enables very verbous logging of SCSI commands and drive
replies. Logging messages get printed to stderr, not to any of
the xorriso output channels.
A special property of this option is that the first -scsi_log
setting among the start arguments is in effect already when the
first operations of xorriso begin. Only "-scsi_log" with dash "-"
is recognized that way.
-end
End program after writing eventually pending changes.
-rollback_end
Discard pending changes. End program immediately.
# any text
Only in dialog or file execution mode, and only as first
non-whitespace in line: Do not execute the line but eventually
store it in history.
File: xorriso.info, Node: Frontend, Next: ExDevices, Prev: Scripting, Up: Options
9.20 Support for frontend programs via stdin and stdout
=======================================================
-pkt_output "on"|"off"
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 follows the payload text.
Example:
I:1: enter option and arguments :
-logfile channel fileaddress
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.
-mark text
If text is not empty it will get put out on "M" channel each time
after a dialog line has been processed.
-prog text
Use text as name of this program in subsequent messages
-prog_help text
Use text as name of this program and perform -help.
File: xorriso.info, Node: Examples, Next: Files, Prev: Options, Up: Top
10 Examples
***********
* Menu:
* ExDevices:: As superuser learn about available drives
* ExCreate:: Blank media 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 media
* ExModifying:: Copy modified ISO image from one media to another
* ExBootable:: Bring a prepared ISOLINUX tree onto media 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 media
* ExMkisofs:: Perform multi-session runs as of cdrtools traditions
* ExGrowisofs:: Let 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 media
File: xorriso.info, Node: ExDevices, Next: ExCreate, Prev: Frontend, Up: Examples
10.1 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 xorriso. On Solaris
use pfexec. Consider to restrict privileges of xorriso to
"base,sys_devices" and to give r-permission to user or group.
$ xorriso -devices
0 -dev '/dev/sr0' rwrw-- : '_NEC ' 'DVD_RW ND-4570A'
1 -dev '/dev/sr1' rwrw-- : 'HL-DT-ST' 'DVDRAM GSA-4082B'
2 -dev '/dev/sr2' rwrw-- : 'PHILIPS ' 'SPD3300L'
File: xorriso.info, Node: ExCreate, Next: ExDialog, Prev: ExDevices, Up: Examples
10.2 Blank media and compose a new ISO image as batch run
=========================================================
Aquire drive /dev/sr2, make media 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 media.
$ xorriso -outdev /dev/sr2 \
-blank as_needed \
-map /home/me/sounds /sounds \
-map /home/me/pictures /pictures
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.
$ 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 \
-- \
-cd / \
-add pictures/confidential/work* --
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. Options -add and -map have different argument rules
but finally the same effect: they put files into the image.
File: xorriso.info, Node: ExDialog, Next: ExGrowing, Prev: ExCreate, Up: Examples
10.3 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 option -dev rather than -outdev in order to see
the message about its current content. By option -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 media, the session needs to be
committed explicitly.
$ xorriso -dialog on -page 20 80 -disk_pattern on
enter option and arguments :
-dev /dev/sr2
enter option and arguments :
-blank as_needed
enter option and arguments :
-map /home/me/sounds /sounds -map /home/me/pictures /pictures
enter option and arguments :
-rm_r /sounds/indecent /pictures/*private* /pictures/confidential
enter option and arguments :
-cdx /home/me/pictures -cd /pictures
enter option and arguments :
-add confidential/office confidential/factory
enter option and arguments :
-du /
enter option and arguments :
-commit_eject all -end
File: xorriso.info, Node: ExGrowing, Next: ExModifying, Prev: ExDialog, Up: Examples
10.4 Manipulate an existing ISO image on the same media
=======================================================
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 media, check whether the tree can be loaded, and eject.
$ xorriso -dev /dev/sr2 \
-rm_r /sounds -- \
-mv \
/pictures/confidential \
/pictures/restricted \
-- \
-chmod go-rwx /pictures/restricted -- \
-map /home/me/prepared_for_dvd/sounds_dummy /sounds \
-map /home/me/prepared_for_dvd/movies /movies \
-commit -eject all
File: xorriso.info, Node: ExModifying, Next: ExBootable, Prev: ExGrowing, Up: Examples
10.5 Copy modified ISO image from one media to another
======================================================
Load image from input drive. Do the same manipulations as in the
previous example. Aquire output drive and blank it. Burn the modified
image as first and only session to the output drive.
$ xorriso -indev /dev/sr2 \
-rm_r /sounds -- \
...
-outdev /dev/sr0 -blank as_needed \
-commit -eject all
File: xorriso.info, Node: ExBootable, Next: ExCharset, Prev: ExModifying, Up: Examples
10.6 Bring a prepared ISOLINUX tree onto media 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
xorriso can burn an El Torito bootable media:
$ xorriso -outdev /dev/sr0 -blank as_needed \
-map /home/me/ISOLINUX_prepared_tree / \
-boot_image isolinux dir=/boot/isolinux
File: xorriso.info, Node: ExCharset, Next: ExPseudo, Prev: ExBootable, Up: Examples
10.7 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 eventual messages which will be made
terminal-safe by option -backslash_codes.
$ xorriso -in_charset ISO-8859-1 -local_charset UTF-8 \
-out_charset UTF-8 -backslash_codes on -dev /dev/sr0 \
-alter_date m +0 / -- -commit -eject all
File: xorriso.info, Node: ExPseudo, Next: ExCdrecord, Prev: ExCharset, Up: Examples
10.8 Operate on storage facilities other than optical drives
============================================================
Full read-write operation is possible with regular files and block
devices:
$ xorriso -dev /tmp/regular_file ...
Paths underneath /dev normally need prefix "stdio:"
$ xorriso -dev stdio:/dev/sdb ...
If /dev/sdb is to be used frequently and /dev/sda is the system disk,
then consider to place the following lines in a xorriso Startup File.
They allow to use /dev/sdb without prefix and protect disk /dev/sda
from xorriso:
-drive_class banned /dev/sda*
-drive_class harmless /dev/sdb
Other writeable file types are supported write-only:
$ xorriso -outdev /tmp/named_pipe ...
Among the write-only drives is standard output:
$ xorriso -outdev - \
...
| gzip >image.iso.gz
File: xorriso.info, Node: ExCdrecord, Next: ExMkisofs, Prev: ExPseudo, Up: Examples
10.9 Burn an existing ISO image file to media
=============================================
Actually this works with any kind of data, not only ISO images:
$ xorriso -as cdrecord -v dev=/dev/sr0 blank=as_needed image.iso
File: xorriso.info, Node: ExMkisofs, Next: ExGrowisofs, Prev: ExCdrecord, Up: Examples
10.10 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:
$ xorriso -as mkisofs prepared_for_iso/tree1 | \
xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -multi -eject -
Follow-up sessions are written like this:
$ 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 -
Always eject the drive tray between sessions. The old sessions get read
via stdio:/dev/sr0 and thus are prone to device driver peculiarities.
This example works for multi-session media only. Add cdrskin option
--grow_overwriteable_iso to all -as cdrecord runs in order to enable
multi-session emulation on overwriteable media.
File: xorriso.info, Node: ExGrowisofs, Next: ExException, Prev: ExMkisofs, Up: Examples
10.11 Let xorriso work underneath growisofs
===========================================
growisofs expects an ISO formatter program which understands options -C
and -M. If xorriso gets started by name "xorrisofs" then it is suitable
for that.
$ export MKISOFS="xorrisofs"
$ growisofs -Z /dev/dvd /some/files
$ growisofs -M /dev/dvd /more/files
If no "xorrisofs" is available on your system, then you will have to
create a link pointing to the xorriso binary and tell growisofs to use
it. E.g. by:
$ ln -s $(which xorriso) "$HOME/xorrisofs"
$ export MKISOFS="$HOME/xorrisofs"
One may quit mkisofs emulation by argument "--" and make use of all
xorriso commands. growisofs dislikes options which start with "-o" but
-outdev must be set to "-". So use "outdev" instead:
$ growisofs -Z /dev/dvd -- outdev - -update_r /my/files /files
$ growisofs -M /dev/dvd -- outdev - -update_r /my/files /files
growisofs has excellent burn capabilities with DVD and BD. It does not
emulate session history on overwriteable media, though.
File: xorriso.info, Node: ExException, Next: ExTime, Prev: ExGrowisofs, Up: Examples
10.12 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.
$ xorriso ... \
-report_about UPDATE \
-return_with FAILURE 32 \
-abort_on NEVER \
...
File: xorriso.info, Node: ExTime, Next: ExIncBackup, Prev: ExException, Up: Examples
10.13 Examples of input timestrings
===================================
As printed by program date:
'Thu Nov 8 14:51:13 CET 2007'
The same without ignored parts:
'Nov 8 14:51:13 2007'
The same as expected by date:
110814512007.13
Four weeks in the future:
+4w
The current time:
+0
Three hours ago:
-3h
Seconds since Jan 1 1970:
=1194531416
File: xorriso.info, Node: ExIncBackup, Next: ExRestore, Prev: ExTime, Up: Examples
10.14 Incremental backup of a few directory trees
=================================================
This changes the directory trees /open_source_project 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.
$ xorriso \
-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/open_source_projects /open_source_projects \
-update_r /home/thomas/personal_mail /personal_mail \
-commit -toc -check_md5 FAILURE -- -eject all
To be used several times on the same media, whenever an update of the
two disk trees to the media is desired. Begin with blank media and start
a new blank media when the run fails 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 options
immediately before -commit :
-hardlinks perform_update \
-find / -type f -pending_data -exec set_filter --zisofs -- \
Options -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 *mount* option *-o "sbsector="* on GNU/Linux resp. *-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 xorriso can
tell the sbsectors of their sessions by xorriso option -toc. Used
after -commit the following option prints the matching mount command for
the newly written session (here for mount point /mnt):
-mount_cmd "indev" "auto" "auto" /mnt
Options -mount_cmd and -mount are also able to produce the mount
commands for older sessions in the table-of-content. E.g. as superuser:
# osirrox -mount /dev/sr0 "volid" '*2008_12_05*' /mnt
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 media does not suffice for the next gap, the drive is supposed
to close the media automatically.
*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 media. Always have a blank media ready to
perform a full backup in case the update attempt fails due to
insufficient remaining capacity.
File: xorriso.info, Node: ExRestore, Next: ExRecovery, Prev: ExIncBackup, Up: Examples
10.15 Restore directory trees from a particular ISO session to disk
===================================================================
This is an alternative to mounting the media and using normal file
operations.
First check which backup sessions are on the media:
$ xorriso -outdev /dev/sr0 -toc
Then load the desired session and copy the file trees to disk. Enable
restoring of ACL, xattr and hard links. Avoid to eventually create
/home/thomas/restored without rwx-permission.
$ xorriso -for_backup \
-load volid 'PROJECTS_MAIL_2008_06_19*' \
-indev /dev/sr0 \
-osirrox on:auto_chmod_on \
-chmod u+rwx / -- \
-extract /open_source_projects \
/home/thomas/restored/open_source_projects \
-extract /personal_mail /home/thomas/restored/personal_mail \
-rollback_end
The final command -rollback_end prevents an error message about the
altered image being discarded.
File: xorriso.info, Node: ExRecovery, Prev: ExRestore, Up: Examples
10.16 Try to retrieve blocks from a damaged media
=================================================
$ 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 --
This can be repeated several times, eventually 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.
File: xorriso.info, Node: Files, Next: Seealso, Prev: Examples, Up: Top
11 Files
********
11.1 Program Alias Names
========================
Normal installation of xorriso creates three links or copies which by
their program name pre-select certain settings:
*xorrisofs* starts xorriso with -as mkisofs emulation.
*xorrecord* starts xorriso with -as cdrecord emulation.
*osirrox* starts with -osirrox "on:o_excl_off" which allows to copy
files from ISO image to disk and to apply option -mount to one or more
of the existing ISO sessions.
11.2 Startup Files
==================
If not -no_rc is given as the first argument then xorriso attempts on
startup to read and execute lines from the following files:
/etc/default/xorriso
/etc/opt/xorriso/rc
/etc/xorriso/xorriso.conf
$HOME/.xorrisorc
The files are read in the sequence given above, but none of them is
required to exist.
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.
11.3 Runtime control files
==========================
The default setting of -check_media abort_file= is:
/var/opt/xorriso/do_abort_check_media
File: xorriso.info, Node: Seealso, Next: Legal, Prev: Files, Up: Top
12 See also
***********
For mounting xorriso generated ISO 9660 images (-t iso9660)
mount(8)
Libreadline, a comfortable input line facility
readline(3)
Other programs which produce ISO 9660 images
mkisofs(8), genisoimage(8)
Other programs which burn sessions to optical media
growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
ACL and xattr
getfacl(1), setfacl(1), getfattr(1), setfattr(1)
MD5 checksums
md5sum(1)
File: xorriso.info, Node: Legal, Next: CommandIdx, Prev: Seealso, Up: Top
13 Author, Copyright, Credits
*****************************
13.1 Author
===========
Thomas Schmitt <scdbackup@gmx.net>
for libburnia-project.org
13.2 Copyright
==============
Copyright (c) 2007 - 2010 Thomas Schmitt
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of xorriso. If you make
use of the license to derive modified versions of xorriso then you are
entitled to modify this text under that same license.
13.3 Credits
============
xorriso is in part based on work by Vreixo Formoso who provides libisofs
together with Mario Danic who also leads the libburnia team. 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.
File: xorriso.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
14 Alphabetic Command List
**************************
[index ]
* Menu:
* # starts a comment line: Scripting. (line 128)
* -abort_on controls abort on error: Exception. (line 27)
* -abstract_file sets abstract file name: SetWrite. (line 128)
* -acl controls handling of ACLs: Loading. (line 123)
* -add inserts one or more paths: Insert. (line 42)
* -add_plainly inserts one or more paths: Insert. (line 61)
* -alter_date sets timestamps in ISO image: Manip. (line 146)
* -alter_date_r sets timestamps in ISO image: Manip. (line 166)
* -application_id sets application id: SetWrite. (line 90)
* -as emulates mkisofs or cdrecord: Emulation. (line 13)
* -assert_volid rejects undesired images: Loading. (line 65)
* -auto_charset learns character set from image: Loading. (line 80)
* -backslash_codes enables backslash conversion: Scripting. (line 45)
* -ban_stdio_write demands real drive: Loading. (line 220)
* -biblio_file sets biblio file name: SetWrite. (line 135)
* -blank erases media: Writing. (line 45)
* -boot_image controls bootability: Bootable. (line 20)
* -calm_drive reduces drive activity: Loading. (line 209)
* -cd sets working directory in ISO: Navigate. (line 7)
* -cdx sets working directory on disk: Navigate. (line 16)
* -charset sets input/output character set: Charset. (line 43)
* -check_md5 verifies file checksum: Verify. (line 144)
* -check_md5_r verifies file tree checksums: Verify. (line 160)
* -check_media reads media block by block: Verify. (line 21)
* -check_media_defaults sets -check_media options: Verify. (line 40)
* -chgrp sets group in ISO image: Manip. (line 50)
* -chgrp_r sets group in ISO image: Manip. (line 55)
* -chmod sets permissions in ISO image: Manip. (line 58)
* -chmod_r sets permissions in ISO image: Manip. (line 70)
* -chown sets ownership in ISO image: Manip. (line 42)
* -chown_r sets ownership in ISO image: Manip. (line 47)
* -close controls media closing: SetWrite. (line 218)
* -close_filter_list bans filter registration: Filter. (line 52)
* -commit writes pending ISO image: Writing. (line 13)
* -commit_eject writes and ejects: Writing. (line 40)
* -compare reports ISO/disk differences: Navigate. (line 134)
* -compare_l reports ISO/disk differences: Navigate. (line 152)
* -compare_r reports ISO/disk differences: Navigate. (line 147)
* -compliance controls standard compliance: SetWrite. (line 14)
* -copyright_file sets copyright file name: SetWrite. (line 122)
* -cp_rx copies file trees to disk: Restore. (line 104)
* -cpax copies files to disk: Restore. (line 100)
* -cpr inserts like with cp -r: Insert. (line 152)
* -cpx copies files to disk: Restore. (line 88)
* -cut_out inserts piece of data file: Insert. (line 126)
* -dev aquires one drive for input and output: AqDrive. (line 10)
* -devices gets list of drives: Inquiry. (line 7)
* -dialog enables dialog mode: DialogCtl. (line 7)
* -disk_dev_ino fast incremental backup: Loading. (line 163)
* -disk_pattern controls pattern expansion: Insert. (line 31)
* -drive_class controls drive accessability: Loading. (line 35)
* -du show directory size in ISO image: Navigate. (line 88)
* -dummy controls write simulation: SetWrite. (line 207)
* -dus show directory size in ISO image: Navigate. (line 92)
* -dusx show directory size on disk: Navigate. (line 101)
* -dux show directory size on disk: Navigate. (line 96)
* -dvd_obs set write block size: SetWrite. (line 194)
* -eject ejects drive tray: Writing. (line 36)
* -end writes pending session and ends program: Scripting. (line 122)
* -errfile_log logs problematic disk files: Scripting. (line 84)
* -error_behavior controls error workarounds: Exception. (line 69)
* -external_filter registers data filter: Filter. (line 20)
* -external_filter unregisters data filter: Filter. (line 48)
* -extract copies file tree to disk: Restore. (line 56)
* -extract_cut copies file piece to disk: Restore. (line 77)
* -extract_l copies files to disk: Restore. (line 72)
* -extract_single copies file to disk: Restore. (line 68)
* -file_size_limit limits data file size: SetInsert. (line 7)
* -find traverses and alters ISO tree: CmdFind. (line 7)
* -findx traverses disk tree: Navigate. (line 105)
* -follow softlinks and mount points: SetInsert. (line 76)
* -for_backup -acl,-xattr,-hardlinks,-md5: Loading. (line 158)
* -format formats media: Writing. (line 69)
* -fs sets size of fifo: SetWrite. (line 211)
* -getfacl shows ACL in ISO image: Navigate. (line 69)
* -getfacl_r shows ACL in ISO image: Navigate. (line 76)
* -getfattr shows xattr in ISO image: Navigate. (line 80)
* -getfattr_r shows xattr in ISO image: Navigate. (line 84)
* -gid sets global ownership: SetWrite. (line 151)
* -grow_blindly overides next writeable address: AqDrive. (line 44)
* -hardlinks controls handling of hard links: Loading. (line 91)
* -help prints help text: Scripting. (line 16)
* -hide excludes file names from directory trees: Manip. (line 170)
* -history brings text into readline history: Scripting. (line 22)
* -in_charset sets input character set: Loading. (line 73)
* -indev aquires a drive for input: AqDrive. (line 22)
* -iso_rr_pattern controls pattern expansion: Manip. (line 10)
* -joliet enables production of Joliet tree: SetWrite. (line 10)
* -list_delimiter replaces '--': Scripting. (line 38)
* -list_formats lists available formats: Writing. (line 107)
* -list_profiles lists supported media: Writing. (line 119)
* -load addresses a particular session as input: Loading. (line 11)
* -local_charset sets terminal character set: Charset. (line 47)
* -logfile logs output channels to file: Frontend. (line 20)
* -ls lists files in ISO image: Navigate. (line 26)
* -lsd lists files in ISO image: Navigate. (line 34)
* -lsdl lists files in ISO image: Navigate. (line 46)
* -lsdlx lists files on disk: Navigate. (line 65)
* -lsdx lists files on disk: Navigate. (line 57)
* -lsl lists files in ISO image: Navigate. (line 38)
* -lslx lists files on disk: Navigate. (line 61)
* -lsx lists files on disk: Navigate. (line 50)
* -map inserts path: Insert. (line 85)
* -map_l inserts paths from disk file: Insert. (line 94)
* -map_single inserts path: Insert. (line 90)
* -mark sets synchronizing message: Frontend. (line 25)
* -md5 controls handling of MD5 sums: Loading. (line 136)
* -mkdir creates ISO directory: Insert. (line 166)
* -mount issues mount command for ISO session: Restore. (line 122)
* -mount_cmd composes mount command line: Inquiry. (line 31)
* -mount_cmd controls mount command: Inquiry. (line 47)
* -mv renames file in ISO image: Manip. (line 35)
* -no_rc disables startup files: Scripting. (line 7)
* -not_leaf sets exclusion pattern: SetInsert. (line 62)
* -not_list sets exclusions from disk file: SetInsert. (line 67)
* -not_mgt controls file exclusion: SetInsert. (line 23)
* -not_paths sets absolute exclusion paths: SetInsert. (line 55)
* -options_from_file reads commands from file: Scripting. (line 12)
* -osirrox enables ISO-to-disk copying: Restore. (line 18)
* -out_charset sets output character set: SetWrite. (line 141)
* -outdev aquires a drive for output: AqDrive. (line 29)
* -overwrite enables overwriting in ISO: SetInsert. (line 127)
* -pacifier controls pacifier text form: Emulation. (line 119)
* -padding sets amount of image padding: SetWrite. (line 224)
* -page set terminal geometry: DialogCtl. (line 15)
* -paste_in copies file into disk file: Restore. (line 117)
* -path_list inserts paths from disk file: Insert. (line 75)
* -pathspecs sets meaning of = with -add: SetInsert. (line 118)
* -pkt_output consolidates text output: Frontend. (line 7)
* -print prints text line: Scripting. (line 77)
* -print_size predicts image size: Inquiry. (line 69)
* -prog sets program name: Frontend. (line 29)
* -prog_help prints help text: Frontend. (line 32)
* -prompt prompts for enter key: Scripting. (line 80)
* -publisher sets publisher id: SetWrite. (line 84)
* -pvd_info shows image id strings: Inquiry. (line 78)
* -pwd tells working directory in ISO: Navigate. (line 20)
* -pwdx tells working directory on disk: Navigate. (line 23)
* -quoted_not_list sets exclusions: SetInsert. (line 72)
* -quoted_path_list inserts paths from disk file: Insert. (line 80)
* -read_mkisofsrc searches and reads .mkisofsrc file: Emulation.
(line 107)
* -reassure enables confirmation question: DialogCtl. (line 28)
* -report_about controls verbosity: Exception. (line 55)
* -return_with controls exit value: Exception. (line 39)
* -rm deletes files from ISO image: Manip. (line 21)
* -rm_r deletes trees from ISO image: Manip. (line 28)
* -rmdir deletes ISO directory: Manip. (line 32)
* -rollback discards pending changes: Writing. (line 9)
* -rollback_end ends program without writing: Scripting. (line 125)
* -rom_toc_scan searches for sessions: Loading. (line 184)
* -scdbackup_tag enables scdbackup checksum tag: Emulation. (line 129)
* -scsi_log reports SCSI commands: Scripting. (line 113)
* -session_log logs written sessions: Scripting. (line 104)
* -session_string composes session info line: Inquiry. (line 56)
* -set_filter applies filter to file: Filter. (line 59)
* -set_filter_r applies filter to file tree: Filter. (line 84)
* -setfacl sets ACL in ISO image: Manip. (line 73)
* -setfacl_list sets ACL in ISO image: Manip. (line 100)
* -setfacl_r sets ACL in ISO image: Manip. (line 97)
* -setfattr sets xattr in ISO image: Manip. (line 110)
* -setfattr_list sets xattr in ISO image: Manip. (line 126)
* -setfattr_r sets xattr in ISO image: Manip. (line 123)
* -show_stream shows data source and filters: Navigate. (line 157)
* -show_stream_r shows data source and filters: Navigate. (line 172)
* -speed set write speed: SetWrite. (line 167)
* -split_size enables large file splitting: SetInsert. (line 140)
* -status shows current settings: Scripting. (line 25)
* -status_history_max curbs -status history: Scripting. (line 34)
* -stdio_sync controls stdio buffer: SetWrite. (line 201)
* -stream_recording controls defect management: SetWrite. (line 182)
* -system_id sets system id: SetWrite. (line 96)
* -tell_media_space reports free space: Inquiry. (line 74)
* -temp_mem_limit curbs memory consumption: Scripting. (line 70)
* -toc shows list of sessions: Inquiry. (line 18)
* -uid sets global ownership: SetWrite. (line 147)
* -update inserts path if different: Insert. (line 99)
* -update_l inserts paths if different: Insert. (line 121)
* -update_r inserts paths if different: Insert. (line 110)
* -use_readline enables readline for dialog: DialogCtl. (line 24)
* -version prints help text: Scripting. (line 19)
* -volid sets volume id: SetWrite. (line 60)
* -volset_id sets volume set id: SetWrite. (line 79)
* -volume_date sets volume timestamp: SetWrite. (line 103)
* -xattr controls handling of xattr (EA): Loading. (line 131)
* -zisofs controls zisofs production: SetWrite. (line 155)
File: xorriso.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top
15 Alphabetic List of Concepts and Objects
******************************************
[index ]
* Menu:
* ACL, _definiton: Extras. (line 37)
* ACL, control handling, -acl: Loading. (line 123)
* ACL, set in ISO image, -setfacl: Manip. (line 73)
* ACL, set in ISO image, -setfacl_list: Manip. (line 100)
* ACL, set in ISO image, -setfacl_r: Manip. (line 97)
* ACL, show in ISO image, -getfacl: Navigate. (line 69)
* ACL, show in ISO image, -getfacl_r: Navigate. (line 76)
* Appendable media, _definition: Media. (line 34)
* Backslash Interpretation, _definition: Processing. (line 49)
* Backup, enable fast incremental, -disk_dev_ino: Loading. (line 163)
* Backup, enable features, -for_backup: Loading. (line 158)
* Backup, scdbackup checksum tag, -scdbackup: Emulation. (line 129)
* Blank media, _definition: Media. (line 25)
* Blind growing, _definition: Methods. (line 40)
* Bootability, control, -boot_image: Bootable. (line 20)
* cdrecord, Emulation: Emulation. (line 74)
* Character Set, _definition: Charset. (line 6)
* Character Set, for input, -in_charset: Loading. (line 73)
* Character Set, for input/output, -charset: Charset. (line 43)
* Character Set, for output, -out_charset: SetWrite. (line 141)
* Character set, learn from image, -auto_charset: Loading. (line 80)
* Character Set, of terminal, -local_charset: Charset. (line 47)
* Closed media, _definition: Media. (line 39)
* Comment, #: Scripting. (line 128)
* Create, new ISO image, _definiton: Methods. (line 6)
* Delete, from ISO image, -rm: Manip. (line 21)
* Delete, from ISO image, -rm_r: Manip. (line 28)
* Delete, ISO directory, -rmdir: Manip. (line 32)
* Dialog, bring text into history, -history: Scripting. (line 22)
* Dialog, confirmation question, -reassure: DialogCtl. (line 28)
* Dialog, enable dialog mode, -dialog: DialogCtl. (line 7)
* Dialog, line editing, -use_readline: DialogCtl. (line 24)
* Dialog, terminal geometry, -page: DialogCtl. (line 15)
* Directory, create, -mkdir: Insert. (line 166)
* Directory, delete, -rmdir: Manip. (line 32)
* disk_path, _definition: Insert. (line 6)
* Drive, _definiton: Drives. (line 6)
* Drive, accessability, -drive_class: Loading. (line 35)
* Drive, demand real MMC, -ban_stdio_write: Loading. (line 220)
* Drive, eject tray, -eject: Writing. (line 36)
* Drive, for input and output, -dev: AqDrive. (line 10)
* Drive, for input, -indev: AqDrive. (line 22)
* Drive, for output, -outdev: AqDrive. (line 29)
* Drive, get drive list, -devices: Inquiry. (line 7)
* Drive, list supported media, -list_profiles: Writing. (line 119)
* Drive, reduce activity, -calm_drive: Loading. (line 209)
* Drive, report SCSI commands, -scsi_log: Scripting. (line 113)
* Drive, write and eject, -commit_eject: Writing. (line 40)
* El Torito, _definiton: Extras. (line 19)
* Emulation, -as: Emulation. (line 13)
* Emulation, .mkisofsrc, -read_mkisofsrc: Emulation. (line 107)
* Emulation, cdrecord, -as: Emulation. (line 74)
* Emulation, mkisofs, -as: Emulation. (line 16)
* Emulation, pacifier form, -pacifier: Emulation. (line 119)
* Examples: Examples. (line 6)
* Filter, _definition: Filter. (line 6)
* Filter, apply to file tree, -set_filter_r: Filter. (line 84)
* Filter, apply to file, -set_filter: Filter. (line 59)
* Filter, ban registration, -close_filter_list: Filter. (line 52)
* Filter, register, -external_filter: Filter. (line 20)
* Filter, show chain, -show_stream: Navigate. (line 157)
* Filter, show chains of tree, -show_stream_r: Navigate. (line 172)
* Filter, unregister, -unregister_filter: Filter. (line 48)
* Filter, zisofs parameters, -zisofs: SetWrite. (line 155)
* Group, global in ISO image, -gid: SetWrite. (line 151)
* Group, in ISO image, -chgrp: Manip. (line 50)
* Group, in ISO image, -chgrp_r: Manip. (line 55)
* Growing, _definition: Methods. (line 19)
* Hard links, control handling, -hardlinks: Loading. (line 91)
* hidden, set in ISO image, -hide: Manip. (line 170)
* Image, _definition: Model. (line 9)
* Image, demand volume id, -assert_volid: Loading. (line 65)
* Image, discard pending changes, -rollback: Writing. (line 9)
* Image, set abstract file name, -abstract_file: SetWrite. (line 128)
* Image, set application id, -application_id: SetWrite. (line 90)
* Image, set biblio file name, -biblio_file: SetWrite. (line 135)
* Image, set copyright file name, -copyright_file: SetWrite. (line 122)
* Image, set publisher id, -publisher: SetWrite. (line 84)
* Image, set system id, -system_id: SetWrite. (line 96)
* Image, set volume id, -volid: SetWrite. (line 60)
* Image, set volume set id, -volset_id: SetWrite. (line 79)
* Image, set volume timestamp, -volume_date: SetWrite. (line 103)
* Image, show id strings, -pvd_info: Inquiry. (line 78)
* Insert, enable overwriting, -overwrite: SetInsert. (line 127)
* Insert, file exclusion absolute, -not_paths: SetInsert. (line 55)
* Insert, file exclusion from file, -not_list: SetInsert. (line 67)
* Insert, file exclusion pattern, -not_leaf: SetInsert. (line 62)
* Insert, file exclusion, -not_mgt: SetInsert. (line 23)
* Insert, file exclusion, -quoted_not_list: SetInsert. (line 72)
* Insert, if different, -update: Insert. (line 99)
* Insert, if different, -update_l: Insert. (line 121)
* Insert, if different, -update_r: Insert. (line 110)
* Insert, large file splitting, -split_size: SetInsert. (line 140)
* Insert, limit data file size, -file_size_limit: SetInsert. (line 7)
* Insert, links or mount points, -follow: SetInsert. (line 76)
* Insert, meaning of = with -add, -pathspecs: SetInsert. (line 118)
* Insert, non-dashed arguments, -add_plainly: Insert. (line 61)
* Insert, path, -map: Insert. (line 85)
* Insert, path, -map_single: Insert. (line 90)
* Insert, paths from disk file, -map_l: Insert. (line 94)
* Insert, paths from disk file, -path_list: Insert. (line 75)
* Insert, paths from disk file, -quoted_path_list: Insert. (line 80)
* Insert, paths, -cpr: Insert. (line 152)
* Insert, pathspecs, -add: Insert. (line 42)
* Insert, piece of data file, -cut_out: Insert. (line 126)
* iso_rr_path, _definition: Insert. (line 7)
* List delimiter, _definiton: Processing. (line 8)
* MBR, _definiton: Extras. (line 26)
* MBR, set, -boot_image system_area=: Bootable. (line 112)
* MD5, control handling, -md5: Loading. (line 136)
* Media, erase, -blank: Writing. (line 45)
* Media, format, -format: Writing. (line 69)
* Media, list formats, -list_formats: Writing. (line 107)
* mkisofs, Emulation: Emulation. (line 16)
* Modifying, _definition: Methods. (line 27)
* Multi-session media, _definition: Media. (line 7)
* Multi-session, _definition: Model. (line 18)
* Navigate, directory size in ISO image, -du: Navigate. (line 88)
* Navigate, directory size in ISO image, -dus: Navigate. (line 92)
* Navigate, directory size in on disk, -dusx: Navigate. (line 101)
* Navigate, directory size in on disk, -dux: Navigate. (line 96)
* Navigate, list disk files, -lsdlx: Navigate. (line 65)
* Navigate, list disk files, -lsdx: Navigate. (line 57)
* Navigate, list disk files, -lslx: Navigate. (line 61)
* Navigate, list disk files, -lsx: Navigate. (line 50)
* Navigate, list ISO files, -ls: Navigate. (line 26)
* Navigate, list ISO files, -lsd: Navigate. (line 34)
* Navigate, list ISO files, -lsdl: Navigate. (line 46)
* Navigate, list ISO files, -lsl: Navigate. (line 38)
* Navigate, set disk working directory, -cdx: Navigate. (line 16)
* Navigate, set ISO working directory, -cd: Navigate. (line 7)
* Navigate, tell disk working directory, -pwdx: Navigate. (line 23)
* Navigate, tell ISO working directory, -pwd: Navigate. (line 20)
* Next writeable address, -grow_blindly: AqDrive. (line 44)
* Overwriteable media, _definition: Media. (line 10)
* Ownership, global in ISO image, -uid: SetWrite. (line 147)
* Ownership, in ISO image, -chown: Manip. (line 42)
* Ownership, in ISO image, -chown_r: Manip. (line 47)
* Partition table, _definiton: Bootable. (line 119)
* Pathspec, _definition: SetInsert. (line 120)
* Pattern expansion, _definition: Processing. (line 22)
* Pattern expansion, for disk paths, -disk_pattern: Insert. (line 31)
* Pattern expansion, for ISO paths, -iso_rr_pattern: Manip. (line 10)
* Permissions, in ISO image, -chmod: Manip. (line 58)
* Permissions, in ISO image, -chmod_r: Manip. (line 70)
* Process, consolidate text output, -pkt_output: Frontend. (line 7)
* Process, control abort on error, -abort_on: Exception. (line 27)
* Process, control exit value, -return_with: Exception. (line 39)
* Process, control verbosity, -report_about: Exception. (line 55)
* Process, disable startup files, -no_rc: Scripting. (line 7)
* Process, end program and write, -end: Scripting. (line 122)
* Process, end program, no writing, -rollback_end: Scripting. (line 125)
* Process, error workarounds, -error_behavior: Exception. (line 69)
* Process, log output channels to file, -logfile: Frontend. (line 20)
* Process, read command file, -options_from_file: Scripting. (line 12)
* Process, set synchronizing message, -mark: Frontend. (line 25)
* Program, backslash conversion, -backslash_codes: Scripting. (line 45)
* Program, curb memory, -temp_mem_limit: Scripting. (line 70)
* Program, end and write, -end: Scripting. (line 122)
* Program, end without writing, -rollback_end: Scripting. (line 125)
* Program, print help text, -help: Scripting. (line 16)
* Program, print help text, -prog_help: Frontend. (line 32)
* Program, print text line, -print: Scripting. (line 77)
* Program, print version, -version: Scripting. (line 19)
* Program, prompt for enter key, -prompt: Scripting. (line 80)
* Program, replace --, -list_delimiter: Scripting. (line 38)
* Program, set name, -prog: Frontend. (line 29)
* Program, show current settings, -status: Scripting. (line 25)
* Program, status history, -status_history_max: Scripting. (line 34)
* Quoted input, _definiton: Processing. (line 43)
* Recovery, retrieve blocks, -check_media: Verify. (line 21)
* Rename, in ISO image, -mv: Manip. (line 35)
* Restore, copy file into disk file, -paste_in: Restore. (line 117)
* Restore, copy file piece to disk, -extract_cut: Restore. (line 77)
* Restore, copy file to disk, -extract_single: Restore. (line 68)
* Restore, copy file tree to disk, -extract: Restore. (line 56)
* Restore, copy file trees to disk, -cp_rx: Restore. (line 104)
* Restore, copy files to disk, -cpax: Restore. (line 100)
* Restore, copy files to disk, -cpx: Restore. (line 88)
* Restore, copy files to disk, -extract_l: Restore. (line 72)
* Restore, enable ISO-to-disk, -osirrox: Restore. (line 18)
* Rock Ridge, _definiton: Extras. (line 6)
* Session, _definition: Model. (line 6)
* Session, info string, -session_string: Inquiry. (line 56)
* Session, issue mount command, -mount: Restore. (line 122)
* Session, log when written, -session_log: Scripting. (line 104)
* Session, mount command line, -mount_cmd: Inquiry. (line 31)
* Session, mount parameters, -mount_opts: Inquiry. (line 47)
* Session, select as input, -load: Loading. (line 11)
* System area, _definiton: Bootable. (line 112)
* Table-of-content, search sessions, -rom_toc_scan: Loading. (line 184)
* Table-of-content, show, -toc: Inquiry. (line 18)
* Timestamps, set in ISO image, -alter_date: Manip. (line 146)
* Timestamps, set in ISO image, -alter_date_r: Manip. (line 166)
* Tree, disk, traverse, -findx: Navigate. (line 105)
* Tree, ISO, traverse and alter, -find: CmdFind. (line 7)
* Verify, check blocks, -check_media: Verify. (line 21)
* Verify, compare ISO and disk file, -compare: Navigate. (line 134)
* Verify, compare ISO and disk tree, -compare_r: Navigate. (line 147)
* Verify, compare ISO and disk, -compare_l: Navigate. (line 152)
* Verify, file checksum, -check_md5: Verify. (line 144)
* Verify, file tree checksums, -check_md5_r: Verify. (line 160)
* Verify, preset -check_media, -check_media_defaults: Verify. (line 40)
* Write, block size, -dvd_obs: SetWrite. (line 194)
* Write, bootability, -boot_image: Bootable. (line 20)
* Write, buffer syncing, -stdio_sync: SetWrite. (line 201)
* Write, close media, -close: SetWrite. (line 218)
* Write, compliance to specs, -compliance: SetWrite. (line 14)
* Write, defect management, -stream_recording: SetWrite. (line 182)
* Write, enable Joliet, -joliet: SetWrite. (line 10)
* Write, fifo size, -fs: SetWrite. (line 211)
* Write, free space, -tell_media_space: Inquiry. (line 74)
* Write, log problematic disk files, -errfile_log: Scripting. (line 84)
* Write, log written sessions, -session_log: Scripting. (line 104)
* Write, padding image, -padding: SetWrite. (line 224)
* Write, pending ISO image, -commit: Writing. (line 13)
* Write, predict image size, -print_size: Inquiry. (line 69)
* Write, set speed, -speed: SetWrite. (line 167)
* Write, simulation, -dummy: SetWrite. (line 207)
* xattr, _definiton: Extras. (line 51)
* xattr, control handling, -xattr: Loading. (line 131)
* xattr, set in ISO image, -setfattr: Manip. (line 110)
* xattr, set in ISO image, -setfattr_list: Manip. (line 126)
* xattr, set in ISO image, -setfattr_r: Manip. (line 123)
* xattr, show in ISO image, -getfattr: Navigate. (line 80)
* xattr, show in ISO image, -getfattr_r: Navigate. (line 84)
Tag Table:
Node: Top420
Node: Overview1324
Node: Model3209
Node: Media6089
Node: Methods8519
Node: Drives11066
Node: Extras14372
Node: Processing17799
Node: Dialog21295
Node: Options22952
Node: AqDrive24520
Node: Loading27426
Node: Insert39605
Node: SetInsert47962
Node: Manip56529
Node: CmdFind65210
Node: Filter75161
Node: Writing79510
Node: SetWrite85799
Node: Bootable96961
Node: Charset104913
Node: Exception107667
Node: DialogCtl112182
Node: Inquiry114527
Node: Navigate118657
Node: Verify126255
Node: Restore134675
Node: Emulation141331
Node: Scripting148929
Node: Frontend154491
Node: Examples155692
Node: ExDevices156861
Node: ExCreate157495
Node: ExDialog158769
Node: ExGrowing160031
Node: ExModifying160833
Node: ExBootable161334
Node: ExCharset161881
Node: ExPseudo162709
Node: ExCdrecord163603
Node: ExMkisofs163918
Node: ExGrowisofs164921
Node: ExException166045
Node: ExTime166499
Node: ExIncBackup166958
Node: ExRestore170430
Node: ExRecovery171399
Node: Files171965
Node: Seealso173193
Node: Legal173717
Node: CommandIdx174639
Node: ConceptIdx188372
End Tag Table