You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
4733 lines
182 KiB
4733 lines
182 KiB
\input texinfo @c -*-texinfo-*- |
|
@c %**start of header |
|
@setfilename xorriso.info |
|
@settitle GNU xorriso |
|
@c %**end of header |
|
@c |
|
@c man-ignore-lines begin |
|
@dircategory Archiving |
|
@direntry |
|
* xorriso: (xorriso). burns ISO 9660 on CD, DVD, BD |
|
@end direntry |
|
@c man-ignore-lines end |
|
@c |
|
@c Notes about embedded man page: |
|
@c This texinfo code contains the necessary info to produce a man page |
|
@c which resembles much the version of xorriso.1 from which this code |
|
@c was originally derived in march 2010. |
|
@c One can produce the man page by applying the following rules: |
|
@c The first line gets discarded. |
|
@c Line start "@c man " will become "", the remainder is put out unaltered. |
|
@c Lines "@*" will be converted to ".br" |
|
@c @c man-ignore-lines N will discard N following lines. |
|
@c "@c man-ignore-lines begin" discards all following lines |
|
@c up to "@c man-ignore-lines end". |
|
@c Line blocks of "@menu" "@end menu" will be discarded. |
|
@c "@item -word words" becomes "\fB\-word\fR words". |
|
@c "@item word words" becomes "\fBword\fR words". |
|
@c @strong{-...} gets mapped to \fB\-...\fR . |
|
@c @strong{... } gets mapped to \fB...\fR . |
|
@c @minus{} will become "-". |
|
@c @@ , @{, @} will get stripped of their first @. |
|
@c Other lines which begin by "@" will be discarded. |
|
@c In lines not stemming from "@c man", "\" becomes "\\" |
|
@c |
|
@c |
|
@c man .\" Hey, EMACS: -*- nroff -*- |
|
@c man .\" |
|
@c man .\" IMPORTANT NOTE: |
|
@c man .\" |
|
@c man .\" The original of this file is kept in xorriso/xorriso.texi |
|
@c man .\" This here was generated by program xorriso/make_xorriso_1 |
|
@c man .\" |
|
@c man .\" |
|
@c man .\" First parameter, NAME, should be all caps |
|
@c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection |
|
@c man .\" other parameters are allowed: see man(7), man(1) |
|
@c man .TH XORRISO 1 "Mar 18, 2010" |
|
@c man .\" Please adjust this date whenever revising the manpage. |
|
@c man .\" |
|
@c man .\" Some roff macros, for reference: |
|
@c man .\" .nh disable hyphenation |
|
@c man .\" .hy enable hyphenation |
|
@c man .\" .ad l left justify |
|
@c man .\" .ad b justify to both left and right margins |
|
@c man .\" .nf disable filling |
|
@c man .\" .fi enable filling |
|
@c man .\" .br insert line break |
|
@c man .\" .sp <n> insert n+1 empty lines |
|
@c man .\" for manpage-specific macros, see man(7) |
|
@c man .nh |
|
@c man-ignore-lines begin |
|
@copying |
|
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images |
|
with Rock Ridge extensions. |
|
|
|
Copyright @copyright{} 2007 - 2010 Thomas Schmitt |
|
|
|
@quotation |
|
Permission is granted to distrubute this text freely. |
|
@end quotation |
|
@end copying |
|
@c man-ignore-lines end |
|
@titlepage |
|
@title Manual of GNU xorriso |
|
@author Thomas Schmitt |
|
@page |
|
@vskip 0pt plus 1filll |
|
@insertcopying |
|
@end titlepage |
|
@contents |
|
@ifnottex |
|
@node Top |
|
@top GNU xorriso |
|
@c man-ignore-lines 1 |
|
|
|
@c man .SH NAME |
|
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images |
|
with Rock Ridge extensions. |
|
@end ifnottex |
|
@menu |
|
* Overview:: Overview |
|
* Model:: Session model |
|
* Media:: Media types and states |
|
* Methods:: Creating, Growing, Modifying, Blind Growing |
|
* Drives:: Libburn drives |
|
* Extras:: Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr |
|
* Processing:: Command processing |
|
* Dialog:: Dialog, Readline, Result pager |
|
* Options:: Reference of commands |
|
* Examples:: Examples |
|
* Files:: Files |
|
* Seealso:: See also |
|
* Legal:: Author, Copyright, Credits |
|
* CommandIdx:: Alphabetic Command List |
|
* ConceptIdx:: Alphabetic List of Concepts and Objects |
|
@end menu |
|
@node Overview, Model, Top, Top |
|
@chapter Overview |
|
@c man .SH SYNOPSIS |
|
@c man .B xorriso |
|
@c man .RI [ settings | actions ] |
|
@c man .br |
|
@c man .SH DESCRIPTION |
|
@c man .PP |
|
@strong{xorriso} |
|
is a program which copies file objects from POSIX compliant |
|
filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows |
|
session-wise manipulation of such filesystems. It can load the management |
|
information of existing ISO images and it writes the session results to |
|
optical media or to filesystem objects. |
|
@* |
|
Vice versa xorriso is able to copy file objects out of ISO 9660 filesystems. |
|
@c man .PP |
|
@sp 1 |
|
A special property of xorriso is that it needs neither an external ISO 9660 |
|
formatter program nor an external burn program for CD, DVD or BD but rather |
|
incorporates the libraries of libburnia-project.org . |
|
@c man .SS |
|
@section Features |
|
@c man .B Overview of features: |
|
@* |
|
Operates on an existing ISO image or creates a new one. |
|
@* |
|
Copies files from disk filesystem into the ISO image. |
|
@* |
|
Copies files from ISO image to disk filesystem (see osirrox). |
|
@* |
|
Renames or deletes file objects in the ISO image. |
|
@* |
|
Changes file properties in the ISO image. |
|
@* |
|
Updates ISO subtrees incrementally to match given disk subtrees. |
|
@* |
|
Writes result either as completely new image or as add-on session |
|
to optical media or filesystem objects. |
|
@* |
|
Can activate ISOLINUX boot images via El Torito. |
|
@* |
|
Can perform multi-session tasks as emulation of mkisofs and cdrecord. |
|
@* |
|
Can record and restore hard links and ACL. |
|
@* |
|
Content may get zisofs compressed or filtered by external processes. |
|
@* |
|
Can issue commands to mount older sessions on GNU/Linux or FreeBSD. |
|
@* |
|
Can check media for damages and copy readable blocks to disk. |
|
@* |
|
Can attach MD5 checksums to each data file and the whole session. |
|
@* |
|
Scans for optical drives, blanks re-useable optical media. |
|
@* |
|
Reads its instructions from command line arguments, dialog, and files. |
|
@* |
|
Provides navigation commands for interactive ISO image manipulation. |
|
@* |
|
Adjustable thresholds for abort, exit value, and problem reporting. |
|
@c man .SS |
|
@c man .B General information paragraphs: |
|
@c man .br |
|
@c man Session model |
|
@c man .br |
|
@c man Media types and states |
|
@c man .br |
|
@c man Creating, Growing, Modifying, Blind Growing |
|
@c man .br |
|
@c man Libburn drives |
|
@c man .br |
|
@c man Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr |
|
@c man .br |
|
@c man Command processing |
|
@c man .br |
|
@c man Dialog, Readline, Result pager |
|
@c man .sp 1 |
|
@c man Maybe you first want to have a look at section EXAMPLES near the end of |
|
@c man this text before reading the next few hundred lines of background information. |
|
@c man .SS |
|
@node Model, Media, Overview, Top |
|
@chapter Session model |
|
@c man \fBSession model:\fR |
|
@c man .br |
|
@cindex Session, _definition |
|
Unlike other filesystems, ISO 9660 is not intended for read-write operation but |
|
rather for being generated in a single sweep and being written to media as a |
|
@strong{session}. |
|
@* |
|
@cindex Image, _definition |
|
The data content of the session is called filesystem @strong{image}. |
|
@c man .PP |
|
@sp 1 |
|
The written image in its session can then be mounted by the operating system |
|
for being used read-only. GNU/Linux is able to mount ISO images from block |
|
devices, which may represent optical media, other media or via a loop device |
|
even from regular disk files. FreeBSD mounts ISO images from devices that |
|
represent arbitrary media or from regular disk files. |
|
@c man .PP |
|
@sp 1 |
|
@cindex Multi-session, _definition |
|
This session usage model has been extended on CD media by the concept of |
|
@strong{multi-session} , |
|
which allows to add information to the CD and gives the mount programs |
|
of the operating systems the addresses of the entry points of each |
|
session. The mount programs recognize block devices which represent |
|
CD media and will by default mount the image in the last session. |
|
@* |
|
This session usually contains an updated directory tree for the whole media |
|
which governs the data contents in all recorded sessions. |
|
So in the view of the mount program all sessions of a particular media |
|
together form a single filesystem image. |
|
@* |
|
Adding a session to an existing ISO image is in this text referred as |
|
@strong{growing}. |
|
@* |
|
The multi-session model of the MMC standard does not apply to all media |
|
types. But program growisofs by Andy Polyakov showed how to extend this |
|
functionality to overwriteable media or disk files which carry valid ISO 9660 |
|
filesystems. |
|
@c man .PP |
|
@sp 1 |
|
xorriso provides growing as well as an own method named |
|
@strong{modifying} which produces a completely new ISO image from the old |
|
one and the modifications. |
|
See paragraph Creating, Growing, Modifying, Blind Growing below. |
|
@c man .PP |
|
@sp 1 |
|
xorriso adopts the concept of multi-session by loading an eventual image |
|
directory tree, allowing to manipulate it by several actions, and to write |
|
the new image to the target media. |
|
@c man .br |
|
The first session of a xorriso run begins by the definition of the input |
|
drive with the eventual ISO image or by the definition of an output drive. |
|
The session ends by command -commit which triggers writing. A -commit is |
|
done automatically when the program ends regularly. |
|
@c man .PP |
|
@sp 1 |
|
After -commit a new session begins with the freshly written one as input. |
|
A new input drive can only be chosen as long as the loaded ISO image was |
|
not altered. Pending alteration can be revoked by command -rollback. |
|
@c man .PP |
|
@sp 1 |
|
Writing a session to the target is supposed to be very expensive in terms of |
|
time and of consumed space on appendable or write-once media. Therefore all |
|
intended manipulations of a particular ISO image should be done in a single |
|
session. But in principle it is possible |
|
to store intermediate states and to continue with image manipulations. |
|
@c man .SS |
|
@node Media, Methods, Model, top |
|
@chapter Media types and states |
|
@c man .B Media types and states: |
|
There are two families of media in the MMC standard: |
|
@* |
|
@cindex Multi-session media, _definition |
|
@strong{Multi-session media} are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and |
|
unformatted DVD-RW. These media provide a table of content which |
|
describes their existing sessions. See option @strong{-toc}. |
|
@* |
|
@cindex Overwriteable media, _definition |
|
@strong{Overwriteable media} are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW. |
|
They allow random write access but do not provide information about their |
|
session history. If they contain one or more ISO 9660 sessions and if the |
|
first session was written by xorriso, then a table of content can |
|
be emulated. Else only a single overall session will be visible. |
|
@* |
|
DVD-RW media can be formatted by -format "full". |
|
They can be made unformatted by -blank "deformat". |
|
@* |
|
Regular files and block devices are handled as overwriteable media. |
|
Pipes and other writeable file types are handled as blank multi-session media. |
|
@c man .PP |
|
@sp 1 |
|
These media can assume several states in which they offer different |
|
capabilities. |
|
@* |
|
@sp 1 |
|
@cindex Blank media, _definition |
|
@strong{Blank} media can be written from scratch. They contain no ISO image |
|
suitable for 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. |
|
@* |
|
@sp 1 |
|
@cindex Appendable media, _definition |
|
@strong{Appendable} media accept further sessions. Either they are MMC |
|
multi-session media in appendable state, or they are overwriteable media |
|
which contain an ISO image suitable for xorriso. |
|
@* |
|
Appendable is the state after writing a session with option -close off. |
|
@* |
|
@sp 1 |
|
@cindex Closed media, _definition |
|
@strong{Closed} media cannot be written. They may contain an ISO image suitable |
|
for xorriso. |
|
@* |
|
Closed is the state of DVD-ROM media and of multi-session media which were |
|
written with option -close on. If the drive is read-only hardware then it will |
|
probably show any media as closed CD-ROM resp. DVD-ROM. |
|
@* |
|
Overwriteable media assume this state in such read-only drives or if they |
|
contain unrecognizable data in the first 32 data blocks. |
|
@* |
|
Read-only drives may or may not show session histories of multi-session |
|
media. Often only the first and the last session are visible. Sometimes |
|
not even that. Option -rom_toc_scan might or might not help in such cases. |
|
@c man .SS |
|
@node Methods, Drives, Media, top |
|
@chapter Creating, Growing, Modifying, Blind Growing: |
|
@c man .B Creating, Growing, Modifying, Blind Growing: |
|
@* |
|
@cindex Create, new ISO image, _definiton |
|
A new empty ISO image gets @strong{created} |
|
if there is no input drive with a valid ISO 9660 image when the first time |
|
an output drive is defined. This is achieved by option -dev on blank media |
|
or by option -outdev on media in any state. |
|
@* |
|
The new empty image can be populated with directories and files. |
|
Before it can be written, the media in the output drive must get into |
|
blank state if it was not blank already. |
|
@c man .PP |
|
@sp 1 |
|
If there is a input drive with a valid ISO image, then this image gets loaded |
|
as foundation for manipulations and extension. The constellation of input |
|
and output drive determines which write method will be used. |
|
They have quite different capabilities and constraints. |
|
@c man .PP |
|
@sp 1 |
|
@cindex Growing, _definition |
|
The method of @strong{growing} adds new data to the existing media. These |
|
data comprise of eventual new file content and they override the existing |
|
ISO 9660 + Rock Ridge directory tree. It is possible to hide files from |
|
previous sessions but they still exist on media and with many types of |
|
optical media it is quite easy to recover them by mounting older sessions. |
|
@* |
|
Growing is achieved by option -dev. |
|
@c man .PP |
|
@sp 1 |
|
@cindex Modifying, _definition |
|
The write method of @strong{modifying} produces compact filesystem |
|
images with no outdated files or directory trees. Modifying can write its |
|
images to target media which are completely unsuitable for multi-session |
|
operations. E.g. DVD-RW which were treated with -blank deformat_quickest, |
|
named pipes, character devices, sockets. |
|
On the other hand modified sessions cannot be written to appendable media |
|
but to blank media only. |
|
@* |
|
So for this method one needs either two optical drives or has to work with |
|
filesystem objects as source and/or target media. |
|
@* |
|
Modifying takes place if input drive and output drive are not the same and |
|
if option -grow_blindly is set to its default "off". |
|
This is achieved by options -indev and -outdev. |
|
@c man .PP |
|
@sp 1 |
|
@cindex Blind growing, _definition |
|
If option -grow_blindly is set to a non-negative number and if -indev and |
|
-outdev are both set to different drives, then @strong{blind growing} is |
|
performed. It produces an add-on session which is ready for being written |
|
to the given block address. This is the usage model of |
|
@* |
|
mkisofs -M $indev -C $msc1,$msc2 -o $outdev |
|
@* |
|
which gives much room for wrong parameter combinations and should thus only be |
|
employed if a strict distinction between ISO formatter xorriso and the burn |
|
program is desired. -C $msc1,$msc2 is equivalent to: |
|
@* |
|
-load sbsector $msc1 -grow_blindly $msc2 |
|
@c man .SS |
|
@node Drives, Extras, Methods, top |
|
@chapter Libburn drives |
|
@c man .B Libburn drives: |
|
@c man .br |
|
@cindex Drive, _definiton |
|
Input drive, i.e. source of an existing or empty ISO image, can be any random |
|
access readable libburn drive: optical media with readable data, |
|
blank optical media, regular files, block devices. |
|
@c man .PP |
|
@sp 1 |
|
Output drive, i.e. target for writing, can be any libburn drive. |
|
Some drive types do not support the method of growing but only the methods |
|
of modifying and blind growing. They all are suitable for newly created images. |
|
@* |
|
All drive file objects have to offer rw-permission to the user of xorriso. |
|
Even those which will not be useable for reading an ISO image. |
|
@c man .PP |
|
@sp 1 |
|
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by |
|
the path of their block device or of their generic character device. E.g. |
|
@* |
|
-dev /dev/sr0 |
|
@* |
|
-dev /dev/hdc |
|
@* |
|
-dev /dev/sg2 |
|
@* |
|
On FreeBSD the device files have names like |
|
@* |
|
-dev /dev/cd0 |
|
@* |
|
Get a list of accessible drives by command |
|
@* |
|
-devices |
|
@* |
|
It might be necessary to do this as |
|
@strong{superuser} |
|
in order to see all drives and to then allow rw-access for the intended users. |
|
Consider to bundle the authorized users in a group like old "floppy". |
|
@c man .PP |
|
@sp 1 |
|
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and |
|
their path in the filesystem. E.g.: |
|
@* |
|
-dev stdio:/dev/sdc |
|
@* |
|
The default setting of -drive_class allows to address files outside the |
|
/dev tree without that prefix. E.g.: |
|
@* |
|
-dev /tmp/pseudo_drive |
|
@* |
|
If path leads to a regular file or to a block device then the emulated drive |
|
is random access readable and can be used for the method of growing if it |
|
already contains a valid ISO 9660 image. Any other file type is not readable |
|
via "stdio:" and can only be used as target for the method of modifying or |
|
blind growing. |
|
Non-existing paths in existing directories are handled as empty regular files. |
|
@c man .PP |
|
@sp 1 |
|
A very special kind of pseudo drive are open file descriptors. They are |
|
depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open). |
|
@* |
|
Addresses "-" or "stdio:/dev/fd/1" depict standard output, which normally is |
|
the output channel for result texts. |
|
To prevent a fatal intermingling of ISO image and text messages, all result |
|
texts get redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among |
|
the start arguments of the program. |
|
@* |
|
Standard output is currently suitable for creating one session |
|
per program run without dialog. Use in other situations is discouraged |
|
and several restrictions apply: |
|
@* |
|
It is not allowed to use standard output as pseudo drive if it was not |
|
among the start arguments. Do not try to fool this ban via backdoor addresses |
|
to stdout. |
|
@* |
|
If stdout is used as drive, then -use_readline is permanently disabled. |
|
Use of backdoors can cause severe memory and/or tty corruption. |
|
@c man .PP |
|
@sp 1 |
|
Be aware that especially the superuser can write into any accessible file or |
|
device by using its path with the "stdio:" prefix. By default any address |
|
in the /dev tree without prefix "stdio:" will work only if it leads to a MMC |
|
drive. |
|
@* |
|
One may use option |
|
@strong{-ban_stdio_write} |
|
to surely prevent this risk and to allow only MMC drives. |
|
@* |
|
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:". |
|
@c man .br |
|
By option -drive_class one may ban certain paths or allow access without |
|
prefix "stdio:" to other paths. |
|
@c man .SS |
|
@node Extras, Processing, Drives, top |
|
@chapter Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr |
|
@c man .B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr: |
|
@c man .br |
|
@cindex Rock Ridge, _definiton |
|
@strong{Rock Ridge} |
|
is the name of a set of additional information which enhance |
|
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem |
|
with ownership, access permissions, symbolic links, and other attributes. |
|
@* |
|
This is what xorriso uses for a decent representation of the disk files |
|
within the ISO image. Rock Ridge information is produced with any xorriso |
|
image. |
|
@c man .PP |
|
@sp 1 |
|
xorriso is not named "porriso" because POSIX only guarantees 14 characters |
|
of filename length. It is the X/Open System Interface standard XSI which |
|
demands a file name length of up to 255 characters and paths of up to 1024 |
|
characters. Rock Ridge fulfills this demand. |
|
@c man .PP |
|
@sp 1 |
|
@cindex El Torito, _definiton |
|
An @strong{El Torito} |
|
boot record connects a boot image, which is a binary program plus some |
|
other files stored in the ISO image, with the bootstrapping facility of |
|
contemporary computers. |
|
The content of the boot image files is not in the scope of El Torito. |
|
@* |
|
Most bootable GNU/Linux CDs are equipped with ISOLINUX boot images. xorriso is |
|
able to create or maintain an El Torito object which makes such an image |
|
bootable. For details see option -boot_image. |
|
Emulation -as mkisofs supports the example options out of the ISOLINUX wiki. |
|
@* |
|
The support for other boot image types is sparse. |
|
@* |
|
An MBR is generated together with the El Torito boot record if the boot image |
|
bears the isohybrid signature of ISOLINUX 3.72 or later. It will occupy the |
|
first 512 bytes of the emerging ISO image and enable booting from media which |
|
appear as hard disk rather than as CDROM. An MBR does not hamper CDROM booting. |
|
The MBR of a follow-up session can get in effect only on overwriteable media. |
|
@c man .PP |
|
@sp 1 |
|
@cindex ACL, _definiton |
|
@strong{ACL} |
|
are an advanced way of controlling access permissions to file objects. Neither |
|
ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has |
|
introduced a standard conformant extension named AAIP for that purpose. |
|
It uses this extension if enabled by option |
|
@strong{-acl}. |
|
@* |
|
AAIP enhanced images are supposed to be mountable normally, but one cannot |
|
expect that the mounted filesystem will show and respect the eventual ACLs. |
|
For now, only xorriso is able to retrieve those ACLs. It can bring them into |
|
effect when files get restored to an ACL enabled file system or it can |
|
print them in a format suitable for tool setfacl. |
|
@* |
|
Files with ACL show as group permissions the setting of entry "mask::" if |
|
that entry exists. Nevertheless the non-listed group members get handled |
|
according to entry "group::". xorriso brings "group::" into effect before |
|
eventually removing the ACL from a file. |
|
@c man .PP |
|
@sp 1 |
|
@cindex xattr, _definiton |
|
@strong{xattr} (aka EA) |
|
are pairs of name and value which can be attached to file objects. AAIP is |
|
able to represent them and xorriso allows to record and restore pairs which |
|
have names out of the user namespace. I.e. those which begin with "user.", |
|
like "user.x" or "user.whatever". Name has to be a 0 terminated string. |
|
Value may be any array of bytes which does not exceed the size of 4095 bytes. |
|
xattr processing happens only if it is enabled by option |
|
@strong{-xattr}. |
|
@* |
|
As with ACL, currently only xorriso is able to retrieve xattr from AAIP |
|
enhanced images, to restore them to xattr capable file systems, or to print |
|
them. |
|
@c man .SS |
|
@node Processing, Dialog, Extras, top |
|
@chapter Command processing |
|
@c man .B Command processing: |
|
@c man .br |
|
Commands are either actions which happen immediately or settings which |
|
influence following actions. So their sequence does matter. |
|
@* |
|
@cindex List delimiter, _definiton |
|
Commands consist of a command word, |
|
followed by zero or more parameter words. If the list of parameter words |
|
is of variable length (indicated by "[...]" or "[***]") then it has to be |
|
terminated by either the @strong{list delimiter}, or the end of argument list, |
|
or an end of an input line. |
|
@c man .PP |
|
@sp 1 |
|
At program start the list delimiter is the word "@minus{}@minus{}". |
|
This may be changed by option -list_delimiter in order to allow |
|
"@minus{}@minus{}" as argument in a list of variable length. |
|
It is advised to reset the delimiter to "@minus{}@minus{}" immediately |
|
afterwards. |
|
@* |
|
For brevity the list delimiter is referred as "@minus{}@minus{}" |
|
throughout this text. |
|
@* |
|
The list delimiter is silently tolerated if it appears after the parameters of |
|
a command with a fixed list length. It is handled as normal text if it |
|
appears among the arguments of such a command. |
|
@c man .PP |
|
@sp 1 |
|
@cindex Pattern expansion, _definition |
|
@strong{Pattern expansion} |
|
converts a list of pattern words into a list of existing file addresses. |
|
Eventual unmatched pattern words appear themselves in that result list, though. |
|
@* |
|
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' |
|
and respects '/' as separator which may only be matched literally. |
|
@* |
|
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. |
|
@c man .PP |
|
@sp 1 |
|
Command and parameter words are either read from program arguments, where one |
|
argument is one word, or from quoted input lines where words are recognized |
|
similar to the quotation rules of a shell parser. |
|
@* |
|
xorriso is not a shell, although it might appear so on first glimpse. |
|
Be aware that the interaction of quotation marks and pattern symbols like "*" |
|
differs from the usual shell parsers. In xorriso, a quotation mark does not |
|
make a pattern symbol literal. |
|
@c man .PP |
|
@sp 1 |
|
@cindex Quoted input, _definiton |
|
@strong{Quoted input} |
|
converts whitespace separated text pieces into words. |
|
The double quotation mark " and the single quotation mark ' can be used to |
|
enclose whitespace and make it part of words (e.g. of file names). Each mark |
|
type can enclose the marks of the other type. A trailing backslash \ outside |
|
quotations or an open quotation cause the next input line to be appended. |
|
@* |
|
@cindex Backslash Interpretation, _definition |
|
Quoted input accepts any ASCII character except NUL (0) as content of quotes. |
|
Nevertheless it can be cumbersome for the user to produce those characters |
|
at all. Therefore quoted input and program arguments allow optional |
|
@strong{Backslash Interpretation} |
|
which can represent all ASCII characters except NUL (0) by backslash codes |
|
as in $'...' of bash. |
|
@* |
|
It is not enabled by default. See option -backslash_codes. |
|
@c man .PP |
|
@sp 1 |
|
When the program begins then it first looks for argument -no_rc. If this is |
|
not present then it looks for its startup files and |
|
eventually reads their content as command input lines. Then it interprets |
|
the program arguments as commands and parameters and finally it enters |
|
dialog mode if command -dialog "on" was executed up to then. |
|
@c man .PP |
|
@sp 1 |
|
The program ends either by command -end, or by the end of program arguments |
|
if not dialog was enabled up to that moment, or by a problem |
|
event which triggers the threshold of command -abort_on. |
|
@c man .SS |
|
@node Dialog, Options, Processing, top |
|
@chapter Dialog, Readline, Result pager |
|
@c man .B Dialog, Readline, Result pager: |
|
@c man .br |
|
Dialog mode prompts for a quoted input line, parses it into words, and performs |
|
them as commands with their parameters. It provides assisting services |
|
to make dialog more comfortable. |
|
@c man .PP |
|
@sp 1 |
|
Readline is an enhancement for the input line. You may know it already from |
|
the bash shell. Whether it is available in xorriso depends on the availability |
|
of package readline-dev at the time when xorriso was built from its sourcecode. |
|
@* |
|
It allows to move the cursor over the text in the line by help of the |
|
Leftward and the Rightward arrow key. |
|
Text may be inserted at the cursor position. The Delete key removes the |
|
character under the cursor. Upward and Downward arrow keys navigate through |
|
the history of previous input lines. |
|
@* |
|
@c man-ignore-lines 1 |
|
See info readline |
|
@c man See man readline |
|
for more info about libreadline. |
|
@c man .PP |
|
@sp 1 |
|
Option -page activates a built-in result text pager which may be convenient in |
|
dialog. After an action has put out the given number of terminal lines, |
|
the pager prompts the user for a line of input. |
|
@* |
|
An empty line lets xorriso resume work until the next page is put out. |
|
@* |
|
The single character "@@" disables paging for the current action. |
|
@* |
|
"@@@@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress |
|
further result output. |
|
@* |
|
Any other line will be interpreted as new dialog line. The current action |
|
is urged to abort. Afterwards, the input line is executed. |
|
@c man .PP |
|
@sp 1 |
|
Some actions apply paging to their info output, too. |
|
@* |
|
The urge to abort may or may not be obeyed by the current action. All actions |
|
try to abort as soon as possible. |
|
@node Options, Examples, Dialog, top |
|
@chapter Options |
|
@c man .br |
|
@c man .SH OPTIONS |
|
@c man .br |
|
All command words are shown with a leading dash although this dash is not |
|
mandatory for the option to be recognized. Nevertheless within option -as |
|
the dashes of the emulated options are mandatory. |
|
@* |
|
Normally any number of leading dashes is ignored with command words and |
|
inner dashes are interpreted as underscores. |
|
@menu |
|
* AqDrive:: Aquiring source and target drive |
|
* Loading:: Influencing the behavior of image loading |
|
* 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 |
|
@end menu |
|
@c man .TP |
|
@node AqDrive, Loading, Options, Options |
|
@section Aquiring source and target drive |
|
@c man .B Aquiring source and target drive: |
|
@c man .PP |
|
Before aquiring a drive one will eventually enable options which influence |
|
the behavior of image loading. See next option group. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -dev address |
|
@kindex -dev aquires one drive for input and output |
|
@cindex Drive, for input and output, -dev |
|
Set input and output drive to the same address and load an eventual ISO image. |
|
If there is no ISO image then create a blank one. |
|
Set the image expansion method to growing. |
|
@* |
|
This is only allowed as long as no changes are pending in the currently |
|
loaded ISO image. Eventually one has to perform -commit or -rollback first. |
|
@* |
|
Special address string "-" means standard output, to which several restrictions |
|
apply. See above paragraph "Libburn drives". |
|
@* |
|
An empty address string "" gives up the current device |
|
without aquiring a new one. |
|
@c man .TP |
|
@item -indev address |
|
@kindex -indev aquires a drive for input |
|
@cindex Drive, for input, -indev |
|
Set input drive and load an eventual ISO image. If the new input drive differs |
|
from -outdev then switch from growing to modifying or to blind growing. |
|
It depends on the setting of -grow_blindly which of both gets activated. |
|
The same rules and restrictions apply as with -dev. |
|
@c man .TP |
|
@item -outdev address |
|
@kindex -outdev aquires a drive for output |
|
@cindex Drive, for output, -outdev |
|
Set output drive and if it differs from the input drive then switch from |
|
growing to modifying or to blind growing. Unlike -dev and -indev this action |
|
does not load a new ISO image. So it can be performed even if there are pending |
|
changes. |
|
@* |
|
-outdev can be performed without previous -dev or -indev. In that case an |
|
empty ISO image with no changes pending is created. It can either be populated |
|
by help of -map, -add et.al. or it can be discarded silently if -dev or -indev |
|
are performed afterwards. |
|
@* |
|
Special address string "-" means standard output, to which several restrictions |
|
apply. See above paragraph "Libburn drives". |
|
@* |
|
An empty address string "" gives up the current output drive |
|
without aquiring a new one. No writing is possible without an output drive. |
|
@c man .TP |
|
@item -grow_blindly "off"|predicted_nwa |
|
@kindex -grow_blindly overides next writeable address |
|
@cindex Next writeable address, -grow_blindly |
|
If predicted_nwa is a non-negative number then perform blind growing rather |
|
than modifying if -indev and -outdev are set to different drives. |
|
"off" or "-1" switch to modifying, which is the default. |
|
@* |
|
predicted_nwa is the block address where the add-on session of blind |
|
growing will finally end up. It is the responsibility of the user to ensure |
|
this final position and the presence of the older sessions. Else the |
|
overall ISO image will not be mountable or will produce read errors when |
|
accessing file content. xorriso will write the session to the address |
|
as obtained from examining -outdev and not necessarily to predicted_nwa. |
|
@* |
|
During a run of blind growing, the input drive is given up before output |
|
begins. The output drive is given up when writing is done. |
|
@end table |
|
@c man .TP |
|
@c man .B Influencing the behavior of image loading: |
|
@node Loading, Insert, AqDrive, Options |
|
@section Influencing the behavior of image loading |
|
@c man .PP |
|
The following options should normally be performed before loading an image |
|
by aquiring an input drive. In rare cases it is desirable to activate |
|
them only after image loading. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -load entity id |
|
@kindex -load addresses a particular session as input |
|
@cindex Session, select as input, -load |
|
Load a particular (possibly outdated) ISO image from -dev or -indev. |
|
Usually all available sessions are shown with option -toc. |
|
@* |
|
entity depicts the kind of addressing. id depicts the particular |
|
address. The following entities are defined: |
|
@* |
|
"auto" with any id addresses the last session in -toc. This is the default. |
|
@* |
|
"session" with id being a number as of a line "ISO session", column "Idx". |
|
@* |
|
"track" with id being a number as of a line "ISO track", column "Idx". |
|
@* |
|
"lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector". |
|
@* |
|
"volid" with a search pattern for a text as of a line "ISO ...", |
|
column "Volume Id". |
|
@* |
|
Adressing a non-existing entity or one which does not represent an ISO |
|
image will either abandon -indev or at least lead to a blank image. |
|
@* |
|
If an input drive is set at the moment when -load is executed, then the |
|
addressed ISO image is loaded immediately. Else, the setting will be pending |
|
until the next -dev or -indev. After the image has been loaded once, the |
|
setting is valid for -rollback until next -dev or -indev, where it |
|
will be reset to "auto". |
|
@c man .TP |
|
@item -drive_class "harmless"|"banned"|"caution"|"clear_list" disk_pattern |
|
@kindex -drive_class controls drive accessability |
|
@cindex Drive, accessability, -drive_class |
|
Add a drive path pattern to one of the safety lists or make those lists empty. |
|
There are three lists defined which get tested in the following sequence: |
|
@* |
|
If a drive address path matches the "harmless" list then the drive will be |
|
accepted. If it is not a MMC device then the prefix "stdio:" will be prepended |
|
automatically. This list is empty by default. |
|
@* |
|
Else if the path matches the "banned" list then the drive will not be |
|
accepted by xorriso but rather lead to a FAILURE event. This list is empty by |
|
default. |
|
@* |
|
Else if the path matches the "caution" list and if it is not a MMC device, |
|
then its address must have the prefix "stdio:" or it will be rejected. |
|
This list has by default one entry: "/dev". |
|
@* |
|
If a drive path matches no list then it is considered "harmless". By default |
|
these are all paths which do not begin with directory "/dev". |
|
@* |
|
A path matches a list if one of its parent paths or itself matches a list |
|
entry. An eventual address prefix "stdio:" or "mmc:" will be ignored when |
|
testing for matches. |
|
@* |
|
By pseudo-class "clear_list" and pseudo-patterns "banned", "caution", |
|
"harmless", or "all", the lists may be made empty. |
|
@* |
|
E.g.: -drive_class clear_list banned |
|
@* |
|
One will normally define the -drive_class lists in one of the xorriso |
|
Startup Files. |
|
@* |
|
Note: This is not a security feature but rather a bumper for the superuser to |
|
prevent inadverted mishaps. For reliably blocking access to a device file you |
|
have to deny its rw-permissions in the filesystem. |
|
@c man .TP |
|
@item -assert_volid pattern severity |
|
@kindex -assert_volid rejects undesired images |
|
@cindex Image, demand volume id, -assert_volid |
|
Refuse to load ISO images with volume ids which do not match the given |
|
search pattern. When refusing an image, give up the input drive and issue |
|
an event of the given severity (like FAILURE, see -abort_on). An empty search |
|
pattern accepts any image. |
|
@* |
|
This option does not hamper the creation of an empty image from blank |
|
input media and does not discard an already loaded image. |
|
@c man .TP |
|
@item -in_charset character_set_name |
|
@kindex -in_charset sets input character set |
|
@cindex Character Set, for input, -in_charset |
|
Set the character set from which to convert file names when loading an |
|
image. This has eventually to be done before specifying -dev , -indev or |
|
-rollback. See paragraph "Character sets" for more explanations. |
|
When loading the written image after -commit the setting of -out_charset |
|
will be copied to -in_charset. |
|
@c man .TP |
|
@item -auto_charset "on"|"off" |
|
@kindex -auto_charset learns character set from image |
|
@cindex Character set, learn from image, -auto_charset |
|
Enable or disable recording and interpretation of the output character |
|
set name in an xattr attribute of the image root directory. If enabled then |
|
an eventual recorded character set name gets used as input character set |
|
when reading an image. |
|
@* |
|
Note that the default output charset is the local character set of the |
|
terminal where xorriso runs. Before attributing this local character set |
|
to the produced ISO image, check whether the terminal properly displays |
|
all intended filenames, especially exotic national characters. |
|
@c man .TP |
|
@item -hardlinks mode[:mode...] |
|
@kindex -hardlinks controls handling of hard links |
|
@cindex Hard links, control handling, -hardlinks |
|
Enable or disable loading and recording of hardlink relations. |
|
@* |
|
In default mode "off", iso_rr files lose their inode numbers at image load |
|
time. Each iso_rr file object which has no inode number at image generation |
|
time will get a new unique inode number if -compliance is set to new_rr. |
|
@* |
|
Mode "on" preserves eventual inode numbers from the loaded image. |
|
When committing a session it searches for families of iso_rr files |
|
which stem from the same disk file, have identical content filtering and have |
|
identical properties. The family members all get the same inode number. |
|
Whether these numbers are respected at mount time depends on the operating |
|
system. |
|
@* |
|
Commands -update and -update_r track splits and fusions of hard links in |
|
filesystems which have stable device and inode numbers. This can cause |
|
automatic last minute changes before the session gets written. Command |
|
-hardlinks "perform_update" may be used to do these changes earlier, |
|
e.g. if you need to apply filters to all updated files. |
|
@* |
|
Mode "without_update" avoids hardlink processing during update commands. |
|
Use this if your filesystem situation does not allow -disk_dev_ino "on". |
|
@* |
|
xorriso commands which extract files from an ISO image try to hardlink files |
|
with identical inode number. The normal scope of this operation is from |
|
image load to image load. One may give up the accumulated hard link addresses |
|
by -hardlinks "discard_extract". |
|
@* |
|
A large number of hardlink families may exhaust -temp_mem_limit |
|
if not -osirrox "sort_lba_on" and -hardlinks "cheap_sorted_extract" |
|
are both in effect. This restricts hard linking to other files restored by |
|
the same single extract command. -hardlinks "normal_extract" re-enables |
|
wide and expensive hardlink accumulation. |
|
@* |
|
Hardlink processing automatically enables @strong{-compliance new_rr}. |
|
This may be overridden by a following -compliance old_rr . In this case |
|
the resulting image will violate the RRIP-1.10 specs for entry PX in |
|
the same way as mkisofs does. |
|
@c man .TP |
|
@item -acl "on"|"off" |
|
@kindex -acl controls handling of ACLs |
|
@cindex ACL, control handling, -acl |
|
Enable or disable processing of ACLs. |
|
If enabled, then xorriso will obtain ACLs from disk file objects, |
|
store ACLs in the ISO image using the libisofs specific AAIP format, |
|
load AAIP data from ISO images, test ACL during file comparison, |
|
and restore ACLs to disk files when extracting them from ISO images. |
|
See also options -getfacl, -setfacl. |
|
@c man .TP |
|
@item -xattr "on"|"off" |
|
@kindex -xattr controls handling of xattr (EA) |
|
@cindex xattr, control handling, -xattr |
|
Enable or disable processing of xattr attributes in user namespace. |
|
If enabled, then xorriso will handle xattr similar to ACL. |
|
See also options -getfattr, -setfattr and above paragraph about xattr. |
|
@c man .TP |
|
@item -md5 "on"|"all"|"off" |
|
@kindex -md5 controls handling of MD5 sums |
|
@cindex MD5, control handling, -md5 |
|
Enable or disable processing of MD5 checksums for the overall session and for |
|
each single data file. If enabled then images get loaded only if eventual |
|
checksums tags of superblock and directory tree match properly. The MD5 |
|
checksums of data files and whole session get loaded from the image if there |
|
are any. |
|
@* |
|
With options -compare and -update the eventually recorded MD5 of a file |
|
will be used to avoid content reading from the image. Only the disk file |
|
content will be read and compared with that MD5. This can save much time |
|
if -disk_dev_ino "on" is not suitable. |
|
@* |
|
At image generation time they are computed for each file which gets its data |
|
written into the new session. The checksums of files which have their data |
|
in older sessions get copied into the new session. Superblock, tree and whole |
|
session get a checksum tag each. |
|
@* |
|
Mode "all" will additionally check during image generation whether the checksum |
|
of a data file changed between the time when its reading began and the time |
|
when it ended. This implies reading every file twice. |
|
@* |
|
Checksums can be exploited via options -check_md5, -check_md5_r, via find |
|
actions get_md5, check_md5, and via -check_media. |
|
@c man .TP |
|
@item -for_backup |
|
@kindex -for_backup -acl,-xattr,-hardlinks,-md5 |
|
@cindex Backup, enable features, -for_backup |
|
Enable all extra features which help to produce or to restore backups with |
|
highest fidelity of file properties. |
|
Currently this is a shortcut for: -hardlinks on -acl on -xattr on -md5 on. |
|
@c man .TP |
|
@item -disk_dev_ino "on"|"ino_only"|"off" |
|
@kindex -disk_dev_ino fast incremental backup |
|
@cindex Backup, enable fast incremental, -disk_dev_ino |
|
Enable or disable processing of recorded file identification numbers |
|
(dev_t and ino_t). They are eventually stored as xattr and allow |
|
to substantially accelerate file comparison. The root node gets a global start |
|
timestamp. If during comparison a file with younger timestamps is found in the |
|
ISO image, then it is suspected to have inconsistent content. |
|
@* |
|
If device numbers and inode numbers of the disk filesystems are persistent |
|
and if no irregular alterations of timestamps or system clock happen, |
|
then potential content changes can be detected without reading that content. |
|
File content change is assumed if any of mtime, ctime, device number or inode |
|
number have changed. |
|
@* |
|
Mode "ino_only" replaces the precondition that device numbers are stable by the |
|
precondition that mount points in the compared tree always lead to the |
|
same filesystems. Use this if mode "on" always sees all files changed. |
|
@* |
|
The speed advantage appears only if the loaded session was produced with |
|
-disk_dev_ino "on" too. |
|
@* |
|
Note that -disk_dev_ino "off" is totally in effect only if -hardlinks is "off", |
|
too. |
|
@c man .TP |
|
@item -rom_toc_scan "on"|"force"|"off"[:"emul_on"|"emul_off"] |
|
@kindex -rom_toc_scan searches for sessions |
|
@cindex Table-of-content, search sessions, -rom_toc_scan |
|
Read-only drives do not tell the actual media type but show any media as |
|
ROM (e.g. as DVD-ROM). The session history of MMC multi-session media might |
|
be truncated to first and last session or even be completely false. |
|
(The eventual emulated history of overwriteable media is not affected by this.) |
|
@* |
|
To have in case of failure a chance of getting the session history and |
|
especially the address of the last session, there is a scan for ISO 9660 |
|
filesystem headers which might help but also might yield worse results |
|
than the drive's table of content. At its end it can cause read attempts |
|
to invalid addresses and thus ugly drive behavior. |
|
Setting "on" enables that scan for alleged read-only media. |
|
@* |
|
Some operating systems are not able to mount the most recent session of |
|
multi-session DVD or BD. If on such a system xorriso has no own MMC |
|
capabilities then it may still find that session from a scanned table of |
|
content. Setting "force" handles any media like a ROM media with setting "on". |
|
@* |
|
On the other hand the emulation of session history on overwriteable media |
|
can hamper reading of partly damaged media. Setting "off:emul_off" disables |
|
the elsewise trustworthy table-of-content scan for those media. |
|
@* |
|
To be in effect, the -rom_toc_scan setting has to be made before the -*dev |
|
command which aquires drive and media. |
|
@c man .TP |
|
@item -calm_drive "in"|"out"|"all"|"revoke"|"on"|"off" |
|
@kindex -calm_drive reduces drive activity |
|
@cindex Drive, reduce activity, -calm_drive |
|
Reduce drive noise until it is actually used again. Some drives stay alert |
|
for substantial time after they have been used for reading. This reduces |
|
the startup time for the next drive operation but can be loud and waste |
|
energy if no i/o with the drive is expected to happen soon. |
|
@* |
|
Modes "in", "out", "all" immediately calm down -indev, -outdev, resp. both. |
|
Mode "revoke" immediately alerts both. |
|
Mode "on" causes -calm_drive to be performed automatically after each -dev, |
|
-indev, and -outdev. Mode "off" disables this. |
|
@c man .TP |
|
@item -ban_stdio_write |
|
@kindex -ban_stdio_write demands real drive |
|
@cindex Drive, demand real MMC, -ban_stdio_write |
|
Allow for writing only the usage of MMC optical drives. Disallow |
|
to write the result into files of nearly arbitrary type. |
|
Once set, this command cannot be revoked. |
|
@end table |
|
@c man .TP |
|
@c man .B Inserting files into ISO image: |
|
@node Insert, SetInsert, Loading, Options |
|
@section Inserting files into ISO image |
|
@c man .PP |
|
The following commands expect file addresses of two kinds: |
|
@c man .br |
|
@cindex disk_path, _definition |
|
@strong{disk_path} |
|
is a path to an object in the local filesystem tree. |
|
@c man .br |
|
@cindex iso_rr_path, _definition |
|
@strong{iso_rr_path} |
|
is the Rock Ridge name of a file object in the ISO image. (Do not |
|
confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.) |
|
@c man .PP |
|
@sp 1 |
|
Note that in the ISO image you are as powerful as the superuser. Access |
|
permissions of the existing files in the image do not apply to your write |
|
operations. They are intended to be in effect with the read-only mounted image. |
|
@c man .PP |
|
@sp 1 |
|
If the iso_rr_path of a newly inserted file leads to an existing |
|
file object in the ISO image, then the following collision handling |
|
happens: |
|
@* |
|
If both objects are directories then they get merged by recursively inserting |
|
the subobjects from filesystem into ISO image. |
|
If other file types collide then the setting of command |
|
@strong{-overwrite} |
|
decides. |
|
@* |
|
Renaming of files has similar collision handling, but directories can only |
|
be replaced, not merged. Note that -mv inserts the source objects into an |
|
eventual existing target directory rather than attempting to replace it. |
|
@c man .PP |
|
@sp 1 |
|
The commands in this section alter the ISO image and not the local filesystem. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -disk_pattern "on"|"ls"|"off" |
|
@kindex -disk_pattern controls pattern expansion |
|
@cindex Pattern expansion, for disk paths, -disk_pattern |
|
Set the pattern expansion mode for the disk_path arguments of several |
|
commands which support this feature. |
|
@* |
|
Setting "off" disables this feature for all commands which are marked in this |
|
man page by "disk_path [***]" or "disk_pattern [***]". |
|
@* |
|
Setting "on" enables it for all those commands. |
|
@* |
|
Setting "ls" enables it only for those which are marked by |
|
"disk_pattern [***]". |
|
@* |
|
Default is "ls". |
|
@c man .TP |
|
@item -add pathspec [...] | disk_path [***] |
|
@kindex -add inserts one or more paths |
|
@cindex Insert, pathspecs, -add |
|
Insert the given files or directory trees from filesystem |
|
into the ISO image. |
|
@* |
|
If -pathspecs is set to "on" then pattern expansion is always disabled and |
|
character '=' has a special meaning. It eventually separates the ISO image path |
|
from the disk path: |
|
@* |
|
iso_rr_path=disk_path |
|
@* |
|
The separator '=' can be escaped by '\'. |
|
If iso_rr_path does not begin with '/' then -cd is prepended. |
|
If disk_path does not begin with '/' then -cdx is prepended. |
|
@* |
|
If no '=' is given then the word is used as both, iso_rr_path and disk path. |
|
If in this case the word does not begin with '/' then -cdx is prepended to |
|
the disk_path and -cd is prepended to the iso_rr_path. |
|
@* |
|
If -pathspecs is set to "off" then eventual -disk_pattern expansion applies. |
|
The resulting words are used as both, iso_rr_path and disk path. Eventually |
|
-cdx gets prepended to disk_path and -cd to iso_rr_path. |
|
@c man .TP |
|
@item -add_plainly mode |
|
@kindex -add_plainly inserts one or more paths |
|
@cindex Insert, non-dashed arguments, -add_plainly |
|
If set to mode "unknown" then any command word that does not begin with "-" and |
|
is not recognized as known command will be subject to a virtual -add command. |
|
I.e. it will be used as pathspec or as disk_path and added to the image. |
|
Eventually -disk_pattern expansion applies to disk_paths. |
|
@* |
|
Mode "dashed" is similar to "unknown" but also adds unrecognized command |
|
words even if they begin with "-". |
|
@* |
|
Mode "any" announces that all further words are to be added as pathspecs |
|
or disk_paths. This does not work in dialog mode. |
|
@* |
|
Mode "none" is the default. It prevents any words from being understood |
|
as files to add, if they are not parameters to appropriate commands. |
|
@c man .TP |
|
@item -path_list disk_path |
|
@kindex -path_list inserts paths from disk file |
|
@cindex Insert, paths from disk file, -path_list |
|
Like -add but read the parameter words from file disk_path |
|
or standard input if disk_path is "-". |
|
The list must contain exactly one pathspec resp. disk_path pattern per line. |
|
@c man .TP |
|
@item -quoted_path_list disk_path |
|
@kindex -quoted_path_list inserts paths from disk file |
|
@cindex Insert, paths from disk file, -quoted_path_list |
|
Like -path_list but with quoted input reading rules. Lines get split into |
|
parameter words for -add. Whitespace outside quotes is discarded. |
|
@c man .TP |
|
@item -map disk_path iso_rr_path |
|
@kindex -map inserts path |
|
@cindex Insert, path, -map |
|
Insert file object disk_path into the ISO image as iso_rr_path. If disk_path |
|
is a directory then its whole sub tree is inserted into the ISO image. |
|
@c man .TP |
|
@item -map_single disk_path iso_rr_path |
|
@kindex -map_single inserts path |
|
@cindex Insert, path, -map_single |
|
Like -map, but if disk_path is a directory then its sub tree is not inserted. |
|
@c man .TP |
|
@item -map_l disk_prefix iso_rr_prefix disk_path [***] |
|
@kindex -map_l inserts paths from disk file |
|
@cindex Insert, paths from disk file, -map_l |
|
Perform -map with each of the disk_path arguments. iso_rr_path will be |
|
composed from disk_path by replacing disk_prefix by iso_rr_prefix. |
|
@c man .TP |
|
@item -update disk_path iso_rr_path |
|
@kindex -update inserts path if different |
|
@cindex Insert, if different, -update |
|
Compare file object disk_path with file object iso_rr_path. If they do not |
|
match, then perform the necessary image manipulations to make iso_rr_path |
|
a matching copy of disk_path. By default this comparison will imply lengthy |
|
content reading before a decision is made. Options -disk_dev_ino or -md5 may |
|
accelerate comparison if they were already in effect when the loaded session |
|
was recorded. |
|
@* |
|
If disk_path is a directory and iso_rr_path does not exist yet, then the |
|
whole subtree will be inserted. Else only directory attributes will be |
|
updated. |
|
@c man .TP |
|
@item -update_r disk_path iso_rr_path |
|
@kindex -update_r inserts paths if different |
|
@cindex Insert, if different, -update_r |
|
Like -update but working recursively. I.e. all file objects below both |
|
addresses get compared whether they have counterparts below the other address |
|
and whether both counterparts match. If there is a mismatch then the necessary |
|
update manipulation is done. |
|
@* |
|
Note that the comparison result may depend on option -follow. Its setting |
|
should always be the same as with the first adding of disk_path as iso_rr_path. |
|
@* |
|
If iso_rr_path does not exist yet, then it gets added. If disk_path does not |
|
exist, then iso_rr_path gets deleted. |
|
@c man .TP |
|
@item -update_l disk_prefix iso_rr_prefix disk_path [***] |
|
@kindex -update_l inserts paths if different |
|
@cindex Insert, if different, -update_l |
|
Perform -update_r with each of the disk_path arguments. iso_rr_path will be |
|
composed from disk_path by replacing disk_prefix by iso_rr_prefix. |
|
@c man .TP |
|
@item -cut_out disk_path byte_offset byte_count iso_rr_path |
|
@kindex -cut_out inserts piece of data file |
|
@cindex Insert, piece of data file, -cut_out |
|
Map a byte interval of a regular disk file into a regular file in the ISO |
|
image. |
|
This may be necessary if the disk file is larger than a single media, or if |
|
it exceeds the traditional limit of 2 GiB - 1 for old operating systems, |
|
or the limit of 4 GiB - 1 for newer ones. Only the newest Linux kernels |
|
seem to read properly files >= 4 GiB - 1. |
|
@* |
|
A clumsy remedy for this limit is to backup file pieces and to concatenate |
|
them at restore time. A well tested chopping size is 2047m. |
|
It is permissible to request a higher byte_count than available. The |
|
resulting file will be truncated to the correct size of a final piece. |
|
To request a byte_offset higher than available yields no file in |
|
the ISO image but a SORRY event. |
|
E.g: |
|
@* |
|
-cut_out /my/disk/file 0 2047m \ |
|
@* |
|
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \ |
|
@* |
|
-cut_out /my/disk/file 2047m 2047m \ |
|
@* |
|
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \ |
|
@* |
|
-cut_out /my/disk/file 4094m 2047m \ |
|
@* |
|
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821 |
|
@* |
|
While option -split_size is set larger than 0, and if all pieces of a file |
|
reside in the same ISO directory with no other files, and if the names look |
|
like above, then their ISO directory will be recognized and handled like a |
|
regular file. This affects options -compare*, -update*, and overwrite |
|
situations. |
|
See option -split_size for details. |
|
@c man .TP |
|
@item -cpr disk_path [***] iso_rr_path |
|
@kindex -cpr inserts like with cp -r |
|
@cindex Insert, paths, -cpr |
|
Insert the given files or directory trees from filesystem |
|
into the ISO image. |
|
@* |
|
The rules for generating the ISO addresses are similar as with |
|
shell command cp -r. Nevertheless, directories of the iso_rr_path |
|
are created if necessary. Especially a not yet existing iso_rr_path |
|
will be handled as directory if multiple disk_paths are present. |
|
The leafnames of the multiple disk_paths will be grafted under that |
|
directory as would be done with an existing directory. |
|
@* |
|
If a single disk_path is present then a non-existing iso_rr_path will |
|
get the same type as the disk_path. |
|
@* |
|
If a disk_path does not begin with '/' then -cdx is prepended. |
|
If the iso_rr_path does not begin with '/' then -cd is prepended. |
|
@c man .TP |
|
@item -mkdir iso_rr_path [...] |
|
@kindex -mkdir creates ISO directory |
|
@cindex Directory, create, -mkdir |
|
Create empty directories if they do not exist yet. |
|
Existence as directory generates a WARNING event, existence as |
|
other file causes a FAILURE event. |
|
@end table |
|
@c man .TP |
|
@c man .B Settings for file insertion: |
|
@node SetInsert, Manip, Insert, Options |
|
@section Settings for file insertion |
|
@c man .TP |
|
@table @asis |
|
@item -file_size_limit value [value [...]] @minus{}@minus{} |
|
@kindex -file_size_limit limits data file size |
|
@cindex Insert, limit data file size, -file_size_limit |
|
Set the maximum permissible size for a single data file. The values get |
|
summed up for the actual limit. If the only value is "off" then the file |
|
size is not limited by xorriso. Default is a limit of 100 extents, 4g -2k each: |
|
@* |
|
-file_size_limit 400g -200k @minus{}@minus{} |
|
@* |
|
When mounting ISO 9660 filesystems, old operating systems can handle only files |
|
up to 2g -1 @minus{}@minus{}. Newer ones are good up to 4g -1 @minus{}@minus{}. |
|
You need quite a new Linux kernel to read correctly the final bytes |
|
of a file >= 4g if its size is not aligned to 2048 byte blocks. |
|
@* |
|
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. |
|
@c man .TP |
|
@item -not_mgt code[:code[...]] |
|
@kindex -not_mgt controls file exclusion |
|
@cindex Insert, file exclusion, -not_mgt |
|
Control the behavior of the exclusion lists. |
|
@* |
|
Exclusion processing happens before disk_paths get mapped to the ISO image |
|
and before disk files get compared with image files. |
|
The absolute disk path of the source is matched against the -not_paths list. |
|
The leafname of the disk path is matched against the patterns in the -not_leaf |
|
list. If a match is detected then the disk path will not be regarded as an |
|
existing file and not be added to the ISO image. |
|
@* |
|
Several codes are defined. |
|
The _on/_off settings persist until they are revoked by their_off/_on |
|
counterparts. |
|
@* |
|
"erase" empties the lists which were accumulated by -not_paths and -not_leaf. |
|
@* |
|
"reset" is like "erase" but also re-installs default behavior. |
|
@* |
|
"off" disables exclusion processing temporarily without invalidating |
|
the lists and settings. |
|
@* |
|
"on" re-enables exclusion processing. |
|
@* |
|
"param_off" applies exclusion processing only to paths below disk_path |
|
parameter of commands. I.e. explicitly given disk_paths are exempted |
|
from exclusion processing. |
|
@* |
|
"param_on" applies exclusion processing to command parameters as well as |
|
to files below such parameters. |
|
@* |
|
"subtree_off" with "param_on" excludes parameter paths only if they |
|
match a -not_paths item exactly. |
|
@* |
|
"subtree_on" additionally excludes parameter paths which lead to a file |
|
address below any -not_paths item. |
|
@* |
|
"ignore_off" treats excluded disk files as if they were missing. I.e. they |
|
get reported with -compare and deleted from the image with -update. |
|
@* |
|
"ignore_on" keeps excluded files out of -compare or -update activities. |
|
@c man .TP |
|
@item -not_paths disk_path [***] |
|
@kindex -not_paths sets absolute exclusion paths |
|
@cindex Insert, file exclusion absolute, -not_paths |
|
Add the given paths to the list of excluded absolute disk paths. If a given |
|
path is relative, then the current -cdx is prepended to form an absolute path. |
|
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 "@minus{}@minus{}") |
|
@c man .TP |
|
@item -not_leaf pattern |
|
@kindex -not_leaf sets exclusion pattern |
|
@cindex Insert, file exclusion pattern, -not_leaf |
|
Add a single shell parser style pattern to the list of exclusions for |
|
disk leafnames. These patterns are evaluated when the exclusion checks are |
|
made. |
|
@c man .TP |
|
@item -not_list disk_path |
|
@kindex -not_list sets exclusions from disk file |
|
@cindex Insert, file exclusion from file, -not_list |
|
Read lines from disk_path and use each of them either as -not_paths argument, |
|
if they contain a / character, or as -not_leaf pattern. |
|
@c man .TP |
|
@item -quoted_not_list disk_path |
|
@kindex -quoted_not_list sets exclusions |
|
@cindex Insert, file exclusion, -quoted_not_list |
|
Like -not_list but with quoted input reading rules. Each word is |
|
handled as one argument for -not_paths resp. -not_leaf. |
|
@c man .TP |
|
@item -follow occasion[:occasion[...]] |
|
@kindex -follow softlinks and mount points |
|
@cindex Insert, links or mount points, -follow |
|
Enable or disable resolution of symbolic links and mountpoints under |
|
disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, |
|
and to -disk_pattern expansion. |
|
@* |
|
There are two kinds of follow decisison to be made: |
|
@* |
|
"link" is the hop from a symbolic link to its target file object. |
|
If enabled then symbolic links are handled as their target file objects, |
|
else symbolic links are handled as themselves. |
|
@* |
|
"mount" is the hop from one filesystem to another subordinate filesystem. |
|
If enabled then mountpoint directories are handled as any other directory, |
|
else mountpoints are handled as empty directories if they are encountered in |
|
directory tree traversals. |
|
@* |
|
Less general than above occasions: |
|
@* |
|
"pattern" is mount and link hopping, but only during -disk_pattern expansion. |
|
@* |
|
"param" is link hopping for parameter words (after eventual pattern expansion). |
|
If enabled then -ls*x will show the link targets rather than the links |
|
themselves. -du*x, -findx, and -add will process the link targets but not |
|
follow links in an eventual directory tree below the targets (unless "link" |
|
is enabled). |
|
@* |
|
Occasions can be combined in a colon separated list. All occasions |
|
mentioned in the list will then lead to a positive follow decision. |
|
@* |
|
"off" prevents any positive follow decision. Use it if no other occasion |
|
applies. |
|
@* |
|
Shortcuts: |
|
@* |
|
"default" is equivalent to "pattern:mount:limit=100". |
|
@* |
|
"on" always decides positive. Equivalent to "link:mount". |
|
@* |
|
@sp 1 |
|
|
|
Not an occasion but an optional setting is: |
|
@* |
|
"limit="<number> which sets the maximum number of link hops. |
|
A link hop consists of a sequence of symbolic links and a final target |
|
of different type. Nevertheless those hops can loop. Example: |
|
@* |
|
$ ln -s .. uploop |
|
@* |
|
Link hopping has a built-in loop detection which stops hopping at the first |
|
repetition of a link target. Then the repeated link is handled as itself |
|
and not as its target. |
|
Regrettably one can construct link networks which |
|
cause exponential workload before their loops get detected. |
|
The number given with "limit=" can curb this workload at the risk of truncating |
|
an intentional sequence of link hops. |
|
@c man .TP |
|
@item -pathspecs "on"|"off" |
|
@kindex -pathspecs sets meaning of = with -add |
|
@cindex Insert, meaning of = with -add, -pathspecs |
|
Control parameter interpretation with xorriso actions -add and -path_list. |
|
@* |
|
@cindex Pathspec, _definition |
|
"on" enables pathspecs of the form |
|
@strong{target=source} |
|
like with program mkisofs -graft-points. |
|
It also disables -disk_pattern expansion for command -add. |
|
@* |
|
"off" disables pathspecs of the form target=source |
|
and eventually enables -disk_pattern expansion. |
|
@c man .TP |
|
@item -overwrite "on"|"nondir"|"off" |
|
@kindex -overwrite enables overwriting in ISO |
|
@cindex Insert, enable overwriting, -overwrite |
|
Allow or disallow to overwrite existing files in the |
|
ISO image by files with the same name. |
|
@* |
|
With setting "off", name collisions cause FAILURE events. |
|
With setting "nondir", only directories are protected by such events, other |
|
existing file types get treated with -rm before the new file gets added. |
|
Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an |
|
existing directory and all its subordinates. |
|
@* |
|
If restoring of files is enabled, then the overwrite rule applies to the |
|
target file objects on disk as well, but "on" is downgraded to "nondir". |
|
@c man .TP |
|
@item -split_size number["k"|"m"] |
|
@kindex -split_size enables large file splitting |
|
@cindex Insert, large file splitting, -split_size |
|
Set the threshold for automatic splitting of regular files. Such splitting |
|
maps a large disk file onto a ISO directory with several part files in it. |
|
This is necessary if the size of the disk file exceeds -file_size_limit. |
|
Older operating systems can handle files in mounted ISO 9660 filesystems |
|
only if they are smaller than 2 GiB resp. 4 GiB. |
|
@* |
|
Default is 0 which will exclude files larger than -file_size_limit by a |
|
FAILURE event. |
|
A well tested -split_size is 2047m. Sizes above -file_size_limit are not |
|
permissible. |
|
@* |
|
While 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. |
|
@end table |
|
@c man .TP |
|
@c man .B File manipulations: |
|
@node Manip, CmdFind, SetInsert, Options |
|
@section File manipulations |
|
@c man .PP |
|
The following commands manipulate files in the ISO image, regardless whether |
|
they stem from the loaded image or were newly inserted. |
|
@c man .PP |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -iso_rr_pattern "on"|"ls"|"off" |
|
@kindex -iso_rr_pattern controls pattern expansion |
|
@cindex Pattern expansion, for ISO paths, -iso_rr_pattern |
|
Set the pattern expansion mode for the iso_rr_path 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". |
|
@c man .TP |
|
@item -rm iso_rr_path [***] |
|
@kindex -rm deletes files from ISO image |
|
@cindex Delete, from ISO image, -rm |
|
Delete the given files from the ISO image. |
|
@* |
|
Note: This does not free any space on the -indev media, even if |
|
the deletion is committed to that same media. |
|
@* |
|
The image size will shrink if the image is written to a different |
|
media in modification mode. |
|
@c man .TP |
|
@item -rm_r iso_rr_path [***] |
|
@kindex -rm_r deletes trees from ISO image |
|
@cindex Delete, from ISO image, -rm_r |
|
Delete the given files or directory trees from the ISO image. |
|
See also the note with option -rm. |
|
@c man .TP |
|
@item -rmdir iso_rr_path [***] |
|
@kindex -rmdir deletes ISO directory |
|
@cindex Delete, ISO directory, -rmdir |
|
@cindex Directory, delete, -rmdir |
|
Delete empty directories. |
|
@c man .TP |
|
@item -mv iso_rr_path [***] iso_rr_path |
|
@kindex -mv renames file in ISO image |
|
@cindex Rename, in ISO image, -mv |
|
Rename the given file objects in the ISO tree to the last |
|
argument in the list. Use the same rules as with shell command mv. |
|
@* |
|
If pattern expansion is enabled and if the last argument contains wildcard |
|
characters then it must match exactly one existing file address, or else the |
|
command fails with a FAILURE event. |
|
@c man .TP |
|
@item -chown uid iso_rr_path [***] |
|
@kindex -chown sets ownership in ISO image |
|
@cindex Ownership, in ISO image, -chown |
|
Set ownership of file objects in the ISO image. uid may either be a decimal |
|
number or the name of a user known to the operating system. |
|
@c man .TP |
|
@item -chown_r uid iso_rr_path [***] |
|
@kindex -chown_r sets ownership in ISO image |
|
@cindex Ownership, in ISO image, -chown_r |
|
Like -chown but affecting all files below eventual directories. |
|
@c man .TP |
|
@item -chgrp gid iso_rr_path [***] |
|
@kindex -chgrp sets group in ISO image |
|
@cindex Group, in ISO image, -chgrp |
|
Set group attribute of file objects in the ISO image. gid may either be a |
|
decimal number or the name of a group known to the operating system. |
|
@c man .TP |
|
@item -chgrp_r gid iso_rr_path [***] |
|
@kindex -chgrp_r sets group in ISO image |
|
@cindex Group, in ISO image, -chgrp_r |
|
Like -chgrp but affecting all files below eventual directories. |
|
@c man .TP |
|
@item -chmod mode iso_rr_path [***] |
|
@kindex -chmod sets permissions in ISO image |
|
@cindex Permissions, in ISO image, -chmod |
|
Equivalent to shell command chmod in the ISO image. |
|
mode is either an octal number beginning with "0" or a comma separated |
|
list of statements of the form [ugoa]*[+-=][rwxst]* . |
|
@* |
|
Like: go-rwx,u+rwx . |
|
@* |
|
@strong{Personalities}: |
|
u=user, g=group, o=others, a=all |
|
@* |
|
@strong{Operators}: |
|
+ adds given permissions, - revokes given permissions, |
|
= revokes all old permissions and then adds the given ones. |
|
@* |
|
@strong{Permissions}: |
|
r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit |
|
@* |
|
For octal numbers see man 2 stat. |
|
@c man .TP |
|
@item -chmod_r mode iso_rr_path [***] |
|
@kindex -chmod_r sets permissions in ISO image |
|
@cindex Permissions, in ISO image, -chmod_r |
|
Like -chmod but affecting all files below eventual directories. |
|
@c man .TP |
|
@item -setfacl acl_text iso_rr_path [***] |
|
@kindex -setfacl sets ACL in ISO image |
|
@cindex ACL, set in ISO image, -setfacl |
|
Attach the given ACL to the given iso_rr_paths after deleting their eventually |
|
existing ACLs. |
|
If acl_text is empty, or contains the text "clear" or the text |
|
"@minus{}@minus{}remove-all", |
|
then the existing ACLs will be removed and no new ones will be |
|
attached. Any other content of acl_text will be interpreted as a list of |
|
ACL entries. It may be in the long multi-line format as put out by -getfacl |
|
but may also be abbreviated as follows: |
|
@* |
|
ACL entries are separated by comma or newline. If an entry is empty text or |
|
begins with "#" then it will be ignored. A valid entry has to begin |
|
by a letter out of @{ugom@} for "user", "group", "other", "mask". It has to |
|
contain two colons ":". A non-empty text between those ":" gives a user id |
|
resp. group id. After the second ":" there may be letters out of @{rwx- #@}. |
|
The first three give read, write resp. execute permission. |
|
Letters "-", " " and TAB are ignored. "#" causes the rest of the entry to |
|
be ignored. Letter "X" or any other letters are not supported. Examples: |
|
@* |
|
g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw |
|
@* |
|
group:toolies:rw@minus{},user::rw@minus{},group::r@minus{}@minus{},other::r@minus{}@minus{},mask::rw@minus{} |
|
@* |
|
A valid entry may be prefixed by "d", some following characters and ":". |
|
This indicates that the entry goes to the "default" ACL rather than to the |
|
"access" ACL. Example: |
|
@* |
|
u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx |
|
@c man .TP |
|
@item -setfacl_r acl_text iso_rr_path [***] |
|
@kindex -setfacl_r sets ACL in ISO image |
|
@cindex ACL, set in ISO image, -setfacl_r |
|
Like -setfacl but affecting all files below eventual directories. |
|
@c man .TP |
|
@item -setfacl_list disk_path |
|
@kindex -setfacl_list sets ACL in ISO image |
|
@cindex ACL, set in ISO image, -setfacl_list |
|
Read the output of -getfacl_r or shell command getfacl -R and apply it to the |
|
iso_rr_paths as given in lines beginning with "# file:". This will change |
|
ownership, group and ACL of the given files. |
|
If disk_path is "-" then lines are read from standard input. Line "@@" ends the |
|
list, "@@@@@@" aborts without changing the pending iso_rr_path. |
|
@* |
|
Since -getfacl and getfacl -R strip leading "/" from file paths, the setting of |
|
-cd does always matter. |
|
@c man .TP |
|
@item -setfattr [-]name value iso_rr_path [***] |
|
@kindex -setfattr sets xattr in ISO image |
|
@cindex xattr, set in ISO image, -setfattr |
|
Attach the given xattr pair of name and value to the given iso_rr_paths. |
|
If the given name is prefixed by "-", then the pair with that name gets |
|
removed from the xattr list. If name is "@minus{}@minus{}remove@minus{}all" |
|
then all user namespace |
|
xattr of the given iso_rr_paths get deleted. In case of deletion, value must |
|
be an empty text. |
|
@* |
|
Only names from the user namespace are allowed. I.e. a name has to begin with |
|
"user.", like "user.x" or "user.whatever". |
|
@* |
|
Values and names undergo the normal input processing of xorriso. |
|
See also option -backslash_codes. Other than with option -setfattr_list, |
|
the byte value 0 cannot be expressed via -setfattr. |
|
@c man .TP |
|
@item -setfattr_r [-]name value iso_rr_path [***] |
|
@kindex -setfattr_r sets xattr in ISO image |
|
@cindex xattr, set in ISO image, -setfattr_r |
|
Like -setfattr but affecting all files below eventual directories. |
|
@c man .TP |
|
@item -setfattr_list disk_path |
|
@kindex -setfattr_list sets xattr in ISO image |
|
@cindex xattr, set in ISO image, -setfattr_list |
|
Read the output of -getfattr_r or shell command getfattr -Rd and apply it to |
|
the iso_rr_paths as given in lines beginning with "# file:". All previously |
|
existing user space xattr of the given iso_rr_paths will be deleted. |
|
If disk_path is "-" then lines are read from standard input. |
|
@* |
|
Since -getfattr and getfattr -Rd strip leading "/" from file paths, the setting |
|
of -cd does always matter. |
|
@* |
|
Empty input lines and lines which begin by "#" will be ignored |
|
(except "# file:"). Line "@@" ends the list, "@@@@@@" aborts without changing |
|
the pending iso_rr_path. Other input lines must have the form |
|
@* |
|
name="value" |
|
@* |
|
Name must be from user namespace. I.e. user.xyz where xyz should consist of |
|
printable characters only. The separator "=" is not allowed in names. |
|
Value may contain any kind of bytes. It must be in quotes. Trailing |
|
whitespace after the end quote will be ignored. Non-printables bytes and quotes |
|
must be represented as \XYZ by their octal ASCII code XYZ. |
|
Use code \000 for 0-bytes. |
|
@c man .TP |
|
@item -alter_date type timestring iso_rr_path [***] |
|
@kindex -alter_date sets timestamps in ISO image |
|
@cindex Timestamps, set in ISO image, -alter_date |
|
Alter the date entries of a file in the ISO image. type is |
|
one of "a", "m", "b" for access time, modification time, |
|
both times. |
|
@* |
|
timestring may be in the following formats |
|
(see also section EXAMPLES): |
|
@* |
|
As expected by program date: |
|
MMDDhhmm[[CC]YY][.ss]] |
|
@* |
|
As produced by program date: |
|
@* |
|
[Day] MMM DD hh:mm:ss [TZON] YYYY |
|
@* |
|
Relative times counted from current clock time: |
|
@* |
|
+|-Number["s"|"h"|"d"|"w"|"m"|"y"] |
|
@* |
|
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, |
|
"y"=365.25d plus 1d added to multiplication result. |
|
@* |
|
Absolute seconds counted from Jan 1 1970: |
|
@* |
|
=Number |
|
@* |
|
xorriso's own timestamps: |
|
@* |
|
YYYY.MM.DD[.hh[mm[ss]]] |
|
@* |
|
scdbackup timestamps: |
|
@* |
|
YYMMDD[.hhmm[ss]] |
|
@* |
|
where "A0" is year 2000, "B0" is 2010, etc. |
|
@c man .TP |
|
@item -alter_date_r type timestring iso_rr_path [***] |
|
@kindex -alter_date_r sets timestamps in ISO image |
|
@cindex Timestamps, set in ISO image, -alter_date_r |
|
Like -alter_date but affecting all files below eventual directories. |
|
@end table |
|
@c man .TP |
|
@c man .B Tree traversal command -find: |
|
@node CmdFind, Filter, Manip, Options |
|
@section Tree traversal command -find |
|
@c man .PP |
|
@table @asis |
|
@c man .TP |
|
@item -find iso_rr_path [test [op] [test ...]] [-exec action [params]] @minus{}@minus{} |
|
@kindex -find traverses and alters ISO tree |
|
@cindex Tree, ISO, traverse and alter, -find |
|
A restricted substitute for shell command find in the ISO image. |
|
It performs an action on matching file objects at or below iso_rr_path. |
|
@* |
|
If not used as last command in the line then the argument list |
|
needs to get terminated by "@minus{}@minus{}". |
|
@* |
|
Tests are optional. If they are omitted then action is applied to all file |
|
objects. If tests are given then they form together an expression. |
|
The action is applied only if the expression matches the file object. Default |
|
expression operator between tests is -and, i.e. the expression matches only |
|
if all its tests match. |
|
@* |
|
Available tests are: |
|
@* |
|
@table @asis |
|
@sp 1 |
|
@item -name pattern : |
|
Matches if pattern matches the file leaf name. |
|
@* |
|
@item -wholename pattern : |
|
Matches if pattern matches the file path as it would be printed by action |
|
"echo". Character '/' is not special but can be matched by wildcards. |
|
@* |
|
@item -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 |
|
@* |
|
@item -damaged : |
|
Matches files which use data blocks marked as damaged by a previous |
|
run of -check_media. The damage info vanishes when a new ISO image gets |
|
loaded. |
|
@* |
|
@item -pending_data : |
|
Matches files which get their content from outside the loaded ISO image. |
|
@* |
|
@item -lba_range start_lba block_count : |
|
Matches files which use data blocks within the range of start_lba |
|
and start_lba+block_count-1. |
|
@* |
|
@item -has_acl : |
|
Matches files which have a non-trivial ACL. |
|
@* |
|
@item -has_xattr : |
|
Matches files which have xattr name-value pairs from user namespace. |
|
@* |
|
@item -has_aaip : |
|
Matches files which have ACL or any xattr. |
|
@* |
|
@item -has_any_xattr : |
|
Matches files which have any xattr other than ACL. |
|
@* |
|
@item -has_md5 : |
|
Matches data files which have MD5 checksums. |
|
@* |
|
@item -has_filter : |
|
Matches files which are filtered by -set_filter. |
|
@* |
|
@item -prune : |
|
If this test is reached and the tested file is a directory then -find will not |
|
dive into that directory. This test itself does always match. |
|
@* |
|
@item -decision "yes"|"no" : |
|
If this test is reached then the evaluation ends immediately and action |
|
is performed if the decision is "yes" or "true". See operator -if. |
|
@* |
|
@c man \fB\-true\fR and \fB\-false\fR : |
|
@c man-ignore-lines 1 |
|
@item -true and -false : |
|
Always match resp. match not. Evaluation goes on. |
|
@* |
|
@item -sort_lba : |
|
Always match. This causes -find to perform its action in a sequence sorted by |
|
the ISO image block addresses of the files. It may improve throughput with |
|
actions which read data from optical drives. Action will always get the |
|
absolute path as parameter. |
|
@* |
|
Available operators are: |
|
@* |
|
@item -not : |
|
Matches if the next test or sub expression does not match. |
|
Several tests do this specifically: |
|
@* |
|
-undamaged, -lba_range with negative start_lba, -has_no_acl, -has_no_xattr, |
|
-has_no_aaip, -has_no_filter . |
|
@* |
|
@item -and : |
|
Matches if both neighboring tests or expressions match. |
|
@* |
|
@item -or : |
|
Matches if at least one of both neighboring tests or expressions matches. |
|
@* |
|
@c man \fB\-sub\fR ... \fB\-subend\fR or \fB(\fR ... \fB)\fR : |
|
@c man-ignore-lines 1 |
|
@item -sub ... -subend or ( ... ) : |
|
Enclose a sub expression which gets evaluated first before it |
|
is processed by neighboring operators. |
|
Normal precedence is: -not, -or , -and. |
|
@* |
|
@c man \fB\-if\fR ... \fB\-then\fR\ ... \fB\-elseif\fR ... \fB\-then\fR ... |
|
@c man \fB\-else\fR ... \fB\-endif\fR : |
|
@c man-ignore-lines 1 |
|
@item -if ... -then\ ... -elseif ... -then ... -else ... -endif : |
|
Enclose one or more sub expressions. If the -if expression matches, then |
|
the -then expression is evaluated as the result of the whole expression |
|
up to -endif. Else the next -elseif expression is evaluated and 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. |
|
@end table |
|
@sp 1 |
|
|
|
Default action is @strong{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. |
|
@c man .br |
|
@table @asis |
|
@sp 1 |
|
@c man \fBchown\fR and \fBchown_r\fR |
|
@c man-ignore-lines 1 |
|
@item chown and chown_r |
|
change the ownership and get the user id |
|
as parameter. E.g.: -exec chown thomas @minus{}@minus{} |
|
@* |
|
@c man \fBchgrp\fR and \fBchgrp_r\fR |
|
@c man-ignore-lines 1 |
|
@item chgrp and Bchgrp_r |
|
change the group attribute and get the group id |
|
as parameter. E.g.: -exec chgrp_r staff @minus{}@minus{} |
|
@* |
|
@c man \fBchmod\fR and \fBchmod_r\fR |
|
@c man-ignore-lines 1 |
|
@item chmod and chmod_r |
|
change access permissions and get a mode string |
|
as parameter. E.g.: -exec chmod a-w,a+r @minus{}@minus{} |
|
@* |
|
@c man \fBalter_date\fR and \fBalter_date_r\fR |
|
@c man-ignore-lines 1 |
|
@item Balter_date and Balter_date_r |
|
change the timestamps. They get a type |
|
character and a timestring as parameters. |
|
@* |
|
E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" @minus{}@minus{} |
|
@* |
|
@item lsdl |
|
prints file information like shell command ls -dl. |
|
@* |
|
@item compare |
|
performs command -compare with the found file address as |
|
iso_rr_path and the corresponding file address below its 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 @minus{}@minus{} |
|
@* |
|
@item update |
|
performs command -update with the found file address as |
|
iso_rr_path. The corresponding file address is determined like with above |
|
action "compare". |
|
@* |
|
@item rm |
|
removes the found iso_rr_path from the image if it is not a directory |
|
with files in it. I.e. this "rm" includes "rmdir". |
|
@* |
|
@item rm_r |
|
removes the found iso_rr_path from the image, including whole |
|
directory trees. |
|
@* |
|
@item 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. |
|
@* |
|
@item report_lba |
|
prints files which are associated to image data blocks. |
|
It tells the logical block address, the block number, the byte size, |
|
and the path of each file. There may be reported more than one |
|
line per file if the file is very large. In this case each line has a |
|
different extent number in column "xt". |
|
@* |
|
@item getfacl |
|
prints access permissions in ACL text form to the result channel. |
|
@* |
|
@item setfacl |
|
attaches ACLs after removing 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::@minus{},m::rw @minus{}@minus{} |
|
@* |
|
@item getfattr |
|
prints eventual xattr name-value pairs from user namespace |
|
to the result channel. |
|
@* |
|
@item 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". |
|
@* |
|
@item get_md5 |
|
prints eventual recorded MD5 sum together with file path. |
|
@* |
|
@item 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 @minus{}@minus{} |
|
@* |
|
@item make_md5 |
|
equips a data file with an MD5 sum of its content. Useful to |
|
upgrade the files in the loaded image to full MD5 coverage by the next |
|
commit with -md5 "on". |
|
@* |
|
E.g.: -find / -type f -not -has_md5 -exec make_md5 @minus{}@minus{} |
|
@* |
|
@item setfattr |
|
sets or deletes xattr name value pairs. |
|
@* |
|
E.g.: -find / -has_xattr -exec setfattr @minus{}@minus{}remove-all '' @minus{}@minus{} |
|
@* |
|
@item set_filter |
|
applies or removes filters. |
|
@* |
|
E.g.: -exec set_filter @minus{}@minus{}zisofs @minus{}@minus{} |
|
@* |
|
@item show_stream |
|
shows the content stream chain of a data file. |
|
@* |
|
@item find |
|
performs another run of -find on the matching file address. |
|
It accepts the same params as -find, except iso_rr_path. |
|
@* |
|
E.g.: |
|
@* |
|
-find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r @minus{}@minus{} |
|
@end table |
|
@end table |
|
@c man .TP |
|
@c man .B Filters for data file content: |
|
@c man .PP |
|
@node Filter, Writing, CmdFind, Options |
|
@section Filters for data file content |
|
@cindex Filter, _definition |
|
@strong{Filters} may be installed between data files in the ISO image and their |
|
content source outside the image. They may also be used vice versa between |
|
data content in the image and target files on disk. |
|
@* |
|
@sp 1 |
|
Built-in filters are "@minus{}@minus{}zisofs" and |
|
"@minus{}@minus{}zisofs-decode". The former is to be |
|
applied via -set_filter, the latter is automatically applied if zisofs |
|
compressed content is detected with a file when loading the ISO image. |
|
@* |
|
Another built-in filter pair is "@minus{}@minus{}gzip" |
|
and "@minus{}@minus{}gunzip" with suffix ".gz". |
|
They behave about like external gzip and gunzip but avoid forking a process |
|
for each single file. So they are much faster if there are many small files. |
|
@c man .PP |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -external_filter name option[:option] program_path [arguments] @minus{}@minus{} |
|
@kindex -external_filter registers data filter |
|
@cindex Filter, register, -external_filter |
|
Register a content filter by associating a name with a program path, |
|
program arguments, and some behavioral options. Once registered it can be |
|
applied to multiple data files in the ISO image, regardless whether their |
|
content resides in the loaded ISO image or in the local filesystem. |
|
External filter processes may produce synthetic file content by reading the |
|
original content from stdin and writing to stdout whatever they want. |
|
They must deliver the same output on the same input in repeated runs. |
|
@* |
|
Options are: |
|
@* |
|
"default" means that no other option is intended. |
|
@* |
|
"suffix=..." sets a file name suffix. If it is not empty then it will be |
|
appended to the file name or removed from it. |
|
@* |
|
"remove_suffix" will remove 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 @minus{}@minus{} |
|
@* |
|
-external_filter bunzip2 suffix=.bz2:remove_suffix \ |
|
@* |
|
/usr/bin/bunzip2 @minus{}@minus{} |
|
@c man .TP |
|
@item -unregister_filter name |
|
@kindex -external_filter unregisters data filter |
|
@cindex Filter, unregister, -unregister_filter |
|
Remove an -external_filter registration. This is only possible if the filter |
|
is not applied to any file in the ISO image. |
|
@c man .TP |
|
@item -close_filter_list |
|
@kindex -close_filter_list bans filter registration |
|
@cindex Filter, ban registration, -close_filter_list |
|
Irrevocably ban commands -external_filter and -unregister_filter, |
|
but not -set_filter. Use this to prevent external filtering in general or |
|
when all intended filters are registered. |
|
External filters may also be banned totally at compile time of xorriso. |
|
By default they are banned if xorriso runs under setuid permission. |
|
@c man .TP |
|
@item -set_filter name iso_rr_path [***] |
|
@kindex -set_filter applies filter to file |
|
@cindex Filter, apply to file, -set_filter |
|
Apply an -external_filter or a built-in filter to the given data files in the |
|
ISO image. |
|
If the filter suffix is not empty , then it will be applied to the file name. |
|
Renaming only happens if the filter really gets attached and is not revoked by |
|
its options. |
|
By default files which already bear the suffix will not get filtered. The |
|
others will get the suffix appended to their names. |
|
If the filter has option "remove_suffix", then the filter will only be |
|
applied if the suffix is present and can be removed. |
|
Name oversize or collision caused by suffix change will prevent filtering. |
|
@* |
|
With most filter types this command will immediately run the filter once for |
|
each file in order to determine the output size. |
|
Content reading operations like -extract , -compare and image generation will |
|
perform further filter runs and deliver filtered content. |
|
@* |
|
At image generation time the filter output must still be the same as the |
|
output from the first run. Filtering for image generation does not happen |
|
with files from the loaded ISO image if the write method of growing is in |
|
effect (i.e -indev and -outdev are identical). |
|
@* |
|
The reserved filter name "@minus{}@minus{}remove-all-filters" revokes |
|
filtering. This will revoke eventual suffix renamings as well. |
|
Use "@minus{}@minus{}remove-all-filters+" to |
|
prevent any suffix renaming. |
|
@c man .TP |
|
@item -set_filter_r name iso_rr_path [***] |
|
@kindex -set_filter_r applies filter to file tree |
|
@cindex Filter, apply to file tree, -set_filter_r |
|
Like -set_filter but affecting all data files below eventual directories. |
|
@end table |
|
@c man .TP |
|
@c man .B Writing the result, drive control: |
|
@node Writing, SetWrite, Filter, Options |
|
@section Writing the result, drive control |
|
@c man .PP |
|
(see also paragraph about settings below) |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -rollback |
|
@kindex -rollback discards pending changes |
|
@cindex Image, discard pending changes, -rollback |
|
Discard the manipulated ISO image and reload it from -indev. |
|
(Use -rollback_end if immediate program end is desired.) |
|
@c man .TP |
|
@item -commit |
|
@kindex -commit writes pending ISO image |
|
@cindex Write, pending ISO image, -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. |
|
@c man .TP |
|
@item -eject "in"|"out"|"all" |
|
@kindex -eject ejects drive tray |
|
@cindex Drive, eject tray, -eject |
|
Eject the media in -indev, resp. -outdev, resp. both drives. |
|
Note: It is not possible yet to effectively eject disk files. |
|
@c man .TP |
|
@item -commit_eject "in"|"out"|"all"|"none" |
|
@kindex -commit_eject writes and ejects |
|
@cindex Drive, write and eject, -commit_eject |
|
Combined -commit and -eject. When writing has finished do not make |
|
-outdev the new -dev, and load no ISO image. Rather eject |
|
-indev and/or -outdev. Eventually give up any non-ejected drive. |
|
@c man .TP |
|
@item -blank mode |
|
@kindex -blank erases media |
|
@cindex Media, erase, -blank |
|
Make media ready for writing from scratch (if not -dummy is activated). |
|
@* |
|
This affects only the -outdev not the -indev. |
|
If both drives are the same and if the ISO image was altered |
|
then this command leads to a FAILURE event. |
|
Defined modes are: |
|
as_needed, fast, all, deformat, deformat_quickest |
|
@* |
|
"as_needed" cares for used CD-RW, DVD-RW and for used overwriteable media |
|
by applying -blank "fast". It applies -format "full" to yet unformatted |
|
DVD-RAM and BD-RE. Other media in blank state are gracefully ignored. |
|
Media which cannot be made ready for writing from scratch cause a FAILURE |
|
event. |
|
@* |
|
"fast" makes CD-RW and unformatted DVD-RW re-usable, or invalidates |
|
overwriteable ISO images. "all" might work more thoroughly and need more time. |
|
@* |
|
"deformat" converts overwriteable DVD-RW into unformatted ones. |
|
@* |
|
"deformat_quickest" is a faster way to deformat or blank DVD-RW |
|
but produces media which are only suitable for a single session. |
|
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. |
|
@c man .TP |
|
@item -format mode |
|
@kindex -format formats media |
|
@cindex Media, format, -format |
|
Convert unformatted DVD-RW into overwriteable ones, "de-ice" DVD+RW, format |
|
newly purchased BD-RE or BD-R, re-format DVD-RAM or BD-RE. |
|
@* |
|
Defined modes are: |
|
@* |
|
as_needed, full, fast, by_index_<num>, fast_by_index_<num> |
|
@* |
|
"as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or blank |
|
unformatted BD-R. Other media are left untouched. |
|
@* |
|
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank unformatted BD-R. |
|
@* |
|
"fast" does the same as "full" but tries to be quicker. |
|
@* |
|
"by_index_" selects a format out of the descriptor list issued by 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. |
|
@c man .TP |
|
@item -list_formats |
|
@kindex -list_formats lists available formats |
|
@cindex Media, list formats, -list_formats |
|
Put out a list of format descriptors as reported by the output drive for |
|
the current 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. |
|
@c man .TP |
|
@item -list_profiles "in"|"out"|"all" |
|
@kindex -list_profiles lists supported media |
|
@cindex Drive, list supported media, -list_profiles |
|
Put out a list of media types supported by -indev, resp. -outdev, resp. both. |
|
The currently recognized type is marked by text "(current)". |
|
@end table |
|
@c man .TP |
|
@c man .B Settings for result writing: |
|
@node SetWrite, Bootable, Writing, Options |
|
@section Settings for result writing |
|
@c man .PP |
|
Rock Ridge info will be generated by the program unconditionally. |
|
ACLs will be written according to the setting of option -acl. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -joliet "on"|"off" |
|
@kindex -joliet enables production of Joliet tree |
|
@cindex Write, enable Joliet, -joliet |
|
If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge |
|
tree. |
|
@c man .TP |
|
@item -compliance rule[:rule...] |
|
@kindex -compliance controls standard compliance |
|
@cindex Write, compliance to specs, -compliance |
|
Adjust the compliance to specifications of ISO 9660 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 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. |
|
@* |
|
"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. |
|
@* |
|
Default setting is |
|
@* |
|
"clear:deep_paths:long_paths: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. |
|
@c man .TP |
|
@item -volid text |
|
@kindex -volid sets volume id |
|
@cindex Image, set volume id, -volid |
|
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. |
|
@c man .TP |
|
@item -volset_id text |
|
@kindex -volset_id sets volume set id |
|
@cindex Image, set volume set id, -volset_id |
|
Set the volume set id string to be written with the next -commit. |
|
Permissible are up to 128 characters. This setting gets overridden by |
|
image loading. |
|
@c man .TP |
|
@item -publisher text |
|
@kindex -publisher sets publisher id |
|
@cindex Image, set publisher id, -publisher |
|
Set the publisher id string to be written with the next -commit. This may |
|
identify the person or organisation who specified what shall be recorded. |
|
Permissible are up to 128 characters. This setting gets overridden by |
|
image loading. |
|
@c man .TP |
|
@item -application_id text |
|
@kindex -application_id sets application id |
|
@cindex Image, set application id, -application_id |
|
Set the application id string to be written with the next -commit. This may |
|
identify the specification of how the data are recorded. |
|
Permissible are up to 128 characters. This setting gets overridden by |
|
image loading. |
|
@c man .TP |
|
@item -system_id text |
|
@kindex -system_id sets system id |
|
@cindex Image, set system id, -system_id |
|
Set the system id string to be written with the next -commit. This may |
|
identify the system which can recognize and act upon the content of the |
|
System Area in image blocks 0 to 15. |
|
Permissible are up to 32 characters. This setting gets overridden by |
|
image loading. |
|
@c man .TP |
|
@item -out_charset character_set_name |
|
@kindex -out_charset sets output character set |
|
@cindex Character Set, for output, -out_charset |
|
Set the character set to which file names get converted when writing an |
|
image. See paragraph "Character sets" for more explanations. |
|
When loading the written image after -commit the setting of -out_charset |
|
will be copied to -in_charset. |
|
@c man .TP |
|
@item -uid uid |
|
@kindex -uid sets global ownership |
|
@cindex Ownership, global in ISO image, -uid |
|
User id to be used for all files when the new ISO tree gets written to media. |
|
@c man .TP |
|
@item -gid gid |
|
@kindex -gid sets global ownership |
|
@cindex Group, global in ISO image, -gid |
|
Group id to be used for all files when the new ISO tree gets written to media. |
|
@c man .TP |
|
@item -zisofs option[:options] |
|
@kindex -zisofs controls zisofs production |
|
@cindex Filter, zisofs parameters, -zisofs |
|
Set global parameters for zisofs compression. This data format is recognized |
|
and transparently uncompressed by some Linux kernels. It is to be applied |
|
via option -set_filter with built-in filter "@minus{}@minus{}zisofs". |
|
Parameters are: |
|
@* |
|
"level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow |
|
@* |
|
"block_size="32k|64k|128k size of compression blocks |
|
@* |
|
"by_magic=on" enables an expensive test at image generation time which checks |
|
files from disk whether they already are zisofs compressed, e.g. by program |
|
mkzftree. |
|
@* |
|
"default" same as "level=6:block_size=32k:by_magic=off" |
|
@c man .TP |
|
@item -speed number[k|m|c|d|b] |
|
@kindex -speed set write speed |
|
@cindex Write, set speed, -speed |
|
Set the burn speed. Default is 0 = maximum speed. |
|
Speed can be given in media dependent numbers or as a |
|
desired throughput per second in MMC compliant kB (= 1000) |
|
or MB (= 1000 kB). Media x-speed factor can be set explicity |
|
by "c" for CD, "d" for DVD, "b" for BD, "x" is optional. |
|
@* |
|
Example speeds: |
|
@* |
|
706k = 706kB/s = 4c = 4xCD |
|
@* |
|
5540k = 5540kB/s = 4d = 4xDVD |
|
@* |
|
If there is no hint about the speed unit attached, then the |
|
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. |
|
@c man .TP |
|
@item -stream_recording "on"|"off"|"full"|"data"|number |
|
@kindex -stream_recording controls defect management |
|
@cindex Write, defect management, -stream_recording |
|
Setting "on" tries to circumvent the management of defects on DVD-RAM, BD-RE, |
|
or BD-R. Defect management keeps partly damaged media usable. But it reduces |
|
write speed to half nominal speed even if the 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. |
|
@c man .TP |
|
@item -dvd_obs "default"|"32k"|"64k" |
|
@kindex -dvd_obs set write block size |
|
@cindex Write, block size, -dvd_obs |
|
GNU/Linux specific: |
|
Set the number of bytes to be transmitted with each write operation to DVD |
|
or BD media. A number of 64 KB may improve throughput with bus systems which |
|
show latency problems. The default depends on media type, on option |
|
-stream_recording , and on compile time options. |
|
@c man .TP |
|
@item -stdio_sync "on"|"off"|number |
|
@kindex -stdio_sync controls stdio buffer |
|
@cindex Write, buffer syncing, -stdio_sync |
|
Set the number of bytes after which to force output to stdio: pseudo drives. |
|
This forcing keeps the memory from being clogged with lots of |
|
pending data for slow devices. Default "on" is the same as "16m". |
|
Forced output can be disabled by "off". |
|
@c man .TP |
|
@item -dummy "on"|"off" |
|
@kindex -dummy controls write simulation |
|
@cindex Write, simulation, -dummy |
|
If "on" then simulate burning or refuse with FAILURE event if |
|
no simulation is possible, do neither blank nor format. |
|
@c man .TP |
|
@item -fs number["k"|"m"] |
|
@kindex -fs sets size of fifo |
|
@cindex Write, fifo size, -fs |
|
Set the size of the fifo buffer which smoothens the data |
|
stream from ISO image generation to media burning. Default |
|
is 4 MiB, minimum 64 kiB, maximum 1 GiB. |
|
The number may be followed by letter "k" or "m" |
|
which means unit is kiB (= 1024) or MiB (= 1024 kiB). |
|
@c man .TP |
|
@item -close "on"|"off" |
|
@kindex -close controls media closing |
|
@cindex Write, close media, -close |
|
If "on" then mark the written 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. |
|
@c man .TP |
|
@item -padding number["k"|"m"] |
|
@kindex -padding sets amount of image padding |
|
@cindex Write, padding image, -padding |
|
Append the given number of extra bytes to the image stream. |
|
This is a traditional remedy for a traditional bug in block |
|
device read drivers. Needed only for CD recordings in TAO mode. |
|
Since one can hardly predict on what media an image might end up, |
|
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 . |
|
@end table |
|
@c man .TP |
|
@c man .B El Torito bootable ISO images: |
|
@node Bootable, Charset, SetWrite, Options |
|
@section El Torito bootable ISO images |
|
@c man .PP |
|
Contrary to published specifications many BIOSes will load an El Torito |
|
object 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 ISOLINUX 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. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -boot_image "any"|"isolinux" |
|
@kindex -boot_image controls bootability |
|
@cindex Write, bootability, -boot_image |
|
@cindex Bootability, control, -boot_image |
|
@* |
|
"discard"|"keep"|"patch"|"show_status"|bootspec |
|
@* |
|
Define the handling of an eventual El Torito object which has |
|
been read from an existing ISO image or define how to make a prepared |
|
ISOLINUX file set bootable. |
|
@* |
|
@sp 1 |
|
|
|
All types ("any") of El Torito boot images can be discarded or kept unaltered. |
|
The latter makes only sense if the format of the boot image is |
|
relocatable without content changes. |
|
@* |
|
With any type, "show_status" will print what is known about the loaded image |
|
and its designated fate. |
|
@* |
|
An existing boot image of type "isolinux" can be discarded or it can be |
|
patched to match its relocation. In the latter case the resulting ISO image |
|
stays bootable if the boot image was really produced by ISOLINUX. |
|
@* |
|
CAUTION: |
|
This is an expert option. |
|
xorriso cannot recognize the inner form of boot images. |
|
So the user has already to know about the particular needs of the |
|
boot image which is present on the input media. |
|
@* |
|
Most safe is the default: -boot_image "any" "discard". |
|
@* |
|
@sp 1 |
|
|
|
A bootspec is a word of the form name=value and is used to describe the |
|
activation of a ISOLINUX boot image by an El Torito record and eventually |
|
a MBR. The names "dir" and "bin_path" lead to boot image activation. |
|
@* |
|
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 ISOLINUX files have to be added to the ISO image by normal means |
|
(image loading, -map, -add, ...) and 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 |
|
@* |
|
bin_path depicts the binary program which is to be started by the BIOS at |
|
boot time. It is among the files produced by ISOLINUX. |
|
@* |
|
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. |
|
@* |
|
Bootspec "isohybrid=off" disables MBR generation, "isohybrid=on" prevents the |
|
write session if not the isohybrid signature is found in the bin_path file. |
|
Default is "isohybrid=auto" which silently omits the MBR if the signature is |
|
missing. |
|
@end table |
|
@c man .TP |
|
@c man .B Character sets: |
|
@node Charset, Exception, Bootable, Options |
|
@section Character sets |
|
@c man .PP |
|
@cindex Character Set, _definition |
|
File names are strings of non-zero bytes with 8 bit each. Unfortunately |
|
the same byte string may appear as different peculiar national characters |
|
on differently nationalized terminals. |
|
The meanings of byte codes are defined in @strong{character sets} which have |
|
names. Shell command iconv -l lists them. |
|
@* |
|
Character sets should not matter as long as only english alphanumeric |
|
characters are used for file names or as long as all writers and readers |
|
of the media use the same character set. |
|
Outside these constraints it may be necessary to let 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. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -charset character_set_name |
|
@kindex -charset sets input/output character set |
|
@cindex Character Set, for input/output, -charset |
|
Set the character set from which to convert file names when loading an |
|
image and to which to convert when writing an image. |
|
@c man .TP |
|
@item -local_charset character_set_name |
|
@kindex -local_charset sets terminal character set |
|
@cindex Character Set, of terminal, -local_charset |
|
Override the system assumption of the local character set name. |
|
If this appears necessary, one should consider to set -backslash_codes to |
|
"on" in order to avoid dangerous binary codes being sent to the terminal. |
|
@end table |
|
@c man .TP |
|
@c man .B Exception processing: |
|
@node Exception, DialogCtl, Charset, Options |
|
@section Exception processing |
|
@c man .PP |
|
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. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -abort_on severity |
|
@kindex -abort_on controls abort on error |
|
@cindex Process, control abort on error, -abort_on |
|
Set the severity threshold for events to abort the program. |
|
@* |
|
Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY" |
|
@* |
|
It may become necessary to abort the program anyway, despite |
|
the setting by this 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. |
|
@c man .TP |
|
@item -return_with severity exit_value |
|
@kindex -return_with controls exit value |
|
@cindex Process, control exit value, -return_with |
|
Set the threshold and exit_value to be returned at program end if no abort |
|
has happened. This is to allow 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 |
|
@c man .TP |
|
@item -report_about severity |
|
@kindex -report_about controls verbosity |
|
@cindex Process, control verbosity, -report_about |
|
Set the threshold for events to be reported. |
|
@* |
|
Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL" |
|
@* |
|
Regardless what is set by -report_about, messages get always reported if they |
|
reach the severity threshold of -abort_on . |
|
@* |
|
Event messages are sent to the info channel "I" which is usually stderr |
|
but may be influenced by command -pkt_output. |
|
Info messages which belong to no event get attributed severity "NOTE". |
|
@* |
|
A special property of this 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. |
|
@c man .TP |
|
@item -error_behavior occasion behavior |
|
@kindex -error_behavior controls error workarounds |
|
@cindex Process, error workarounds, -error_behavior |
|
Control the program behavior at problem event occasions. |
|
For now this applies to occasions "image_loading" which is given while |
|
an image tree is read from the input device, and to "file_extraction" which |
|
is given with osirrox 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. |
|
@end table |
|
@c man .TP |
|
@c man .B Dialog mode control: |
|
@node DialogCtl, Inquiry, Exception, Options |
|
@section Dialog mode control |
|
@table @asis |
|
@c man .TP |
|
@item -dialog "on"|"off"|"single_line" |
|
@kindex -dialog enables dialog mode |
|
@cindex Dialog, enable dialog mode, -dialog |
|
Enable or disable to enter dialog mode after all 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. |
|
@c man .TP |
|
@item -page length width |
|
@kindex -page set terminal geometry |
|
@cindex Dialog, terminal geometry, -page |
|
Describe terminal to the text pager. See also above, paragraph Result pager. |
|
@* |
|
If parameter length is nonzero then the user gets prompted after that |
|
number of terminal lines. Zero length disables paging. |
|
@* |
|
Parameter width is the number of characters per terminal line. It is used |
|
to compute the number of terminal lines which get occupied by an output line. |
|
A usual terminal width is 80. |
|
@c man .TP |
|
@item -use_readline "on"|"off" |
|
@kindex -use_readline enables readline for dialog |
|
@cindex Dialog, line editing, -use_readline |
|
If "on" then use readline for dialog. Else use plain stdin. |
|
@* |
|
See also above, paragraph Dialog, Readline, Result pager. |
|
@c man .TP |
|
@item -reassure "on"|"tree"|"off" |
|
@kindex -reassure enables confirmation question |
|
@cindex Dialog, confirmation question, -reassure |
|
If "on" then ask the user for "y" or "n": |
|
@* |
|
before deleting or overwriting any file in the ISO image, |
|
@* |
|
before overwriting any disk file during restore operations, |
|
@* |
|
before rolling back pending image changes, |
|
@* |
|
before committing image changes to media, |
|
@* |
|
before changing the input drive, |
|
@* |
|
before blanking or formatting media, |
|
@* |
|
before ending the program. |
|
@* |
|
With setting "tree" the reassuring prompt will appear for an eventual |
|
directory only once and not for each file in its whole subtree. |
|
@* |
|
Setting "off" silently kills any kind of image file object resp. performs |
|
above irrevocable actions. |
|
@* |
|
To really produce user prompts, 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. |
|
@end table |
|
@c man .TP |
|
@c man .B Drive and media related inquiry actions: |
|
@node Inquiry, Navigate, DialogCtl, Options |
|
@section Drive and media related inquiry actions |
|
@table @asis |
|
@c man .TP |
|
@item -devices |
|
@kindex -devices gets list of drives |
|
@cindex Drive, get drive list, -devices |
|
Show list of available MMC drives with the addresses of |
|
their libburn standard device files. |
|
@* |
|
This is only possible when no ISO image changes are pending. |
|
After this 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 |
|
@strong{superuser} |
|
who is able to see all drives. |
|
@* |
|
Drives which are occupied by other processes get not shown. |
|
@c man .TP |
|
@item -toc |
|
@* |
|
@kindex -toc shows list of sessions |
|
@cindex Table-of-content, show, -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. |
|
@c man .TP |
|
@item -mount_cmd drive entity id path |
|
@kindex -mount_cmd composes mount command line |
|
@cindex Session, mount command line, -mount_cmd |
|
Emit an appropriate command line for mounting the ISO session |
|
indicated by drive, entity and id. |
|
The result will be different on GNU/Linux and on FreeBSD. |
|
@* |
|
drive can be "indev" or "outdev" to indicate already acquired drives, |
|
or it can be the path of a not yet acquired drive. |
|
Prefix "stdio:" for non-MMC drives is not mandatory. |
|
@* |
|
entity must be either "sbsector" with the superblock sector address as id, |
|
or "track" with a track number as id, or "session" with a session number, |
|
or "volid" with a search pattern for the volume id, or "auto" with any text |
|
as id. |
|
@* |
|
path will be used as mount point and must already exist as a directory on disk. |
|
@* |
|
The command gets printed to the result channel. See option -mount |
|
for direct execution of this command. |
|
@c man .TP |
|
@item -mount_opts option[:option...] |
|
@kindex -mount_cmd controls mount command |
|
@cindex Session, mount parameters, -mount_opts |
|
Set options which influence -mount and -mount_cmd. Currently there is only |
|
option "exclusive" which is default and its counterpart "shared". The latter |
|
causes 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. |
|
@c man .TP |
|
@item -session_string drive entity id format |
|
@kindex -session_string composes session info line |
|
@cindex Session, info string, -session_string |
|
Print to the result channel a text which gets composed according to |
|
format and the parameters of the addressed session. |
|
@* |
|
Formats "linux:"path or "freebsd:"path produce the output of -mount_cmd |
|
for the given operating systems. |
|
@* |
|
In other texts xorriso will substitute the following parameter names. |
|
An optional prefix "string:" will be removed. |
|
@* |
|
"%device%" will be substituted by the mountable device path of the drive |
|
address. |
|
@* |
|
"%sbsector%" will be substituted by the session start sector. |
|
@* |
|
"%track%", "%session%", "%volid%" will be substituted by track number, |
|
session number, resp. volume id of the depicted session. |
|
@c man .TP |
|
@item -print_size |
|
@kindex -print_size predicts image size |
|
@cindex Write, predict image size, -print_size |
|
Print the foreseeable consumption of 2048 byte blocks |
|
by next -commit. This can last a while as a -commit gets |
|
prepared and only in last moment is revoked by this option. |
|
@c man .TP |
|
@item -tell_media_space |
|
@kindex -tell_media_space reports free space |
|
@cindex Write, free space, -tell_media_space |
|
Print available space on output media and the free space after |
|
subtracting already foreseeable consumption by next -commit. |
|
@c man .TP |
|
@item -pvd_info |
|
@kindex -pvd_info shows image id strings |
|
@cindex Image, show id strings, -pvd_info |
|
Print various id strings which can be found in loaded ISO images. Some of |
|
them may be changed by options -volid, -publisher, -application_id. For these |
|
ids -pvd_info reports what would be written with the next -commit. |
|
@end table |
|
@c man .TP |
|
@c man .B Navigation in ISO image and disk filesystem: |
|
@node Navigate, Verify, Inquiry, Options |
|
@section Navigation in ISO image and disk filesystem |
|
@table @asis |
|
@c man .TP |
|
@item -cd iso_rr_path |
|
@kindex -cd sets working directory in ISO |
|
@cindex Navigate, set ISO working directory, -cd |
|
Change the current working directory in the ISO image. |
|
This is prepended to iso_rr_paths which do not begin with '/'. |
|
@* |
|
It is possible to set the working directory to a path which does not exist |
|
yet in the ISO image. The necessary parent directories will be created when |
|
the first file object is inserted into that virtual directory. |
|
Use -mkdir if you want to enforce the existence of the directory already at |
|
first insertion. |
|
@c man .TP |
|
@item -cdx disk_path |
|
@kindex -cdx sets working directory on disk |
|
@cindex Navigate, set disk working directory, -cdx |
|
Change the current working directory in the local filesystem. |
|
To be prepended to disk_paths which do not begin with '/'. |
|
@c man .TP |
|
@item -pwd |
|
@* |
|
@kindex -pwd tells working directory in ISO |
|
@cindex Navigate, tell ISO working directory, -pwd |
|
Tell the current working directory in the ISO image. |
|
@c man .TP |
|
@item -pwdx |
|
@kindex -pwdx tells working directory on disk |
|
@cindex Navigate, tell disk working directory, -pwdx |
|
@* |
|
Tell the current working directory in the local filesystem. |
|
@c man .TP |
|
@item -ls iso_rr_pattern [***] |
|
@kindex -ls lists files in ISO image |
|
@cindex Navigate, list ISO files, -ls |
|
List files in the ISO image which match shell patterns |
|
(i.e. with wildcards '*' '?' '[a-z]'). |
|
If a pattern does not begin with '/' then it is compared with addresses |
|
relative to -cd. |
|
@* |
|
Directories are listed by their content rather than as single file item. |
|
@* |
|
Pattern expansion may be disabled by command -iso_rr_pattern. |
|
@c man .TP |
|
@item -lsd iso_rr_pattern [***] |
|
@kindex -lsd lists files in ISO image |
|
@cindex Navigate, list ISO files, -lsd |
|
Like -ls but listing directories as themselves and not by their content. |
|
This resembles shell command ls -d. |
|
@c man .TP |
|
@item -lsl iso_rr_pattern [***] |
|
@kindex -lsl lists files in ISO image |
|
@cindex Navigate, list ISO files, -lsl |
|
Like -ls but also list some of the file attributes. |
|
The output format resembles shell command ls -ln. |
|
@c man .TP |
|
@item -lsdl iso_rr_pattern [***] |
|
@kindex -lsdl lists files in ISO image |
|
@cindex Navigate, list ISO files, -lsdl |
|
Like -lsd but also list some of the file attributes. |
|
The output format resembles shell command ls -dln. |
|
@c man .TP |
|
@item -lsx disk_pattern [***] |
|
@kindex -lsx lists files on disk |
|
@cindex Navigate, list disk files, -lsx |
|
List files in the local filesystem which match shell patterns. Patterns which |
|
do not begin with '/' are used relative to -cdx. |
|
@* |
|
Directories are listed by their content rather than as single file item. |
|
@* |
|
Pattern expansion may be disabled by command -disk_pattern. |
|
@c man .TP |
|
@item -lsdx disk_pattern [***] |
|
@kindex -lsdx lists files on disk |
|
@cindex Navigate, list disk files, -lsdx |
|
Like -lsx but listing directories as themselves and not by their content. |
|
This resembles shell command ls -d. |
|
@c man .TP |
|
@item -lslx disk_pattern [***] |
|
@kindex -lslx lists files on disk |
|
@cindex Navigate, list disk files, -lslx |
|
Like -lsx but also listing some of the file attributes. |
|
Output format resembles shell command ls -ln. |
|
@c man .TP |
|
@item -lsdlx disk_pattern [***] |
|
@kindex -lsdlx lists files on disk |
|
@cindex Navigate, list disk files, -lsdlx |
|
Like -lsdx but also listing some of the file attributes. |
|
Output format resembles shell command ls -dln. |
|
@c man .TP |
|
@item -getfacl iso_rr_pattern [***] |
|
@kindex -getfacl shows ACL in ISO image |
|
@cindex ACL, show in ISO image, -getfacl |
|
Print the access permissions of the given files in the ISO image using the |
|
format of shell command getfacl. If a file has no ACL then it gets fabricated |
|
from the -chmod settings. A file may have a real ACL if it was introduced into |
|
the ISO image while option -acl was set to "on". |
|
@c man .TP |
|
@item -getfacl_r iso_rr_pattern [***] |
|
@kindex -getfacl_r shows ACL in ISO image |
|
@cindex ACL, show in ISO image, -getfacl_r |
|
Like -gefacl but listing recursively the whole file trees underneath eventual |
|
directories. |
|
@c man .TP |
|
@item -getfattr iso_rr_pattern [***] |
|
@kindex -getfattr shows xattr in ISO image |
|
@cindex xattr, show in ISO image, -getfattr |
|
Print the xattr of the given files in the ISO image. |
|
If a file has no such xattr then noting is printed for it. |
|
@c man .TP |
|
@item -getfattr_r iso_rr_pattern [***] |
|
@kindex -getfattr_r shows xattr in ISO image |
|
@cindex xattr, show in ISO image, -getfattr_r |
|
Like -gefattr but listing recursively the whole file trees underneath eventual |
|
directories. |
|
@c man .TP |
|
@item -du iso_rr_pattern [***] |
|
@kindex -du show directory size in ISO image |
|
@cindex Navigate, directory size in ISO image, -du |
|
Recursively list size of directories and files in the ISO image |
|
which match one of the patterns. |
|
similar to shell command du -k. |
|
@c man .TP |
|
@item -dus iso_rr_pattern [***] |
|
@kindex -dus show directory size in ISO image |
|
@cindex Navigate, directory size in ISO image, -dus |
|
List size of directories and files in the ISO image |
|
which match one of the patterns. |
|
Similar to shell command du -sk. |
|
@c man .TP |
|
@item -dux disk_pattern [***] |
|
@kindex -dux show directory size on disk |
|
@cindex Navigate, directory size in on disk, -dux |
|
Recursively list size of directories and files in the local filesystem |
|
which match one of the patterns. Similar to shell command du -k. |
|
@c man .TP |
|
@item -dusx disk_pattern [***] |
|
@kindex -dusx show directory size on disk |
|
@cindex Navigate, directory size in on disk, -dusx |
|
List size of directories and files in the local filesystem |
|
which match one of the patterns. |
|
Similar to shell command du -sk. |
|
@c man .TP |
|
@item -findx disk_path [-name pattern] [-type t] [-exec action [params]] @minus{}@minus{} |
|
@kindex -findx traverses disk tree |
|
@cindex Tree, disk, traverse, -findx |
|
Like -find but operating on local filesystem and not on the ISO image. |
|
This is subject to the settings of -follow. |
|
@* |
|
-findx accepts the same -type 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". |
|
@* |
|
@table @asis |
|
@sp 1 |
|
@item 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 @minus{}@minus{} |
|
@* |
|
@item not_in_iso |
|
reports the path if its counterpart does |
|
not exist in the ISO image. The report format is the same as with command |
|
-compare. |
|
@* |
|
@item add_missing iso_rr_path_start |
|
adds the counterpart if it does not yet |
|
exist in the ISO image. |
|
@* |
|
E.g.: -findx /home/thomas -exec add_missing /thomas_on_cd @minus{}@minus{} |
|
@* |
|
@item is_full_in_iso |
|
reports if the counterpart in the ISO image |
|
contains files. To be used with -type "m" to report mount points. |
|
@* |
|
@item empty_iso_dir |
|
deletes all files from the counterpart |
|
in the ISO image. To be used with -type "m" to truncate mount points. |
|
@end table |
|
@c man .TP |
|
@item -compare disk_path iso_rr_path |
|
@kindex -compare reports ISO/disk differences |
|
@cindex Verify, compare ISO and disk file, -compare |
|
Compare attributes and eventual data file content of a fileobject in the |
|
local filesystem with a file object in the ISO image. The iso_rr_path may |
|
well point to an image file object which is not yet committed, i.e. of which |
|
the data content still resides in the local filesystem. Such data content is |
|
prone to externally caused changes. |
|
@* |
|
If iso_rr_path is empty then disk_path is used as path in the ISO image too. |
|
@* |
|
Differing attributes are reported in detail, differing content is summarized. |
|
Both to the result channel. In case of no differences no result lines are |
|
emitted. |
|
@c man .TP |
|
@item -compare_r disk_path iso_rr_path |
|
@kindex -compare_r reports ISO/disk differences |
|
@cindex Verify, compare ISO and disk tree, -compare_r |
|
Like -compare but working recursively. I.e. all file objects below both |
|
addresses get compared whether they have counterparts below the other address |
|
and whether both counterparts match. |
|
@c man .TP |
|
@item -compare_l disk_prefix iso_rr_prefix disk_path [***] |
|
@kindex -compare_l reports ISO/disk differences |
|
@cindex Verify, compare ISO and disk, -compare_l |
|
Perform -compare_r with each of the disk_path arguments. iso_rr_path will be |
|
composed from disk_path by replacing disk_prefix by iso_rr_prefix. |
|
@c man .TP |
|
@item -show_stream iso_rr_path [***] |
|
@kindex -show_stream shows data source and filters |
|
@cindex Filter, show chain, -show_stream |
|
Display the content stream chain of data files in the ISO image. The chain |
|
consists of the iso_rr_name and one or more streams, separated by " < " marks. |
|
A stream 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' |
|
@c man .TP |
|
@item -show_stream_r iso_rr_path [***] |
|
@kindex -show_stream_r shows data source and filters |
|
@cindex Filter, show chains of tree, -show_stream_r |
|
Like -show_stream but working recursively. |
|
@end table |
|
@c man .TP |
|
@c man .B Evaluation of readability and recovery: |
|
@node Verify, Restore, Navigate, Options |
|
@section Evaluation of readability and recovery |
|
@c man .PP |
|
It is not uncommon that optical media produce read errors. The reasons may be |
|
various and get obscured by error correction which is performed by the drives |
|
and based on extra data on the media. If a drive returns data then one can |
|
quite trust that they are valid. But at some degree of read problems the |
|
correction will fail and the drive is supposed to indicate error. |
|
@* |
|
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. |
|
@table @asis |
|
@sp 1 |
|
@c man .TP |
|
@item -check_media [option [option ...]] @minus{}@minus{} |
|
@kindex -check_media reads media block by block |
|
@cindex Verify, check blocks, -check_media |
|
@cindex Recovery, retrieve blocks, -check_media |
|
Try to read data blocks from the indev drive, 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. |
|
@* |
|