xorriso 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.
Vice versa xorriso is able to copy file objects out of ISO 9660
filesystems.
A special property of xorriso is that it needs neither an
external ISO 9660 formatter program nor an external burn program for CD, DVD
or BD but rather incorporates the libraries of libburnia-project.org .
Overview of features:
Operates on an existing ISO image or creates a new one.
Copies files from disk filesystem into the ISO image.
Copies files from ISO image to disk filesystem (see osirrox).
Renames or deletes file objects in the ISO image.
Changes file properties in the ISO image.
Updates ISO subtrees incrementally to match given disk subtrees.
Writes result either as completely new image or as add-on session to optical
media or filesystem objects.
Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
Can perform multi-session tasks as emulation of mkisofs and cdrecord.
Can record and restore hard links and ACL.
Content may get zisofs compressed or filtered by external processes.
Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
Can check media for damages and copy readable blocks to disk.
Can attach MD5 checksums to each data file and the whole session.
Scans for optical drives, blanks re-useable optical media.
Reads its instructions from command line arguments, dialog, and files.
Provides navigation commands for interactive ISO image manipulation.
Adjustable thresholds for abort, exit value, and problem reporting.
Note that xorriso does not write audio CDs and that it does
not produce UDF filesystems which are specified for official video DVD or
BD.
General information paragraphs:
Session model
Media types and states
Creating, Growing, Modifying, Blind Growing
Libburn drives
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
Command processing
Dialog, Readline, Result pager
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.
Unlike other filesystems, ISO 9660 (aka ECMA-119) is not intended
for read-write operation but rather for being generated in a single sweep and
being written to media as a session.
The data content of the session is called filesystem image.
The written image in its session can then be mounted by the
operating system for being used read-only. GNU/Linux is able to mount ISO
images from block devices, which may represent optical media, other media or
via a loop device even from regular disk files. FreeBSD mounts ISO images
from devices that represent arbitrary media or from regular disk files.
This session usage model has been extended on CD media by the
concept of multi-session , which 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.
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.
Adding a session to an existing ISO image is in this text referred as
growing.
The multi-session model of the MMC standard does not apply to all media types.
But program growisofs by Andy Polyakov showed how to extend this
functionality to overwriteable media or disk files which carry valid ISO
9660 filesystems.
xorriso provides growing as well as an own method named
modifying which produces a completely new ISO image from the old one
and the modifications. See paragraph Creating, Growing, Modifying, Blind
Growing below.
xorriso adopts the concept of multi-session by loading an
image directory tree if present, by offering to manipulate it by several
actions, and by writing the new image to the target medium.
The first session of a xorriso run begins by the definition of the
input drive with the ISO image or by the definition of an output drive. The
session ends by command -commit which triggers writing. A -commit is done
automatically when the program ends regularly.
After -commit a new session begins with the freshly written one as
input. A new input drive can only be chosen as long as the loaded ISO image
was not altered. Pending alteration can be revoked by command -rollback.
Writing a session to the target is supposed to be very expensive
in terms of time and of consumed space on appendable or write-once media.
Therefore all intended manipulations of a particular ISO image should be
done in a single session. But in principle it is possible to store
intermediate states and to continue with image manipulations.
Media types and states:
There are two families of media in the MMC standard:
Multi-session media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, BD-R, and
unformatted DVD-RW. These media provide a table of content which describes
their existing sessions. See command -toc.
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.
xorriso will write onto them only if command -close is set to
"on".
Overwriteable media 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 xorriso, then a table of content can be
emulated. Else only a single overall session will be visible.
DVD-RW media can be formatted by -format "full". They can be made
unformatted by -blank "deformat".
Regular files and block devices are handled as overwriteable media. Pipes and
other writeable file types are handled as blank multi-session media.
These media can assume several states in which they offer
different capabilities.
Blank media can be written from scratch. They contain no ISO image
suitable for xorriso.
Blank is the state of newly purchased optical media. With used CD-RW and
DVD-RW it can be achieved by action -blank "as_needed".
Overwriteable media are considered blank if they are new or if they have
been marked as blank by xorriso. Action -blank "as_needed"
can be used to do this marking on overwriteable media, or to apply mandatory
formatting to new media if necessary.
Appendable media accept further sessions. Either they are MMC
multi-session media in appendable state, or they are overwriteable media
which contain an ISO image suitable for xorriso.
Appendable is the state after writing a session with command -close off.
Closed media cannot be written. They may contain an ISO image suitable
for xorriso.
Closed is the state of DVD-ROM media and of multi-session media which were
written with command -close on. If the drive is read-only hardware then it
will probably show any media as closed CD-ROM or DVD-ROM.
Overwriteable media assume this state in such read-only drives or if they
contain unrecognizable data in the first 32 data blocks.
Read-only drives may or may not show session histories of multi-session media.
Often only the first and the last session are visible. Sometimes not even
that. Command -rom_toc_scan might or might not help in such cases.
Creating, Growing, Modifying, Blind Growing:
A new empty ISO image gets created if there is no input drive with a
valid ISO 9660 image when the first time an output drive is defined. This is
achieved by command -dev on blank media or by command -outdev on media in any
state.
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.
If there is a input drive with a valid ISO image, then this image
gets loaded as foundation for manipulations and extension. The constellation
of input and output drive determines which write method will be used. They
have quite different capabilities and constraints.
The method of growing adds new data to the existing 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.
Growing is achieved by command -dev.
The write method of modifying produces compact filesystem
images with no outdated files or directory trees. Modifying can write its
images to target media which are completely unsuitable for multi-session
operations. E.g. DVD-RW which were treated with -blank deformat_quickest,
DVD-R DL, named pipes, character devices, sockets. On the other hand
modified sessions cannot be written to appendable media but to blank media
only.
So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target medium.
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.
If command -grow_blindly is set to a non-negative number and if
-indev and -outdev are both set to different drives, then blind
growing is performed. It produces an add-on session which is ready for
being written to the given block address. This is the usage model of
mkisofs -M $indev -C $msc1,$msc2 -o $outdev
which gives much room for wrong parameter combinations and should thus only be
employed if a strict distinction between ISO formatter xorriso and
the burn program is desired. -C $msc1,$msc2 is equivalent to:
-load sbsector $msc1 -grow_blindly $msc2
Libburn drives:
Input drive, i.e. source of an existing or empty ISO image, can be any random
access readable libburn drive: optical media with readable data, blank optical
media, regular files, block devices.
Output drive, i.e. target for writing, can be any libburn drive. Some drive
types do not support the method of growing but only the methods of modifying
and blind growing. They all are suitable for newly created images.
All drive file objects have to offer rw-permission to the user of
xorriso. Even those which will not be useable for reading an ISO
image.
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
(LBA) which gives the number of a particular data block.
MMC compliant (i.e. optical) drives on GNU/Linux usually get
addressed by the path of their block device or of their generic character
device. E.g.
-dev /dev/sr0
-dev /dev/hdc
-dev /dev/sg2
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).
On FreeBSD the device files have names like
-dev /dev/cd0
On NetBSD:
-dev /dev/rcd0d
On OpenSolaris:
-dev /dev/rdsk/c4t0d0s2
Get a list of accessible drives by command
-device_links
It might be necessary to do this as superuser in order to see all
drives and to then allow rw-access for the intended users. Consider to
bundle the authorized users in a group like old "floppy".
Filesystem objects of nearly any type can be addressed by prefix
"stdio:" and their path in the filesystem. E.g.:
-dev stdio:/dev/sdc
The default setting of -drive_class allows the user to address files outside
the /dev tree without that prefix. E.g.:
-dev /tmp/pseudo_drive
If path leads to a regular file or to a block device then the emulated drive
is random access readable and can be used for the method of growing if it
already contains a valid ISO 9660 image. Any other file type is not readable
via "stdio:" and can only be used as target for the method of
modifying or blind growing. Non-existing paths in existing directories are
handled as empty regular files.
A very special kind of pseudo drive are open file descriptors.
They are depicted by "stdio:/dev/fd/" and descriptor number (see
man 2 open).
Addresses "-" or "stdio:/dev/fd/1" depict standard output,
which normally is the output channel for result texts. To prevent a fatal
intermingling of ISO image and text messages, all result texts get
redirected to stderr if -*dev "-" or "stdio:/dev/fd/1"
is among the start arguments of the program.
Standard output is currently suitable for creating one session per program run
without dialog. Use in other situations is discouraged and several
restrictions apply:
It is not allowed to use standard output as pseudo drive if it was not among
the start arguments. Do not try to fool this ban via backdoor addresses to
stdout.
If stdout is used as drive, then -use_readline is permanently disabled. Use of
backdoors can cause severe memory and/or tty corruption.
Be aware that especially the superuser can write into any
accessible file or device by using its path with the "stdio:"
prefix. By default any address in the /dev tree without prefix
"stdio:" will work only if it leads to a MMC drive.
One may use command -ban_stdio_write to surely prevent this risk and to
restrict drive usage to MMC drives.
One may prepend "mmc:" to a path to surely disallow any automatic
"stdio:".
By command -drive_class one may ban certain paths or allow access without
prefix "stdio:" to other paths.
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
Rock Ridge is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
This is what xorriso uses for a decent representation of the disk files
within the ISO image. xorriso produces Rock Ridge information by
default. It is strongly discouraged to disable this feature.
xorriso is not named "porriso" because POSIX only
guarantees 14 characters of filename length. It is the X/Open System
Interface standard XSI which demands a file name length of up to 255
characters and paths of up to 1024 characters. Rock Ridge fulfills this
demand.
An El Torito boot record points the BIOS bootstrapping
facility to one or more boot images, which are binary program files stored
in the ISO image. The content of the boot image files is not in the scope of
El Torito.
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.
xorriso is able to create or maintain an El Torito object which makes
such an image bootable. For details see command -boot_image.
It is possible to make ISO images bootable from USB stick or other
hard-disk-like media. Several options install a MBR (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.
MBR is read by PC-BIOS when booting from USB stick or hard disk, and by
PowerPC CHRP or PReP when booting. An MBR partition with type 0xee indicates
the presence of GPT.
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.
A GPT (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.
An APM (Apple Partition Map) marks the HFS+ partition. It is read by
Macs for booting and for mounting.
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.
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.
ACL are an advanced way of controlling access permissions
to file objects. Neither ISO 9660 nor Rock Ridge specify a way to record
ACLs. So libisofs has introduced a standard conformant extension named AAIP
for that purpose. It uses this extension if enabled by command -acl.
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 xorriso is able to retrieve those ACLs. It can bring them into
effect when files get restored to an ACL enabled file system or it can print
them in a format suitable for tool setfacl.
Files with ACL show as group permissions the setting of entry
"mask::" if that entry exists. Nevertheless the non-listed group
members get handled according to entry "group::". When removing
ACL from a file, xorriso brings "group::" into effect.
Recording and restoring of ACLs from and to local files works currently only
on GNU/Linux and FreeBSD.
xattr (aka EA, or extattr) are pairs of name and value
which can be attached to file objects. AAIP is able to represent them and
xorriso can record and restore them.
But be aware that pairs with names of non-user namespaces are not necessarily
portable between operating systems and not even between filesystems. Only
those which begin with "user.", like "user.x" or
"user.whatever", can unconditionally be expected to be appropriate
on other machines and disks. Processing of other xattr may need
administrator privileges.
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 -xattr.
As with ACL, currently only xorriso is able to retrieve xattr from AAIP
enhanced images, to restore them to xattr capable file systems, or to print
them.
Recording and restoring of xattr from and to local files works currently only
on GNU/Linux and FreeBSD, where they are known as extattr.
Command processing:
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 -x is among them.
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 list delimiter, occur at the end of the argument list, or occur at
the end of an input line.
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.
For brevity the list delimiter is referred as "--" throughout this
text.
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.
Pattern expansion converts a list of pattern words into a
list of existing file addresses. Unmatched pattern words will appear
unaltered in that result list.
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' and
respects '/' as the path separator, which may only be matched literally.
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
"[...]".
Some other commands perform pattern matching unconditionally.
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.
xorriso 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 xorriso, a
quotation mark does not make a pattern symbol literal.
Quoted input 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.
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 Backslash Interpretation which can represent all 8-bit
characters except NUL (0) via backslash codes as in $'...' of bash.
This is not enabled by default. See command -backslash_codes.
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.
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.
Dialog, Readline, Result pager:
Dialog mode prompts for a quoted input line, parses it into words, and performs
them as commands with their parameters. It provides assisting services to make
dialog more comfortable.
Readline is an enhancement for the input line. You may already
know it from the bash shell. Whether it is available in xorriso
depends on the availability of package readline-dev at the time when
xorriso was built from its sourcecode.
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.
See man readline for more info about libreadline.
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.
An empty line lets xorriso resume work until the next page is output.
The single character "@" disables paging for the current action.
"@@@", "x", "q", "X", or "Q"
request that the current action aborts and suppress further result output.
Any other line input will be interpreted as new dialog line. The current
action is requested to abort. Afterwards, the input line is executed.
Some actions apply paging to their info output, too.
The request to abort may or may not be obeyed by the current action. All
actions try to abort as soon as possible.
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.
Normally any number of leading dashes is ignored with command words and inner
dashes are interpreted as underscores.
- Execution order of program arguments:
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.
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.
- -x
- 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.
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.
- -list_arg_sorting
- List all xorriso commands in the order which applies if command -x is in
effect.
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.
- Acquiring source and target drive:
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.
- -dev 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.
This is only allowed as long as no changes are pending in the currently
loaded ISO image. If changes are pending, then one has to perform -commit
or -rollback first.
Special address string "-" means standard output, to which several
restrictions apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current device without
acquiring a new one.
- -indev 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.
- -outdev address
- Set output drive and if it differs from the input drive then switch from
growing to modifying or to blind growing. Unlike -dev and -indev this
action does not load a new ISO image. So it can be performed even if there
are pending changes.
-outdev can be performed without previous -dev or -indev. In that case an
empty ISO image with no changes pending is created. It can either be
populated by help of -map, -add et.al. or it can be discarded silently if
-dev or -indev are performed afterwards.
Special address string "-" means standard output, to which several
restrictions apply. See above paragraph "Libburn drives".
An empty address string "" gives up the current output drive
without acquiring a new one. No writing is possible without an output
drive.
- -drive_class
"harmless"|"banned"|"caution"|"clear_list"
disk_pattern
- Add a drive path pattern to one of the safety lists or make those lists
empty. There are three lists defined which get tested in the following
sequence:
If a drive address path matches the "harmless" list then the drive
will be accepted. If it is not a MMC device then the prefix
"stdio:" will be prepended automatically. This list is empty by
default.
Else if the path matches the "banned" list then the drive will not
be accepted by xorriso but rather lead to a FAILURE event. This
list is empty by default.
Else if the path matches the "caution" list and if it is not a MMC
device, then its address must have the prefix "stdio:" or it
will be rejected. This list has by default one entry: "/dev".
If a drive path matches no list then it is considered "harmless".
By default these are all paths which do not begin with directory
"/dev".
A path matches a list if one of its parent paths or itself matches a list
entry. Address prefix "stdio:" or "mmc:" will be
ignored when testing for matches.
By pseudo-class "clear_list" and pseudo-patterns
"banned", "caution", "harmless", or
"all", the lists may be made empty.
E.g.: -drive_class clear_list banned
One will normally define the -drive_class lists in one of the xorriso
Startup Files.
Note: This is not a security feature but rather a bumper for the superuser
to prevent inadverted mishaps. For reliably blocking access to a device
file you have to deny its rw-permissions in the filesystem.
- -drive_access
"exclusive"|"shared":"unrestricted"|"readonly"
- Control whether device file locking mechanisms shall be used when
acquiring a drive, and whether status or content of the medium in the
drive may be altered. Useful and most harmless are the setting
"shared:readonly" and the default setting
"exclusive:unrestricted".
"exclusive" enables tests and locks when acquiring the drive. It
depends on the operating system which locking mechanisms get applied, if
any. On GNU/Linux it is open(O_EXCL). On FreeBSD it is flock(LOCK_EX).
"shared" disables the use of these mechanisms to become able to
acquire drives which are mounted, or opened by some process, or guarded by
/dev/pktcdvd*.
"unrestricted" enables all technically appropriate operations on
an acquired drive. "shared:unrestricted" risks to get own burn
runs spoiled by other processes or to vice versa spoil activities of such
processes. So use "exclusive:unrestricted" unless you know for
sure that "shared" is safe.
"readonly" disables operations which might surprise a co-user of
the drive. For -outdev these are formatting, blanking, writing, ejecting.
For -indev this is ejecting. Be aware that even reading and drive status
inquiries can disturb an ongoing burn run on CD-R[W] and DVD-R[W].
- -scsi_dev_family
"default"|"sr"|"scd"|"sg"
- GNU/Linux specific:
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:".
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*.
If you decide so, consider to put the command into a global startup file
like /etc/opt/xorriso/rc.
- -grow_blindly "off"|predicted_nwa
- If predicted_nwa is a non-negative number then perform blind growing
rather than modifying if -indev and -outdev are set to different drives.
"off" or "-1" switch to modifying, which is the
default.
predicted_nwa is the block address where the add-on session of blind growing
will finally end up. It is the responsibility of the user to ensure this
final position and the presence of the older sessions. Else the overall
ISO image will not be mountable or will produce read errors when accessing
file content. xorriso will write the session to the address as
obtained from examining -outdev and not necessarily to predicted_nwa.
During a run of blind growing, the input drive is given up before output
begins. The output drive is given up when writing is done.
- Influencing the behavior of image loading:
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.
- -read_speed 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.
Further special speed codes are:
"max" (or "0") selects maximum speed as announced by the
drive.
"min" (or "-1") selects minimum speed as announced by
the drive.
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.
Example speeds:
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then the medium in the
-indev will decide. Default unit is CD = 176.4k.
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.
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.
- -load entity id
- Load a particular (possibly outdated) ISO session from -dev or -indev.
Usually all available sessions are shown with command -toc.
entity depicts the kind of addressing. id depicts the particular address.
The following entities are defined:
"auto" with any id addresses the last session in -toc. This is the
default.
"session" with id being a number as of a line "ISO
session", column "Idx".
"track" with id being a number as of a line "ISO track",
column "Idx".
"lba" or "sbsector" with a number as of a line "ISO
...", column "sbsector".
"volid" with a search pattern for a text as of a line "ISO
...", column "Volume Id".
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.
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".
- -displacement [-]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.
Examples:
If a track of a CD starts at block 123456 and gets copied to a disk file
where it begins at block 0, then this copy can be loaded with
-displacement -123456
If an ISO image was written onto a partition with offset of 640000 blocks of
512 bytes, then it can be loaded from the base device by
-load sbsector 160000 -displacement 160000
(If the partition start address is not divisible by 4, then you will have to
employ a loop device instead.)
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.
- -read_fs
"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.
"any" first tries to read Rock Ridge. If not present, Joliet is
tried.
"norock" does not try Rock Ridge.
"nojoliet" does not try Joliet.
"ecma119" tries neither Rock Ridge nor Joliet.
- -assert_volid pattern severity
- Refuse to load ISO images with volume IDs which do not match the given
search pattern. When refusing an image, give up the input drive and issue
an event of the given severity (like FAILURE, see -abort_on). An empty
search pattern accepts any image.
This command does not hamper the creation of an empty image from blank input
media and does not discard an already loaded image.
- -in_charset character_set_name
- Set the character set from which to convert file names when loading an
image. See paragraph "Character sets" for more explanations.
When loading the written image after -commit the setting of -out_charset
will be copied to -in_charset.
- -auto_charset "on"|"off"
- Enable or disable recording and interpretation of the output character set
name in an xattr attribute of the image root directory. If enabled 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.
Note that the default output charset is the local character set of the
terminal where xorriso runs. Before attributing this local
character set to the produced ISO image, check whether the terminal
properly displays all intended filenames, especially exotic national
characters.
- -hardlinks mode[:mode...]
- Enable or disable loading and recording of hardlink relations.
In default mode "off", iso_rr files lose their inode numbers at
image load time. Each iso_rr file object which has no inode number at
image generation time will get a new unique inode number if -compliance is
set to new_rr.
Mode "on" preserves 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.
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".
Commands -update and -update_r track splits and fusions of hard links in
filesystems which have stable device and inode numbers. This can cause
automatic last minute changes before the session gets written. Command
-hardlinks "perform_update" may be used to do these changes
earlier, e.g. if you need to apply filters to all updated files.
Mode "without_update" avoids hardlink processing during update
commands. Use this if your filesystem situation does not allow
-disk_dev_ino "on".
xorriso commands which extract files from an ISO image try to
hardlink files with identical inode number. The normal scope of this
operation is from image load to image load. One may give up the
accumulated hard link addresses by -hardlinks "discard_extract".
A large number of hardlink families may exhaust -temp_mem_limit if not
-osirrox "sort_lba_on" and -hardlinks
"cheap_sorted_extract" are both in effect. This restricts hard
linking to other files restored by the same single extract command.
-hardlinks "normal_extract" re-enables wide and expensive
hardlink accumulation.
- -acl "on"|"off"
- Enable or disable processing of ACLs. If enabled, then xorriso will
obtain ACLs from disk file objects, store ACLs in the ISO image using the
libisofs specific AAIP format, load AAIP data from ISO images, test ACL
during file comparison, and restore ACLs to disk files when extracting
them from ISO images. See also commands -getfacl, -setfacl.
- -xattr
"on"|"user"|"any"|"off"
- Enable or disable processing of xattr attributes. If enabled, then
xorriso will handle xattr similar to ACL. See also commands
-getfattr, -setfattr and above paragraph about xattr.
Modes "on" and "user" read and write only attributes
from namespace "user".
Mode "any" processes attributes of all namespaces. This might need
administrator privileges, even if the owner of the disk file tries to read
or write the attributes.
Note that xattr from namespace "isofs." are never read from disk
or restored to disk. Further it is not possible to set them via xorriso
xattr manipulation commands.
- -md5
"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.
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.
At image generation time they are computed for each file which gets its data
written into the new session. The checksums of files which have their data
in older sessions get copied into the new session. Superblock, tree and
whole session get a checksum tag each.
Mode "all" will additionally check during image generation whether
the checksum of a data file changed between the time when its reading
began and the time when it ended. This implies reading every file twice.
Mode "load_check_off" together with "on" or
"all" will load recorded MD5 sums but not test the recorded
checksum tags of superblock and directory tree. This is necessary if
growisofs was used as burn program, because it does not overwrite the
superblock checksum tag of the first session. Therefore load_check_off is
in effect when xorriso -as mkisofs option -M is performed.
The test can be re-enabled by mode "load_check_on".
Checksums can be exploited via commands -check_md5, -check_md5_r, via find
actions get_md5, check_md5, and via -check_media.
- -for_backup
- Enable all extra features which help to produce or to restore backups with
highest fidelity of file properties. Currently this is a shortcut for:
-hardlinks on -acl on -xattr any -md5 on
If you restore a backup with xattr from non-user namespaces, then make sure
that the target operating system and filesystem know what these attributes
mean. Possibly you will need administrator privileges to record or restore
such attributes. At recording time, xorriso will try to tolerate missing
privileges and just record what is readable. But at restore time, missing
privileges will cause failure events.
Command -xattr "user" after command -for_backup excludes non-user
attributes from being recorded or restored.
- -ecma119_map
"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.
Mode "stripped" is the default. It shows the names as found in the
ISO but removes trailing ";1" or ".;1" if present.
Mode "unmapped" shows names as found without removing characters.
Mode "lowercase" is like "stripped" but also maps
uppercase letters to lowercase letters. This is compatible to default
GNU/Linux mount behavior.
Mode "uppercase" is like "stripped" but maps lowercase
letters to uppercase, if any occur despite the prescriptions of
ECMA-119.
- -iso_nowtime "dynamic"|timestring
- Choose whether to use the current time ("dynamic") or a fixed
time point for timestamps of ISO 9660 nodes without a disk source file and
as default for superblock timestamps.
If a timestring is given, then it is used for such timestamps. For the
formats of timestrings see command -alter_date.
- -disk_dev_ino
"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.
If device numbers and inode numbers of the disk filesystems are persistent
and if no irregular alterations of timestamps or system clock happen, then
potential content changes can be detected without reading that content.
File content change is assumed if any of mtime, ctime, device number or
inode number have changed.
Mode "ino_only" replaces the precondition that device numbers are
stable by the precondition that mount points in the compared tree always
lead to the same filesystems. Use this if mode "on" always sees
all files changed.
The speed advantage appears only if the loaded session was produced with
-disk_dev_ino "on" too.
Note that -disk_dev_ino "off" is totally in effect only if
-hardlinks is "off", too.
- -file_name_limit [+]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 '_'.
iso_rr_paths with the long components will still be able to access the file
paths with truncated components.
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.
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.
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.
File name patterns will only work if they match the truncated name. This
might change in future.
Files with truncated names get deleted and re-added unconditionally during
-update and -update_r. This might change in future.
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.
- -rom_toc_scan
"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.)
To have in case of failure a chance of getting the session history and
especially the address of the last session, there is a scan for ISO 9660
filesystem headers which might help but also might yield worse results
than the drive's table of content. At its end it can cause read attempts
to invalid addresses and thus ugly drive behavior. Setting "on"
enables that scan for alleged read-only media.
Some operating systems are not able to mount the most recent session of
multi-session DVD or BD. If on such a system xorriso has no own MMC
capabilities then it may still find that session from a scanned table of
content. Setting "force" handles any media like a ROM medium
with setting "on".
On the other hand the emulation of session history on overwriteable media
can hamper reading of partly damaged media. Setting
"off:emul_off" disables the elsewise trustworthy
table-of-content scan for those media.
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.
- -calm_drive
"in"|"out"|"all"|"revoke"|"on"|"off"
- Reduce drive noise until it is actually used again. Some drives stay alert
for substantial time after they have been used for reading. This reduces
the startup time for the next drive operation but can be loud and waste
energy if no i/o with the drive is expected to happen soon.
Modes "in", "out", "all" immediately calm down
-indev, -outdev, 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.
- -ban_stdio_write
- Allow for writing only the usage of MMC optical drives. Disallow to write
the result into files of nearly arbitrary type. Once set, this command
cannot be revoked.
- -early_stdio_test
"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.
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.
Mode "appendable_wo" is like "on" with the additional
property that non-empty write-only files are regarded as appendable rather
than blank.
- -data_cache_size 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.
Larger cache sizes help best with image loading from MMC drives. They are an
inferior alternative to -osirrox option "sort_lba_on".
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.
- Inserting files into ISO image:
The following commands expect file addresses of two kinds:
disk_path is a path to an object in the local filesystem tree.
iso_rr_path is the Rock Ridge name of a file object in the ISO image.
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.
Note that in the ISO image you are as powerful as the superuser.
Access permissions of the existing files in the image do not apply to your
write operations. They are intended to be in effect with the read-only
mounted image.
If the iso_rr_path of a newly inserted file leads to an existing
file object in the ISO image, then the following collision handling happens:
If both objects are directories then they get merged by recursively inserting
the subobjects from filesystem into ISO image. If other file types collide
then the setting of command -overwrite decides.
Renaming of files has similar collision handling, but directories can only be
replaced, not merged. Note that 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.
The commands in this section alter the ISO image and not the local
filesystem.
- -disk_pattern "on"|"ls"|"off"
- Set the pattern expansion mode for the disk_path parameters of several
commands which support this feature.
Setting "off" disables this feature for all commands which are
marked in this man page by "disk_path [***]" or
"disk_pattern [***]".
Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked by
"disk_pattern [***]".
Default is "ls".
- -add pathspec [...] | disk_path [***]
- Insert the given files or directory trees from filesystem into the ISO
image.
If -pathspecs is set to "on" 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:
iso_rr_path=disk_path
Character '=' in the iso_rr_path must be escaped by '\' (i.e. as
"\=").
With -pathspecs "on", the character '\' must not be escaped. The
character '=' in the disk_path must not be escaped.
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.
If iso_rr_path does not begin with '/' then -cd is prepended. If disk_path
does not begin with '/' then -cdx is prepended.
If no '=' is given then the word is used as both, iso_rr_path and disk path.
If in this case the word does not begin with '/' then -cdx is prepended to
the disk_path and -cd is prepended to the iso_rr_path.
If -pathspecs is set to "off" then -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.
- -add_plainly mode
- If set to mode "unknown" then any command word that does not
begin with "-" and is not recognized as known command will be
subject to a virtual -add command. I.e. it will be used as pathspec or as
disk_path and added to the image. If enabled, -disk_pattern expansion
applies to disk_paths.
Mode "dashed" is similar to "unknown" but also adds
unrecognized command words even if they begin with "-".
Mode "any" announces that all further words are to be added as
pathspecs or disk_paths. This does not work in dialog mode.
Mode "none" is the default. It prevents any words from being
understood as files to add, if they are not parameters to appropriate
commands.
- -path_list disk_path
- Like -add but read the parameter words from file disk_path or standard
input if disk_path is "-". The list must contain exactly one
pathspec or disk_path pattern per line.
- -quoted_path_list disk_path
- Like -path_list but with quoted input reading rules. Lines get split into
parameter words for -add. Whitespace outside quotes is discarded.
- -map disk_path iso_rr_path
- Insert file object disk_path into the ISO image as iso_rr_path. If
disk_path is a directory then its whole sub tree is inserted into the ISO
image.
- -map_single disk_path iso_rr_path
- Like -map, but if disk_path is a directory then its sub tree is not
inserted.
- -map_l disk_prefix iso_rr_prefix disk_path [***]
- Perform -map with each of the disk_path parameters. iso_rr_path will be
composed from disk_path by replacing disk_prefix by iso_rr_prefix.
- -update disk_path iso_rr_path
- Compare file object disk_path with file object iso_rr_path. If they do not
match, then perform the necessary image manipulations to make iso_rr_path
a matching copy of disk_path. By default this comparison will imply
lengthy content reading before a decision is made. Commands -disk_dev_ino
or -md5 may accelerate comparison if they were already in effect when the
loaded session was recorded.
If disk_path is a directory and iso_rr_path does not exist yet, then the
whole subtree will be inserted. Else only directory attributes will be
updated.
- -update_r disk_path iso_rr_path
- Like -update but working recursively. I.e. all file objects below both
addresses get compared whether they have counterparts below the other
address and whether both counterparts match. If there is a mismatch then
the necessary update manipulation is done.
Note that the comparison result may depend on command -follow. Its setting
should always be the same as with the first adding of disk_path as
iso_rr_path.
If iso_rr_path does not exist yet, then it gets added. If disk_path does not
exist, then iso_rr_path gets deleted.
- -update_l disk_prefix iso_rr_prefix disk_path [***]
- Perform -update_r with each of the disk_path parameters. iso_rr_path will
be composed from disk_path by replacing disk_prefix by iso_rr_prefix.
- -update_li iso_rr_prefix disk_prefix iso_rr_path [***]
- Perform -update_r with each of the iso_rr_path parameters. disk_path will
be composed from iso_rr_path by replacing iso_rr_prefix by
disk_prefix.
- -update_lxi disk_prefix iso_rr_prefix disk_path [***]
- Perform -update_r with each of the disk_path parameters and with
iso_rr_paths in the ISO filesystem which are derived from the disk_path
parameters after exchanging disk_prefix by iso_rr_prefix. So, other than
-update_l, this detects missing matches of disk_path and deletes the
corresponding iso_rr_path.
Note that relative disk_paths and disk_path patterns are interpreted as sub
paths of the current disk working directory -cdx. The corresponding
iso_rr_paths are derived by exchanging disk_prefix by iso_rr_prefix before
pattern expansion happens. The current -cdi directory has no
influence.
- -cut_out disk_path byte_offset byte_count iso_rr_path
- Map a byte interval of a regular disk file into a regular file in the ISO
image. This may be necessary if the disk file is larger than a single
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.
A clumsy remedy for this limit is to backup file pieces and to concatenate
them at restore time. A well tested chopping size is 2047m. It is
permissible to request a higher byte_count than available. The resulting
file will be truncated to the correct size of a final piece. To request a
byte_offset higher than available yields no file in the ISO image but a
SORRY event. E.g:
-cut_out /my/disk/file 0 2047m \
/file/part_1_of_3_at_0_with_2047m_of_5753194821 \
-cut_out /my/disk/file 2047m 2047m \
/file/part_2_of_3_at_2047m_with_2047m_of_5753194821 \
-cut_out /my/disk/file 4094m 2047m \
/file/part_3_of_3_at_4094m_with_2047m_of_5753194821
While 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.
- -cpr disk_path [***] iso_rr_path
- Insert the given files or directory trees from filesystem into the ISO
image.
The rules for generating the ISO addresses are similar as with shell command
cp -r. Nevertheless, directories of the iso_rr_path are created if
necessary. Especially a not yet existing iso_rr_path will be handled as
directory if multiple disk_paths are present. The leafnames of the
multiple disk_paths will be grafted under that directory as would be done
with an existing directory.
If a single disk_path is present then a non-existing iso_rr_path will get
the same type as the disk_path.
If a disk_path does not begin with '/' then -cdx is prepended. If the
iso_rr_path does not begin with '/' then -cd is prepended.
- -mkdir iso_rr_path [...]
- Create empty directories if they do not exist yet. Existence as directory
generates a WARNING event, existence as other file causes a FAILURE
event.
- -lns 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.
Hint: Command -clone produces the ISO equivalent of a hard link.
- -clone 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.
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.
This command will refuse execution if the address iso_rr_path_copy already
exists in the ISO tree.
- -cp_clone 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.
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.
- Settings for file insertion:
- -file_size_limit value [value [...]] --
- Set the maximum permissible size for a single data file. The values get
summed up for the actual limit. If the only value is "off" then
the file size is not limited by xorriso. Default is a limit of 100
extents, 4g -2k each:
-file_size_limit 400g -200k --
When mounting ISO 9660 filesystems, old operating systems can handle only
files up to 2g -1 --. Newer ones are good up to 4g -1 --. You need quite a
new Linux kernel to read correctly the final bytes of a file >= 4g if
its size is not aligned to 2048 byte blocks.
xorriso's own data read capabilities are not affected by 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.
- -not_mgt code[:code[...]]
- Control the behavior of the exclusion lists.
Exclusion processing happens before disk_paths get mapped to the ISO image
and before disk files get compared with image files. The absolute disk
path of the source is matched against the -not_paths list. The leafname of
the disk path is matched against the patterns in the -not_leaf list. If a
match is detected then the disk path will not be regarded as an existing
file and not be added to the ISO image.
Several codes are defined. The _on/_off settings persist until they are
revoked by their_off/_on counterparts.
"erase" empties the lists which were accumulated by -not_paths and
-not_leaf.
"reset" is like "erase" but also re-installs default
behavior.
"off" disables exclusion processing temporarily without
invalidating the lists and settings.
"on" re-enables exclusion processing.
"param_off" applies exclusion processing only to paths below
disk_path parameter of commands. I.e. explicitly given disk_paths are
exempted from exclusion processing.
"param_on" applies exclusion processing to command parameters as
well as to files below such parameters.
"subtree_off" with "param_on" excludes parameter paths
only if they match a -not_paths item exactly.
"subtree_on" additionally excludes parameter paths which lead to a
file address below any -not_paths item.
"ignore_off" treats excluded disk files as if they were missing.
I.e. they get reported with -compare and deleted from the image with
-update.
"ignore_on" keeps excluded files out of -compare or -update
activities.
- -not_paths disk_path [***]
- Add the given paths to the list of excluded absolute disk paths. If a
given path is relative, then the current -cdx is prepended to form an
absolute path. Pattern matching, if enabled, happens at definition time
and not when exclusion checks are made.
(Do not forget to end the list of disk_paths by "--")
- -not_leaf pattern
- Add a single shell parser style pattern to the list of exclusions for disk
leafnames. These patterns are evaluated when the exclusion checks are
made.
- -not_list disk_path
- Read lines from disk_path and use each of them either as -not_paths
parameter, if they contain a / character, or as -not_leaf pattern.
- -quoted_not_list disk_path
- Like -not_list but with quoted input reading rules. Each word is handled
as one parameter for -not_paths or -not_leaf.
- -follow occasion[:occasion[...]]
- Enable or disable resolution of symbolic links and mountpoints under
disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, -concat,
and to -disk_pattern expansion.
There are three kinds of follow decisison to be made:
link 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.
mount is the hop from one filesystem to another subordinate
filesystem. If enabled then mountpoint directories are handled as any
other directory, else mountpoints are handled as empty directories if they
are encountered in directory tree traversals.
concat 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
!
Less general than above occasions:
pattern is mount and link hopping, but only during -disk_pattern
expansion.
param is link hopping for parameter words (after eventual pattern
expansion). If enabled then -ls*x will show the link targets rather than
the links themselves. -du*x, -findx, and -add will process the link
targets but not follow links in an eventual directory tree below the
targets (unless "link" is enabled).
Occasions can be combined in a colon separated list. All occasions mentioned
in the list will then lead to a positive follow decision.
off prevents any positive follow decision. Use it if no other
occasion applies.
Shortcuts:
default is equivalent to "pattern:mount:limit=100".
on always decides positive. Equivalent to
"link:mount:concat".
Not an occasion but an optional setting is:
limit=<number> which sets the maximum number of link hops. A
link hop consists of a sequence of symbolic links and a final target of
different type. Nevertheless those hops can loop. Example:
$ ln -s .. uploop
Link hopping has a built-in loop detection which stops hopping at the
first repetition of a link target. Then the repeated link is handled as
itself and not as its target. Regrettably one can construct link
networks which cause exponential workload before their loops get
detected. The number given with "limit=" can curb this
workload at the risk of truncating an intentional sequence of link
hops.
- -pathspecs
"on"|"off"|"as_mkisofs"
- Control parameter interpretation with xorriso actions -add and
-path_list.
Mode "as_mkisofs" enables pathspecs of the form
iso_rr_path=disk_path
like with program mkisofs -graft-points.
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.
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 '\'.
Mode "off" disables pathspecs of the form target=source and
re-enables -disk_pattern expansion.
- -overwrite "on"|"nondir"|"off"
- Allow or disallow overwriting of existing files in the ISO image by files
with the same name.
With setting "off", name collisions with at least one
non-directory file cause FAILURE events. Collisions of two directories
lead to merging of their file lists.
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.
If restoring of files is enabled, then the overwrite rule applies to the
target file objects on disk as well, but "on" is downgraded to
"nondir".
- -split_size number["k"|"m"]
- Set the threshold for automatic splitting of regular files. Such splitting
maps a large disk file onto a ISO directory with several part files in it.
This is necessary if the size of the disk file exceeds -file_size_limit.
Older operating systems can handle files in mounted ISO 9660 filesystems
only if they are smaller than 2 GiB or in other cases 4 GiB.
Default is 0 which will exclude files larger than -file_size_limit by a
FAILURE event. A well tested -split_size is 2047m. Sizes above
-file_size_limit are not permissible.
While 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 -osirrox
parameters "concat_split_on" and "concat_split_off"
which control the handling when files get restored to disk.
In order to be recognizable, the names of the part files have to describe
the splitting by 5 numbers:
part_number,total_parts,byte_offset,byte_count,disk_file_size
which are embedded in the following text form:
part_#_of_#_at_#_with_#_of_#
Scaling characters like "m" or "k" are taken into
respect. All digits are interpreted as decimal, even if leading zeros are
present.
E.g: /file/part_1_of_3_at_0_with_2047m_of_5753194821
No other files are allowed in the directory. All parts have to be present
and their numbers have to be plausible. E.g. byte_count must be valid as
-cut_out parameter and their contents may not overlap.
- File manipulations:
The following commands manipulate files in the ISO image,
regardless whether they stem from the loaded image or were newly
inserted.
- -iso_rr_pattern "on"|"ls"|"off"
- Set the pattern expansion mode for the iso_rr_path parameters of several
commands which support this feature.
Setting "off" disables pattern expansion for all commands which
are marked in this man page by "iso_rr_path [***]" or
"iso_rr_pattern [***]".
Setting "on" enables it for all those commands.
Setting "ls" enables it only for those which are marked by
"iso_rr_pattern [***]".
Default is "on".
- -rm iso_rr_path [***]
- Delete the given files from the ISO image.
Note: This does not free any space on the -indev medium, even if the
deletion is committed to that same medium.
The image size will shrink if the image is written to a different medium in
modification mode.
- -rm_r iso_rr_path [***]
- Delete the given files or directory trees from the ISO image. See also the
note with command -rm.
- -rmdir iso_rr_path [***]
- Delete empty directories.
- -move 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.
- -mv 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.
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.
- -chown uid iso_rr_path [***]
- Set ownership of file objects in the ISO image. uid may either be a
decimal number or the name of a user known to the operating system.
- -chown_r uid iso_rr_path [***]
- Like -chown but affecting all files below eventual directories.
- -chgrp gid iso_rr_path [***]
- Set group attribute of file objects in the ISO image. gid may either be a
decimal number or the name of a group known to the operating system.
- -chgrp_r gid iso_rr_path [***]
- Like -chgrp but affecting all files below eventual directories.
- -chmod mode iso_rr_path [***]
- Equivalent to shell command chmod in the ISO image. mode is either an
octal number beginning with "0" or a comma separated list of
statements of the form [ugoa]*[+-=][rwxst]* .
Like: go-rwx,u+rwx .
Personalities: u=user, g=group, o=others, a=all
Operators: + adds given permissions, - revokes given permissions, =
revokes all old permissions and then adds the given ones.
Permissions: r=read, w=write, x=execute|inspect, s=setuid|setgid,
t=sticky bit
For octal numbers see man 2 stat.
- -chmod_r mode iso_rr_path [***]
- Like -chmod but affecting all files below eventual directories.
- -setfacl acl_text iso_rr_path [***]
- Attach the given ACL to the given iso_rr_paths. 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:
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:
g:toolies:rw,u:lisa:rw,u:1001:rw,u::wr,g::r,o::r,m::rw
group:toolies:rw-,user::rw-,group::r--,other::r--,mask::rw-
A valid entry may be prefixed by "d", some following characters
and ":". This indicates that the entry goes to the
"default" ACL rather than to the "access" ACL.
Example:
u::rwx,g::rx,o::,d:u::rwx,d:g::rx,d:o::,d:u:lisa:rwx,d:m::rwx
- -setfacl_r acl_text iso_rr_path [***]
- Like -setfacl but affecting all files below eventual directories.
- -setfacl_list disk_path
- Read the output of -getfacl_r or shell command getfacl -R and apply it to
the iso_rr_paths as given in lines beginning with "# file:".
This will change ownership, group and ACL of the given files. If disk_path
is "-" then lines are read from standard input. Line
"@" ends the list, "@@@" aborts without changing the
pending iso_rr_path.
Since -getfacl and getfacl -R strip leading "/" from file paths,
the setting of -cd does always matter.
- -setfattr [-]name value iso_rr_path [***]
- Attach the given xattr pair of name and value to the given iso_rr_paths.
If the given name is prefixed by "-", then the pair with that
name gets removed from the xattr list. If name is "--remove-all"
then all user namespace xattr of the given iso_rr_paths get deleted. In
case of deletion, value must be an empty text.
Which names are permissible depends on the setting of command -xattr.
"on" or "user" restricts them to namespace
"user". I.e. a name has to look like "user.x" or
"user.whatever".
-xattr setting "any" enables names from all namespaces except
"isofs".
Values and names undergo the normal input processing of xorriso. See
also command -backslash_codes. Other than with command -setfattr_list, the
byte value 0 cannot be expressed via -setfattr.
- -setfattr_r [-]name value iso_rr_path [***]
- Like -setfattr but affecting all files below eventual directories.
- -setfattr_list disk_path
- Read the output format 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 xattr of the acceptable namespaces
will be deleted before the new xattr get attached. The set of acceptable
names depends on the setting of command -xattr.
If disk_path is "-" then lines are read from standard input.
Since -getfattr and getfattr -Rd strip leading "/" from file
paths, the setting of -cd does always matter.
Empty input lines and lines which begin by "#" will be ignored
(except "# file:"). Line "@" ends the list,
"@@@" aborts without changing the pending iso_rr_path. Other
input lines must have the form
name="value"
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.
- -alter_date type timestring iso_rr_path [***]
- Alter the date entries of files in the ISO image. type may be one of the
following:
"a" sets access time, updates ctime.
"m" sets modification time, updates ctime.
"b" sets access time and modification time, updates ctime.
"a-c", "m-c", and "b-c" set the times without
updating ctime.
"c" sets the ctime.
timestring may be in the following formats (see also section EXAMPLES):
As expected by program date:
MMDDhhmm[[CC]YY][.ss]]
As produced by program date:
[Day] MMM DD hh:mm:ss [TZON] YYYY
Relative times counted from current clock time:
+|-Number["s"|"h"|"d"|"w"|"m"|"y"]
where "s" means seconds, "h" hours, "d" days,
"w" weeks, "m"=30d, "y"=365.25d plus 1d
added to multiplication result.
Absolute seconds counted from Jan 1 1970:
=Number
xorriso's own timestamps:
YYYY.MM.DD[.hh[mm[ss]]]
scdbackup timestamps:
YYMMDD[.hhmm[ss]]
where "A0" is year 2000, "B0" is 2010, etc.
ECMA-119 volume timestamps:
YYYYMMDDhhmmsscc
These are normally given as GMT. The suffix "LOC" causes local
timezone conversion. E.g.<PHONE_NUMBER>574700,<PHONE_NUMBER>574700LOC. The last
two digits cc (centiseconds) will be ignored, but must be present in order
to make the format recognizable.
Example:
-alter_date m-c 2<IP_ADDRESS>951 /file1 /file2 --
This command does not persistently apply to the boot catalog, which gets
fresh timestamps at -commit time. Command -volume_date "uuid"
can set this time value.
- -alter_date_r type timestring iso_rr_path [***]
- Like -alter_date but affecting all files below eventual directories.
- -hide hide_state iso_rr_path [***]
- Prevent the names of the given files from showing up in the directory
trees of ISO 9660 and/or Joliet 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.
Warning: Data which are hidden from the ISO 9660 tree will not be copied by
the write method of modifying.
Possible values of hide_state are: "iso_rr" for hiding from ISO
9660 tree, "joliet" for Joliet tree, "hfsplus" for
HFS+, "on" for them all. "off" means visibility in all
directory trees.
These values may be combined. E.g.: joliet:hfsplus
This command does not apply to the boot catalog. Rather use: -boot_image
"any" "cat_hidden=on"
- Tree traversal command -find:
- -find iso_rr_path [test [op] [test ...]] [-exec action [params]]
--
- A restricted substitute for shell command find in the ISO image. It
performs an action on matching file objects at or below iso_rr_path.
If not used as last command in the line then the parameter list needs to get
terminated by "--".
Tests are optional. If they are omitted then action is applied to all file
objects. If tests are given then they form together an expression. The
action is applied only if the expression matches the file object. Default
expression operator between tests is -and, i.e. the expression matches
only if all its tests match.
Available tests are:
-name pattern : Matches if pattern matches the file leaf name. 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.
-wholename 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.
-disk_name 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.
-disk_path 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.
-type 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.
Only the first letter is interpreted. E.g.: -find / -type d
-maxdepth number : Matches only files which are at most at the given
depth level relative to the iso_rr_path where -find starts. That path
itself is at depth 0, its directory children are at 1, their directory
children at 2, and so on.
-mindepth number : Matches only files which are at least at the given
depth level.
-damaged : Matches files which use data blocks marked as damaged by a
previous run of -check_media. The damage info vanishes when a new ISO
image gets loaded.
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.
-pending_data : Matches files which get their content from outside
the loaded ISO image.
-lba_range start_lba block_count : Matches files which use data
blocks within the range of start_lba and start_lba+block_count-1.
-has_acl : Matches files which have a non-trivial ACL.
-has_xattr : Matches files which have xattr name-value pairs from
user namespace.
-has_aaip : Matches files which have ACL or any xattr.
-has_any_xattr : Matches files which have any xattr other than ACL.
-has_md5 : Matches data files which have MD5 checksums.
-has_hfs_crtp 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:.
-has_hfs_crtp YYDN TEXT
-has_hfs_crtp - -
-has_hfs_bless 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.
-has_filter : Matches files which are filtered by -set_filter.
-hidden hide_state : Matches files which are hidden in
"iso_rr" tree, in "joliet" tree, in
"hfsplus" tree, in all trees ("on"), or not hidden in
any tree ("off").
Those which are hidden in some tree match -not -hidden "off".
-bad_outname 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".
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".
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.
-name_limit_blocker length : Matches file names which would prevent
command -file_name_limit with the given length. The command itself reports
only the first problem file.
-prune : If this test is reached and the tested file is a directory
then -find will not dive into that directory. This test itself does always
match.
-use_pattern "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.
-or_use_pattern "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.
-decision "yes"|"no" : If this test is reached
then the evaluation ends immediately and action is performed if the
decision is "yes" or "true". See operator -if.
-true and -false : Always match or match not, respectively.
Evaluation goes on.
-sort_lba : Always match. This causes -find to perform its action in
a sequence sorted by the ISO image block addresses of the files. It may
improve throughput with actions which read data from optical drives.
Action will always get the absolute path as parameter.
Available operators are:
-not : Matches if the next test or sub expression does not match.
Several tests do this specifically:
-undamaged, -lba_range with negative start_lba, -has_no_acl, -has_no_xattr,
-has_no_aaip, -has_no_filter .
-and : Matches if both neighboring tests or expressions match.
-or : Matches if at least one of both neighboring tests or
expressions matches.
-sub ... -subend or ( ... ) : Enclose a sub
expression which gets evaluated first before it is processed by
neighboring operators. Normal precedence is: -not, -or , -and.
-if ... -then ... -elseif ... -then ...
-else ... -endif : Enclose one or more sub expressions. If
the -if expression matches, then the -then expression is evaluated as the
result of the whole expression up to -endif. Else the next -elseif
expression is evaluated and 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.
-if-expressions are the main use case for above test -decision.
Default action is echo, i.e. to print the address of
the found file. Other actions are certain xorriso commands which
get performed on the found files. These commands may have specific
parameters. See also their particular descriptions.
chown and chown_r change the ownership and get the user id
as parameter. E.g.: -exec chown thomas --
chgrp and chgrp_r change the group attribute and get the
group id as parameter. E.g.: -exec chgrp_r staff --
chmod and chmod_r change access permissions and get a mode
string as parameter. E.g.: -exec chmod a-w,a+r --
alter_date and alter_date_r change the timestamps. They get
a type character and a timestring as parameters.
E.g.: -exec alter_date "m" "Dec 30 19:34:12 2007" --
set_to_mtime sets the ctime and atime to the value found in mtime.
lsdl prints file information like shell command ls -dl.
compare performs command -compare with the found file address as
iso_rr_path and the corresponding file address below its parameter
disk_path_start. For this the iso_rr_path of the -find command gets
replaced by the disk_path_start.
E.g.: -find /thomas -exec compare /home/thomas --
update performs command -update with the found file address as
iso_rr_path. The corresponding file address is determined like with
above action "compare".
update_merge 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.
Up to the next "rm_merge" or "clear_merge" all newly
inserted files will get marked as having a disk counterpart.
rm removes the found iso_rr_path from the image if it is not a
directory with files in it. I.e. this "rm" includes
"rmdir".
rm_r removes the found iso_rr_path from the image, including whole
directory trees.
rm_merge 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.
clear_merge removes an eventual marking from action
"update_merge".
report_damage 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.
report_lba prints files which are associated to image data blocks.
It tells the logical block address, the block number, the byte size, and
the path of each file. There may be reported more than one line per file
if the file has more than one section. In this case each line has a
different extent number in column "xt".
report_sections like report_lba but telling the byte sizes of the
particular sections rather than the overall byte size of the file.
getfacl prints access permissions in ACL text form to the result
channel.
setfacl attaches ACLs after removing existing ones. The new ACL is
given in text form as defined with command -setfacl.
E.g.: -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
getfattr prints xattr name-value pairs to the result channel. The
choice of namespaces depends on the setting of command -xattr:
"on" or "user" restricts it to the namespace
"user", "any" only omits namespace
"isofs".
get_any_xattr prints xattr name-value pairs from any namespace
except ACL to the result channel. This is mostly for debugging of
namespace "isofs".
list_extattr 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.
E.g. -exec list_extattr e --
Command -backslash_codes does not affect the output.
get_md5 prints the MD5 sum, if recorded, together with file path.
check_md5 compares the MD5 sum, if recorded, with the file content
and reports if mismatch.
E.g.: -find / -not -pending_data -exec check_md5 FAILURE --
make_md5 equips a data file with an MD5 sum of its content. Useful
to upgrade the files in the loaded image to full MD5 coverage by the
next commit with -md5 "on".
E.g.: -find / -type f -not -has_md5 -exec make_md5 --
setfattr sets or deletes xattr name value pairs.
E.g.: -find / -has_xattr -exec setfattr --remove-all '' --
set_hfs_crtp adds, changes, or removes HFS+ creator and type
attributes.
E.g.: -exec set_hfs_crtp YYDN TEXT
E.g.: -find /my/dir -prune -exec set_hfs_crtp --delete -
get_hfs_crtp prints the HFS+ creator and type attributes together
with the iso_rr_path, if the file has such attributes at all.
E.g.: -exec get_hfs_crtp
set_hfs_bless applies or removes HFS+ blessings. They are roles
which can be attributed to up to four directories and a data file:
"ppc_bootdir", "intel_bootfile",
"show_folder", "os9_folder", "osx_folder".
They may be abbreviated as "p", "i", "s",
"9", and "x".
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.
E.g.: -find /my/blessed/directory -exec set_hfs_bless p
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.
E.g.: -find / -has_hfs_bless any -exec set_hfs_bless none
get_hfs_bless prints the HFS+ blessing role and the iso_rr_path, if
the file is blessed at all.
E.g.: -exec get_hfs_bless
set_filter applies or removes filters.
E.g.: -exec set_filter --zisofs --
mkisofs_r applies the rules of mkisofs -r to the file object:
user id and group id become 0, all r-permissions get granted, all w
denied. If there is any x-permission, then all three x get granted. s-
and t-bits get removed.
sort_weight attributes a LBA weight number to regular files.
The number may range from -2147483648 to<PHONE_NUMBER>. The higher it is, the
lower will be the block address of the file data in the emerging ISO
image. Currently the boot catalog has a hardcoded weight of 1 billion.
Normally it should occupy the block with the lowest possible address.
Data files 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.
Data files which are added by other commands get an initial weight of 0.
Boot image files have a default weight of 2.
E.g.: -exec sort_weight 3 --
show_stream shows the content stream chain of a data file.
show_stream_id is like show_stream, but also prints between stream
type and first ":" in square brackets libisofs id numbers:
[fs_id,dev_id,ino_id].
hide brings the file into one of the hide states "on",
"iso_rr", "joliet", "hfsplus",
"off". They may be combined. E.g.: joliet:hfsplus
E.g.:
-find / -disk_name *_secret -exec hide on
print_outname 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
"--" .
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.
E.g.:
-find / -bad_outname joliet -exec print_outname joliet
estimate_size 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.
find performs another run of -find on the matching file address. It
accepts the same params as -find, except iso_rr_path.
E.g.:
-find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r
--
- Filters for data file content:
Filters may be installed between data files in the ISO
image and their content source outside the image. They may also be used vice
versa between data content in the image and target files on disk.
Built-in filters are "--zisofs" and "--zisofs-decode". The
former is to be applied via -set_filter, the latter is automatically applied
if zisofs compressed content is detected with a file when loading the ISO
image.
Another built-in filter pair is "--gzip" and "--gunzip"
with suffix ".gz". They behave about like external gzip and gunzip
but avoid forking a process for each single file. So they are much faster if
there are many small files.
- -external_filter name option[:option] program_path [arguments]
--
- Register a content filter by associating a name with a program path,
program arguments, and some behavioral options. Once registered it can be
applied to multiple data files in the ISO image, regardless whether their
content resides in the loaded ISO image or in the local filesystem.
External filter processes may produce synthetic file content by reading
the original content from stdin and writing to stdout whatever they want.
They must deliver the same output on the same input in repeated runs.
Options are:
"default" means that no other option is intended.
"suffix=..." sets a file name suffix. If it is not empty then it
will be appended to the file name or removed from it.
"remove_suffix" will remove a file name suffix rather than
appending it.
"if_nonempty" will leave 0-sized files unfiltered.
"if_reduction" will try filtering and revoke it if the content
size does not shrink.
"if_block_reduction" will revoke if the number of 2 kB blocks
does not shrink.
"used=..." is ignored. Command -status shows it with the number
of files which currently have the filter applied.
Examples:
-external_filter bzip2 suffix=.bz2:if_block_reduction \
/usr/bin/bzip2 --
-external_filter bunzip2 suffix=.bz2:remove_suffix \
/usr/bin/bunzip2 --
- -unregister_filter name
- Remove an -external_filter registration. This is only possible if the
filter is not applied to any file in the ISO image.
- -close_filter_list
- Irrevocably ban commands -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 xorriso. By default they
are banned if xorriso runs under setuid permission.
- -set_filter name iso_rr_path [***]
- Apply an -external_filter or a built-in filter to the given data files in
the ISO image. If the filter suffix is not empty , then it will be applied
to the file name. Renaming only happens if the filter really gets attached
and is not revoked by its options. By default files which already bear the
suffix will not get filtered. The others will get the suffix appended to
their names. If the filter has option "remove_suffix", then the
filter will only be applied if the suffix is present and can be removed.
Name oversize or collision caused by suffix change will prevent filtering.
With most filter types this command will immediately run the filter once for
each file in order to determine the output size. Content reading
operations like -extract , -compare and image generation will perform
further filter runs and deliver filtered content.
At image generation time the filter output must still be the same as the
output from the first run. Filtering for image generation does not happen
with files from the loaded ISO image if the write method of growing is in
effect (i.e -indev and -outdev are identical).
The reserved filter name "--remove-all-filters" revokes filtering.
This will revoke suffix renamings as well. Use
"--remove-all-filters+" to prevent any suffix renaming.
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".
- -set_filter_r name iso_rr_path [***]
- Like -set_filter but affecting all data files below eventual
directories.
- Writing the result, drive control:
(see also paragraph about settings below)
- -rollback
- Discard the manipulated ISO image and reload it from -indev. (Use
-rollback_end if immediate program end is desired.)
- -changes_pending
"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).
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.
The pseudo-state "show_status" can be used to print the current
state to result channel.
Image loading or manipulations which happen after this command will again
update automatically the change status of the image.
- -commit
- 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.
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".
To suppress a final write, execute -rollback_end.
Writing can last quite a while. It is not unnormal with
several types of media that there is no progress visible for the first
few minutes or that the drive gnaws on the medium for a few minutes
after all data have been transmitted. xorriso and the drives are
in a client-server relationship. The drives have much freedom about what
to do with the media. Some combinations of drives and media simply do
not work, despite the promises by their vendors. If writing fails then
try other media or another drive. The reason for such failure is hardly
ever in the code of the various burn programs but you may well try some
of those listed below under SEE ALSO.
- -eject "in"|"out"|"all"
- Eject the medium in -indev, -outdev, or both drives, respectively. Note:
It is not possible yet to effectively eject disk files.
- -commit_eject
"in"|"out"|"all"|"none"
- Combined -commit and -eject. When writing has finished do not make -outdev
the new -dev, and load no ISO image. Rather eject -indev and/or -outdev.
Give up any non-ejected drive.
- -blank mode
- Make media ready for writing from scratch (if not -dummy is activated).
This affects only the -outdev not the -indev. If both drives are the same
and if the ISO image was altered then this command leads to a FAILURE
event. Defined modes are:
as_needed, fast, all, deformat, deformat_quickest
"as_needed" cares for used CD-RW, DVD-RW and for used
overwriteable media by applying -blank "fast". It applies
-format "full" to yet unformatted DVD-RAM and BD-RE. Other media
in blank state are gracefully ignored. Media which cannot be made ready
for writing from scratch cause a FAILURE event.
"fast" makes CD-RW and unformatted DVD-RW re-usable, or
invalidates overwriteable ISO images. "all" might work more
thoroughly and need more time.
"deformat" converts overwriteable DVD-RW into unformatted ones.
"deformat_quickest" is a faster way to deformat or blank DVD-RW
but produces media which are only suitable for a single session. Some
drives announce this state by not offering feature 21h, but some drives
offer it anyway. If feature 21h is missing, then xorriso will
refuse to write on DVD-RW if not command -close is set to "on".
The progress reports issued by some drives while blanking are quite
unrealistic. Do not conclude success or failure from the reported
percentages. Blanking was successful if no SORRY event or worse occurred.
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.
- -format mode
- Convert unformatted DVD-RW into overwriteable ones, "de-ice"
DVD+RW, format newly purchased BD-RE or BD-R, re-format DVD-RAM or BD-RE.
Defined modes are:
as_needed, full, fast, by_index_<num>, fast_by_index_<num>,
by_size_<num>, fast_by_size_<num>, without_spare
"as_needed" formats yet unformatted DVD-RW, DVD-RAM, BD-RE, or
blank unformatted BD-R. Other media are left untouched.
"full" (re-)formats DVD-RW, DVD+RW, DVD-RAM, BD-RE, or blank
unformatted BD-R.
"fast" does the same as "full" but tries to be quicker.
"by_index_" selects a format out of the descriptor list issued by
command -list_formats. The index number from that list is to be appended
to the mode word. E.g: "by_index_3".
"fast_by_index_" does the same as "by_index_" but tries
to be quicker.
"by_size_" selects a format out of the descriptor list which
provides at least the given size. That size is to be appended to the mode
word. E.g: "by_size_4100m". This applies to media with Defect
Management. On BD-RE it will not choose format 0x31, which offers no
Defect Management.
"fast_by_size_" does the same as "by_size_" but tries to
be quicker.
"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.
The formatting action has no effect on media if -dummy is activated.
Formatting is normally needed only once during the lifetime of a medium, if
ever. But it is a reason for re-formatting if:
DVD-RW was deformatted by -blank,
DVD+RW has read failures (re-format before next write),
DVD-RAM or BD-RE shall change their amount of defect reserve.
BD-R may be written unformatted or may be formatted before first use.
Formatting activates Defect Management which tries to catch and repair bad
spots on media during the write process at the expense of half speed even
with flawless media.
The progress reports issued by some drives while formatting are quite
unrealistic. Do not conclude success or failure from the reported
percentages. Formatting was successful if no SORRY event or worse
occurred. Be patient with apparently frozen progress.
- -list_formats
- 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.
MMC format codes are manifold. Most important are: "00h" general
formatting, "01h" increases reserve space for DVD-RAM,
"26h" for DVD+RW, "30h" for BD-RE with reserve space,
"31h" for BD-RE without reserve space, "32h" for BD-R.
Smaller format size with DVD-RAM, BD-RE, or BD-R means more reserve
space.
- -list_speeds
- 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.
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.
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.
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.
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".
"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".
- -close_damaged "as_needed"|"force"
- Try to close the upcoming 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.
The setting of command -close determines whether the medium stays
appendable.
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.
No image changes are allowed to be pending before this command is performed.
After closing was attempted, both drives are given up.
- -list_profiles "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)".
- Settings for result writing:
Rock Ridge info will be generated by default. ACLs will be written
according to the setting of command -acl.
- -joliet "on"|"off"
- If enabled by "on", generate Joliet tree additional to ISO 9660
+ Rock Ridge tree.
- -hfsplus "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.
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.
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.
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.
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.
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_...".
- -rockridge "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".
- -compliance 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.
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".
Rule keywords are:
"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.
"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.
"omit_version" does not add versions (";1") to ECMA-119
and Joliet file names.
"only_iso_version" does not add versions (";1") to
Joliet file names.
"deep_paths" allows ECMA-119 file paths deeper than 8 levels.
"long_paths" allows ECMA-119 file paths longer than 255
characters.
"long_names" allows up to 37 characters with ECMA-119 file names.
"no_force_dots" does not add a dot to ECMA-119 file names which
have none.
"no_j_force_dots" does not add a dot to Joliet file names which
have none.
"lowercase" allows lowercase characters in ECMA-119 file names.
"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.
"full_ascii" allows all 8-bit characters except 0x0 and '/' in
ECMA-119 file names.
"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.
"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.
"joliet_long_names" allows Joliet leaf names up to 103 characters
rather than 64.
"joliet_long_paths" allows Joliet paths longer than 240
characters.
"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.
"always_gmt" stores timestamps in GMT representation with timezone
0.
"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.
"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".
Default is "old_rr" which uses Rock Ridge version 1.10. This
implies also "aaip_susp_1_10" which may be changed by subsequent
"aaip_susp_1_10_off".
"aaip_susp_1_10" allows AAIP to be written as unofficial extension
of RRIP rather than as official extension under SUSP-1.12.
"no_emul_toc" saves 64 kB with the first session on overwriteable
media but makes the image incapable of displaying its session history.
"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.
"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.
Default setting is
"clear:only_iso_version:deep_paths:long_paths:no_j_force_dots:
always_gmt:old_rr".
Note: The term "ECMA-119 name" means the plain ISO 9660 names and
attributes which get visible if the reader ignores Rock Ridge.
- -rr_reloc_dir 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.
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.
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.
The name must not contain a '/' character and must not be longer than 255
bytes.
- -volid text
- Specify the volume ID, which most operating systems will consider to be
the volume name of the image or medium.
xorriso accepts any text up to 32 characters, but according to rarely
obeyed specs stricter rules apply:
ECMA-119 demands ASCII characters out of [A-Z0-9_]. Like:
"IMAGE_23"
Joliet allows 16 UCS-2 characters. Like:
"Windows name"
Be aware that the volume id might get used automatically as the name of the
mount point when the medium is inserted into a playful computer system.
If an ISO image gets loaded while the volume ID is set to default
"ISOIMAGE" or to "", then the volume ID of the loaded
image will become the effective volume id for the next write run. But as
soon as command -volid is performed afterwards, this pending ID is
overridden by the new setting.
Consider this when setting -volid "ISOIMAGE" before executing
-dev, -indev, or -rollback. If you insist in -volid "ISOIMAGE",
set it again after those commands.
- -volset_id text
- Set the volume set ID string to be written with the next -commit.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
- -publisher text
- Set the publisher ID string to be written with the next -commit. This may
identify the person or organisation who specified what shall be recorded.
Permissible are up to 128 characters. This setting gets overridden by
image loading.
- -application_id text
- Set the application ID string to be written with the next -commit. This
may identify the specification of how the data are recorded. Permissible
are up to 128 characters. This setting gets overridden by image loading.
The special text "@xorriso@" gets converted to the ID string of
xorriso which is normally written as -preparer_id. It is a wrong
tradition to write the program ID as -application_id.
- -system_id text
- Set the system ID string to be written with the next -commit. This may
identify the system which can recognize and act upon the content of the
System Area in image blocks 0 to 15. Permissible are up to 32 characters.
This setting gets overridden by image loading.
- -volume_date type timestring
- Set one of the four overall timestamps for subsequent image writing.
Available types are:
"c" time when the volume was created.
"m" time when volume was last modified.
"x" time when the information in the volume expires.
"f" time since when the volume is effectively valid.
"all_file_dates" sets mtime, atime, and ctime of all files and
directories to the given time. If the timestring is
"set_to_mtime", then the atime and ctime of each file and
directory get set to the value found in their mtime.
These actions stay delayed until actual ISO production begins. Up to then
they can be revoked by "all_file_dates" with empty timestring or
timestring "default".
The timestamps of the El Torito boot catalog file get refreshed when the ISO
is produced. They can be influenced by "uuid".
"uuid" sets a timestring that overrides "c" and
"m" times literally and sets the time of the El Torito boot
catalog. It must consist of 16 decimal digits which form YYYYMMDDhhmmsscc,
with YYYY between 1970 and 2999. Time zone is GMT. It is supposed to match
this GRUB line:
search --fs-uuid --set YYYY-MM-DD-hh-mm-ss-cc
E.g.<PHONE_NUMBER>405800 is 7 Apr 2010 11:40:58 (+0 centiseconds).
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.
At -commit time, some timestamps get set to the maximum value of effectively
written volume creation and modification time: El Torito boot catalog,
HFS+ superblock, ECMA-119 file modification time if -compliance
"no_rec_mtime". The isohybrid MBR id is computed from
"uuid" if given, else from the effective volume modification
date.
- -copyright_file text
- Set the copyright file name to be written with the next -commit. This
should be the ISO 9660 path of a file in the image which contains a
copyright statement. Permissible are up to 37 characters. This setting
gets overridden by image loading.
- -abstract_file text
- Set the abstract file name to be written with the next -commit. This
should be the ISO 9660 path of a file in the image which contains an
abstract statement about the image content. Permissible are up to 37
characters. This setting gets overridden by image loading.
- -biblio_file text
- Set the biblio file name to be written with the next -commit. This should
be the ISO 9660 path of a file in the image which contains bibliographic
records. Permissible are up to 37 characters. This setting gets overridden
by image loading.
- -preparer_id
- 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
xorriso and not of the person or program which operates
xorriso. Please avoid to change it. Permissible are up to 128
characters.
The special text "@xorriso@" gets converted to the ID string of
xorriso which is default at program startup.
Unlike other ID strings, this setting is not influenced by image
loading.
- -application_use character|0xXY|disk_path
- Specify the content of the Application Use field which can take at most
512 bytes.
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.
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.
This setting is not influenced by image loading.
- -out_charset character_set_name
- Set the character set to which file names get converted when writing an
image. See paragraph "Character sets" for more explanations.
When loading the written image after -commit the setting of -out_charset
will be copied to -in_charset.
- -uid uid
- User id to be used for all files when the new ISO tree gets written to
media.
- -gid gid
- Group id to be used for all files when the new ISO tree gets written to
media.
- -zisofs option[:options]
- Set global parameters for zisofs compression. This data format is
recognized and transparently uncompressed by some Linux kernels. It is to
be applied via command -set_filter with built-in filter
"--zisofs". Parameters are:
"level="[0-9] zlib compression: 0=none, 1=fast,..., 9=slow
"block_size="32k|64k|128k size of compression blocks
"by_magic=on" enables an expensive test at image generation time
which checks files from disk whether they already are zisofs compressed,
e.g. by program mkzftree.
"default" same as
"level=6:block_size=32k:by_magic=off"
- -speed 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:
"min" (or "-1") selects minimum speed as announced by
the drive.
"none" avoids to send a speed setting command to the drive before
burning begins.
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.
Example speeds:
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then the medium in the
-outdev will decide. Default unit is CD = 176.4k.
MMC drives usually activate their own idea of speed and take the speed value
given by the burn program only as upper limit for their own decision.
- -stream_recording
"on"|"off"|"full"|"data"|number
- Setting "on" tries to circumvent the management of defects on
DVD-RAM, BD-RE, or BD-R. Defect management keeps partly damaged media
usable. But it reduces write speed to half nominal speed even if the
medium is in perfect shape. For the case of flawless media, one may use
-stream_recording "on" to get full speed.
"full" tries full speed with all write operations, whereas
"on" does this only above byte address 32s. One may give a
number of at least 16s in order to set an own address limit.
"data" causes full speed to start when superblock and directory
entries are written and writing of file content blocks begins.
- -dvd_obs "default"|"32k"|"64k"
- GNU/Linux specific: Set the number of bytes to be transmitted with each
write operation to DVD or BD media. A number of 64 KB may improve
throughput with bus systems which show latency problems. The default
depends on media type, on command -stream_recording , and on compile time
options.
- -modesty_on_drive 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.
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.
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.
Parameters "off" or "0" disable this feature.
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=".
E.g.: -modesty_on_drive 75
The optimal values depend on the buffer behavior of the drive.
Parameter "timeout_sec=" defines after which time of unsuccessful
waiting the modesty shall be disabled because it does not work.
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.
Parameters, which are not mentioned with a -modesty_on_drive command, stay
unchanged. Default is:
-modesty_on_drive off:min_percent=90:max_percent=95:
timeout_sec=120:min_usec=5000:max_usec=25000
- -use_immed_bit
"on"|"off"|"default"
- Control whether several long lasting SCSI commands shall be executed with
the Immed bit, which makes the commands end early while the drive
operation is still going on. xorriso then inquires progress indication
until the drive reports to be ready again. If this feature is turned off,
then blanking and formatting will show no progress indication.
It may depend on the operating system whether -use_immed_bit is set to
"off" by default. Command -status will tell by appending
"/on" or "/off" if a drive has already been acquired
and -use_immed_bit is currently set to "default". Command
-use_immed_bit tolerates and ignores such appended text.
- -stdio_sync
"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.
- -dummy "on"|"off"
- If "on" then simulate burning or refuse with FAILURE event if no
simulation is possible, do neither blank nor format.
- -fs number["k"|"m"]
- Set the size of the fifo buffer which smoothens the data stream from ISO
image generation to media burning. Default is 4 MiB, minimum 64 kiB,
maximum 1 GiB. The number may be followed by letter "k" or
"m" which means unit is kiB (= 1024) or MiB (= 1024 kiB).
- -close "on"|"off"|"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.
If set to "off" then keep the medium writable for an appended