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.
6004 lines
241 KiB
6004 lines
241 KiB
.\" Hey, EMACS: -*- nroff -*- |
|
.\" |
|
.\" IMPORTANT NOTE: |
|
.\" |
|
.\" The original of this file is kept in xorriso/xorriso.texi |
|
.\" This here was generated by program xorriso/make_xorriso_1 |
|
.\" |
|
.\" |
|
.\" First parameter, NAME, should be all caps |
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection |
|
.\" other parameters are allowed: see man(7), man(1) |
|
.TH XORRISO 1 "Version 1.4.5, Jul 03, 2016" |
|
.\" Please adjust this date whenever revising the manpage. |
|
.\" |
|
.\" Some roff macros, for reference: |
|
.\" .nh disable hyphenation |
|
.\" .hy enable hyphenation |
|
.\" .ad l left justify |
|
.\" .ad b justify to both left and right margins |
|
.\" .nf disable filling |
|
.\" .fi enable filling |
|
.\" .br insert line break |
|
.\" .sp <n> insert n+1 empty lines |
|
.\" for manpage-specific macros, see man(7) |
|
.nh |
|
.SH NAME |
|
xorriso \- creates, loads, manipulates and writes ISO 9660 filesystem images |
|
with Rock Ridge extensions. |
|
.SH SYNOPSIS |
|
.B xorriso |
|
.RI [ settings | actions ] |
|
.br |
|
.SH DESCRIPTION |
|
.PP |
|
\fBxorriso\fR |
|
is a program which copies file objects from POSIX compliant |
|
filesystems into Rock Ridge enhanced ISO 9660 filesystems and performs |
|
session\-wise manipulation of such filesystems. It can load the management |
|
information of existing ISO images and it writes the session results to |
|
optical media or to filesystem objects. |
|
.br |
|
Vice versa \fBxorriso\fR is able to copy file objects out of ISO 9660 |
|
filesystems. |
|
.PP |
|
A special property of \fBxorriso\fR is that it needs neither an external |
|
ISO 9660 |
|
formatter program nor an external burn program for CD, DVD or BD but rather |
|
incorporates the libraries of libburnia\-project.org . |
|
.SS |
|
.B Overview of features: |
|
.br |
|
Operates on an existing ISO image or creates a new one. |
|
.br |
|
Copies files from disk filesystem into the ISO image. |
|
.br |
|
Copies files from ISO image to disk filesystem (see osirrox). |
|
.br |
|
Renames or deletes file objects in the ISO image. |
|
.br |
|
Changes file properties in the ISO image. |
|
.br |
|
Updates ISO subtrees incrementally to match given disk subtrees. |
|
.br |
|
Writes result either as completely new image or as add\-on session |
|
to optical media or filesystem objects. |
|
.br |
|
Can activate ISOLINUX and GRUB boot images via El Torito and MBR. |
|
.br |
|
Can perform multi\-session tasks as emulation of mkisofs and cdrecord. |
|
.br |
|
Can record and restore hard links and ACL. |
|
.br |
|
Content may get zisofs compressed or filtered by external processes. |
|
.br |
|
Can issue commands to mount older sessions on GNU/Linux or FreeBSD. |
|
.br |
|
Can check media for damages and copy readable blocks to disk. |
|
.br |
|
Can attach MD5 checksums to each data file and the whole session. |
|
.br |
|
Scans for optical drives, blanks re\-useable optical media. |
|
.br |
|
Reads its instructions from command line arguments, dialog, and files. |
|
.br |
|
Provides navigation commands for interactive ISO image manipulation. |
|
.br |
|
Adjustable thresholds for abort, exit value, and problem reporting. |
|
.br |
|
.sp 1 |
|
Note that \fBxorriso\fR does not write audio CDs and that it does not |
|
produce UDF filesystems which are specified for official video DVD or BD. |
|
.SS |
|
.B General information paragraphs: |
|
.br |
|
Session model |
|
.br |
|
Media types and states |
|
.br |
|
Creating, Growing, Modifying, Blind Growing |
|
.br |
|
Libburn drives |
|
.br |
|
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr |
|
.br |
|
Command processing |
|
.br |
|
Dialog, Readline, Result pager |
|
.sp 1 |
|
Maybe you first want to have a look at section EXAMPLES near the end of |
|
this text before reading the next few hundred lines of background information. |
|
.SS |
|
\fBSession model:\fR |
|
.br |
|
Unlike other filesystems, \fBISO 9660\fR (aka \fBECMA\-119\fR) |
|
is not intended for read\-write operation but |
|
rather for being generated in a single sweep and being written to media as a |
|
\fBsession\fR. |
|
.br |
|
The data content of the session is called filesystem \fBimage\fR. |
|
.PP |
|
The written image in its session can then be mounted by the operating system |
|
for being used read\-only. GNU/Linux is able to mount ISO images from block |
|
devices, which may represent optical media, other media or via a loop device |
|
even from regular disk files. FreeBSD mounts ISO images from devices that |
|
represent arbitrary media or from regular disk files. |
|
.PP |
|
This session usage model has been extended on CD media by the concept of |
|
\fBmulti\-session\fR , |
|
which adds information to the CD and gives the mount programs |
|
of the operating systems the addresses of the entry points of each |
|
session. The mount programs recognize block devices which represent |
|
CD media and will by default mount the image in the last session. |
|
.br |
|
This session usually contains an updated directory tree for the whole medium |
|
which governs the data contents in all recorded sessions. |
|
So in the view of the mount program all sessions of a particular medium |
|
together form a single filesystem image. |
|
.br |
|
Adding a session to an existing ISO image is in this text referred as |
|
\fBgrowing\fR. |
|
.br |
|
The multi\-session model of the MMC standard does not apply to all media |
|
types. But program growisofs by Andy Polyakov showed how to extend this |
|
functionality to overwriteable media or disk files which carry valid ISO 9660 |
|
filesystems. |
|
.PP |
|
\fBxorriso\fR provides growing as well as an own method named |
|
\fBmodifying\fR which produces a completely new ISO image from the old |
|
one and the modifications. |
|
See paragraph Creating, Growing, Modifying, Blind Growing below. |
|
.PP |
|
\fBxorriso\fR adopts the concept of multi\-session by loading an |
|
image directory tree if present, |
|
by offering to manipulate it by several actions, |
|
and by writing the new image to the target medium. |
|
.br |
|
The first session of a \fBxorriso\fR run begins by the definition of |
|
the input drive with the ISO image or by the definition of an output drive. |
|
The session ends by command \-commit which triggers writing. A \-commit is |
|
done automatically when the program ends regularly. |
|
.PP |
|
After \-commit a new session begins with the freshly written one as input. |
|
A new input drive can only be chosen as long as the loaded ISO image was |
|
not altered. Pending alteration can be revoked by command \-rollback. |
|
.PP |
|
Writing a session to the target is supposed to be very expensive in terms of |
|
time and of consumed space on appendable or write\-once media. Therefore all |
|
intended manipulations of a particular ISO image should be done in a single |
|
session. But in principle it is possible |
|
to store intermediate states and to continue with image manipulations. |
|
.SS |
|
.B Media types and states: |
|
There are two families of media in the MMC standard: |
|
.br |
|
\fBMulti\-session media\fR are CD\-R, CD\-RW, DVD\-R, DVD+R, DVD+R/DL, BD\-R, and |
|
unformatted DVD\-RW. These media provide a table of content which |
|
describes their existing sessions. See command \fB\-toc\fR. |
|
.br |
|
Similar to multi\-session media are DVD\-R DL and minimally blanked DVD\-RW. |
|
They record only a single session of which the size must be known in advance. |
|
\fBxorriso\fR will write onto them only if command \-close is set to "on". |
|
.br |
|
\fBOverwriteable media\fR are DVD\-RAM, DVD+RW, BD\-RE, and formatted DVD\-RW. |
|
They offer 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 \fBxorriso\fR, then a table of content can |
|
be emulated. Else only a single overall session will be visible. |
|
.br |
|
DVD\-RW media can be formatted by \-format "full". |
|
They can be made unformatted by \-blank "deformat". |
|
.br |
|
Regular files and block devices are handled as overwriteable media. |
|
Pipes and other writeable file types are handled as blank multi\-session media. |
|
.PP |
|
These media can assume several states in which they offer different |
|
capabilities. |
|
.br |
|
\fBBlank\fR media can be written from scratch. They contain no ISO image |
|
suitable for \fBxorriso\fR. |
|
.br |
|
Blank is the state of newly purchased optical media. |
|
With used CD\-RW and DVD\-RW it can be achieved by action \-blank "as_needed". |
|
Overwriteable media are considered blank if they are new or if they have |
|
been marked as blank by \fBxorriso\fR. |
|
Action \-blank "as_needed" can be used to do this marking on overwriteable |
|
media, or to apply mandatory formatting to new media if necessary. |
|
.br |
|
\fBAppendable\fR media accept further sessions. Either they are MMC |
|
multi\-session media in appendable state, or they are overwriteable media |
|
which contain an ISO image suitable for \fBxorriso\fR. |
|
.br |
|
Appendable is the state after writing a session with command \-close off. |
|
.br |
|
\fBClosed\fR media cannot be written. They may contain an ISO image suitable |
|
for \fBxorriso\fR. |
|
.br |
|
Closed is the state of DVD\-ROM media and of multi\-session media which were |
|
written with command \-close on. If the drive is read\-only hardware then it will |
|
probably show any media as closed CD\-ROM or DVD\-ROM. |
|
.br |
|
Overwriteable media assume this state in such read\-only drives or if they |
|
contain unrecognizable data in the first 32 data blocks. |
|
.br |
|
Read\-only drives may or may not show session histories of multi\-session |
|
media. Often only the first and the last session are visible. Sometimes |
|
not even that. Command \-rom_toc_scan might or might not help in such cases. |
|
.SS |
|
.B Creating, Growing, Modifying, Blind Growing: |
|
.br |
|
A new empty ISO image gets \fBcreated\fR |
|
if there is no input drive with a valid ISO 9660 image when the first time |
|
an output drive is defined. This is achieved by command \-dev on blank media |
|
or by command \-outdev on media in any state. |
|
.br |
|
The new empty image can be populated with directories and files. |
|
Before it can be written, the medium in the output drive must get into |
|
blank state if it was not blank already. |
|
.PP |
|
If there is a input drive with a valid ISO image, then this image gets loaded |
|
as foundation for manipulations and extension. The constellation of input |
|
and output drive determines which write method will be used. |
|
They have quite different capabilities and constraints. |
|
.PP |
|
The method of \fBgrowing\fR adds new data to the existing data on the |
|
medium. These data comprise of new file content and they override the existing |
|
ISO 9660 + Rock Ridge directory tree. It is possible to hide files from |
|
previous sessions but they still exist on the medium and with many types of |
|
optical media it is quite easy to recover them by mounting older sessions. |
|
.br |
|
Growing is achieved by command \-dev. |
|
.PP |
|
The write method of \fBmodifying\fR produces compact filesystem |
|
images with no outdated files or directory trees. Modifying can write its |
|
images to target media which are completely unsuitable for multi\-session |
|
operations. E.g. DVD\-RW which were treated with \-blank deformat_quickest, |
|
DVD\-R DL, named pipes, character devices, sockets. |
|
On the other hand modified sessions cannot be written to appendable media |
|
but to blank media only. |
|
.br |
|
So for this method one needs either two optical drives or has to work with |
|
filesystem objects as source and/or target medium. |
|
.br |
|
Modifying takes place if input drive and output drive are not the same and |
|
if command \-grow_blindly is set to its default "off". |
|
This is achieved by commands \-indev and \-outdev. |
|
.PP |
|
If command \-grow_blindly is set to a non\-negative number and if \-indev and |
|
\-outdev are both set to different drives, then \fBblind growing\fR is |
|
performed. It produces an add\-on session which is ready for being written |
|
to the given block address. This is the usage model of |
|
.br |
|
mkisofs \-M $indev \-C $msc1,$msc2 \-o $outdev |
|
.br |
|
which gives much room for wrong parameter combinations and should thus only be |
|
employed if a strict distinction between ISO formatter \fBxorriso\fR |
|
and the burn program is desired. \-C $msc1,$msc2 is equivalent to: |
|
.br |
|
\-load sbsector $msc1 \-grow_blindly $msc2 |
|
.SS |
|
.B Libburn drives: |
|
.br |
|
Input drive, i.e. source of an existing or empty ISO image, can be any random |
|
access readable libburn drive: optical media with readable data, |
|
blank optical media, regular files, block devices. |
|
.br |
|
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. |
|
.PP |
|
All drive file objects have to offer rw\-permission to the user of |
|
\fBxorriso\fR. |
|
Even those which will not be useable for reading an ISO image. |
|
.br |
|
With any type of drive object, the data are considered to be organized in |
|
blocks of 2 KiB. Access happens in terms of Logical Block Address |
|
(\fBLBA\fR) which gives the number of a particular data block. |
|
.PP |
|
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by |
|
the path of their block device or of their generic character device. E.g. |
|
.br |
|
\-dev /dev/sr0 |
|
.br |
|
\-dev /dev/hdc |
|
.br |
|
\-dev /dev/sg2 |
|
.br |
|
By default xorriso will try to map the given address to /dev/hd* and /dev/sr*. |
|
The command \-scsi_dev_family can redirect the mapping from sr to scd or sg. |
|
The latter does not suffer from the concurrency problems which plague /dev/sr |
|
of Linux kernels since version 3. But it does not yield the same addresses |
|
which are used by mount(8) or by open(2) for read(2). |
|
.br |
|
On FreeBSD the device files have names like |
|
.br |
|
\-dev /dev/cd0 |
|
.br |
|
On NetBSD: |
|
.br |
|
\-dev /dev/rcd0d |
|
.br |
|
On OpenSolaris: |
|
.br |
|
\-dev /dev/rdsk/c4t0d0s2 |
|
.br |
|
Get a list of accessible drives by command |
|
.br |
|
\-device_links |
|
.br |
|
It might be necessary to do this as |
|
\fBsuperuser\fR |
|
in order to see all drives and to then allow rw\-access for the intended users. |
|
Consider to bundle the authorized users in a group like old "floppy". |
|
.PP |
|
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and |
|
their path in the filesystem. E.g.: |
|
.br |
|
\-dev stdio:/dev/sdc |
|
.br |
|
The default setting of \-drive_class allows the user to address files outside |
|
the /dev tree without that prefix. E.g.: |
|
.br |
|
\-dev /tmp/pseudo_drive |
|
.br |
|
If path leads to a regular file or to a block device then the emulated drive |
|
is random access readable and can be used for the method of growing if it |
|
already contains a valid ISO 9660 image. Any other file type is not readable |
|
via "stdio:" and can only be used as target for the method of modifying or |
|
blind growing. |
|
Non\-existing paths in existing directories are handled as empty regular files. |
|
.PP |
|
A very special kind of pseudo drive are open file descriptors. They are |
|
depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open). |
|
.br |
|
Addresses "\-" or "stdio:/dev/fd/1" depict standard output, which normally is |
|
the output channel for result texts. |
|
To prevent a fatal intermingling of ISO image and text messages, all result |
|
texts get redirected to stderr if \-*dev "\-" or "stdio:/dev/fd/1" is among |
|
the start arguments of the program. |
|
.br |
|
Standard output is currently suitable for creating one session |
|
per program run without dialog. Use in other situations is discouraged |
|
and several restrictions apply: |
|
.br |
|
It is not allowed to use standard output as pseudo drive if it was not |
|
among the start arguments. Do not try to fool this ban via backdoor addresses |
|
to stdout. |
|
.br |
|
If stdout is used as drive, then \-use_readline is permanently disabled. |
|
Use of backdoors can cause severe memory and/or tty corruption. |
|
.PP |
|
Be aware that especially the superuser can write into any accessible file or |
|
device by using its path with the "stdio:" prefix. By default any address |
|
in the /dev tree without prefix "stdio:" will work only if it leads to a MMC |
|
drive. |
|
.br |
|
One may use command |
|
\fB\-ban_stdio_write\fR |
|
to surely prevent this risk and to restrict drive usage to MMC drives. |
|
.br |
|
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:". |
|
.br |
|
By command \-drive_class one may ban certain paths or allow access without |
|
prefix "stdio:" to other paths. |
|
.SS |
|
.B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr: |
|
.br |
|
\fBRock Ridge\fR |
|
is the name of a set of additional information which enhance |
|
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem |
|
with ownership, access permissions, symbolic links, and other attributes. |
|
.br |
|
This is what \fBxorriso\fR uses for a decent representation of the disk |
|
files within the ISO image. \fBxorriso\fR produces Rock Ridge information |
|
by default. It is strongly discouraged to disable this feature. |
|
.PP |
|
\fBxorriso\fR is not named "porriso" because POSIX only guarantees |
|
14 characters |
|
of filename length. It is the X/Open System Interface standard XSI which |
|
demands a file name length of up to 255 characters and paths of up to 1024 |
|
characters. Rock Ridge fulfills this demand. |
|
.PP |
|
An \fBEl Torito\fR |
|
boot record points the BIOS bootstrapping facility to one or more boot |
|
images, which are binary program files stored in the ISO image. |
|
The content of the boot image files is not in the scope of El Torito. |
|
.br |
|
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images. |
|
\fBxorriso\fR is able to create or maintain an El Torito object which |
|
makes such an image bootable. For details see command \-boot_image. |
|
.br |
|
It is possible to make ISO images bootable from USB stick or other |
|
hard\-disk\-like media. Several options install a \fBMBR\fR |
|
(Master Boot Record), It may get adjusted according to the needs of the |
|
intended boot firmware and the involved boot loaders, e.g. GRUB2 or ISOLINUX. |
|
A MBR contains boot code and a partition table. |
|
The new MBR of a follow\-up session can get in effect |
|
only on overwriteable media. |
|
.br |
|
MBR is read by PC\-BIOS when booting from USB stick or hard disk, |
|
and by PowerPC CHRP or PReP when booting. |
|
An MBR partiton with type 0xee indicates the presence of GPT. |
|
.br |
|
Emulation \-as mkisofs supports the example options out of the ISOLINUX wiki, |
|
the options used in GRUB script grub\-mkrescue, and the example in the |
|
FreeBSD AvgLiveCD wiki. |
|
.br |
|
A \fBGPT\fR (GUID Partition Table) marks partitions in a more modern way. |
|
It is read by EFI when booting from USB stick or hard disk, and may be used |
|
for finding and mounting a HFS+ partition inside the ISO image. |
|
.br |
|
An \fBAPM\fR (Apple Partition Map) marks the HFS+ partition. |
|
It is read by Macs for booting and for mounting. |
|
.br |
|
MBR, GPT and APM are combinable. APM occupies the first 8 bytes of |
|
MBR boot code. All three do not hamper El Torito booting from CDROM. |
|
.br |
|
There is support for further facilities: |
|
MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC, HP\-PA. |
|
Those are mutually not combinable and also not combinable with MBR, GPT, |
|
or APM. |
|
.br |
|
.PP |
|
\fBACL\fR |
|
are an advanced way of controlling access permissions to file objects. Neither |
|
ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has |
|
introduced a standard conformant extension named AAIP for that purpose. |
|
It uses this extension if enabled by command |
|
\fB\-acl\fR. |
|
.br |
|
AAIP enhanced images are supposed to be mountable normally, but one cannot |
|
expect that the mounted filesystem will show and respect the ACLs. |
|
For now, only \fBxorriso\fR is able to retrieve those ACLs. |
|
It can bring them into |
|
effect when files get restored to an ACL enabled file system or it can |
|
print them in a format suitable for tool setfacl. |
|
.br |
|
Files with ACL show as group permissions the setting of entry "mask::" if |
|
that entry exists. Nevertheless the non\-listed group members get handled |
|
according to entry "group::". When removing ACL from a file, |
|
\fBxorriso\fR brings "group::" into effect. |
|
.br |
|
Recording and restoring of ACLs from and to local files works currently |
|
only on GNU/Linux and FreeBSD. |
|
.PP |
|
\fBxattr\fR (aka EA, or extattr) |
|
are pairs of name and value which can be attached to file objects. AAIP is |
|
able to represent them and \fBxorriso\fR can record and restore pairs which |
|
have names out of the user namespace. I.e. those which begin with "user.", |
|
like "user.x" or "user.whatever". Name has to be a 0 terminated string. |
|
Value may be any array of bytes which does not exceed the size of 4095 bytes. |
|
xattr processing happens only if it is enabled by command |
|
\fB\-xattr\fR. |
|
.br |
|
As with ACL, currently only \fBxorriso\fR is able to retrieve xattr |
|
from AAIP enhanced images, to restore them to xattr capable file systems, |
|
or to print them. |
|
.br |
|
Recording and restoring of xattr from and to local files works currently |
|
only on GNU/Linux and FreeBSD, where they are known as extattr. |
|
.SS |
|
.B Command processing: |
|
.br |
|
Commands are either actions which happen immediately or settings which |
|
influence following actions. So their sequence does matter, unless they are |
|
given as program arguments and command |
|
\fB\-x\fR |
|
is among them. |
|
.br |
|
Commands consist of a command word, |
|
followed by zero or more parameter words. If the list of parameter words |
|
is of variable length (indicated by "[...]" or "[***]") then it must be |
|
terminated by either the \fBlist delimiter\fR, occur at the end of |
|
the argument list, or occur at the end of an input line. |
|
.PP |
|
At program start the list delimiter is the string "\-\-". |
|
This may be changed with the \-list_delimiter command in order to allow |
|
"\-\-" as parameter in a variable length list. |
|
However, it is advised to reset the delimiter to "\-\-" |
|
immediately afterwards. |
|
.br |
|
For brevity the list delimiter is referred as "\-\-" |
|
throughout this text. |
|
.br |
|
The list delimiter is silently ignored if it appears after the parameters of |
|
a command with a fixed list length. It is handled as normal text if it |
|
appears among the parameters of such a command. |
|
.PP |
|
\fBPattern expansion\fR |
|
converts a list of pattern words into a list of existing file addresses. |
|
Unmatched pattern words will appear unaltered in that result list. |
|
.br |
|
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' |
|
and respects '/' as the path separator, which may only be matched literally. |
|
.br |
|
Pattern expansion is a property of some particular commands and not a general |
|
feature. It is controlled by commands \-iso_rr_pattern and \-disk_pattern. |
|
Commands which use pattern expansion all have variable parameter |
|
lists which are specified in this text by "[***]" rather than "[...]". |
|
.br |
|
Some other commands perform pattern matching unconditionally. |
|
.PP |
|
Command and parameter words are either read from the program arguments, where |
|
one argument is one word, or from quoted input lines where words are recognized |
|
similar to the quotation rules of a shell parser. |
|
.br |
|
\fBxorriso\fR is not a shell, although it might appear so at first glimpse. |
|
Be aware that the interaction of quotation marks and pattern symbols like "*" |
|
differs from the usual shell parsers. In \fBxorriso\fR, a quotation mark |
|
does not make a pattern symbol literal. |
|
.PP |
|
\fBQuoted input\fR |
|
converts whitespace\-separated text into words. |
|
The double quotation mark " and the single quotation mark ' can be used to |
|
enclose whitespace and make it part of words (e.g. of file names). Each mark |
|
type can enclose the marks of the other type. A trailing backslash \\ outside |
|
quotations or an open quotation cause the next input line to be appended. |
|
.br |
|
Quoted input accepts any 8\-bit character except NUL (0) as the content of |
|
the quotes. |
|
Nevertheless it can be cumbersome for the user to produce those characters |
|
directly. Therefore quoted input and program arguments offer optional |
|
\fBBackslash Interpretation\fR |
|
which can represent all 8\-bit characters except NUL (0) via backslash codes |
|
as in $'...' of bash. |
|
.br |
|
This is not enabled by default. See command \-backslash_codes. |
|
.PP |
|
When the program starts then it first looks for argument \-no_rc. If this is |
|
not present then it looks for its startup files and |
|
reads their content as command input lines. Then it interprets |
|
the program arguments as commands and parameters. Finally it enters |
|
dialog mode if command \-dialog "on" has been executed by this point. |
|
.PP |
|
The program ends either by command \-end, or by the end of program arguments |
|
if dialog mode has not been enabled at that point, or by a problem |
|
event which triggers the threshold of command \-abort_on. |
|
.SS |
|
.B Dialog, Readline, Result pager: |
|
.br |
|
Dialog mode prompts for a quoted input line, parses it into words, and performs |
|
them as commands with their parameters. It provides assisting services |
|
to make dialog more comfortable. |
|
.PP |
|
Readline is an enhancement for the input line. You may already know it from |
|
the bash shell. Whether it is available in \fBxorriso\fR depends on the |
|
availability |
|
of package readline\-dev at the time when \fBxorriso\fR was built from |
|
its sourcecode. |
|
.br |
|
Readline lets the user move the cursor over the text in the line by help of the |
|
Left and the Right arrow keys. |
|
Text may be inserted at the cursor position. The Delete key removes the |
|
character under the cursor. Up and Down arrow keys navigate through |
|
the history of previous input lines. |
|
.br |
|
See man readline |
|
for more info about libreadline. |
|
.PP |
|
Command \-page activates a built\-in result text pager which may be convenient in |
|
dialog mode. After an action has output the given number of terminal lines, |
|
the pager prompts the user for a line of input. |
|
.br |
|
An empty line lets \fBxorriso\fR resume work until the next page is output. |
|
.br |
|
The single character "@" disables paging for the current action. |
|
.br |
|
"@@@", "x", "q", "X", or "Q" request that the current action aborts and |
|
suppress further result output. |
|
.br |
|
Any other line input will be interpreted as new dialog line. The current action |
|
is requested to abort. Afterwards, the input line is executed. |
|
.PP |
|
Some actions apply paging to their info output, too. |
|
.br |
|
The request to abort may or may not be obeyed by the current action. |
|
All actions try to abort as soon as possible. |
|
.br |
|
.SH OPTIONS |
|
.br |
|
All command words are shown with a leading dash although this dash is not |
|
mandatory for the command to be recognized. Nevertheless within command \-as |
|
the dashes of the emulated commands are mandatory. |
|
.br |
|
Normally any number of leading dashes is ignored with command words and |
|
inner dashes are interpreted as underscores. |
|
.TP |
|
.B Execution order of program arguments: |
|
.PP |
|
By default the program arguments of a xorriso run are interpreted as a |
|
sequence of commands which get performed exactly in the given order. |
|
This requires the user to write commands for desired settings before the |
|
commands which shall be influenced by those settings. |
|
.br |
|
Many other programs support program arguments in an arbitrary ordering |
|
and perform settings and actions in a sequence at their own discretion. |
|
xorriso provides an option to enable such a behavior |
|
at the cost of loss of expressivity. |
|
.TP |
|
\fB\-x\fR |
|
Enable automatic sorting of program arguments into a sequence that |
|
(most likely) is sensible. |
|
This command may be given at any position among the commands |
|
which are handed over as program arguments. |
|
.br |
|
Note: It works only if it is given as program argument and |
|
with a single dash (i.e. "\-x"). It will not work in startup files, nor with |
|
\-options_from_file, nor in dialog mode, nor as "x" and finally not as |
|
"\-\-x". |
|
It affects only the commands given as program arguments. |
|
.TP |
|
\fB\-list_arg_sorting\fR |
|
List all xorriso commands in the order which applies if command \-x is in |
|
effect. |
|
.br |
|
This list may also be helpful without \-x for a user who ponders over the |
|
sequence in which to put commands. Deviations from the listed sorting order may |
|
well make sense, though. |
|
.PP |
|
.TP |
|
.B Acquiring source and target drive: |
|
.PP |
|
The effect of acquiring a drive may depend on several commands in the |
|
next paragraph "Influencing the behavior of image loading". |
|
If desired, their enabling commands have to be performed before the |
|
commands which acquire the drive. |
|
.TP |
|
\fB\-dev\fR address |
|
Set input and output drive to the same address and load an ISO image if it |
|
is present. |
|
If there is no ISO image then create a blank one. |
|
Set the image expansion method to growing. |
|
.br |
|
This is only allowed as long as no changes are pending in the currently |
|
loaded ISO image. If changes are pending, then one has to perform \-commit |
|
or \-rollback first. |
|
.br |
|
Special address string "\-" means standard output, to which several restrictions |
|
apply. See above paragraph "Libburn drives". |
|
.br |
|
An empty address string "" gives up the current device |
|
without acquiring a new one. |
|
.TP |
|
\fB\-indev\fR address |
|
Set input drive and load an ISO image if present. |
|
If the new input drive differs |
|
from \-outdev then switch from growing to modifying or to blind growing. |
|
It depends on the setting of \-grow_blindly which of both gets activated. |
|
The same rules and restrictions apply as with \-dev. |
|
.TP |
|
\fB\-outdev\fR address |
|
Set output drive and if it differs from the input drive then switch from |
|
growing to modifying or to blind growing. Unlike \-dev and \-indev this action |
|
does not load a new ISO image. So it can be performed even if there are pending |
|
changes. |
|
.br |
|
\-outdev can be performed without previous \-dev or \-indev. In that case an |
|
empty ISO image with no changes pending is created. It can either be populated |
|
by help of \-map, \-add et.al. or it can be discarded silently if \-dev or \-indev |
|
are performed afterwards. |
|
.br |
|
Special address string "\-" means standard output, to which several restrictions |
|
apply. See above paragraph "Libburn drives". |
|
.br |
|
An empty address string "" gives up the current output drive |
|
without acquiring a new one. No writing is possible without an output drive. |
|
.TP |
|
\fB\-scsi_dev_family\fR "default"|"sr"|"scd"|"sg" |
|
GNU/Linux specific: |
|
.br |
|
By default, xorriso tries to map Linux drive addresses to /dev/sr* before |
|
they get opened for operating the drive. This coordinates well with |
|
other use cases of optical drives, like mount(8). But since year 2010 |
|
all /dev/sr* share a global lock which allows only one drive to process |
|
an SCSI command while all others have to wait for its completion. |
|
This yields awful throughput if more than one drive is writing or reading |
|
simultaneously. |
|
The global lock is not applied to device files /dev/sg* and also not if |
|
the xorriso drive address is prepended by "stdio:". |
|
.br |
|
So for simultaneous burn runs on modern GNU/Linux it is advisable to perform |
|
\-scsi_dev_family "sg" before any \-dev, \-indev, or \-outdev. The drive addresses |
|
may then well be given as /dev/sr* but will nevertheless get used as |
|
the matching /dev/sg*. |
|
.br |
|
If you decide so, consider to put the command into a global startup file like |
|
/etc/opt/xorriso/rc. |
|
.TP |
|
\fB\-grow_blindly\fR "off"|predicted_nwa |
|
If predicted_nwa is a non\-negative number then perform blind growing rather |
|
than modifying if \-indev and \-outdev are set to different drives. |
|
"off" or "\-1" switch to modifying, which is the default. |
|
.br |
|
predicted_nwa is the block address where the add\-on session of blind |
|
growing will finally end up. It is the responsibility of the user to ensure |
|
this final position and the presence of the older sessions. Else the |
|
overall ISO image will not be mountable or will produce read errors when |
|
accessing file content. \fBxorriso\fR will write the session to the address |
|
as obtained from examining \-outdev and not necessarily to predicted_nwa. |
|
.br |
|
During a run of blind growing, the input drive is given up before output |
|
begins. The output drive is given up when writing is done. |
|
.TP |
|
.B Influencing the behavior of image loading: |
|
.PP |
|
The following commands should normally be performed before loading an image |
|
by acquiring an input drive. In rare cases it is desirable to activate |
|
them only after image loading. |
|
.TP |
|
\fB\-read_speed\fR code|number[k|m|c|d|b] |
|
Set the speed for reading. Default is "none", which avoids to send a speed |
|
setting command to the drive before reading begins. |
|
.br |
|
Further special speed codes are: |
|
.br |
|
"max" (or "0") selects maximum speed as announced by the drive. |
|
.br |
|
"min" (or "\-1") selects minimum speed as announced by the drive. |
|
.br |
|
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 explicitly |
|
by "c" for CD, "d" for DVD, "b" for BD, "x" is optional. |
|
.br |
|
Example speeds: |
|
.br |
|
706k = 706kB/s = 4c = 4xCD |
|
.br |
|
5540k = 5540kB/s = 4d = 4xDVD |
|
.br |
|
If there is no hint about the speed unit attached, then the |
|
medium in the \-indev will decide. Default unit is CD = 176.4k. |
|
.br |
|
Depending on the drive, the reported read speeds can be deceivingly low |
|
or high. Therefore "min" cannot become higher than 1x speed of the involved |
|
medium type. Read speed "max" cannot become lower than 52xCD, 24xDVD, |
|
or 20xBD, depending on the medium type. |
|
.br |
|
MMC drives usually activate their own idea of speed and take |
|
the speed value given by the burn program only as hint |
|
for their own decision. |
|
.TP |
|
\fB\-load\fR entity id |
|
Load a particular (possibly outdated) ISO session from \-dev or \-indev. |
|
Usually all available sessions are shown with command \-toc. |
|
.br |
|
entity depicts the kind of addressing. id depicts the particular |
|
address. The following entities are defined: |
|
.br |
|
"auto" with any id addresses the last session in \-toc. This is the default. |
|
.br |
|
"session" with id being a number as of a line "ISO session", column "Idx". |
|
.br |
|
"track" with id being a number as of a line "ISO track", column "Idx". |
|
.br |
|
"lba" or "sbsector" with a number as of a line "ISO ...", column "sbsector". |
|
.br |
|
"volid" with a search pattern for a text as of a line "ISO ...", |
|
column "Volume Id". |
|
.br |
|
Addressing a non\-existing entity or one which does not represent an ISO |
|
image will either abandon \-indev or at least lead to a blank image. |
|
.br |
|
If an input drive is set at the moment when \-load is executed, then the |
|
addressed ISO image is loaded immediately. Else, the setting will be pending |
|
until the next \-dev or \-indev. After the image has been loaded once, the |
|
setting is valid for \-rollback until next \-dev or \-indev, where it |
|
will be reset to "auto". |
|
.TP |
|
\fB\-displacement\fR [-]lba |
|
Compensate a displacement of the image versus the start address |
|
for which the image was prepared. This affects only loading of ISO images |
|
and reading of their files. The multi\-session method of growing is not allowed |
|
as long as \-displacement is non\-zero. I.e. \-indev and \-outdev must be |
|
different. The displacement gets reset to 0 before the drive |
|
gets re\-acquired after writing. |
|
.br |
|
Examples: |
|
.br |
|
If a track of a CD starts at block 123456 and gets copied to a disk file |
|
where it begins at block 0, then this copy can be loaded with |
|
\-displacement \-123456. |
|
.br |
|
If an ISO image was written onto a partition with offset of 640000 blocks of |
|
512 bytes, then it can be loaded from the base device by \-displacement 160000. |
|
.br |
|
In both cases, the ISO sessions should be self contained, i.e. not add\-on |
|
sessions to an ISO image outside their track or partition. |
|
.TP |
|
\fB\-drive_class\fR "harmless"|"banned"|"caution"|"clear_list" disk_pattern |
|
Add a drive path pattern to one of the safety lists or make those lists empty. |
|
There are three lists defined which get tested in the following sequence: |
|
.br |
|
If a drive address path matches the "harmless" list then the drive will be |
|
accepted. If it is not a MMC device then the prefix "stdio:" will be prepended |
|
automatically. This list is empty by default. |
|
.br |
|
Else if the path matches the "banned" list then the drive will not be |
|
accepted by \fBxorriso\fR but rather lead to a FAILURE event. |
|
This list is empty by default. |
|
.br |
|
Else if the path matches the "caution" list and if it is not a MMC device, |
|
then its address must have the prefix "stdio:" or it will be rejected. |
|
This list has by default one entry: "/dev". |
|
.br |
|
If a drive path matches no list then it is considered "harmless". By default |
|
these are all paths which do not begin with directory "/dev". |
|
.br |
|
A path matches a list if one of its parent paths or itself matches a list |
|
entry. Address prefix "stdio:" or "mmc:" will be ignored when |
|
testing for matches. |
|
.br |
|
By pseudo\-class "clear_list" and pseudo\-patterns "banned", "caution", |
|
"harmless", or "all", the lists may be made empty. |
|
.br |
|
E.g.: \-drive_class clear_list banned |
|
.br |
|
One will normally define the \-drive_class lists in one of the \fBxorriso\fR |
|
Startup Files. |
|
.br |
|
Note: This is not a security feature but rather a bumper for the superuser to |
|
prevent inadverted mishaps. For reliably blocking access to a device file you |
|
have to deny its rw\-permissions in the filesystem. |
|
.TP |
|
\fB\-read_fs\fR "any"|"norock"|"nojoliet"|"ecma119" |
|
Specify which kind of filesystem tree to load if present. If the wish cannot |
|
be fulfilled, then ECMA\-119 names are loaded and converted according |
|
to \-ecma119_map. |
|
.br |
|
"any" first tries to read Rock Ridge. If not present, Joliet is tried. |
|
.br |
|
"norock" does not try Rock Ridge. |
|
.br |
|
"nojoliet" does not try Joliet. |
|
.br |
|
"ecma119" tries neither Rock Ridge nor Joliet. |
|
.TP |
|
\fB\-assert_volid\fR pattern severity |
|
Refuse to load ISO images with volume IDs which do not match the given |
|
search pattern. When refusing an image, give up the input drive and issue |
|
an event of the given severity (like FAILURE, see \-abort_on). An empty search |
|
pattern accepts any image. |
|
.br |
|
This command does not hamper the creation of an empty image from blank |
|
input media and does not discard an already loaded image. |
|
.TP |
|
\fB\-in_charset\fR character_set_name |
|
Set the character set from which to convert file names when loading an |
|
image. See paragraph "Character sets" for more explanations. |
|
When loading the written image after \-commit the setting of \-out_charset |
|
will be copied to \-in_charset. |
|
.TP |
|
\fB\-auto_charset\fR "on"|"off" |
|
Enable or disable recording and interpretation of the output character |
|
set name in an xattr attribute of the image root directory. If enabled and |
|
if a recorded character set name is found, then this name will be used as |
|
name of the input character set when reading an image. |
|
.br |
|
Note that the default output charset is the local character set of the |
|
terminal where \fBxorriso\fR runs. Before attributing this local |
|
character set |
|
to the produced ISO image, check whether the terminal properly displays |
|
all intended filenames, especially exotic national characters. |
|
.TP |
|
\fB\-hardlinks\fR mode[:mode...] |
|
Enable or disable loading and recording of hardlink relations. |
|
.br |
|
In default mode "off", iso_rr files lose their inode numbers at image load |
|
time. Each iso_rr file object which has no inode number at image generation |
|
time will get a new unique inode number if \-compliance is set to new_rr. |
|
.br |
|
Mode "on" preserves inode numbers from the loaded image if such numbers |
|
were recorded. |
|
When committing a session it searches for families of iso_rr files |
|
which stem from the same disk file, have identical content filtering and have |
|
identical properties. The family members all get the same inode number. |
|
Whether these numbers are respected at mount time depends on the operating |
|
system. |
|
.br |
|
Command \-lsl displays hardlink counts if "lsl_count" is enabled. This can |
|
slow down the command substantially after changes to the ISO image have |
|
been made. Therefore the default is "no_lsl_count". |
|
.br |
|
Commands \-update and \-update_r track splits and fusions of hard links in |
|
filesystems which have stable device and inode numbers. This can cause |
|
automatic last minute changes before the session gets written. Command |
|
\-hardlinks "perform_update" may be used to do these changes earlier, |
|
e.g. if you need to apply filters to all updated files. |
|
.br |
|
Mode "without_update" avoids hardlink processing during update commands. |
|
Use this if your filesystem situation does not allow \-disk_dev_ino "on". |
|
.br |
|
\fBxorriso\fR commands which extract files from an ISO image try to |
|
hardlink files |
|
with identical inode number. The normal scope of this operation is from |
|
image load to image load. One may give up the accumulated hard link addresses |
|
by \-hardlinks "discard_extract". |
|
.br |
|
A large number of hardlink families may exhaust \-temp_mem_limit |
|
if not \-osirrox "sort_lba_on" and \-hardlinks "cheap_sorted_extract" |
|
are both in effect. This restricts hard linking to other files restored by |
|
the same single extract command. \-hardlinks "normal_extract" re\-enables |
|
wide and expensive hardlink accumulation. |
|
.br |
|
.TP |
|
\fB\-acl\fR "on"|"off" |
|
Enable or disable processing of ACLs. |
|
If enabled, then \fBxorriso\fR will obtain ACLs from disk file objects, |
|
store ACLs in the ISO image using the libisofs specific AAIP format, |
|
load AAIP data from ISO images, test ACL during file comparison, |
|
and restore ACLs to disk files when extracting them from ISO images. |
|
See also commands \-getfacl, \-setfacl. |
|
.TP |
|
\fB\-xattr\fR "on"|"off" |
|
Enable or disable processing of xattr attributes in user namespace. |
|
If enabled, then \fBxorriso\fR will handle xattr similar to ACL. |
|
See also commands \-getfattr, \-setfattr and above paragraph about xattr. |
|
.TP |
|
\fB\-md5\fR "on"|"all"|"off"|"load_check_off" |
|
Enable or disable processing of MD5 checksums for the overall session and for |
|
each single data file. If enabled then images with checksum tags get loaded |
|
only if the tags of superblock and directory tree match properly. The MD5 |
|
checksums of data files and whole session get loaded from the image if there |
|
are any. |
|
.br |
|
With commands \-compare and \-update the recorded MD5 of a file |
|
will be used to avoid content reading from the image. Only the disk file |
|
content will be read and compared with that MD5. This can save much time |
|
if \-disk_dev_ino "on" is not suitable. |
|
.br |
|
At image generation time they are computed for each file which gets its data |
|
written into the new session. The checksums of files which have their data |
|
in older sessions get copied into the new session. Superblock, tree and whole |
|
session get a checksum tag each. |
|
.br |
|
Mode "all" will additionally check during image generation whether the checksum |
|
of a data file changed between the time when its reading began and the time |
|
when it ended. This implies reading every file twice. |
|
.br |
|
Mode "load_check_off" together with "on" or "all" will load recorded MD5 sums |
|
but not test the recorded checksum tags of superblock and directory tree. |
|
This is necessary if growisofs was used as burn program, because it does |
|
not overwrite the superblock checksum tag of the first session. |
|
Therefore load_check_off is in effect when \fBxorriso\fR \-as mkisofs |
|
option \-M is performed. |
|
.br |
|
The test can be re\-enabled by mode "load_check_on". |
|
.br |
|
Checksums can be exploited via commands \-check_md5, \-check_md5_r, via find |
|
actions get_md5, check_md5, and via \-check_media. |
|
.TP |
|
\fB\-for_backup\fR |
|
Enable all extra features which help to produce or to restore backups with |
|
highest fidelity of file properties. |
|
Currently this is a shortcut for: \-hardlinks on \-acl on \-xattr on \-md5 on. |
|
.TP |
|
\fB\-ecma119_map\fR "stripped"|"unmapped"|"lowercase"|"uppercase" |
|
Choose the conversion of file names from the loaded session if neither |
|
a Rock Ridge name nor a Joliet name was read from the session. |
|
.br |
|
Mode "stripped" is the default. It shows the names as found in the ISO but |
|
removes trailing ";1" or ".;1" if present. |
|
.br |
|
Mode "unmapped" shows names as found without removing characters. |
|
.br |
|
Mode "lowercase" is like "stripped" but also maps uppercase letters to |
|
lowercase letters. This is compatible to default GNU/Linux mount behavior. |
|
.br |
|
Mode "uppercase" is like "stripped" but maps lowercase letters to uppercase, |
|
if any occur despite the prescriptions of ECMA\-119. |
|
.TP |
|
\fB\-disk_dev_ino\fR "on"|"ino_only"|"off" |
|
Enable or disable processing of recorded file identification numbers |
|
(dev_t and ino_t). If enabled they are stored as xattr and can |
|
substantially accelerate file comparison. The root node gets a global start |
|
timestamp. If during comparison a file with younger timestamps is found in the |
|
ISO image, then it is suspected to have inconsistent content. |
|
.br |
|
If device numbers and inode numbers of the disk filesystems are persistent |
|
and if no irregular alterations of timestamps or system clock happen, |
|
then potential content changes can be detected without reading that content. |
|
File content change is assumed if any of mtime, ctime, device number or inode |
|
number have changed. |
|
.br |
|
Mode "ino_only" replaces the precondition that device numbers are stable by the |
|
precondition that mount points in the compared tree always lead to the |
|
same filesystems. Use this if mode "on" always sees all files changed. |
|
.br |
|
The speed advantage appears only if the loaded session was produced with |
|
\-disk_dev_ino "on" too. |
|
.br |
|
Note that \-disk_dev_ino "off" is totally in effect only if \-hardlinks is "off", |
|
too. |
|
.TP |
|
\fB\-file_name_limit\fR [+]number |
|
Set the maximum permissible length for file names in the range of 64 to 255. |
|
Path components which are longer than the given number will get truncated |
|
and have their last 33 bytes overwritten by a colon ':' and the |
|
hex representation of the MD5 of the first 4095 bytes of the whole |
|
oversized name. Potential incomplete UTF\-8 characters will get their |
|
leading bytes replaced by '_'. |
|
.br |
|
iso_rr_paths with the long components will still be able to access the |
|
file paths with truncated components. |
|
.br |
|
If \-file_name_limit is executed while an ISO tree is present, the file names |
|
in the ISO tree get checked for existing truncated file names of the current |
|
limit and for name collisions between newly truncated files and existing files. |
|
In both cases, the setting will be refused with a SORRY event. |
|
.br |
|
One may lift this ban by prepending the character "+" to the argument |
|
of \-file_name_limit. Truncated filenames may then get truncated again, |
|
invalidating their MD5 part. Colliding truncated names are made unique, |
|
consuming at least 9 more bytes of the remaining name part. |
|
.br |
|
If writing of xattr is enabled, then the length will be stored in "isofs.nt" |
|
of the root directory. |
|
If reading of xattr is enabled and "isofs.nt" is found, then the found length |
|
will get into effect if it is smaller than the current setting |
|
of \-file_name_limit. |
|
.br |
|
File name patterns will only work if they match the truncated name. |
|
This might change in future. |
|
.br |
|
Files with truncated names get deleted and re\-added unconditionally |
|
during \-update and \-update_r. This might change in future. |
|
.br |
|
Linux kernels up to at least 4.1 misrepresent names of length 254 and 255. |
|
If you expect such names in or under disk_paths and plan to mount the ISO |
|
by such Linux kernels, consider to set \-file_name_limit 253. |
|
Else just avoid names longer than 253 characters. |
|
.TP |
|
\fB\-rom_toc_scan\fR "on"|"force"|"off"[:"emul_off"][:"emul_wide"] |
|
Read\-only drives do not tell the actual media type but show any media as |
|
ROM (e.g. as DVD\-ROM). The session history of MMC multi\-session media might |
|
be truncated to first and last session or even be completely false. |
|
(The emulated history of overwriteable media is not affected by this.) |
|
.br |
|
To have in case of failure a chance of getting the session history and |
|
especially the address of the last session, there is a scan for ISO 9660 |
|
filesystem headers which might help but also might yield worse results |
|
than the drive's table of content. At its end it can cause read attempts |
|
to invalid addresses and thus ugly drive behavior. |
|
Setting "on" enables that scan for alleged read\-only media. |
|
.br |
|
Some operating systems are not able to mount the most recent session of |
|
multi\-session DVD or BD. If on such a system \fBxorriso\fR has no own MMC |
|
capabilities then it may still find that session from a scanned table of |
|
content. Setting "force" handles any media like a ROM medium with setting "on". |
|
.br |
|
On the other hand the emulation of session history on overwriteable media |
|
can hamper reading of partly damaged media. Setting "off:emul_off" disables |
|
the elsewise trustworthy table\-of\-content scan for those media. |
|
.br |
|
The table\-of\-content scan on overwriteable media normally searches only up to |
|
the end of the session that is pointed to by the superblock at block 0. |
|
Setting "on:emul_wide" lets the scan continue up to the end of the medium. |
|
This may be useful after copying a medium with \-check_media patch_lba0=on |
|
when not the last session was loaded. |
|
.TP |
|
\fB\-calm_drive\fR "in"|"out"|"all"|"revoke"|"on"|"off" |
|
Reduce drive noise until it is actually used again. Some drives stay alert |
|
for substantial time after they have been used for reading. This reduces |
|
the startup time for the next drive operation but can be loud and waste |
|
energy if no i/o with the drive is expected to happen soon. |
|
.br |
|
Modes "in", "out", "all" immediately calm down \-indev, \-outdev, or both, |
|
respectively. |
|
Mode "revoke" immediately alerts both. |
|
Mode "on" causes \-calm_drive to be performed automatically after each \-dev, |
|
\-indev, and \-outdev. Mode "off" disables this. |
|
.TP |
|
\fB\-ban_stdio_write\fR |
|
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. |
|
.TP |
|
\fB\-early_stdio_test\fR "on"|"appendable_wo"|"off" |
|
If enabled by "on" then regular files and block devices get tested for |
|
effective access permissions. This implies to try opening those files for |
|
writing, which otherwise will happen only later and only if actual |
|
writing is desired. |
|
.br |
|
The test result is used for classifying the pseudo drives as overwriteable, |
|
read\-only, write\-only, or uselessly empty. This may lead to earlier detection |
|
of severe problems, and may avoid some less severe error events. |
|
.br |
|
Mode "appendable_wo" is like "on" with the additional property that |
|
non\-empty write\-only files are regarded as appendable rather than blank. |
|
.TP |
|
\fB\-data_cache_size\fR number_of_tiles blocks_per_tile |
|
Set the size and granularity of the data cache which is used when ISO images |
|
are loaded and when file content is read from ISO images. The cache consists |
|
of several tiles, which each consists of several blocks. A larger cache |
|
reduces the need for tiles being read multiple times. Larger tiles might |
|
additionally improve the data throughput from the drive, but can be |
|
wasteful if the data are scattered over the medium. |
|
.br |
|
Larger cache sizes help best with image loading from MMC drives. They are an |
|
inferior alternative to \-osirrox option "sort_lba_on". |
|
.br |
|
blocks_per_tile must be a power of 2. E.g. 16, 32, or 64. The overall cache |
|
size must not exceed 1 GiB. |
|
The default values can be restored by parameter "default" instead of one or |
|
both of the numbers. |
|
Currently the default is 32 tiles of 32 blocks = 2 MiB. |
|
.TP |
|
.B Inserting files into ISO image: |
|
.PP |
|
The following commands expect file addresses of two kinds: |
|
.br |
|
\fBdisk_path\fR |
|
is a path to an object in the local filesystem tree. |
|
.br |
|
\fBiso_rr_path\fR |
|
is the Rock Ridge name of a file object in the ISO image. |
|
If no Rock Ridge information is recorded in the loaded ISO image, then you |
|
will see ISO 9660 names which are of limited length and character set. |
|
If no Rock Ridge information shall be stored in an emerging ISO image, then |
|
their names will get mapped to such restricted ISO 9660 (aka ECMA\-119) names. |
|
.PP |
|
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. |
|
.PP |
|
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: |
|
.br |
|
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 |
|
\fB\-overwrite\fR |
|
decides. |
|
.br |
|
Renaming of files has similar collision handling, but directories can only |
|
be replaced, not merged. Note that if the target directory exists, then \-mv |
|
inserts the source objects into this directory rather than attempting |
|
to replace it. Command \-move, on the other hand, would attempt to replace it. |
|
.PP |
|
The commands in this section alter the ISO image and not the local filesystem. |
|
.TP |
|
\fB\-disk_pattern\fR "on"|"ls"|"off" |
|
Set the pattern expansion mode for the disk_path parameters of several |
|
commands which support this feature. |
|
.br |
|
Setting "off" disables this feature for all commands which are marked in this |
|
man page by "disk_path [***]" or "disk_pattern [***]". |
|
.br |
|
Setting "on" enables it for all those commands. |
|
.br |
|
Setting "ls" enables it only for those which are marked by |
|
"disk_pattern [***]". |
|
.br |
|
Default is "ls". |
|
.TP |
|
\fB\-add\fR pathspec [...] | disk_path [***] |
|
Insert the given files or directory trees from filesystem |
|
into the ISO image. |
|
.br |
|
If \-pathspecs is set to "on" or "as_mkisofs" then pattern expansion is always |
|
disabled and character '=' has a special meaning. It separates the ISO image |
|
path from the disk path: |
|
.br |
|
iso_rr_path=disk_path |
|
.br |
|
Character '=' in the iso_rr_path must be escaped by '\\' (i.e. as "\\="). |
|
.br |
|
With \-pathspecs "on", the character '\\' must not be escaped. The character '=' |
|
in the disk_path must not be escaped. |
|
.br |
|
With \-pathspecs "as_mkisofs", all characters '\\' must be escaped in both, |
|
iso_rr_path and disk_path. The character '=' may or may not be escaped |
|
in the disk_path. |
|
.br |
|
If iso_rr_path does not begin with '/' then \-cd is prepended. |
|
If disk_path does not begin with '/' then \-cdx is prepended. |
|
.br |
|
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. |
|
.br |
|
If \-pathspecs is set to "off" then \-disk_pattern expansion applies, if enabled. |
|
The resulting words are used as both, iso_rr_path and disk path. Relative |
|
path words get prepended the setting of \-cdx to disk_path and the setting |
|
of \-cd to iso_rr_path. |
|
.TP |
|
\fB\-add_plainly\fR mode |
|
If set to mode "unknown" then any command word that does not begin with "\-" and |
|
is not recognized as known command will be subject to a virtual \-add command. |
|
I.e. it will be used as pathspec or as disk_path and added to the image. |
|
If enabled, \-disk_pattern expansion applies to disk_paths. |
|
.br |
|
Mode "dashed" is similar to "unknown" but also adds unrecognized command |
|
words even if they begin with "\-". |
|
.br |
|
Mode "any" announces that all further words are to be added as pathspecs |
|
or disk_paths. This does not work in dialog mode. |
|
.br |
|
Mode "none" is the default. It prevents any words from being understood |
|
as files to add, if they are not parameters to appropriate commands. |
|
.TP |
|
\fB\-path_list\fR disk_path |
|
Like \-add but read the parameter words from file disk_path |
|
or standard input if disk_path is "\-". |
|
The list must contain exactly one pathspec or disk_path pattern per line. |
|
.TP |
|
\fB\-quoted_path_list\fR disk_path |
|
Like \-path_list but with quoted input reading rules. Lines get split into |
|
parameter words for \-add. Whitespace outside quotes is discarded. |
|
.TP |
|
\fB\-map\fR disk_path iso_rr_path |
|
Insert file object disk_path into the ISO image as iso_rr_path. If disk_path |
|
is a directory then its whole sub tree is inserted into the ISO image. |
|
.TP |
|
\fB\-map_single\fR disk_path iso_rr_path |
|
Like \-map, but if disk_path is a directory then its sub tree is not inserted. |
|
.TP |
|
\fB\-map_l\fR disk_prefix iso_rr_prefix disk_path [***] |
|
Perform \-map with each of the disk_path parameters. iso_rr_path will be |
|
composed from disk_path by replacing disk_prefix by iso_rr_prefix. |
|
.TP |
|
\fB\-update\fR disk_path iso_rr_path |
|
Compare file object disk_path with file object iso_rr_path. If they do not |
|
match, then perform the necessary image manipulations to make iso_rr_path |
|
a matching copy of disk_path. By default this comparison will imply lengthy |
|
content reading before a decision is made. Commands \-disk_dev_ino or \-md5 may |
|
accelerate comparison if they were already in effect when the loaded session |
|
was recorded. |
|
.br |
|
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. |
|
.TP |
|
\fB\-update_r\fR disk_path iso_rr_path |
|
Like \-update but working recursively. I.e. all file objects below both |
|
addresses get compared whether they have counterparts below the other address |
|
and whether both counterparts match. If there is a mismatch then the necessary |
|
update manipulation is done. |
|
.br |
|
Note that the comparison result may depend on command \-follow. Its setting |
|
should always be the same as with the first adding of disk_path as iso_rr_path. |
|
.br |
|
If iso_rr_path does not exist yet, then it gets added. If disk_path does not |
|
exist, then iso_rr_path gets deleted. |
|
.TP |
|
\fB\-update_l\fR disk_prefix iso_rr_prefix disk_path [***] |
|
Perform \-update_r with each of the disk_path parameters. iso_rr_path will be |
|
composed from disk_path by replacing disk_prefix by iso_rr_prefix. |
|
.TP |
|
\fB\-cut_out\fR disk_path byte_offset byte_count iso_rr_path |
|
Map a byte interval of a regular disk file into a regular file in the ISO |
|
image. |
|
This may be necessary if the disk file is larger than a single medium, or if |
|
it exceeds the traditional limit of 2 GiB \- 1 for old operating systems, |
|
or the limit of 4 GiB \- 1 for newer ones. Only the newest Linux kernels |
|
seem to read properly files >= 4 GiB \- 1. |
|
.br |
|
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: |
|
.br |
|
\-cut_out /my/disk/file 0 2047m \\ |
|
.br |
|
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \\ |
|
.br |
|
\-cut_out /my/disk/file 2047m 2047m \\ |
|
.br |
|
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \\ |
|
.br |
|
\-cut_out /my/disk/file 4094m 2047m \\ |
|
.br |
|
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821 |
|
.br |
|
While command \-split_size is set larger than 0, and if all pieces of a file |
|
reside in the same ISO directory with no other files, and if the names look |
|
like above, then their ISO directory will be recognized and handled like a |
|
regular file. This affects commands \-compare*, \-update*, and overwrite |
|
situations. |
|
See command \-split_size for details. |
|
.TP |
|
\fB\-cpr\fR disk_path [***] iso_rr_path |
|
Insert the given files or directory trees from filesystem |
|
into the ISO image. |
|
.br |
|
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. |
|
.br |
|
If a single disk_path is present then a non\-existing iso_rr_path will |
|
get the same type as the disk_path. |
|
.br |
|
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. |
|
.TP |
|
\fB\-mkdir\fR iso_rr_path [...] |
|
Create empty directories if they do not exist yet. |
|
Existence as directory generates a WARNING event, existence as |
|
other file causes a FAILURE event. |
|
.TP |
|
\fB\-lns\fR target_text iso_rr_path |
|
Create a symbolic link with address iso_rr_path which points to target_text. |
|
iso_rr_path may not exist yet. |
|
.br |
|
Hint: Command \-clone produces the ISO equivalent of a hard link. |
|
.TP |
|
\fB\-clone\fR iso_rr_path_original iso_rr_path_copy |
|
Create a copy of the ISO file object iso_rr_path_original with the new |
|
address iso_rr_path_copy. If the original is a directory then copy all |
|
files and directories underneath. If iso_rr_path_original is a boot catalog |
|
file, then it gets not copied but is silently ignored. |
|
.br |
|
The copied ISO file objects have the same attributes. Copied data files |
|
refer to the same content source as their originals. |
|
The copies may then be manipulated independendly of their originals. |
|
.br |
|
This command will refuse execution if the address iso_rr_path_copy |
|
already exists in the ISO tree. |
|
.TP |
|
\fB\-cp_clone\fR iso_rr_path_original [***] iso_rr_path_dest |
|
Create copies of one or more ISO file objects as with command \-clone. |
|
In case of collision merge directories with existing ones, but do not overwrite |
|
existing ISO file objects. |
|
.br |
|
The rules for generating the copy addresses are the same as with |
|
command \-cpr (see above) or shell command cp \-r. Other than with \-cpr, |
|
relative iso_rr_path_original will get prepended the \-cd path and not |
|
the \-cdx path. Consider to \-mkdir iso_rr_path_dest before \-cp_clone |
|
so the copy address does not depend on the number of iso_rr_path_original |
|
parameters. |
|
.TP |
|
.B Settings for file insertion: |
|
.TP |
|
\fB\-file_size_limit\fR value [value [...]] -- |
|
Set the maximum permissible size for a single data file. The values get |
|
summed up for the actual limit. If the only value is "off" then the file |
|
size is not limited by \fBxorriso\fR. |
|
Default is a limit of 100 extents, 4g \-2k each: |
|
.br |
|
\-file_size_limit 400g \-200k \-\- |
|
.br |
|
When mounting ISO 9660 filesystems, old operating systems can handle only files |
|
up to 2g \-1 \-\-. Newer ones are good up to 4g \-1 \-\-. |
|
You need quite a new Linux kernel to read correctly the final bytes |
|
of a file >= 4g if its size is not aligned to 2048 byte blocks. |
|
.br |
|
\fBxorriso\fR's own data read capabilities are not affected by |
|
operating system size limits. Such limits apply to mounting only. Nevertheless, |
|
the target filesystem of an \-extract must be able to take the file size. |
|
.TP |
|
\fB\-not_mgt\fR code[:code[...]] |
|
Control the behavior of the exclusion lists. |
|
.br |
|
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. |
|
.br |
|
Several codes are defined. |
|
The _on/_off settings persist until they are revoked by their_off/_on |
|
counterparts. |
|
.br |
|
"erase" empties the lists which were accumulated by \-not_paths and \-not_leaf. |
|
.br |
|
"reset" is like "erase" but also re\-installs default behavior. |
|
.br |
|
"off" disables exclusion processing temporarily without invalidating |
|
the lists and settings. |
|
.br |
|
"on" re\-enables exclusion processing. |
|
.br |
|
"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. |
|
.br |
|
"param_on" applies exclusion processing to command parameters as well as |
|
to files below such parameters. |
|
.br |
|
"subtree_off" with "param_on" excludes parameter paths only if they |
|
match a \-not_paths item exactly. |
|
.br |
|
"subtree_on" additionally excludes parameter paths which lead to a file |
|
address below any \-not_paths item. |
|
.br |
|
"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. |
|
.br |
|
"ignore_on" keeps excluded files out of \-compare or \-update activities. |
|
.TP |
|
\fB\-not_paths\fR disk_path [***] |
|
Add the given paths to the list of excluded absolute disk paths. If a given |
|
path is relative, then the current \-cdx is prepended to form an absolute path. |
|
Pattern matching, if enabled, happens at definition time and not when exclusion |
|
checks are made. |
|
.br |
|
(Do not forget to end the list of disk_paths by "\-\-") |
|
.TP |
|
\fB\-not_leaf\fR pattern |
|
Add a single shell parser style pattern to the list of exclusions for |
|
disk leafnames. These patterns are evaluated when the exclusion checks are |
|
made. |
|
.TP |
|
\fB\-not_list\fR disk_path |
|
Read lines from disk_path and use each of them either as \-not_paths parameter, |
|
if they contain a / character, or as \-not_leaf pattern. |
|
.TP |
|
\fB\-quoted_not_list\fR disk_path |
|
Like \-not_list but with quoted input reading rules. Each word is |
|
handled as one parameter for \-not_paths or \-not_leaf. |
|
.TP |
|
\fB\-follow\fR occasion[:occasion[...]] |
|
Enable or disable resolution of symbolic links and mountpoints under |
|
disk_paths. This applies to actions \-add, \-du*x, \-ls*x, \-findx, \-concat, |
|
and to \-disk_pattern expansion. |
|
.br |
|
There are three kinds of follow decisison to be made: |
|
.br |
|
\fBlink\fR is the hop from a symbolic link to its target file object for the |
|
purpose of reading. I.e. not for command \-concat. |
|
If enabled then symbolic links are handled as their target file objects, |
|
else symbolic links are handled as themselves. |
|
.br |
|
\fBmount\fR 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. |
|
.br |
|
\fBconcat\fR is the hop from a symbolic link to its target file object for |
|
the purpose of writing. I.e. for command \-concat. This is a security risk ! |
|
.br |
|
Less general than above occasions: |
|
.br |
|
\fBpattern\fR is mount and link hopping, but only during \-disk_pattern |
|
expansion. |
|
.br |
|
\fBparam\fR 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). |
|
.br |
|
Occasions can be combined in a colon separated list. All occasions |
|
mentioned in the list will then lead to a positive follow decision. |
|
.br |
|
\fBoff\fR prevents any positive follow decision. Use it if no other occasion |
|
applies. |
|
.br |
|
Shortcuts: |
|
.br |
|
\fBdefault\fR is equivalent to "pattern:mount:limit=100". |
|
.br |
|
\fBon\fR always decides positive. Equivalent to "link:mount:concat". |
|
.br |
|
|
|
Not an occasion but an optional setting is: |
|
.br |
|
\fBlimit=\fR<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: |
|
.br |
|
$ ln \-s .. uploop |
|
.br |
|
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. |
|
.TP |
|
\fB\-pathspecs\fR "on"|"off"|"as_mkisofs" |
|
Control parameter interpretation with \fBxorriso\fR |
|
actions \-add and \-path_list. |
|
.br |
|
Mode "as_mkisofs" enables pathspecs of the form |
|
.br |
|
\fBiso_rr_path=disk_path\fR |
|
.br |
|
like with program mkisofs \-graft\-points. |
|
.br |
|
All characters '\\' must be escaped in both, iso_rr_path and disk_path. |
|
The character '=' must be escaped in the iso_rr_path and |
|
may or may not be escaped in the disk_path. |
|
This mode temporarily disables \-disk_pattern expansion for command \-add. |
|
.br |
|
Mode "on" does nearly the same. But '=' must only be escaped in the iso_rr_path |
|
and '\\' must not be escaped at all. This has the disadvantage that one |
|
cannot express an iso_rr_path which ends by '\\'. |
|
.br |
|
Mode "off" disables pathspecs of the form target=source |
|
and re\-enables \-disk_pattern expansion. |
|
.TP |
|
\fB\-overwrite\fR "on"|"nondir"|"off" |
|
Allow or disallow overwriting of existing files in the |
|
ISO image by files with the same name. |
|
.br |
|
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" enables automatic \-rm_r. I.e. a non\-directory can replace an |
|
existing directory and all its subordinates. |
|
.br |
|
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". |
|
.TP |
|
\fB\-split_size\fR number["k"|"m"] |
|
Set the threshold for automatic splitting of regular files. Such splitting |
|
maps a large disk file onto a ISO directory with several part files in it. |
|
This is necessary if the size of the disk file exceeds \-file_size_limit. |
|
Older operating systems can handle files in mounted ISO 9660 filesystems |
|
only if they are smaller than 2 GiB or in other cases 4 GiB. |
|
.br |
|
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. |
|
.br |
|
While command \-split_size is set larger than 0 such a directory with split |
|
file pieces will be recognized and handled like a regular file by commands |
|
\-compare* , \-update*, and in overwrite situations. There are \-ossirox |
|
parameters "concat_split_on" and "concat_split_off" which control the handling |
|
when files get restored to disk. |
|
.br |
|
In order to be recognizable, the names of the part files have to |
|
describe the splitting by 5 numbers: |
|
.br |
|
part_number,total_parts,byte_offset,byte_count,disk_file_size |
|
.br |
|
which are embedded in the following text form: |
|
.br |
|
part_#_of_#_at_#_with_#_of_# |
|
.br |
|
Scaling characters like "m" or "k" are taken into respect. |
|
All digits are interpreted as decimal, even if leading zeros are present. |
|
.br |
|
E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821 |
|
.br |
|
No other files are allowed in the directory. All parts have to be present and |
|
their numbers have to be plausible. E.g. byte_count must be valid as \-cut_out |
|
parameter and their contents may not overlap. |
|
.TP |
|
.B File manipulations: |
|
.PP |
|
The following commands manipulate files in the ISO image, regardless whether |
|
they stem from the loaded image or were newly inserted. |
|
.PP |
|
.TP |
|
\fB\-iso_rr_pattern\fR "on"|"ls"|"off" |
|
Set the pattern expansion mode for the iso_rr_path parameters of several |
|
commands which support this feature. |
|
.br |
|
Setting "off" disables pattern expansion for all commands which are marked |
|
in this man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". |
|
.br |
|
Setting "on" enables it for all those commands. |
|
.br |
|
Setting "ls" enables it only for those which are marked by |
|
"iso_rr_pattern [***]". |
|
.br |
|
Default is "on". |
|
.TP |
|
\fB\-rm\fR iso_rr_path [***] |
|
Delete the given files from the ISO image. |
|
.br |
|
Note: This does not free any space on the \-indev medium, even if |
|
the deletion is committed to that same medium. |
|
.br |
|
The image size will shrink if the image is written to a different |
|
medium in modification mode. |
|
.TP |
|
\fB\-rm_r\fR iso_rr_path [***] |
|
Delete the given files or directory trees from the ISO image. |
|
See also the note with command \-rm. |
|
.TP |
|
\fB\-rmdir\fR iso_rr_path [***] |
|
Delete empty directories. |
|
.TP |
|
\fB\-move\fR iso_rr_path iso_rr_path |
|
Rename the file given by the first (origin) iso_rr_path to the second |
|
(destination) iso_rr_path. |
|
Deviate from rules of shell command mv by not moving the origin file underneath |
|
an existing destination directory. The origin file will rather replace such a |
|
directory, if this is allowed by command \-overwrite. |
|
.TP |
|
\fB\-mv\fR iso_rr_path [***] iso_rr_path |
|
Rename the given file objects in the ISO tree to the last |
|
parameter in the list. Use the same rules as with shell command mv. |
|
.br |
|
If pattern expansion is enabled and if the last parameter contains wildcard |
|
characters then it must match exactly one existing file address, or else the |
|
command fails with a FAILURE event. |
|
.TP |
|
\fB\-chown\fR uid iso_rr_path [***] |
|
Set ownership of file objects in the ISO image. uid may either be a decimal |
|
number or the name of a user known to the operating system. |
|
.TP |
|
\fB\-chown_r\fR uid iso_rr_path [***] |
|
Like \-chown but affecting all files below eventual directories. |
|
.TP |
|
\fB\-chgrp\fR gid iso_rr_path [***] |
|
Set group attribute of file objects in the ISO image. gid may either be a |
|
decimal number or the name of a group known to the operating system. |
|
.TP |
|
\fB\-chgrp_r\fR gid iso_rr_path [***] |
|
Like \-chgrp but affecting all files below eventual directories. |
|
.TP |
|
\fB\-chmod\fR mode iso_rr_path [***] |
|
Equivalent to shell command chmod in the ISO image. |
|
mode is either an octal number beginning with "0" or a comma separated |
|
list of statements of the form [ugoa]*[+\-=][rwxst]* . |
|
.br |
|
Like: go\-rwx,u+rwx . |
|
.br |
|
\fBPersonalities\fR: |
|
u=user, g=group, o=others, a=all |
|
.br |
|
\fBOperators\fR: |
|
+ adds given permissions, \- revokes given permissions, |
|
= revokes all old permissions and then adds the given ones. |
|
.br |
|
\fBPermissions\fR: |
|
r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit |
|
.br |
|
For octal numbers see man 2 stat. |
|
.TP |
|
\fB\-chmod_r\fR mode iso_rr_path [***] |
|
Like \-chmod but affecting all files below eventual directories. |
|
.TP |
|
\fB\-setfacl\fR acl_text iso_rr_path [***] |
|
Attach the given ACL to the given iso_rr_paths. If the files already have |
|
ACLs, then those get deleted before the new ones get into effect. |
|
If acl_text is empty, or contains the text "clear" or the text |
|
"\-\-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: |
|
.br |
|
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 |
|
or group id. After the second ":" there may be letters out of {rwx\- #}. |
|
The first three give read, write, or 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: |
|
.br |
|
g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw |
|
.br |
|
group:toolies:rw\-,user::rw\-,group::r\-\-,other::r\-\-,mask::rw\- |
|
.br |
|
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: |
|
.br |
|
u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx |
|
.TP |
|
\fB\-setfacl_r\fR acl_text iso_rr_path [***] |
|
Like \-setfacl but affecting all files below eventual directories. |
|
.TP |
|
\fB\-setfacl_list\fR disk_path |
|
Read the output of \-getfacl_r or shell command getfacl \-R and apply it to the |
|
iso_rr_paths as given in lines beginning with "# file:". This will change |
|
ownership, group and ACL of the given files. |
|
If disk_path is "\-" then lines are read from standard input. Line "@" ends the |
|
list, "@@@" aborts without changing the pending iso_rr_path. |
|
.br |
|
Since \-getfacl and getfacl \-R strip leading "/" from file paths, the setting of |
|
\-cd does always matter. |
|
.TP |
|
\fB\-setfattr\fR [-]name value iso_rr_path [***] |
|
Attach the given xattr pair of name and value to the given iso_rr_paths. |
|
If the given name is prefixed by "\-", then the pair with that name gets |
|
removed from the xattr list. If name is "\-\-remove\-all" |
|
then all user namespace |
|
xattr of the given iso_rr_paths get deleted. In case of deletion, value must |
|
be an empty text. |
|
.br |
|
Only names from the user namespace are allowed. I.e. a name has to begin with |
|
"user.", like "user.x" or "user.whatever". |
|
.br |
|
Values and names undergo the normal input processing of \fBxorriso\fR. |
|
See also command \-backslash_codes. Other than with command \-setfattr_list, |
|
the byte value 0 cannot be expressed via \-setfattr. |
|
.TP |
|
\fB\-setfattr_r\fR [-]name value iso_rr_path [***] |
|
Like \-setfattr but affecting all files below eventual directories. |
|
.TP |
|
\fB\-setfattr_list\fR disk_path |
|
Read the output of \-getfattr_r or shell command getfattr \-Rd and apply it to |
|
the iso_rr_paths as given in lines beginning with "# file:". All previously |
|
existing user space xattr of the given iso_rr_paths will be deleted. |
|
If disk_path is "\-" then lines are read from standard input. |
|
.br |
|
Since \-getfattr and getfattr \-Rd strip leading "/" from file paths, the setting |
|
of \-cd does always matter. |
|
.br |
|
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 |
|
.br |
|
name="value" |
|
.br |
|
Name must be from user namespace. I.e. user.xyz where xyz should consist of |
|
printable characters only. The separator "=" is not allowed in names. |
|
Value may contain any kind of bytes. It must be in quotes. Trailing |
|
whitespace after the end quote will be ignored. Non\-printables bytes and quotes |
|
must be represented as \\XYZ by their octal 8\-bit code XYZ. |
|
Use code \\000 for 0\-bytes. |
|
.TP |
|
\fB\-alter_date\fR type timestring iso_rr_path [***] |
|
Alter the date entries of files in the ISO image. type may be one of |
|
the following: |
|
.br |
|
"a" sets access time, updates ctime. |
|
.br |
|
"m" sets modification time, updates ctime. |
|
.br |
|
"b" sets access time and modification time, updates ctime. |
|
.br |
|
"a\-c", "m\-c", and "b\-c" set the times without updating ctime. |
|
.br |
|
"c" sets the ctime. |
|
.br |
|
timestring may be in the following formats |
|
(see also section EXAMPLES): |
|
.br |
|
As expected by program date: |
|
MMDDhhmm[[CC]YY][.ss]] |
|
.br |
|
As produced by program date: |
|
.br |
|
[Day] MMM DD hh:mm:ss [TZON] YYYY |
|
.br |
|
Relative times counted from current clock time: |
|
.br |
|
+|\-Number["s"|"h"|"d"|"w"|"m"|"y"] |
|
.br |
|
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, |
|
"y"=365.25d plus 1d added to multiplication result. |
|
.br |
|
Absolute seconds counted from Jan 1 1970: |
|
.br |
|
=Number |
|
.br |
|
\fBxorriso\fR's own timestamps: |
|
.br |
|
YYYY.MM.DD[.hh[mm[ss]]] |
|
.br |
|
scdbackup timestamps: |
|
.br |
|
YYMMDD[.hhmm[ss]] |
|
.br |
|
where "A0" is year 2000, "B0" is 2010, etc. |
|
.br |
|
ECMA\-119 volume timestamps: |
|
.br |
|
YYYYMMDDhhmmsscc |
|
.br |
|
These are normally given as GMT. The suffix "LOC" causes local timezone |
|
conversion. E.g. 2013010720574700, 2013010720574700LOC. |
|
The last two digits cc (centiseconds) will be ignored, but must be present |
|
in order to make the format recognizable. |
|
.br |
|
Example: |
|
.br |
|
\-alter_date m\-c 2013.11.27.103951 /file1 /file2 \-\- |
|
.TP |
|
\fB\-alter_date_r\fR type timestring iso_rr_path [***] |
|
Like \-alter_date but affecting all files below eventual directories. |
|
.TP |
|
\fB\-hide\fR hide_state iso_rr_path [***] |
|
Prevent the names of the given files from showing up in the directory trees |
|
of ISO 9660 and/or Joliet and/or HFS+ when the image gets written. |
|
The data content of such hidden files will be included in the |
|
resulting image, even if they do not show up in any directory. |
|
But you will need own means to find nameless data in the image. |
|
.br |
|
Warning: Data which are hidden from the ISO 9660 tree will not be copied |
|
by the write method of modifying. |
|
.br |
|
Possible values of hide_state are: "iso_rr" for hiding from ISO 9660 tree, |
|
"joliet" for Joliet tree, "hfsplus" for HFS+, "on" for them all. |
|
"off" means visibility in all directory trees. |
|
.br |
|
These values may be combined. |
|
E.g.: joliet:hfsplus |
|
.br |
|
This command does not apply to the boot catalog. |
|
Rather use: \-boot_image "any" "cat_hidden=on" |
|
.TP |
|
.B Tree traversal command -find: |
|
.PP |
|
.TP |
|
\fB\-find\fR iso_rr_path [test [op] [test ...]] [-exec action [params]] -- |
|
A restricted substitute for shell command find in the ISO image. |
|
It performs an action on matching file objects at or below iso_rr_path. |
|
.br |
|
If not used as last command in the line then the parameter list |
|
needs to get terminated by "\-\-". |
|
.br |
|
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. |
|
.br |
|
Available tests are: |
|
.br |
|
\fB\-name\fR pattern : |
|
Matches if pattern matches the file leaf name. If the pattern does not contain |
|
any of the characters "*?[", then it will be truncated according |
|
to \-file_name_limit and thus match the truncated name in the ISO filesystem. |
|
.br |
|
\fB\-wholename\fR pattern : |
|
Matches if pattern matches the file path as it would be printed by action |
|
"echo". Character '/' can be matched by wildcards. If pattern pieces |
|
between '/' do not contain any of the characters "*?[", they will |
|
be truncated according to \-file_name_limit. |
|
.br |
|
\fB\-disk_name\fR pattern : |
|
Like \-name but testing the leaf name of the file source on disk. |
|
Can match only data files which do not stem from the loaded image, |
|
or for directories above such data files. With directories the result can |
|
change between \-find runs if their content stems from multiple sources. |
|
.br |
|
\fB\-disk_path\fR disk_path : |
|
Matches if the given disk_path is equal to the path of the file source |
|
on disk. The same restrictions apply as with \-disk_name. |
|
.br |
|
\fB\-type\fR type_letter : |
|
Matches files of the given type: |
|
"block", "char", "dir", "pipe", "file", "link", "socket", "eltorito", |
|
and "Xotic" which matches what is not matched by the other types. |
|
.br |
|
Only the first letter is interpreted. E.g.: \-find / \-type d |
|
.br |
|
\fB\-damaged\fR : |
|
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. |
|
.br |
|
Note that a MD5 session mismatch marks all files of the session as damaged. |
|
If finer distinction is desired, perform \-md5 off before \-check_media. |
|
.br |
|
\fB\-pending_data\fR : |
|
Matches files which get their content from outside the loaded ISO image. |
|
.br |
|
\fB\-lba_range\fR start_lba block_count : |
|
Matches files which use data blocks within the range of start_lba |
|
and start_lba+block_count\-1. |
|
.br |
|
\fB\-has_acl\fR : |
|
Matches files which have a non\-trivial ACL. |
|
.br |
|
\fB\-has_xattr\fR : |
|
Matches files which have xattr name\-value pairs from user namespace. |
|
.br |
|
\fB\-has_aaip\fR : |
|
Matches files which have ACL or any xattr. |
|
.br |
|
\fB\-has_any_xattr\fR : |
|
Matches files which have any xattr other than ACL. |
|
.br |
|
\fB\-has_md5\fR : |
|
Matches data files which have MD5 checksums. |
|
.br |
|
\fB\-has_hfs_crtp\fR creator type : |
|
Matches files which have the given HFS+ creator and type attached. |
|
These are codes of 4 characters which get stored if \-hfsplus is |
|
enabled. Use a single dash '\-' as wildcard that matches any such code. |
|
E.g:. |
|
.br |
|
\-has_hfs_crtp YYDN TEXT |
|
.br |
|
\-has_hfs_crtp \- \- |
|
.br |
|
\fB\-has_hfs_bless\fR blessing : |
|
Matches files which bear the given HFS+ blessing. It may be one of : |
|
"ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx_folder", |
|
"any". See also action set_hfs_bless. |
|
.br |
|
\fB\-has_filter\fR : |
|
Matches files which are filtered by \-set_filter. |
|
.br |
|
\fB\-hidden\fR hide_state : |
|
Matches files which are hidden in "iso_rr" tree, in "joliet" tree, |
|
in "hfsplus" tree, in all trees ("on"), or not hidden in any tree ("off"). |
|
.br |
|
Those which are hidden in some tree match \-not \-hidden "off". |
|
.br |
|
\fB\-bad_outname\fR namespace : |
|
Matches files with names which change when converted forth and back |
|
between the local character set and one of the namespaces "rockridge", |
|
"joliet", "ecma119", "hfsplus". |
|
.br |
|
All applicable \-compliance rules are taken into respect. |
|
Rule "omit_version" is always enabled, because else |
|
namespaces "joliet" and "ecma119" would cause changes with every |
|
non\-directory name. |
|
Consider to also enable rules "no_force_dots" and "no_j_force_dots". |
|
.br |
|
The namespaces use different character sets and apply further restrictions |
|
to name length, permissible characters, and mandatory name components. |
|
"rockridge" uses the character set defined by \-out_charset, |
|
"joliet" uses UCS\-2BE, "ecma119" uses ASCII, "hfsplus" uses UTF\-16BE. |
|
.br |
|
\fB\-name_limit_blocker\fR length : |
|
Matches file names which would prevent command \-file_name_limit with the |
|
given length. The command itself reports only the first problem file. |
|
.br |
|
\fB\-prune\fR : |
|
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. |
|
.br |
|
\fB\-use_pattern\fR "on"|"off" : |
|
This pseudo test controls the interpretation of wildcards with tests |
|
\-name, \-wholename, and \-disk_name. Default is "on". If interpretation |
|
is disabled by "off", then the parameters of \-name, \-wholename, and \-disk_name |
|
have to match literally rather than as search pattern. |
|
This test itself does always match. |
|
.br |
|
\fB\-or_use_pattern\fR "on"|"off" : |
|
Like \-use_pattern, but automatically appending the test by \-or rather |
|
than by \-and. Further the test itself does never match. So a subsequent |
|
test \-or will cause its other operand to be performed. |
|
.br |
|
\fB\-decision\fR "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. |
|
.br |
|
\fB\-true\fR and \fB\-false\fR : |
|
Always match or match not, respectively. Evaluation goes on. |
|
.br |
|
\fB\-sort_lba\fR : |
|
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. |
|
.br |
|
Available operators are: |
|
.br |
|
\fB\-not\fR : |
|
Matches if the next test or sub expression does not match. |
|
Several tests do this specifically: |
|
.br |
|
\-undamaged, \-lba_range with negative start_lba, \-has_no_acl, \-has_no_xattr, |
|
\-has_no_aaip, \-has_no_filter . |
|
.br |
|
\fB\-and\fR : |
|
Matches if both neighboring tests or expressions match. |
|
.br |
|
\fB\-or\fR : |
|
Matches if at least one of both neighboring tests or expressions matches. |
|
.br |
|
\fB\-sub\fR ... \fB\-subend\fR or \fB(\fR ... \fB)\fR : |
|
Enclose a sub expression which gets evaluated first before it |
|
is processed by neighboring operators. |
|
Normal precedence is: \-not, \-or , \-and. |
|
.br |
|
\fB\-if\fR ... \fB\-then\fR\ ... \fB\-elseif\fR ... \fB\-then\fR ... |
|
\fB\-else\fR ... \fB\-endif\fR : |
|
Enclose one or more sub expressions. If the \-if expression matches, then |
|
the \-then expression is evaluated as the result of the whole expression |
|
up to \-endif. Else the next \-elseif expression is evaluated and if it matches, |
|
its \-then expression. Finally in case of no match, the \-else expression |
|
is evaluated. |
|
There may be more than one \-elseif. Neither \-else nor \-elseif are mandatory. |
|
If \-else is missing and would be hit, then the result is a non\-match. |
|
.br |
|
\-if\-expressions are the main use case for above test \-decision. |
|
|
|
Default action is \fBecho\fR, |
|
i.e. to print the address of the found file. Other actions are certain |
|
\fBxorriso\fR commands which get performed on the found files. |
|
These commands |
|
may have specific parameters. See also their particular descriptions. |
|
.br |
|
\fBchown\fR and \fBchown_r\fR |
|
change the ownership and get the user id |
|
as parameter. E.g.: \-exec chown thomas \-\- |
|
.br |
|
\fBchgrp\fR and \fBchgrp_r\fR |
|
change the group attribute and get the group id |
|
as parameter. E.g.: \-exec chgrp_r staff \-\- |
|
.br |
|
\fBchmod\fR and \fBchmod_r\fR |
|
change access permissions and get a mode string |
|
as parameter. E.g.: \-exec chmod a\-w,a+r \-\- |
|
.br |
|
\fBalter_date\fR and \fBalter_date_r\fR |
|
change the timestamps. They get a type |
|
character and a timestring as parameters. |
|
.br |
|
E.g.: \-exec alter_date "m" "Dec 30 19:34:12 2007" \-\- |
|
.br |
|
\fBlsdl\fR |
|
prints file information like shell command ls \-dl. |
|
.br |
|
\fBcompare\fR |
|
performs command \-compare with the found file address as |
|
iso_rr_path and the corresponding file address below its parameter |
|
disk_path_start. For this the iso_rr_path of the \-find command gets |
|
replaced by the disk_path_start. |
|
.br |
|
E.g.: \-find /thomas \-exec compare /home/thomas \-\- |
|
.br |
|
\fBupdate\fR |
|
performs command \-update with the found file address as |
|
iso_rr_path. The corresponding file address is determined like with above |
|
action "compare". |
|
.br |
|
\fBupdate_merge\fR |
|
is like update but does not delete the found file if it is missing on disk. |
|
It may be run several times and records with all visited files whether their |
|
counterpart on disk has already been seen by one of the update_merge runs. |
|
Finally, a \-find run with action "rm_merge" may remove all files that |
|
saw no counterpart on disk. |
|
.br |
|
Up to the next "rm_merge" or "clear_merge" all newly inserted files will |
|
get marked as having a disk counterpart. |
|
.br |
|
\fBrm\fR |
|
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". |
|
.br |
|
\fBrm_r\fR |
|
removes the found iso_rr_path from the image, including whole |
|
directory trees. |
|
.br |
|
\fBrm_merge\fR |
|
removes the found iso_rr_path if it was visited by one or more previous actions |
|
"update_merge" and saw no counterpart on disk in any of them. The marking from |
|
the update actions is removed in any case. |
|
.br |
|
\fBclear_merge\fR |
|
removes an eventual marking from action "update_merge". |
|
.br |
|
\fBreport_damage\fR |
|
classifies files whether they hit a data block that is |
|
marked as damaged. The result is printed together with the address |
|
of the first damaged byte, the maximum span of damages, file size, and the |
|
path of the file. |
|
.br |
|
\fBreport_lba\fR |
|
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 has more than one section. |
|
In this case each line has a different extent number in column "xt". |
|
.br |
|
\fBreport_sections\fR |
|
like report_lba but telling the byte sizes of the particular sections rather |
|
than the overall byte size of the file. |
|
.br |
|
\fBgetfacl\fR |
|
prints access permissions in ACL text form to the result channel. |
|
.br |
|
\fBsetfacl\fR |
|
attaches ACLs after removing existing ones. The new |
|
ACL is given in text form as defined with command \-setfacl. |
|
.br |
|
E.g.: \-exec setfacl u:lisa:rw,u::rw,g::r,o::\-,m::rw \-\- |
|
.br |
|
\fBgetfattr\fR |
|
prints xattr name\-value pairs from user namespace |
|
to the result channel. |
|
.br |
|
\fBget_any_xattr\fR |
|
prints xattr name\-value pairs from any namespace |
|
except ACL to the result channel. This is mostly for debugging of |
|
namespace "isofs". |
|
.br |
|
\fBlist_extattr\fR mode |
|
prints a script to the result channel, which would use FreeBSD command |
|
setextattr to set the file's xattr name\-value pairs of user namespace. |
|
Parameter mode controls the form of the output of names and values. |
|
Default mode "e" prints harmless characters in shell quotation marks, |
|
but represents texts with octal 001 to 037 and 0177 to 0377 by an embedded |
|
echo \-e command. |
|
Mode "q" prints any characters in shell quotation marks. This might not be |
|
terminal\-safe but should work in script files. |
|
Mode "r" uses no quotation marks. Not safe. |
|
Mode "b" prints backslash encoding. Not suitable for shell parsing. |
|
.br |
|
E.g. \-exec list_extattr e \-\- |
|
.br |
|
Command \-backslash_codes does not affect the output. |
|
.br |
|
\fBget_md5\fR |
|
prints the MD5 sum, if recorded, together with file path. |
|
.br |
|
\fBcheck_md5\fR |
|
compares the MD5 sum, if recorded, with the file content |
|
and reports if mismatch. |
|
.br |
|
E.g.: \-find / \-not \-pending_data \-exec check_md5 FAILURE \-\- |
|
.br |
|
\fBmake_md5\fR |
|
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". |
|
.br |
|
E.g.: \-find / \-type f \-not \-has_md5 \-exec make_md5 \-\- |
|
.br |
|
\fBsetfattr\fR |
|
sets or deletes xattr name value pairs. |
|
.br |
|
E.g.: \-find / \-has_xattr \-exec setfattr \-\-remove\-all '' \-\- |
|
.br |
|
\fBset_hfs_crtp\fR |
|
adds, changes, or removes HFS+ creator and type attributes. |
|
.br |
|
E.g.: \-exec set_hfs_crtp YYDN TEXT |
|
.br |
|
E.g.: \-find /my/dir \-prune \-exec set_hfs_crtp \-\-delete \- |
|
.br |
|
\fBget_hfs_crtp\fR |
|
prints the HFS+ creator and type attributes together with the iso_rr_path, |
|
if the file has such attributes at all. |
|
.br |
|
E.g.: \-exec get_hfs_crtp |
|
.br |
|
\fBset_hfs_bless\fR |
|
applies or removes HFS+ blessings. They are roles which can be attributed to |
|
up to four directories and a data file: |
|
.br |
|
"ppc_bootdir", "intel_bootfile", "show_folder", "os9_folder", "osx_folder". |
|
.br |
|
They may be abbreviated as "p", "i", "s", "9", and "x". |
|
.br |
|
Each such role can be attributed to at most one file object. "intel_bootfile" |
|
is the one that would apply to a data file. All others apply to directories. |
|
The \-find run will end as soon as the first blessing is issued. The previous |
|
bearer of the blessing will lose it then. |
|
No file object can bear more than one blessing. |
|
.br |
|
E.g.: \-find /my/blessed/directory \-exec set_hfs_bless p |
|
.br |
|
Further there is blessing "none" or "n" which revokes any blessing from |
|
the found files. This \-find run will not stop when the first match is reached. |
|
.br |
|
E.g.: \-find / \-has_hfs_bless any \-exec set_hfs_bless none |
|
.br |
|
\fBget_hfs_bless\fR |
|
prints the HFS+ blessing role and the iso_rr_path, if the file is blessed |
|
at all. |
|
.br |
|
E.g.: \-exec get_hfs_bless |
|
.br |
|
\fBset_filter\fR |
|
applies or removes filters. |
|
.br |
|
E.g.: \-exec set_filter \-\-zisofs \-\- |
|
.br |
|
\fBmkisofs_r\fR |
|
applies the rules of mkisofs \-r to the file object: |
|
.br |
|
user id and group id become 0, all r\-permissions get granted, all w denied. |
|
If there is any x\-permission, then all three x get granted. |
|
s\- and t\-bits get removed. |
|
.br |
|
\fBsort_weight\fR |
|
attributes a LBA weight number to regular files. |
|
.br |
|
The number may range from \-2147483648 to 2147483647. The higher it is, the |
|
lower will be the block address of the file data in the emerging ISO image. |
|
Currently the boot catalog has a hardcoded weight of 1 billion. |
|
Normally it should occupy the block with the lowest possible address. |
|
.br |
|
Data files which are loaded by \-indev or \-dev get a weight between 1 and |
|
2 exp 28 = 268,435,456, depending on their block address. This shall keep |
|
them roughly in the same order if the write method of modifying is applied. |
|
.br |
|
Data files which are added by other commands get an initial weight of 0. |
|
Boot image files have a default weight of 2. |
|
.br |
|
E.g.: \-exec sort_weight 3 \-\- |
|
.br |
|
\fBshow_stream\fR |
|
shows the content stream chain of a data file. |
|
.br |
|
\fBshow_stream_id\fR |
|
is like show_stream, but also prints between stream type and first ":" |
|
in square brackets libisofs id numbers: [fs_id,dev_id,ino_id]. |
|
.br |
|
\fBhide\fR |
|
brings the file into one of the hide states "on", "iso_rr", "joliet", |
|
"hfsplus", "off". They may be combined. E.g.: joliet:hfsplus |
|
.br |
|
E.g.: |
|
.br |
|
\-find / \-disk_name *_secret \-exec hide on |
|
.br |
|
\fBprint_outname\fR |
|
prints in the first line the filename as registered by the program model, |
|
and in the second line the filename after conversion forth and back between |
|
local character set and one of the namespaces "rockridge", "joliet", "ecma119", |
|
or "hfsplus". The third output line is "\-\-" . |
|
.br |
|
The name conversion does not take into respect the possibility of name |
|
collisions in the target namespace. Such collisions are most likely in "joliet" |
|
and "ecma119", where they get resolved by automatic file name changes. |
|
.br |
|
E.g.: |
|
.br |
|
\-find / \-bad_outname joliet \-exec print_outname joliet |
|
.br |
|
\fBestimate_size\fR |
|
prints a lower and an upper estimation of the number of blocks which the |
|
found files together will occupy in the emerging ISO image. |
|
This does not account for the superblock, |
|
for the directories in the \-find path, or for image padding. |
|
.br |
|
\fBfind\fR |
|
performs another run of \-find on the matching file address. |
|
It accepts the same params as \-find, except iso_rr_path. |
|
.br |
|
E.g.: |
|
.br |
|
\-find / \-name '???' \-type d \-exec find \-name '[abc]*' \-exec chmod a\-w,a+r \-\- |
|
.TP |
|
.B Filters for data file content: |
|
.PP |
|
\fBFilters\fR 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. |
|
.br |
|
Built\-in filters are "\-\-zisofs" and |
|
"\-\-zisofs\-decode". The former is to be |
|
applied via \-set_filter, the latter is automatically applied if zisofs |
|
compressed content is detected with a file when loading the ISO image. |
|
.br |
|
Another built\-in filter pair is "\-\-gzip" |
|
and "\-\-gunzip" with suffix ".gz". |
|
They behave about like external gzip and gunzip but avoid forking a process |
|
for each single file. So they are much faster if there are many small files. |
|
.PP |
|
.TP |
|
\fB\-external_filter\fR name option[:option] program_path [arguments] -- |
|
Register a content filter by associating a name with a program path, |
|
program arguments, and some behavioral options. Once registered it can be |
|
applied to multiple data files in the ISO image, regardless whether their |
|
content resides in the loaded ISO image or in the local filesystem. |
|
External filter processes may produce synthetic file content by reading the |
|
original content from stdin and writing to stdout whatever they want. |
|
They must deliver the same output on the same input in repeated runs. |
|
.br |
|
Options are: |
|
.br |
|
"default" means that no other option is intended. |
|
.br |
|
"suffix=..." sets a file name suffix. If it is not empty then it will be |
|
appended to the file name or removed from it. |
|
.br |
|
"remove_suffix" will remove a file name suffix |
|
rather than appending it. |
|
.br |
|
"if_nonempty" will leave 0\-sized files unfiltered. |
|
.br |
|
"if_reduction" will try filtering and revoke it if the content size does not |
|
shrink. |
|
.br |
|
"if_block_reduction" will revoke if the number of 2 kB blocks does not shrink. |
|
.br |
|
"used=..." is ignored. Command \-status shows it with the number of |
|
files which currently have the filter applied. |
|
.br |
|
Examples: |
|
.br |
|
\-external_filter bzip2 suffix=.bz2:if_block_reduction \\ |
|
.br |
|
/usr/bin/bzip2 \-\- |
|
.br |
|
\-external_filter bunzip2 suffix=.bz2:remove_suffix \\ |
|
.br |
|
/usr/bin/bunzip2 \-\- |
|
.TP |
|
\fB\-unregister_filter\fR name |
|
Remove an \-external_filter registration. This is only possible if the filter |
|
is not applied to any file in the ISO image. |
|
.TP |
|
\fB\-close_filter_list\fR |
|
Irrevocably ban commands \-concat "pipe", \-external_filter, |
|
and \-unregister_filter, but not \-set_filter. Use this to prevent external |
|
filtering in general or when all intended filters are registered and \-concat |
|
mode "pipe" shall be disallowed. |
|
External filters may also be banned totally at compile time of |
|
\fBxorriso\fR. |
|
By default they are banned if \fBxorriso\fR runs under setuid permission. |
|
.TP |
|
\fB\-set_filter\fR name iso_rr_path [***] |
|
Apply an \-external_filter or a built\-in filter to the given data files in the |
|
ISO image. |
|
If the filter suffix is not empty , then it will be applied to the file name. |
|
Renaming only happens if the filter really gets attached and is not revoked by |
|
its options. |
|
By default files which already bear the suffix will not get filtered. The |
|
others will get the suffix appended to their names. |
|
If the filter has option "remove_suffix", then the filter will only be |
|
applied if the suffix is present and can be removed. |
|
Name oversize or collision caused by suffix change will prevent filtering. |
|
.br |
|
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. |
|
.br |
|
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). |
|
.br |
|
The reserved filter name "\-\-remove\-all\-filters" revokes |
|
filtering. This will revoke suffix renamings as well. |
|
Use "\-\-remove\-all\-filters+" to |
|
prevent any suffix renaming. |
|
.br |
|
Attaching or detaching filters will not alter the state of \-changes_pending. |
|
If the filter manipulations shall be the only changes in a write run, then |
|
explicitly execute \-changes_pending "yes". |
|
.TP |
|
\fB\-set_filter_r\fR name iso_rr_path [***] |
|
Like \-set_filter but affecting all data files below eventual directories. |
|
.TP |
|
.B Writing the result, drive control: |
|
.PP |
|
(see also paragraph about settings below) |
|
.TP |
|
\fB\-rollback\fR |
|
Discard the manipulated ISO image and reload it from \-indev. |
|
(Use \-rollback_end if immediate program end is desired.) |
|
.TP |
|
\fB\-changes_pending\fR "no"|"yes"|"mkisofs_printed"|"show_status" |
|
Write runs are performed only if a change of the image has been made |
|
since the image was loaded or created blank. Vice versa the program will |
|
start a write run for pending changes when it ends normally (i.e. not by abort |
|
and not by command \-rollback_end). |
|
.br |
|
The command \-changes_pending can be used to override the automatically |
|
determined state. This is mainly useful for setting state "yes" despite |
|
no real changes were made. The sequence \-changes_pending "no" \-end |
|
is equivalent to the command \-rollback_end. State "mkisofs_printed" |
|
is caused by emulation command \-as mkisofs if option \-print\-size is present. |
|
.br |
|
The pseudo\-state "show_status" can be used to print the current state to result |
|
channel. |
|
.br |
|
Image loading or manipulations which happen after this command will again |
|
update automatically the change status of the image. |
|
.TP |
|
\fB\-commit\fR |
|
Perform the write operation. Afterwards, if \-outdev is readable, make it |
|
the new \-dev and load the image from there. |
|
Switch to growing mode. |
|
(A subsequent \-outdev will activate modification mode or blind growing.) |
|
\-commit is performed automatically at end of program if there |
|
are uncommitted manipulations pending. |
|
.br |
|
So, to perform a final write operation with no new \-dev |
|
and no new loading of image, rather execute command \-end. |
|
If you want to go on without image loading, execute \-commit_eject "none". |
|
To eject after write without image loading, use \-commit_eject "all". |
|
.br |
|
To suppress a final write, execute \-rollback_end. |
|
.br |
|
|
|
Writing can last quite a while. It is not unnormal with several |
|
types of media that there is no progress visible for the first |
|
few minutes or that the drive gnaws on the medium for a few |
|
minutes after all data have been transmitted. |
|
\fBxorriso\fR 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. |
|
.TP |
|
\fB\-eject\fR "in"|"out"|"all" |
|
Eject the medium in \-indev, \-outdev, or both drives, respectively. |
|
Note: It is not possible yet to effectively eject disk files. |
|
.TP |
|
\fB\-commit_eject\fR "in"|"out"|"all"|"none" |
|
Combined \-commit and \-eject. When writing has finished do not make |
|
\-outdev the new \-dev, and load no ISO image. Rather eject |
|
\-indev and/or \-outdev. Give up any non\-ejected drive. |
|
.TP |
|
\fB\-blank\fR mode |
|
Make media ready for writing from scratch (if not \-dummy is activated). |
|
.br |
|
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 |
|
.br |
|
"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. |
|
.br |
|
"fast" makes CD\-RW and unformatted DVD\-RW re\-usable, or invalidates |
|
overwriteable ISO images. "all" might work more thoroughly and need more time. |
|
.br |
|
"deformat" converts overwriteable DVD\-RW into unformatted ones. |
|
.br |
|
"deformat_quickest" is a faster way to deformat or blank DVD\-RW |
|
but produces media which are only suitable for a single session. |
|
Some drives announce this state by not offering feature 21h, |
|
but some drives offer it anyway. |
|
If feature 21h is missing, then \fBxorriso\fR |
|
will refuse to write on DVD\-RW if not command \-close is set to "on". |
|
.br |
|
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 occurred. |
|
.br |
|
Mode may be prepended by "force:" in order to override the evaluation |
|
of the medium state by libburn. E.g. "force:fast". |
|
Blanking will nevertheless only succeed if the drive is willing to do it. |
|
.br |
|
.TP |
|
\fB\-format\fR mode |
|
Convert unformatted DVD\-RW into overwriteable ones, "de\-ice" DVD+RW, format |
|
newly purchased BD\-RE or BD\-R, re\-format DVD\-RAM or BD\-RE. |
|
.br |
|
Defined modes are: |
|
.br |
|
as_needed, full, fast, by_index_<num>, fast_by_index_<num>, |
|
by_size_<num>, fast_by_size_<num>, without_spare |
|
.br |
|
"as_needed" formats yet unformatted DVD\-RW, DVD\-RAM, BD\-RE, or blank |
|
unformatted BD\-R. Other media are left untouched. |
|
.br |
|
"full" (re\-)formats DVD\-RW, DVD+RW, DVD\-RAM, BD\-RE, or blank unformatted BD\-R. |
|
.br |
|
"fast" does the same as "full" but tries to be quicker. |
|
.br |
|
"by_index_" selects a format out of the descriptor list issued by command |
|
\-list_formats. The index number from that list is to be appended to the |
|
mode word. E.g: "by_index_3". |
|
.br |
|
"fast_by_index_" does the same as "by_index_" but tries to be quicker. |
|
.br |
|
"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. |
|
On BD\-RE it will not choose format 0x31, which offers no Defect Management. |
|
.br |
|
"fast_by_size_" does the same as "by_size_" but tries to be quicker. |
|
.br |
|
"without_spare" selects the largest format out of the descriptor list |
|
which provides no Spare Area for Defect Management. On BD\-RE this |
|
will be format 0x31. |
|
.br |
|
The formatting action has no effect on media if \-dummy is activated. |
|
.br |
|
Formatting is normally needed only once during the lifetime of a medium, |
|
if ever. But it is a reason for re\-formatting if: |
|
.br |
|
DVD\-RW was deformatted by \-blank, |
|
.br |
|
DVD+RW has read failures (re\-format before next write), |
|
.br |
|
DVD\-RAM or BD\-RE shall change their amount of defect reserve. |
|
.br |
|
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. |
|
.br |
|
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 occurred. Be patient with apparently frozen progress. |
|
.TP |
|
\fB\-list_formats\fR |
|
Put out a list of format descriptors as reported by the output drive for |
|
the current medium. The list gives the index number after "Format idx", |
|
a MMC format code, the announced size in blocks (like "2236704s") |
|
and the same size in MiB. |
|
.br |
|
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. |
|
.br |
|
Smaller format size with DVD\-RAM, BD\-RE, or BD\-R means more reserve space. |
|
.TP |
|
\fB\-list_speeds\fR |
|
Put out a list of speed values as reported by the drives with the loaded |
|
media. The list tells read speeds of the input drive and of the output |
|
drive. Further it tells write speeds of the output drive. |
|
.br |
|
The list of write speeds does not necessarily mean that the medium is writable |
|
or that these speeds are actually achievable. Especially the |
|
lists reported with empty drive or with ROM media obviously advertise |
|
speeds for other media. |
|
.br |
|
It is not mandatory to use speed values out of the listed range. |
|
The drive is supposed to choose a safe speed that is as near to the desired |
|
speed as possible. |
|
.br |
|
At the end of the list, "Write speed L" and "Write speed H" |
|
are the best guesses for lower and upper write speed limit. |
|
"Write speed l" and "Write speed h" may appear only with CD |
|
and eventually override the list of other speed offers. |
|
.br |
|
Only if the drive reports contradicting speed information there will appear |
|
"Write speed 0", which tells the outcome of speed selection by command |
|
\-speed 0, if it deviates from "Write speed H". |
|
.br |
|
"Read speed L" and "Read speed H" tell the minimum and maximum read speeds, |
|
as reported by the drive. They would be chosen by \-read_speed "min" or |
|
"max" if they undercut or surpass the built\-in limits. These are "1x", |
|
"52xCD", "24xDVD", "20xBD". |
|
.TP |
|
\fB\-close_damaged\fR "as_needed"|"force" |
|
Try to close the upcomming track and session if the drive reported the medium |
|
as damaged. This may apply to CD\-R, CD\-RW, DVD\-R, DVD\-RW, DVD+R, DVD+R DL, |
|
or BD\-R media. It is indicated by warning messages when the drive gets |
|
acquired, and by a remark "but next track is damaged" with the line |
|
"Media status :" of command \-toc. |
|
.br |
|
The setting of command \-close determines whether the medium stays appendable. |
|
.br |
|
Mode "as_needed" gracefully refuses on media which are not reported as |
|
damaged. Mode "force" attempts the close operation even with media which |
|
appear undamaged. |
|
.br |
|
No image changes are allowed to be pending before this command is performed. |
|
After closing was attempted, both drives are given up. |
|
.TP |
|
\fB\-list_profiles\fR "in"|"out"|"all" |
|
Put out a list of media types supported by \-indev, \-outdev, or both, |
|
respectively. |
|
The currently recognized type is marked by text "(current)". |
|
.TP |
|
.B Settings for result writing: |
|
.PP |
|
Rock Ridge info will be generated by default. |
|
ACLs will be written according to the setting of command \-acl. |
|
.TP |
|
\fB\-joliet\fR "on"|"off" |
|
If enabled by "on", generate Joliet tree additional to ISO 9660 + Rock Ridge |
|
tree. |
|
.TP |
|
\fB\-hfsplus\fR "on"|"off" |
|
If enabled by "on", generate a HFS+ filesystem inside the ISO 9660 image |
|
and mark it by Apple Partition Map (APM) entries in the System Area, |
|
the first 32 KiB of the image. |
|
.br |
|
This may collide with data submitted by \-boot_image system_area=. |
|
The first 8 bytes of the System Area get overwritten by |
|
{ 0x45, 0x52, 0x08 0x00, 0xeb, 0x02, 0xff, 0xff } |
|
which can be executed as x86 machine code without negative effects. |
|
So if an MBR gets combined with this feature, then its first 8 bytes |
|
should contain no essential commands. |
|
.br |
|
The next blocks of 2 KiB in the System Area will be occupied by APM entries. |
|
The first one covers the part of the ISO image before the HFS+ filesystem |
|
metadata. The second one marks the range from HFS+ metadata to the end |
|
of file content data. If more ISO image data follow, then a third partition |
|
entry gets produced. Other features of xorriso might cause the need for |
|
more APM entries. |
|
.br |
|
The HFS+ filesystem is not suitable for add\-on sessions produced by the |
|
multi\-session method of growing. An existing ISO image may nevertheless |
|
be the base for a new image produced by the method of modifying. |
|
If \-hfsplus is enabled when \-indev or \-dev gets executed, then AAIP |
|
attributes get loaded from the input image and checked for information about |
|
HFS creator, filetype, or blessing. If found, then they get enabled as |
|
settings for the next image production. |
|
Therefore it is advisable to perform \-hfsplus "on" before \-indev or \-dev. |
|
.br |
|
Information about HFS creator, type, and blessings gets stored by xorriso |
|
if \-hfsplus is enabled at \-commit time. It is stored as copy outside the |
|
HFS+ partition, but rather along with the Rock Ridge information. |
|
xorriso does not read any information from the HFS+ meta data. |
|
.br |
|
Be aware that HFS+ is case\-insensitive although it can record file names |
|
with upper\-case and lower\-case letters. Therefore, file names from the iso_rr |
|
name tree may collide in the HFS+ name tree. In this case they get changed |
|
by adding underscore characters and counting numbers. In case of very long |
|
names, it might be necessary to map them to "MANGLED_...". |
|
.TP |
|
\fB\-rockridge\fR "on"|"off" |
|
Mode "off" disables production of Rock Ridge information for the ISO 9660 file |
|
objects. The multi\-session capabilities of xorriso depend much on the naming |
|
fidelity of Rock Ridge. So it is strongly discouraged to deviate from |
|
default setting "on". |
|
.TP |
|
\fB\-compliance\fR rule[:rule...] |
|
Adjust the compliance to specifications of ISO 9660/ECMA\-119 and its |
|
contemporary extensions. In some |
|
cases it is worth to deviate a bit in order to circumvent bugs of the intended |
|
reader system or to get unofficial extra features. |
|
.br |
|
There are several adjustable rules which have a keyword each. If they |
|
are mentioned with this command then their rule gets added to the relaxation |
|
list. This list can be erased by rules "strict" or "clear". It can be reset |
|
to its start setting by "default". All of the following relaxation rules |
|
can be revoked individually by appending "_off". Like "deep_paths_off". |
|
.br |
|
Rule keywords are: |
|
.br |
|
"iso_9660_level="number chooses level 1 with ECMA\-119 names of the form 8.3 |
|
and \-file_size_limit <= 4g \- 1, or level 2 with ECMA\-119 names up to |
|
length 32 and the same \-file_size_limit, or level 3 with ECMA\-119 names up to |
|
length 32 and \-file_size_limit >= 400g \-200k. If necessary \-file_size_limit |
|
gets adjusted. |
|
.br |
|
"allow_dir_id_ext" allows ECMA\-119 names of directories to have a name extension |
|
as with other file types. It does not force dots and it omits the version |
|
number, though. This is a bad tradition of mkisofs which violates ECMA\-119. |
|
Especially ISO level 1 only allows 8 characters in a directory name and |
|
not 8.3. |
|
.br |
|
"omit_version" does not add versions (";1") to ECMA\-119 and Joliet file names. |
|
.br |
|
"only_iso_version" does not add versions (";1") to Joliet file names. |
|
.br |
|
"deep_paths" allows ECMA\-119 file paths deeper than 8 levels. |
|
.br |
|
"long_paths" allows ECMA\-119 file paths longer than 255 characters. |
|
.br |
|
"long_names" allows up to 37 characters with ECMA\-119 file names. |
|
.br |
|
"no_force_dots" does not add a dot to ECMA\-119 file names which have none. |
|
.br |
|
"no_j_force_dots" does not add a dot to Joliet file names which have none. |
|
.br |
|
"lowercase" allows lowercase characters in ECMA\-119 file names. |
|
.br |
|
"7bit_ascii" allows nearly all 7\-bit characters in ECMA\-119 file names. |
|
Not allowed are 0x0 and '/'. If not "lowercase" is enabled, then lowercase |
|
letters get converted to uppercase. |
|
.br |
|
"full_ascii" allows all 8\-bit characters except 0x0 and '/' |
|
in ECMA\-119 file names. |
|
.br |
|
"untranslated_names" might be dangerous for inadverted reader programs |
|
which rely on the restriction to at most 37 characters in ECMA\-119 file names. |
|
This rule allows ECMA\-119 file names up to 96 characters with no character |
|
conversion. If a file name has more characters, then image production will |
|
fail deliberately. |
|
.br |
|
"untranslated_name_len="number enables untranslated_names with a smaller limit |
|
for the length of file names. 0 disables this feature, \-1 chooses maximum |
|
length limit, numbers larger than 0 give the desired length limit. |
|
.br |
|
"joliet_long_names" allows Joliet leaf names up to 103 characters rather |
|
than 64. |
|
.br |
|
"joliet_long_paths" allows Joliet paths longer than 240 characters. |
|
.br |
|
"joliet_utf16" encodes Joliet names in UTF\-16BE rather than UCS\-2. |
|
The difference is with characters which are not present |
|
in UCS\-2 and get encoded in UTF\-16 by 2 words of 16 bit each. |
|
Both words then stem from a reserved subset of UCS\-2. |
|
.br |
|
"always_gmt" stores timestamps in GMT representation with timezone 0. |
|
.br |
|
"rec_mtime" records with non\-RockRidge directory entries the disk file's |
|
mtime and not the creation time of the image. This applies to the ECMA\-119 |
|
tree (plain ISO 9660), to Joliet, and to ISO 9660:1999. "rec_time" is |
|
default. If disabled, it gets automatically re\-enabled by \-as mkisofs emulation |
|
when a pathspec is encountered. |
|
.br |
|
"new_rr" uses Rock Ridge version 1.12 (suitable for GNU/Linux but not for older |
|
FreeBSD or for Solaris). This implies "aaip_susp_1_10_off" which may be changed |
|
by subsequent "aaip_susp_1_10". |
|
.br |
|
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". |
|
.br |
|
"aaip_susp_1_10" allows AAIP to be written as unofficial extension of RRIP |
|
rather than as official extension under SUSP\-1.12. |
|
.br |
|
"no_emul_toc" saves 64 kB with the first session on overwriteable media |
|
but makes the image incapable of displaying its session history. |
|
.br |
|
"iso_9660_1999" causes the production of an additional directory tree |
|
compliant to ISO 9660:1999. It can record long filenames for readers which |
|
do not understand Rock Ridge. |
|
.br |
|
"old_empty" uses the old way of of giving block addresses in the range |
|
of [0,31] to files with no own data content. The new way is to have |
|
a dedicated block to which all such files will point. |
|
.br |
|
Default setting is |
|
.br |
|
"clear:only_iso_version:deep_paths:long_paths:no_j_force_dots: |
|
.br |
|
always_gmt:old_rr". |
|
.br |
|
Note: The term "ECMA\-119 name" means the plain ISO 9660 names and attributes |
|
which get visible if the reader ignores Rock Ridge. |
|
.TP |
|
\fB\-rr_reloc_dir\fR name |
|
Specify the name of the relocation directory in which deep directory subtrees |
|
shall be placed if \-compliance is set to "deep_paths_off" or "long_paths_off". |
|
A deep directory is one that has a chain of 8 parent directories (including |
|
root) above itself, or one that contains a file with an ECMA\-119 path of more |
|
than 255 characters. |
|
.br |
|
The overall directory tree will appear originally deep when interpreted |
|
as Rock Ridge tree. It will appear as re\-arranged if only ECMA\-119 |
|
information is considered. |
|
.br |
|
The default relocation directory is the root directory. By giving a non\-empty |
|
name with \-rr_reloc_dir, a directory in the root directory may get this role. |
|
If that directory does not already exist at \-commit time, then it will get |
|
created and marked for Rock Ridge as relocation artefact. At least on |
|
GNU/Linux it will not be displayed in mounted Rock Ridge images. |
|
.br |
|
The name must not contain a '/' character and must not be longer than |
|
255 bytes. |
|
.TP |
|
\fB\-volid\fR text |
|
Specify the volume ID, which most operating systems will consider to be |
|
the volume name of the image or medium. |
|
.br |
|
\fBxorriso\fR accepts any text up to 32 characters, |
|
but according to rarely obeyed specs stricter rules apply: |
|
.br |
|
ECMA\-119 demands ASCII characters out of [A\-Z0\-9_]. Like: |
|
.br |
|
"IMAGE_23" |
|
.br |
|
Joliet allows 16 UCS\-2 characters. Like: |
|
.br |
|
"Windows name" |
|
.br |
|
Be aware that the volume id might get used automatically as the name of the |
|
mount point when the medium is inserted into a playful computer system. |
|
.br |
|
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. |
|
.br |
|
Consider this when setting \-volid "ISOIMAGE" before executing \-dev, \-indev, |
|
or \-rollback. |
|
If you insist in \-volid "ISOIMAGE", set it again after those commands. |
|
.TP |
|
\fB\-volset_id\fR text |
|
Set the volume set ID string to be written with the next \-commit. |
|
Permissible are up to 128 characters. This setting gets overridden by |
|
image loading. |
|
.TP |
|
\fB\-publisher\fR text |
|
Set the publisher ID string to be written with the next \-commit. This may |
|
identify the person or organisation who specified what shall be recorded. |
|
Permissible are up to 128 characters. This setting gets overridden by |
|
image loading. |
|
.TP |
|
\fB\-application_id\fR text |
|
Set the application ID string to be written with the next \-commit. This may |
|
identify the specification of how the data are recorded. |
|
Permissible are up to 128 characters. This setting gets overridden by |
|
image loading. |
|
.br |
|
The special text "@xorriso@" gets converted to the ID string of |
|
\fBxorriso\fR |
|
which is normally written as \-preparer_id. It is a wrong tradition to write |
|
the program ID as \-application_id. |
|
.TP |
|
\fB\-system_id\fR text |
|
Set the system ID string to be written with the next \-commit. This may |
|
identify the system which can recognize and act upon the content of the |
|
System Area in image blocks 0 to 15. |
|
Permissible are up to 32 characters. This setting gets overridden by |
|
image loading. |
|
.TP |
|
\fB\-volume_date\fR type timestring |
|
Set one of the four overall timestamps for subsequent image writing. |
|
Available types are: |
|
.br |
|
"c" time when the volume was created. |
|
.br |
|
"m" time when volume was last modified. |
|
.br |
|
"x" time when the information in the volume expires. |
|
.br |
|
"f" time since when the volume is effectively valid. |
|
.br |
|
"uuid" sets a timestring that overrides "c" and "m" times literally. |
|
It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc, with |
|
YYYY between 1970 and 2999. Time zone is GMT. |
|
It is supposed to match this GRUB line: |
|
.br |
|
search \-\-fs\-uuid \-\-set YYYY\-MM\-DD\-hh\-mm\-ss\-cc |
|
.br |
|
E.g. 2010040711405800 is 7 Apr 2010 11:40:58 (+0 centiseconds). |
|
.br |
|
Timestrings for the other types may be given as with command \-alter_date. |
|
Some of them are prone to timezone computations. The timestrings "default" or |
|
"overridden" cause default settings: "c" and "m" will show the current time |
|
of image creation. "x" and "f" will be marked as insignificant. |
|
"uuid" will be deactivated. |
|
.TP |
|
\fB\-copyright_file\fR text |
|
Set the copyright file name to be written with the next \-commit. This should |
|
be the ISO 9660 path of a file in the image which contains a copyright |
|
statement. |
|
Permissible are up to 37 characters. This setting gets overridden by |
|
image loading. |
|
.TP |
|
\fB\-abstract_file\fR text |
|
Set the abstract file name to be written with the next \-commit. This should |
|
be the ISO 9660 path of a file in the image which contains an abstract |
|
statement about the image content. |
|
Permissible are up to 37 characters. This setting gets overridden by |
|
image loading. |
|
.TP |
|
\fB\-biblio_file\fR text |
|
Set the biblio file name to be written with the next \-commit. This should |
|
be the ISO 9660 path of a file in the image which contains bibliographic |
|
records. |
|
Permissible are up to 37 characters. This setting gets overridden by |
|
image loading. |
|
.TP |
|
\fB\-preparer_id\fR |
|
Set the preparer ID string to be written with the next \-commit. This may |
|
identify the person or other entity which controls the preparation of the data |
|
which shall be recorded. Normally this should be the ID of \fBxorriso\fR |
|
and not of the person or program which operates \fBxorriso\fR. |
|
Please avoid to change it. Permissible are up to 128 characters. |
|
.br |
|
The special text "@xorriso@" gets converted to the ID string of |
|
\fBxorriso\fR which is default at program startup. |
|
.br |
|
Unlike other ID strings, this setting is not influenced by image loading. |
|
.TP |
|
\fB\-application_use\fR character|0xXY|disk_path |
|
Specify the content of the Application Use field which can take at most |
|
512 bytes. |
|
.br |
|
If the parameter of this command is empty, then the field is filled |
|
with 512 0\-bytes. If it is a single character, then it gets repeated 512 times. |
|
If it begins by "0x" followed by two hex digits [0\-9a\-fA\-F], then the digits |
|
are read as byte value which gets repeated 512 times. |
|
.br |
|
Any other parameter text is used as disk_path to open a data file and to |
|
read up to 512 bytes from it. If the file is smaller than 512 bytes, then the |
|
remaining bytes in the field get set to binary 0. |
|
.br |
|
This setting is not influenced by image loading. |
|
.TP |
|
\fB\-out_charset\fR character_set_name |
|
Set the character set to which file names get converted when writing an |
|
image. See paragraph "Character sets" for more explanations. |
|
When loading the written image after \-commit the setting of \-out_charset |
|
will be copied to \-in_charset. |
|
.TP |
|
\fB\-uid\fR uid |
|
User id to be used for all files when the new ISO tree gets written to media. |
|
.TP |
|
\fB\-gid\fR gid |
|
Group id to be used for all files when the new ISO tree gets written to media. |
|
.TP |
|
\fB\-zisofs\fR option[:options] |
|
Set global parameters for zisofs compression. This data format is recognized |
|
and transparently uncompressed by some Linux kernels. It is to be applied |
|
via command \-set_filter with built\-in filter "\-\-zisofs". |
|
Parameters are: |
|
.br |
|
"level="[0\-9] zlib compression: 0=none, 1=fast,..., 9=slow |
|
.br |
|
"block_size="32k|64k|128k size of compression blocks |
|
.br |
|
"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. |
|
.br |
|
"default" same as "level=6:block_size=32k:by_magic=off" |
|
.TP |
|
\fB\-speed\fR code|number[k|m|c|d|b] |
|
Set the burn speed. Default is "max" (or "0") = maximum speed as announced |
|
by the drive. |
|
Further special speed codes are: |
|
.br |
|
"min" (or "\-1") selects minimum speed as announced by the drive. |
|
.br |
|
"none" avoids to send a speed setting command to the drive before |
|
burning begins. |
|
.br |
|
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 explicitly |
|
by "c" for CD, "d" for DVD, "b" for BD, "x" is optional. |
|
.br |
|
Example speeds: |
|
.br |
|
706k = 706kB/s = 4c = 4xCD |
|
.br |
|
5540k = 5540kB/s = 4d = 4xDVD |
|
.br |
|
If there is no hint about the speed unit attached, then the |
|
medium in the \-outdev will decide. Default unit is CD = 176.4k. |
|
.br |
|
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. |
|
.TP |
|
\fB\-stream_recording\fR "on"|"off"|"full"|"data"|number |
|
Setting "on" tries to circumvent the management of defects on DVD\-RAM, BD\-RE, |
|
or BD\-R. Defect management keeps partly damaged media usable. But it reduces |
|
write speed to half nominal speed even if the medium is in perfect shape. |
|
For the case of flawless media, one may use \-stream_recording "on" to get |
|
full speed. |
|
.br |
|
"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. |
|
.br |
|
"data" causes full speed to start when superblock and directory entries are |
|
written and writing of file content blocks begins. |
|
.TP |
|
\fB\-dvd_obs\fR "default"|"32k"|"64k" |
|
GNU/Linux specific: |
|
Set the number of bytes to be transmitted with each write operation to DVD |
|
or BD media. A number of 64 KB may improve throughput with bus systems which |
|
show latency problems. The default depends on media type, on command |
|
\-stream_recording , and on compile time options. |
|
.TP |
|
\fB\-modesty_on_drive\fR parameter[:parameters] |
|
Control whether the drive buffer shall be kept from getting completely filled. |
|
Parameter "on" (or "1") keeps the program from trying to write to the burner |
|
drive while its buffer is in danger to be filled over a given limit. |
|
If this limit is exceeded then the program will wait until the filling |
|
reaches a given low percentage value. |
|
.br |
|
This can ease the load on operating system and drive controller and thus help |
|
with achieving better input bandwidth if disk and burner are not on independent |
|
controllers (like hda and hdb). It may also help with throughput problems of |
|
simultaneous burns on different burners with Linux kernels like 3.16, if one |
|
has reason not to fix the problem by \-scsi_dev_family "sg". |
|
On the other hand it increases the risk of buffer underflow and thus |
|
reduced write speed. |
|
.br |
|
Some burners are not suitable because they |
|
report buffer fill with granularity too coarse in size or time, |
|
or expect their buffer to be filled to the top before they go to full speed. |
|
.br |
|
Parameters "off" or "0" disable this feature. |
|
.br |
|
The threshold for beginning to wait is given by parameter "max_percent=". |
|
Parameter "min_percent=" defines the threshold for resuming transmission. |
|
Percentages are permissible in the range of 25 to 100. Numbers in this |
|
range without a prepended name are interpreted as "on:min_percent=". |
|
.br |
|
E.g.: \-modesty_on_drive 75 |
|
.br |
|
The optimal values depend on the buffer behavior of the drive. |
|
.br |
|
Parameter "timeout_sec=" defines after which time of unsuccessful waiting |
|
the modesty shall be disabled because it does not work. |
|
.br |
|
Parameter "min_usec=" defines the initial sleeping period in microseconds. |
|
If the drive buffer appears to be too full for sending more data, the |
|
program will wait the given time and inquire the buffer fill state again. |
|
If repeated inquiry shows not enough free space, the sleep time will |
|
slowly be increased to what parameter "max_usec=" defines. |
|
.br |
|
Parameters, which are not mentioned with a \-modesty_on_drive command, |
|
stay unchanged. |
|
Default is: |
|
.br |
|
\-modesty_on_drive off:min_percent=90:max_percent=95: |
|
timeout_sec=120:min_usec=5000:max_usec=25000 |
|
.TP |
|
\fB\-stdio_sync\fR "on"|"off"|"end"|number |
|
Set the number of bytes after which to force output to stdio: pseudo drives. |
|
This forcing keeps the memory from being clogged with lots of |
|
pending data for slow devices. Default "on" is the same as "16m". |
|
Forced output can be disabled by "off", or be delayed by "end" until all |
|
data are produced. If a number is chosen, then it must be at least 64k. |
|
.TP |
|
\fB\-dummy\fR "on"|"off" |
|
If "on" then simulate burning or refuse with FAILURE event if |
|
no simulation is possible, do neither blank nor format. |
|
.TP |
|
\fB\-fs\fR number["k"|"m"] |
|
Set the size of the fifo buffer which smoothens the data |
|
stream from ISO image generation to media burning. Default |
|
is 4 MiB, minimum 64 kiB, maximum 1 GiB. |
|
The number may be followed by letter "k" or "m" |
|
which means unit is kiB (= 1024) or MiB (= 1024 kiB). |
|
.TP |
|
\fB\-close\fR "on"|"off"|"as_needed" |
|
If \-close is set to "on" then mark the written medium as not appendable |
|
any more. This will have no effect on overwritable media types. |
|
Setting "on" is the contrary of cdrecord option \-multi, |
|
and is one aspect of growisofs option \-dvd\-compat. |
|
.br |
|
If set to "off" then keep the medium writable for an appended session. |
|
.br |
|
If set to "as_needed" then use "on" only if "off" is predicted to |
|
fail with the given medium and its state. |
|
.br |
|
Not all drives correctly recognize fast\-blanked DVD\-RW which need "on". |
|
If there is well founded suspicion that a burn run failed due to |
|
\-close "off", then \-close "as_needed" causes a re\-try with "on". |
|
.br |
|
Note that emulation command \-as "cdrecord" temporarily overrides |
|
the current setting of \-close by its own default \-close "on" if |
|
its option \-multi is missing. |
|
.TP |
|
\fB\-write_type\fR "auto"|"tao"|"sao/dao" |
|
Set the write type for the next burn run. "auto" will select SAO with blank |
|
CD media, DAO with blank DVD\-R[W] if \-close is "on", and elsewise CD TAO or the |
|
equivalent write type of the particular DVD/BD media. |
|
Choosing TAO or SAO/DAO explicitly might cause the burn run to fail if the |
|
desired write type is not possible with the given media state. |
|
.TP |
|
\fB\-padding\fR number["k"|"m"]|"included"|"appended" |
|
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, |
|
\fBxorriso\fR adds the traditional 300k of padding by default to |
|
all images. |
|
.br |