You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1666 lines
59 KiB
1666 lines
59 KiB
.\" Hey, EMACS: -*- nroff -*- |
|
.\" First parameter, NAME, should be all caps |
|
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection |
|
.\" other parameters are allowed: see man(7), man(1) |
|
.TH XORRISO 1 "February 21, 2008" |
|
.\" Please adjust this date whenever revising the manpage. |
|
.\" |
|
.\" Some roff macros, for reference: |
|
.\" .nh disable hyphenation |
|
.\" .hy enable hyphenation |
|
.\" .ad l left justify |
|
.\" .ad b justify to both left and right margins |
|
.\" .nf disable filling |
|
.\" .fi enable filling |
|
.\" .br insert line break |
|
.\" .sp <n> insert n+1 empty lines |
|
.\" for manpage-specific macros, see man(7) |
|
.SH NAME |
|
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images |
|
with Rock Ridge extensions. |
|
.SH SYNOPSIS |
|
.B xorriso |
|
.RI [ settings | actions ] |
|
.br |
|
.SH DESCRIPTION |
|
.PP |
|
.B xorriso |
|
is a program which maps file objects from POSIX compliant |
|
filesystems into Rock Ridge enhanced ISO 9660 filesystems and allows |
|
session-wise manipulation of such filesystems. It can load the management |
|
information of existing ISO images and it writes the session results to |
|
optical media or to filesystem objects. |
|
.PP |
|
A special property of xorriso is that it needs neither an external ISO 9660 |
|
formatter program nor an external burn program for CD or DVD but rather |
|
incorporates the libraries of libburnia-project.org . |
|
.SS |
|
.B Overview of features: |
|
.br |
|
Operates on an existing ISO image or creates a new one. |
|
.br |
|
Copies files from filesystem into the ISO image. |
|
.br |
|
Renames or deletes file objects in the ISO image. |
|
.br |
|
Changes file properties in the ISO image. |
|
.br |
|
Can write result as completely new image to optical media or |
|
filesystem objects. |
|
.br |
|
Can write result as add-on session to appendable multi-session media, |
|
to overwriteable media, to regular files, and to block devices. |
|
.br |
|
Scans for optical drives, blanks re-useable optical media. |
|
.br |
|
Reads its instructions from command line arguments, dialog, and batch files. |
|
.br |
|
Provides navigation commands for interactive ISO image manipulation. |
|
.br |
|
Adjustable thresholds for abort, exit value, and problem reporting. |
|
.SS |
|
.B General information paragraphs: |
|
.br |
|
Session model |
|
.br |
|
Media types and states |
|
.br |
|
Creating, Growing, Modifying |
|
.br |
|
Libburn drives |
|
.br |
|
Rock Ridge, POSIX, X/Open |
|
.br |
|
Command processing |
|
.br |
|
Dialog, Readline, Result pager |
|
.sp 1 |
|
Maybe you first want to have a look at section EXAMPLES near the end of |
|
this text before reading the next few hundred lines of background information. |
|
.SS |
|
.B Session model: |
|
.br |
|
Unlike other filesystems, ISO 9660 is not intended for read-write operation but |
|
rather for being generated in a single sweep and being written to media as a |
|
.B session. |
|
.br |
|
The data content of the session is called filesystem |
|
.B image. |
|
.PP |
|
The written image in its session can then be mounted by the operating system |
|
for being used read-only. 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. |
|
.PP |
|
This session usage model has been extended on CD media by the concept of |
|
.B multi-session , |
|
which allows to add information to the CD and gives the mount programs |
|
of the operating systems the addresses of the entry points of each |
|
session. The mount programs recognize block devices which represent |
|
CD media and will by default mount the image in the last session. |
|
.br |
|
This session usually contains an updated directory tree for the whole media |
|
which governs the data contents in all recorded sessions. |
|
So in the view of the mount program all sessions of a particular media |
|
together form a single filesystem image. |
|
.br |
|
Adding a session to an existing ISO image is in this text referred as |
|
\fBgrowing\fR. |
|
.br |
|
The multi-session model of the MMC standard does not apply to all media |
|
types. But program growisofs by Andy Polyakov showed how to extend this |
|
functionality to overwriteable media or disk files which carry valid ISO 9660 |
|
filesystems. This expansion method is referred as emulated growing. |
|
.PP |
|
xorriso provides both ways of growing as well as an own method named |
|
\fBmodifying\fR which produces a completely new ISO image from the old |
|
one and the modifications. See paragraph Creating, Growing, Modifying below. |
|
.PP |
|
xorriso adopts the concept of multi-session by loading an eventual image |
|
directory tree, allowing to manipulate it by several actions, and to write |
|
the new image to the target media. |
|
.br |
|
The first session of a xorriso run begins by the definition of the input |
|
drive with the eventual ISO image or by the definition of an output drive. |
|
The session ends by command -commit which triggers writing. A -commit is |
|
done automatically when the program ends regularly. |
|
.PP |
|
After -commit a new session begins with the freshly written one as input. |
|
A new input drive can only be chosen as long as the loaded ISO image was |
|
not altered. Pending alteration can be revoked by command -rollback. |
|
.PP |
|
Writing a session to the target is supposed to be very expensive in terms of |
|
time and of consumed space on appendable or write-once media. Therefore all |
|
intended manipulations of a particular ISO image should be done in a single |
|
session. |
|
.br |
|
In some special situations (e.g. in a file-to-file situation) it can be |
|
useful to store intermediate states and to continue with image manipulations. |
|
.SS |
|
.B Media types and states: |
|
There are two families of media in the MMC standard: |
|
.br |
|
\fBMulti-session\fR media are CD-R, CD-RW, DVD-R, DVD+R, and |
|
unformatted DVD-RW. These media provide a table of content which |
|
describes their existing sessions. |
|
.br |
|
\fBOverwriteable\fR media are DVD-RAM, DVD+RW, and formatted DVD-RW. |
|
They allow random write access but do not provide information about their |
|
session history. |
|
.br |
|
DVD-RW media can be formatted by -format full. |
|
They can be made unformatted by -blank deformat. |
|
.br |
|
Emulated drives are handled as overwriteable media if they are random |
|
read-write accessible. If they are only sequentially writeable then |
|
they are handled as blank multi-session media. |
|
.PP |
|
These media can assume several states in which they offer different |
|
capabilities. |
|
.br |
|
\fBBlank\fR media can be written from scratch. They contain no ISO image |
|
suitable for xorriso. |
|
.br |
|
Blank is the state of newly purchased optical media. |
|
With used CD-RW and DVD-RW it can be achieved by action -blank fast. |
|
Overwriteable media are considered blank unless they contain an ISO image |
|
suitable for xorriso. |
|
.br |
|
\fBAppendable\fR media accept further sessions. Either they are MMC |
|
multi-session media in appendable state, or they are overwriteable media |
|
which contain an ISO image suitable for xorriso. |
|
.br |
|
Appendable is the state after writing a session with option -close off. |
|
.br |
|
\fBClosed\fR media cannot be written. They may contain an ISO image suitable |
|
for xorriso. |
|
.br |
|
Closed is the state of DVD-ROM media and of multi-session media which were |
|
written with option -close on. If the drive is incapable of writing it will |
|
probably show any media as closed CD-ROM resp. DVD-ROM. |
|
.br |
|
Overwriteable media assume this state only in such read-only drives. |
|
.SS |
|
.B Creating, Growing, Modifying: |
|
.br |
|
A new empty ISO image gets \fBcreated\fR |
|
if there is no input drive with a valid |
|
ISO 9660 image plus Rock Ridge extensions when the first time an output drive |
|
is defined. This is achieved by option -dev on blank media or by option -outdev |
|
on media in any state. |
|
.br |
|
The new empty image can be populated with directories and files. |
|
Before it can be written, the media in the output drive must get into |
|
blank state if it was not blank already. |
|
.PP |
|
If there is a input drive with a valid ISO image, then this image gets loaded |
|
as foundation for manipulations and extension. The constellation of input |
|
and output drive determines which of two write methods will be used. |
|
They have quite different capabilities and constraints. |
|
.PP |
|
The method of \fBgrowing\fR adds new data to the existing media. These |
|
data comprise of eventual new file content and they override the existing |
|
ISO 9660 + Rock Ridge directory tree. It is possible to hide files from |
|
previous sessions but they still exist on media and with many types of |
|
optical media it is quite easy to recover them by mounting older sessions. |
|
.br |
|
Growing is achieved by option -dev. |
|
.PP |
|
The write method of \fBmodifying\fR produces compact filesystem |
|
images with no outdated files or directory trees. Modifying can write its |
|
images to target media which are completely unsuitable for multi-session |
|
operations. E.g. fast blanked DVD-RW, named pipes, character devices, sockets. |
|
On the other hand modified sessions cannot be written to appendable media |
|
but to blank media only. |
|
.br |
|
Modifying takes place whenever input drive and output drive are not the same. |
|
This is achieved by options -indev and -outdev. |
|
.br |
|
So for this method one needs either two optical drives or has to work with |
|
filesystem objects as source and/or target media. |
|
.SS |
|
.B Libburn drives: |
|
.br |
|
Input drive, i.e. source of an existing or empty ISO image, can be any random |
|
access readable libburn drive: optical media with readable data, |
|
blank optical media, regular files, block devices. |
|
.br |
|
Rock Ridge info must be present in existing ISO images and it will be generated |
|
by the program unconditionally. |
|
.PP |
|
Output drive, i.e. target for writing, can be any libburn drive. |
|
Some drive types do not support the method of growing but only the method |
|
of modifying. They all are suitable for newly created images. |
|
.br |
|
All drive file objects have to offer rw-permission to the user of xorriso. |
|
Even those which will not be useable for reading an ISO image. |
|
.PP |
|
MMC compliant (i.e. optical) drives on Linux usually get addressed by |
|
the path of their block device or of their generic character device. E.g. |
|
.br |
|
-dev /dev/sr0 |
|
.br |
|
-dev /dev/hdc |
|
.br |
|
-dev /dev/sg2 |
|
.br |
|
Get a list of accessible drives by command |
|
.br |
|
-devices |
|
.br |
|
It might be necessary to do this as |
|
.B 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". |
|
.PP |
|
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and |
|
their path in the filesystem. E.g.: |
|
.br |
|
-dev stdio:/tmp/pseudo_drive |
|
.br |
|
If path leads to a regular file or to a block device then the emulated drive |
|
is random access readable and can be used for the method of growing if it |
|
already contains a valid ISO 9660 image. Any other file type is not readable |
|
via "stdio:" and can only be used as target for the method of modifying. |
|
Non existing paths in existing directories are handled as empty regular files. |
|
.PP |
|
A very special kind of pseudo drive are open file descriptors. They are |
|
depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open). |
|
.br |
|
Addresses "-" or "stdio:/dev/fd/1" depict standard output, which normally is |
|
the output channel for result texts. |
|
To prevent a fatal intermingling of ISO image and text messages, all result |
|
texts get redirected to stderr if -*dev "-" or "stdio:/dev/fd/1" is among |
|
the start arguments of the program. |
|
.br |
|
Standard output is currently suitable for creating a single new session |
|
per program run without dialog. Use in other situations is discouraged |
|
and several restrictions apply: |
|
.br |
|
It is not allowed to use standard output as pseudo drive if it was not |
|
among the start arguments. Do not try to fool this ban via backdoor addresses |
|
to stdout. |
|
.br |
|
If stdout is used as drive, then -use_readline is permanently disabled. |
|
Use of backdoors will cause severe memory and/or terminal corruption. |
|
.PP |
|
Be aware that especially the superuser can write into any accessible file or |
|
device by using its path with the "stdio:" prefix. Addresses without prefix |
|
"stdio:" will only work if they lead to a MMC drive. |
|
.br |
|
One may use option |
|
.B -ban_stdio_write |
|
to surely prevent this risk and to allow only MMC drives. |
|
.SS |
|
.B Rock Ridge, POSIX, X/Open: |
|
.br |
|
.B Rock Ridge |
|
is the name of a set of additional informations which enhance |
|
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem |
|
with ownership, access permissions, symbolic links, and other attributes. |
|
.PP |
|
This is what xorriso uses for a decent representation of the disk files |
|
within the ISO image. Rock Ridge information is produced with any xorriso |
|
image and xorriso will load for manipulation only Rock Ridge enhanced images. |
|
.PP |
|
xorriso is not named "porriso" because POSIX only guarantees 14 characters |
|
of filename length. It is the X/Open System Interface standard XSI which |
|
demands a file name length of up to 255 characters and paths of up to 1024 |
|
characters. Rock Ridge fulfills this demand. |
|
.SS |
|
.B Command processing: |
|
.br |
|
Commands are either actions or settings. They consist of a command word, |
|
followed by zero or more parameter words. If the list of parameter words |
|
is of variable length (indicated by "[...]" or "[***]") then it has to be |
|
terminated by either the word "--" or the end of argument list or an end of |
|
an input line. |
|
It is not an error if "--" appears after the parameters of a command |
|
with a fixed list length. |
|
.PP |
|
.B Pattern expansion |
|
is a property of some particular commands and not a general |
|
feature. It gets controlled by commands -iso_rr_pattern and -disk_pattern. |
|
Commands which eventually use pattern expansion all have variable argument |
|
lists which are marked in this man page by "[***]" rather than "[...]". |
|
.br |
|
Some other commands perform pattern matching unconditionally. |
|
.PP |
|
Command and parameter words are either read from program arguments, where one |
|
argument is one word, or from input lines where words are recognized similar |
|
to the quotation rules of a shell parser. |
|
.br |
|
xorriso is not a shell, although it might appear so on first glimpse. |
|
Be aware that the interaction of quotation marks and pattern symbols like "*" |
|
differs from the usual shell parsers. In xorriso, a quotation mark does not |
|
make a pattern symbol literal. |
|
.PP |
|
When the program begins then it first looks for argument -no_rc. If this is |
|
not present then it looks for its startup files and |
|
eventually reads their content as command input lines. Then it interprets |
|
the program arguments as commands and parameters and finally it enters |
|
dialog mode if command -dialog "on" was executed up to then. |
|
.PP |
|
The program ends either by command -end, or by the end of program arguments |
|
if not dialog was enabled up to that moment, or by a problem |
|
event which triggers the threshold of command -abort_on. |
|
.SS |
|
.B Dialog, Readline, Result pager: |
|
.br |
|
Dialog mode prompts for an input line, parses it into words, and performs |
|
them as commands with their parameters. It provides assisting services |
|
to make dialog more comfortable. |
|
.PP |
|
Readline is an enhancement for the input line. You may know it already from |
|
the bash shell. Whether it is available in xorriso depends on the availability |
|
of package readline-dev at the time when xorriso was built from its sourcecode. |
|
.br |
|
It allows to move the cursor over the text in the line by help of the |
|
Leftward and the Rightward arrow key. |
|
Text may be inserted at the cursor position. The Delete key removes the |
|
character under the cursor. Upward and Downward arrow keys navigate through |
|
the history of previous input lines. |
|
.br |
|
See man readline for more info about libreadline. |
|
.PP |
|
Option -page activates a builtin result text pager which may be convenient in |
|
dialog. After an action has put out the given number of terminal lines, |
|
the pager prompts the user for a line of input. |
|
.br |
|
An empty line lets xorriso resume work until the next page is put out. |
|
.br |
|
The single character "@" disables paging for the current action. |
|
.br |
|
"@@@", "x", "q", "X", or "Q" urge the current action to abort and suppress |
|
further result output. |
|
.br |
|
Any other line will be interpreted as new dialog line. The current action |
|
is urged to abort. Afterwards, the input line is executed. |
|
.PP |
|
Some actions apply paging to their info output, too. |
|
.br |
|
The urge to abort may or may not be obeyed by the current action. All actions |
|
try to abort as soon as possible. |
|
.br |
|
.SH OPTIONS |
|
.br |
|
All command words are shown with a leading dash although this dash is not |
|
mandatory for the option to be recognized. There may be future emulation |
|
modes, where dashes may become mandatory in order to distinguish options |
|
from file addresses. |
|
.TP |
|
.B Aquiring source and target drive: |
|
.TP |
|
\fB\-dev\fR address |
|
Set input and output drive to the same address and load an eventual ISO image. |
|
If there is no ISO image then create a blank one. |
|
Set the image expansion method to growing. |
|
.br |
|
This is only allowed as long as no changes are pending in the currently |
|
loaded ISO image. Eventually one has to perform -commit or -rollback first. |
|
Violation yields a FAILURE event. |
|
.br |
|
Special address string "-" means standard output, to which several restrictions |
|
apply. See above paragraph "Libburn drives". |
|
.br |
|
An empty address string "" gives up the current device |
|
without aquiring a new one. |
|
.TP |
|
\fB\-indev\fR address |
|
Set input drive and load eventual ISO image. If the new input drive differs |
|
from -outdev then switch from growing to modifying. The same rules and |
|
restrictions apply as with -dev. |
|
.TP |
|
\fB\-outdev\fR address |
|
Set output drive and if it differs from the input drive then switch from |
|
growing to modifying. Unlike -dev and -indev this action does not load a |
|
new ISO image. So it can be performed even if there are pending changes. |
|
.br |
|
-outdev can be performed without previous -dev or -indev. In that case an |
|
empty ISO image with no changes pending is created. It can either be populated |
|
by help of -add or it can be discarded silently if -dev or -indev are |
|
performed afterwards. |
|
.br |
|
Special address string "-" means standard output, to which several restrictions |
|
apply. See above paragraph "Libburn drives". |
|
.br |
|
An empty address string "" gives up the current output drive |
|
without aquiring a new one. No writing is possible without an output drive. |
|
.TP |
|
\fB\-ban_stdio_write\fR |
|
Allow for writing only the usage of MMC optical drives. Disallow |
|
to write the result into files of nearly arbitrary type. |
|
Once set, this command cannot be revoked. |
|
.TP |
|
.B Data manipulations: |
|
.PP |
|
The following commands expect file addresses of two kinds: |
|
.br |
|
.B disk_path |
|
is a path to an object in the local filesystem tree. |
|
.br |
|
.B iso_rr_path |
|
is the Rock Ridge name of a file object in the ISO image. (Do not |
|
confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.) |
|
.PP |
|
Note that in the ISO image you are as powerful as the superuser. Access |
|
permissions of the existing files in the image do not apply to your write |
|
operations. They are intended to be in effect with the read-only mounted image. |
|
.PP |
|
If the iso_rr_path of a newly inserted file leads to an existing |
|
file object in the ISO image, then the following collision handling |
|
happens: |
|
.br |
|
If both objects are directories then they get merged by recursively inserting |
|
the subobjects from filesystem into ISO image. |
|
If other file types collide then the setting of command |
|
.B \-overwrite |
|
decides. |
|
.br |
|
Renaming of files has similar collision handling, but directories can only |
|
be replaced, not merged. Directories can hardly collide on renaming because |
|
of the shell-like behavior of -mv: if a file object hits an existing directory |
|
then it gets inserted rather than trying to replace that directory. |
|
Nevertheless, the overwriting rules apply if an operation of xorriso |
|
ever attempts to do such a replacement. |
|
.PP |
|
The commands in this section alter the ISO image and not the local filesystem. |
|
.TP |
|
\fB\-iso_rr_pattern\fR "on"|"ls"|"off" |
|
Set the pattern expansion mode for the iso_rr_path arguments of several |
|
commands which support this feature. |
|
.br |
|
.B Pattern expansion |
|
converts a list of pattern words into a list of existing file addresses. |
|
Eventual unmatched pattern words appear themselves in that result list, though. |
|
.br |
|
Pattern matching supports the usual shell parser wildcards '*' '?' '[xyz]' |
|
and respects '/' as separator which may only be matched literally. |
|
.br |
|
Setting "off" disables this feature for all commands which are marked in this |
|
man page by "iso_rr_path [***]" or "iso_rr_pattern [***]". |
|
.br |
|
Setting "on" enables it for all those commands. |
|
.br |
|
Setting "ls" enables it only for those which are marked by |
|
"iso_rr_pattern [***]". |
|
.br |
|
Default is "on". |
|
.TP |
|
\fB\-disk_pattern\fR "on"|"ls"|"off" |
|
Set the pattern expansion mode for the disk_path arguments of several |
|
commands which support this feature. |
|
.br |
|
Setting "off" disables this feature for all commands which are marked in this |
|
man page by "disk_path [***]" or "disk_pattern [***]". |
|
.br |
|
Setting "on" enables it for all those commands. |
|
.br |
|
Setting "ls" enables it only for those which are marked by |
|
"disk_pattern [***]". |
|
.br |
|
Default is "ls". |
|
.TP |
|
\fB\-add\fR pathspec [...] | disk_path [***] |
|
Insert the given files or directory trees from filesystem |
|
into the ISO image. |
|
.br |
|
If -pathspecs is set to "on" then pattern expansion is always disabled and |
|
character '=' has a special meaning. It eventually separates the ISO image path |
|
from the disk path: |
|
.br |
|
iso_rr_path=disk_path |
|
.br |
|
The separator '=' can be escaped by '\\'. |
|
If iso_rr_path does not begin with '/' then -cd is prepended. |
|
If disk_path does not begin with '/' then -cdx is prepended. |
|
.br |
|
If no '=' is given then the word is used as both, iso_rr_path and disk path. |
|
If in this case the word does not begin with '/' then -cdx is prepended to |
|
the disk_path and -cd is prepended to the iso_rr_path. |
|
.br |
|
If -pathspecs is set to "off" then eventual -disk_pattern expansion applies. |
|
The resulting words are used as both, iso_rr_path and disk path. Eventually |
|
-cdx gets prepended to disk_path and -cd to iso_rr_path. |
|
.TP |
|
\fB\-add_plainly\fR mode |
|
If set to mode "unknown" then any command word that does not begin with "-" and |
|
is not recognized as known command will be subject to a virtual -add command. |
|
I.e. it will be used as pathspec or as disk_path and added to the image. |
|
Eventually -disk_pattern expansion applies to disk_paths. |
|
.br |
|
Mode "dashed" is similar to "unknown" but also adds unrecognized command |
|
words even if they begin with "-". |
|
.br |
|
Mode "any" announces that all further words are to be added as pathspecs |
|
or disk_paths. This does not work in dialog mode. |
|
.br |
|
Mode "none" is the default. It prevents any words from being understood |
|
as files to add, if they are not parameters to appropriate commands. |
|
.TP |
|
\fB\-path_list\fR disk_path |
|
Like -add but read the parameter words from file disk_path. |
|
One pathspec resp. disk_path pattern per line. |
|
.TP |
|
\fB\-cpr\fR disk_path [***] iso_rr_path |
|
Insert the given files or directory trees from filesystem |
|
into the ISO image. |
|
.br |
|
The rules for generating the ISO addresses are similar as with |
|
shell command cp -r. Nevertheless, directories of the iso_rr_path |
|
are created if necessary. Especially a not yet existing iso_rr_path |
|
will be handled as directory if multiple disk_paths are present. |
|
The leafnames of the multiple disk_paths will be grafted under that |
|
directory as would be done with an existing directory. |
|
.br |
|
If a single disk_path is present then a non-existing iso_rr_path will |
|
get the same type as the disk_path. |
|
.br |
|
If a disk_path does not begin with '/' then -cdx is prepended. |
|
If the iso_rr_path does not begin with '/' then -cd is prepended. |
|
.TP |
|
\fB\-rm\fR iso_rr_path [***] |
|
Delete the given files from the ISO image. |
|
.br |
|
Note: This does not free any space on the -indev media, even if |
|
the deletion is committed to that same media. |
|
.br |
|
The image size will shrink if the image is written to a different |
|
media in modification mode. |
|
.TP |
|
\fB\-rm_r\fR iso_rr_path [***] |
|
Delete the given files or directory trees from the ISO image. |
|
See also the note with option -rm. |
|
.TP |
|
\fB\-mv\fR iso_rr_path [***] iso_rr_path |
|
Rename the given file objects in the ISO tree to the last |
|
argument in the list. Use the same rules as with shell command mv. |
|
.br |
|
If pattern expansion is enabled and if the last argument contains wildcard |
|
characters then it must match exactly one existing file address, or else the |
|
command fails with a FAILURE event. |
|
.TP |
|
\fB\-chown\fR uid iso_rr_path [***] |
|
Set ownership of file objects in the ISO image. uid may either be a decimal |
|
number or the name of a user known to the operating system. |
|
.TP |
|
\fB\-chown_r\fR uid iso_rr_path [***] |
|
Like -chown but affecting all files below eventual directories. |
|
.TP |
|
\fB\-chgrp\fR gid iso_rr_path [***] |
|
Set group attribute of file objects in the ISO image. gid may either be a |
|
decimal number or the name of a group known to the operating system. |
|
.TP |
|
\fB\-chgrp_r\fR gid iso_rr_path [***] |
|
Like -chgrp but affecting all files below eventual directories. |
|
.TP |
|
\fB\-chmod\fR mode iso_rr_path [***] |
|
Equivalent to shell command chmod in the ISO image. |
|
mode is either an octal number beginning with "0" or a comma separated |
|
list of statements of the form [ugoa]*[+-=][rwxst]* . |
|
.br |
|
Like: go-rwx,u+rwx . |
|
.br |
|
.B Personalities: |
|
u=user, g=group, o=others, a=all |
|
.br |
|
.B Operators: |
|
+ adds given permissions, - revokes given permissions, |
|
= revokes all old permissions and then adds the given ones. |
|
.br |
|
.B Permissions: |
|
r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit |
|
.br |
|
For octal numbers see man 2 stat. |
|
.TP |
|
\fB\-chmod_r\fR mode iso_rr_path [***] |
|
Like -chmod but affecting all files below eventual directories. |
|
.TP |
|
\fB\-alter_date\fR type timestring iso_rr_path [***] |
|
Alter the date entries of a file in the ISO image. type is |
|
one of "a", "m", "b" for access time, modification time, |
|
both times. |
|
.br |
|
timestring may be in the following formats |
|
(see also section EXAMPLES): |
|
.br |
|
As expected by program date: |
|
MMDDhhmm[[CC]YY][.ss]] |
|
.br |
|
As produced by program date: |
|
[Day] MMM DD hh:mm:ss [TZON] YYYY |
|
.br |
|
Relative times counted from current clock time: |
|
+|-Number["s"|"h"|"d"|"w"|"m"|"y"] |
|
.br |
|
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d, |
|
"y"=365.25d plus 1d added to multiplication result. |
|
.br |
|
Absolute seconds counted from Jan 1 1970: |
|
=Number |
|
.br |
|
xorriso's own timestamps: |
|
YYYY.MM.DD[.hh[mm[ss]]] |
|
.br |
|
scdbackup timestamps: |
|
YYMMDD[.hhmm[ss]] |
|
.br |
|
where "A0" is year 2000, "B0" is 2010, etc. |
|
.TP |
|
\fB\-alter_date_r\fR type timestring iso_rr_path [***] |
|
Like -alter_date but affecting all files below eventual directories. |
|
.TP |
|
\fB\-find\fR iso_rr_path [-name pattern] [-type t] [-exec action [params]] -- |
|
A very restricted substitute for shell command find in the ISO image. |
|
It performs an action on matching file objects at or below iso_rr_path. |
|
.br |
|
Optional -name pattern is not expanded but used for comparison with |
|
the particular file names of the eventual directory tree underneath |
|
iso_rr_path. If no -name pattern is given, then any file name matches. |
|
.br |
|
The optional -type test restricts matching to files of the given type: |
|
"block", "char", "dir", "pipe", "file", "link", "socket", "Xotic", |
|
where "X" eventually matches what is not matched by the other types. |
|
.br |
|
Only the first letter is interpreted. E.g.: -find / -type d |
|
.br |
|
If a file matches then the action is performed. 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. |
|
.br |
|
"chown" and "chown_r" change the ownership and get the user id as param. E.g.: |
|
.br |
|
-find / -exec chown thomas |
|
.br |
|
"chgrp" and "chgrp_r" change the group attribute and get the group id as param. |
|
E.g.: |
|
.br |
|
-find / name 'news*' -type d -exec chgrp_r staff |
|
.br |
|
"chmod" and "chmod_r" change access permissions and get a mode string as param. |
|
E.g.: |
|
.br |
|
-find / -exec chmod a-w,a+r |
|
.br |
|
"alter_date" and "alter_date_r" change the timestamps. |
|
They get a type character and a timestring as params. |
|
E.g.: |
|
.br |
|
-find / -exec alter_date "m" "Dec 30 19:34:12 2007" |
|
.br |
|
"lsdl" prints file information like shell command ls -dl. |
|
E.g.: |
|
.br |
|
-find / -exec lsdl |
|
.br |
|
"find" performs another run of -find on the matching file address. It accepts |
|
the same params as -find, except iso_rr_path. |
|
E.g.: |
|
.br |
|
-find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r |
|
.br |
|
If not used as last command in the line then the argument list |
|
needs to get terminated by "--". |
|
.TP |
|
\fB\-mkdir\fR iso_rr_path [...] |
|
Create empty directories if they do not exist yet. |
|
Existence as directory generates a WARNING event, existence as |
|
other file causes a FAILURE event. |
|
.TP |
|
\fB\-rmdir\fR iso_rr_path [***] |
|
Delete empty directories. |
|
.TP |
|
\fB\-\-\fR |
|
.br |
|
Mark end of particular action argument list. |
|
.TP |
|
\fB\-rollback\fR |
|
Discard the manipulated ISO image and reload it from -indev. |
|
.TP |
|
\fB\-rollback_end\fR |
|
Discard the manipulated ISO image. End program without loading a new image. |
|
.TP |
|
.B Writing the result: |
|
(see also paragraph about settings below) |
|
.TP |
|
\fB\-commit\fR |
|
Perform the write operation. Afterwards eventually make the |
|
-outdev the new -dev and load the image from there. |
|
Switch from eventual modifiying mode to growing mode. |
|
(A subsequent -outdev will activate modification mode.) |
|
-commit is performed automatically at end of program if there |
|
are uncommitted manipulations pending. |
|
So, to perform a final write operation with no new -dev |
|
and no new loading of image, rather execute option -end. |
|
To suppress a final write, execute -rollback -end. |
|
To eject outdev after write without new loading of image, use -commit_eject. |
|
.br |
|
|
|
Writing can last quite a while. It is not unnormal with several |
|
types of media that there is no progress visible for the first |
|
few minutes or that the drive gnaws on the media for a few |
|
minutes after all data have been transmitted. |
|
xorriso and the drives are in a client-server relationship. |
|
The drives have much freedom about what to do with the media. |
|
Some combinations of drives and media simply do not work, |
|
despite the promises by their vendors. |
|
If writing fails - or even the drive gets stuck and you need |
|
to reboot - then try other media or another drive. The reason |
|
for such failure is hardly ever in the code of the various |
|
burn programs but you may well try some of those listed below |
|
under SEE ALSO. |
|
.TP |
|
\fB\-eject\fR "in"|"out"|"all" |
|
Eject the media in -indev, resp. -outdev, resp. both drives. |
|
Note: It is not possible yet to effectively eject disk files. |
|
.TP |
|
\fB\-commit_eject\fR "in"|"out"|"all"|"none" |
|
Combined -commit and -eject. When writing has finished do not make |
|
-outdev the new -dev, and load no ISO image. Rather eject |
|
-indev and/or -outdev. Eventually give up any non-ejected drive. |
|
.TP |
|
\fB\-blank\fR mode |
|
Blank media resp. invalidate ISO image on media if not -dummy |
|
is activated. |
|
.br |
|
This affects only the -outdev not the -indev. |
|
If both drives are the same and if the ISO image was altered |
|
then this command leads to a FAILURE event. |
|
Defined modes are: |
|
fast, all, deformat, deformat_quickest |
|
.br |
|
"fast" and "all" make CD-RW and unformatted DVD-RW re-usable, |
|
or invalidate overwriteable ISO images. |
|
"deformat" converts overwriteable DVD-RW into unformatted ones. |
|
"deformat_quickest" is a faster way to deformat or blank DVD-RW |
|
but produces media which are only suitable for a single session. |
|
xorriso will write onto them only if option -close is set to "on". |
|
.br |
|
The progress reports issued by some drives while blanking are |
|
quite unrealistic. Do not conclude success or failure from the |
|
reported percentages. Blanking was successful if no SORRY event or |
|
worse occured. |
|
.TP |
|
\fB\-format\fR mode |
|
Convert unformatted DVD-RW into overwriteable ones, |
|
"de-ice" DVD+RW. |
|
For now, mode should be the word "full". |
|
.br |
|
This action has no effect on media if -dummy is activated. |
|
.br |
|
Be warned that re-formatting DVD+RW is considered to be risky |
|
to the media's health. DVD+RW get formatted as far as needed |
|
during writing, but an entirely formatted media might be better |
|
readable in some DVD players. |
|
.br |
|
On the other hand unreliable DVD+RW can sometimes be repaired by |
|
re-formatting. |
|
.br |
|
|
|
The progress reports issued by some drives while formatting are |
|
quite unrealistic. Do not conclude success or failure from the |
|
reported percentages. Formatting was successful if no SORRY event |
|
or worse occured. |
|
.TP |
|
.B Settings for data insertion: |
|
.TP |
|
\fB\-follow\fR occasion[:occasion[...]] |
|
Enable or disable resolution of symbolic links and mountpoints under |
|
disk_paths. This applies to actions -add, -du*x, -ls*x, -findx, |
|
and to -disk_pattern expansion. |
|
.br |
|
There are two kinds of follow decisison to be made: |
|
.br |
|
"link" is the hop from a symbolic link to its target file object. |
|
If enabled then symbolic links are handled as their target file objects, |
|
else symbolic links are handled as themselves. |
|
.br |
|
"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. |
|
.br |
|
Less general than above occasions: |
|
.br |
|
"pattern" is mount and link hopping, but only during -disk_pattern expansion. |
|
.br |
|
"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). |
|
.br |
|
Occasions can be combined in a colon separated list. All occasions |
|
mentioned in the list will then lead to a positive follow decision. |
|
.br |
|
"off" prevents any positive follow decision. Use it if no other occasion |
|
applies. |
|
.br |
|
Shortcuts: |
|
.br |
|
"default" is equivalent to "pattern:mount:limit=100". |
|
.br |
|
"on" always decides positive. Equivalent to "link:mount". |
|
.br |
|
|
|
Not an occasion but an optional setting is: |
|
.br |
|
"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: |
|
.br |
|
\fB$\fR ln -s .. uploop |
|
.br |
|
Link hopping has a builtin loop detection which stops hopping at the first |
|
repetition of a link target. Then the repeated link is handled as itself |
|
and not as its target. |
|
Regrettably one can construct link networks which |
|
cause exponential workload before their loops get detected. |
|
The number given with "limit=" can curb this workload at the risk of truncating |
|
an intentional sequence of link hops. |
|
.TP |
|
\fB\-pathspecs\fR "on"|"off" |
|
Control parameter interpretation with xorriso actions -add and -path_list. |
|
.br |
|
"on" enables pathspecs of the form |
|
.B target=source |
|
like with program mkisofs -graft-points. |
|
It also disables -disk_pattern expansion for command -add. |
|
.br |
|
"off" disables pathspecs of the form target=source |
|
and eventually enables -disk_pattern expansion. |
|
.TP |
|
\fB\-overwrite\fR "on"|"nondir"|"off" |
|
Allow or disallow to overwrite existing files in the |
|
ISO image by files with the same user defined name. |
|
.br |
|
With setting "off", name collisions cause FAILURE events. |
|
With setting "nondir", only directories are protected by such events, other |
|
existing file types get treated with -rm before the new file gets added. |
|
Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an |
|
existing directory and all its subordinates. |
|
.TP |
|
.B Settings for result writing: |
|
.TP |
|
Rock Ridge info will be generated by the program unconditionally. |
|
.TP |
|
\fB\-joliet\fR "on"|"off" |
|
If enabled by "on", generate Joliet info additional to Rock Ridge info. |
|
.TP |
|
\fB\-volid\fR text |
|
Specifies the volume ID. xorriso accepts any text up to 32 characters, |
|
but according to rarely obeyed specs stricter rules apply: |
|
.br |
|
ECMA 119 demands character set [A-Z0-9_]. Like: "IMAGE_23" |
|
.br |
|
Joliet allows 16 UCS-2 characters. Like: "Windows name" |
|
.br |
|
Be aware that the volume id might get used automatically as name of the |
|
mount point when the media is inserted into a playful computer system. |
|
.br |
|
If an ISO image gets loaded while the volume ID is set to default "ISOIMAGE" |
|
or to "", then the volume ID of the loaded image will become the effective |
|
volume id for the next write run. But as soon as command -volid is performed |
|
afterwards, this pending id is overridden by the new setting. |
|
.br |
|
Consider this when setting -volid "ISOIMAGE" before executing -dev, -indev, |
|
or -rollback. |
|
If you insist in -volid "ISOIMAGE", set it again after those commands. |
|
.TP |
|
\fB\-uid\fR uid |
|
User id to be used for all files when the new ISO tree gets written to media. |
|
.TP |
|
\fB\-gid\fR gid |
|
Group id to be used for all files when the new ISO tree gets written to media. |
|
.TP |
|
\fB\-speed\fR number[k|m|c|d] |
|
Set the burn speed. Default is 0 = maximum speed. |
|
Speed can be given in media dependent numbers or as a |
|
desired throughput per second in MMC compliant kB (= 1000) |
|
or MB (= 1000 kB). Media x-speed factor can be set explicity |
|
by "c" for CD and "d" for DVD. Example speeds: |
|
.br |
|
706k = 706kB/s = 4c = 4xCD |
|
.br |
|
5540k = 5540kB/s = 4d = 4xDVD |
|
.br |
|
If there is no hint about the speed unit attached, then the |
|
media in the -outdev will decide. Default unit is CD = 176.4k. |
|
.br |
|
MMC drives usually activate their own idea of speed and take |
|
the speed value given by the burn program only as upper limit |
|
for their own decision. |
|
.TP |
|
\fB\-dummy\fR "on"|"off" |
|
If "on" simulate burning or refuse with FAILURE event if |
|
no simulation is possible, do neither blank nor format. |
|
.TP |
|
\fB-fs\fR number["k"|"m"] |
|
Set the size of the fifo buffer which smoothens the data |
|
stream from ISO image generation to media burning. Default |
|
is 4 MiB, minimum 64 kiB, maximum 1 GiB. |
|
The number may be followed by letter "k" or "m" |
|
which means unit is kiB (= 1024) or MiB (= 1024 kiB). |
|
.TP |
|
\fB\-close\fR "on"|"off" |
|
If "on" then mark the written media as not appendable |
|
any more (if possible at all with the given type of target media). |
|
.br |
|
This is the contrary of cdrecord, wodim, cdrskin option -multi, |
|
and is one aspect of growisofs option -dvd-compat. |
|
.TP |
|
\fB\-padding\fR number["k"|"m"] |
|
Append the given number of extra bytes to the image stream. |
|
This is a traditional remedy for a traditional bug in block |
|
device read drivers. Needed only for CD recordings in TAO mode. |
|
Since one can hardly predict on what media an image might end up, |
|
xorriso adds the traditional 300k of padding by default to all images. |
|
.br |
|
For images which will never get to a CD it is safe to use -padding 0 . |
|
.TP |
|
\fB\-boot_image\fR "any"|"isolinux" "discard"|"keep"|"patch" |
|
Defines the handling of an eventual boot image (El-Torito) which has been read |
|
from an existing ISO image. All types ("any") can be discarded or kept |
|
unaltered. The latter makes only sense if the format of the boot image is |
|
relocatable without content changes. |
|
.br |
|
The boot image type "isolinux" can be kept unaltered (not advisable), or |
|
discarded, or it can be patched to match its relocation. In the latter case |
|
the resulting ISO image is bootable if the boot image was really complying |
|
to the isolinux standard. |
|
.br |
|
Creation of new boot images is not yet possible. |
|
.br |
|
CAUTION: |
|
This is an expert option. xorriso is not an expert yet. |
|
It cannot recognize the inner form of boot images. |
|
So the user has already to know about the particular needs of the |
|
bootimage which is present on the input media. |
|
Most safe is the default: "any" "discard". |
|
.TP |
|
.B Exception processing: |
|
.PP |
|
Since the tasks of xorriso are manifold and prone to external influence, there |
|
may arise the need for xorriso to report and handle problem events. |
|
.br |
|
Those events get classified when they are detected by one of the software |
|
modules and forwarded to reporting and evaluation modules which decide about |
|
reactions. Event classes are sorted by severity: |
|
.br |
|
"NEVER" The upper end of the severity spectrum. |
|
.br |
|
"ABORT" The program is being aborted and on its way to end. |
|
.br |
|
"FATAL" The main purpose of the run failed |
|
or an important resource failed unexpectedly. |
|
.br |
|
"FAILURE" An important part of the job could not be performed. |
|
.br |
|
"MISHAP" A FAILURE which can be tolerated during ISO image generation. |
|
.br |
|
"SORRY" A less important part of the job could not be performed. |
|
.br |
|
"WARNING" A situation is suspicious of being not intended by the user. |
|
.br |
|
"HINT" A proposal to the user how to achieve better results. |
|
.br |
|
"NOTE" A harmless information about noteworthy circumstances. |
|
.br |
|
"UPDATE" A pacifier message during long running operations. |
|
.br |
|
"DEBUG" A message which would only interest the program developers. |
|
.br |
|
"ALL" The lower end of the severity spectrum. |
|
.TP |
|
\fB\-abort_on\fR severity |
|
Set the severity threshold for events to abort the program. |
|
.br |
|
Useful: "NEVER", "ABORT", "FATAL", "FAILURE" , "MISHAP", "SORRY" |
|
.br |
|
It may become necessary to abort the program anyway, despite |
|
the setting by this option. Expect not many "ABORT" events to |
|
be ignorable. |
|
.br |
|
A special property of this option is that it works preemptive if given as |
|
program start argument. I.e. the first -abort_on setting among the |
|
start arguments is in effect already when the first operations of xorriso |
|
begin. Only "-abort_on" with dash "-" is recognized that way. |
|
.TP |
|
\fB\-return_with\fR severity exit_value |
|
Set the threshold and exit_value to be returned at program end if no abort |
|
has happened. This is to allow xorriso to go on after problems but to get |
|
a failure indicating exit value from the program, nevertheless. |
|
Useful is a value lower than the -abort_on threshold, down to "WARNING". |
|
.br |
|
exit_value may be either 0 (indicating success to the starter of the program) |
|
or a number between 32 and 63. Some other exit_values are used by xorriso if |
|
it decides to abort the program run: |
|
.br |
|
1=abort due to external signal |
|
.br |
|
2=no program arguments given |
|
.br |
|
3=creation of xorriso main object failed |
|
.br |
|
4=failure to start libburnia-project.org libraries |
|
.br |
|
5=program abort during argument processing |
|
.br |
|
6=program abort during dialog processing |
|
.TP |
|
\fB\-report_about\fR severity |
|
Set the threshold for events to be reported. |
|
.br |
|
Useful: "SORRY", "WARNING", "HINT", "NOTE", "UPDATE", "DEBUG", "ALL" |
|
.br |
|
Regardless what is set by -report_about, messages get always reported if they |
|
reach the severity threshold of -abort_on . |
|
.br |
|
Event messages are sent to the info channel "I" which is usually stderr |
|
but may be influenced by command -pkt_output. |
|
Info messages which belong to no event get attributed severity "NOTE". |
|
.br |
|
A special property of this option is that the first -report_about setting |
|
among the start arguments is in effect already when the first operations |
|
of xorriso begin. Only "-report_about" with dash "-" is recognized that way. |
|
.TP |
|
.B Dialog mode control: |
|
.TP |
|
\fB\-dialog\fR "on"|"off" |
|
Enable or disable to enter dialog mode after all arguments |
|
are processed. In dialog mode input lines get prompted via |
|
readline or from stdin. |
|
.TP |
|
\fB\-page\fR length width |
|
Describe terminal to the text pager. See also above, paragraph Result pager. |
|
.br |
|
If parameter length is nonzero then the user gets prompted after that |
|
number of terminal lines. Zero length disables paging. |
|
.br |
|
Parameter width is the number of characters per terminal line. It is used |
|
to compute the number of terminal lines which get occupied by an output line. |
|
A usual terminal width is 80. |
|
.TP |
|
\fB\-use_readline\fR "on"|"off" |
|
If "on" then use readline for dialog. Else use plain stdin. |
|
.br |
|
See also above, paragraph Dialog, Readline, Result pager. |
|
.TP |
|
\fB\-reassure\fR "on"|"tree"|"off" |
|
If "on" then ask the user for "y" or "n": |
|
.br |
|
before deleting or overwriting any file in the ISO image, |
|
.br |
|
before rolling back pending image changes, |
|
.br |
|
before committing image changes to media, |
|
.br |
|
before changing the input drive, |
|
.br |
|
before blanking or formatting media, |
|
.br |
|
before ending the program. |
|
.br |
|
With setting "tree" the reassuring prompt will appear for an eventual |
|
directory only once and not for each file in its whole subtree. |
|
.br |
|
Setting "off" silently kills any kind of image file object resp. performs |
|
above irrevocable actions. |
|
.br |
|
To really produce user prompts, option -dialog needs to be set to "on". |
|
Note that the prompt does not appear in situations where file removal |
|
is forbidden by option -overwrite. -reassure only imposes an additional |
|
curb for removing existing file objects. |
|
.br |
|
Be aware that file objects get deleted from the ISO image immediately |
|
after confirmation. They are gone even if the running command gets aborted |
|
and its desired effect gets revoked. In case of severe mess-up, consider to |
|
use -rollback to revoke the whole session. |
|
.TP |
|
.B Drive and media related inquiry actions: |
|
.TP |
|
\fB\-toc\fR |
|
.br |
|
Show media specific table of content. This is the media |
|
structure, not the ISO image directory tree. In case of |
|
overwriteable media holding a valid ISO image, a single |
|
session gets fabricated from the ISO image size info. |
|
.br |
|
A drive which is incapable of writing may show any media as CD-ROM or DVD-ROM |
|
with only one or two sessions on it. The last of these sessions is supposed |
|
to be the most recent real session then. |
|
.TP |
|
\fB\-devices\fR |
|
Show list of available MMC drives with the addresses of |
|
their libburn standard device files. |
|
.br |
|
This is only possible when no ISO image changes are pending. |
|
After this option was executed, there is no drive current |
|
and no image loaded. Eventually one has to aquire a drive again. |
|
.br |
|
In order to be visible, a device has to offer rw-permissions |
|
with its libburn standard device file. Thus it might be only the |
|
.B superuser |
|
who is able to see all drives. |
|
.br |
|
Drives which are occupied by other processes get not shown. |
|
.TP |
|
\fB\-print-size\fR |
|
Print the foreseeable consumption of 2048 byte blocks |
|
by next -commit. This can last a while as a -commit gets |
|
prepared and only in last moment is revoked by this option. |
|
.TP |
|
\fB\-tell_media_space\fR |
|
Print available space on output media and the free space after |
|
subtracting already foreseeable consumption by next -commit. |
|
.TP |
|
.B Navigation in ISO image and disk filesystem: |
|
.TP |
|
\fB\-cd\fR iso_rr_path |
|
Change the current working directory in the emerging ISO |
|
image as it is at the moment. This is prepended to iso_rr_paths |
|
which do not begin with '/'. |
|
.br |
|
It is possible to set the working directory to a path which does not exist |
|
yet in the ISO image. The necessary parent directories will be created when |
|
the first file object is inserted into that virtual directory. |
|
Use -mkdir if you want to enforce the existence of the directory already at |
|
first insertion. |
|
.TP |
|
\fB\-cdx\fR disk_path |
|
Change the current working directory on filesystem. |
|
To be prepended to disk_paths which do not begin with '/'. |
|
.TP |
|
\fB\-pwd\fR |
|
.br |
|
Tell the current working directory in the ISO image. |
|
.TP |
|
\fB\-pwdx\fR |
|
.br |
|
Tell the current working directory on local filesystem. |
|
.TP |
|
\fB\-ls\fR iso_rr_pattern [***] |
|
List files in the ISO image which match shell patterns |
|
(i.e. with wildcards '*' '?' '[a-z]'). |
|
If a pattern does not begin with '/' then it is compared with addresses |
|
relative to -cd, the current working directory in the ISO image. |
|
.br |
|
Directories are listed by their content rather than as single file item. |
|
.br |
|
Pattern expansion may be disabled by command -iso_rr_pattern. |
|
.TP |
|
\fB\-lsd\fR iso_rr_pattern [***] |
|
Like -ls but listing directories as themselves and not by their content. |
|
This resembles shell command ls -d. |
|
.TP |
|
\fB\-lsl\fR iso_rr_pattern [***] |
|
Like -ls but also list some of the file attributes. |
|
Output format resembles shell command ls -ln. |
|
.TP |
|
\fB\-lsdl\fR iso_rr_pattern [***] |
|
Like -lsd but also list some of the file attributes. |
|
Output format resembles shell command ls -dln. |
|
.TP |
|
\fB\-lsx\fR disk_pattern [***] |
|
List files on local filesystem which match shell patterns. Patterns which do |
|
not begin with '/' are used relative to -cdx, the current working directory in |
|
the local filesystem. |
|
.br |
|
Directories are listed by their content rather than as single file item. |
|
.br |
|
Pattern expansion may be disabled by command -disk_pattern. |
|
.TP |
|
\fB\-lsdx\fR disk_pattern [***] |
|
Like -lsx but listing directories as themselves and not by their content. |
|
This resembles shell command ls -d. |
|
.TP |
|
\fB\-lslx\fR disk_pattern [***] |
|
Like -lsx but also listing some of the file attributes. |
|
Output format resembles shell command ls -ln. |
|
.TP |
|
\fB\-lsdlx\fR disk_pattern [***] |
|
Like -lsdx but also listing some of the file attributes. |
|
Output format resembles shell command ls -dln. |
|
.TP |
|
\fB\-du\fR iso_rr_pattern [***] |
|
Recursively list size of directories and files in the ISO image |
|
which match one of the patterns. |
|
similar to shell command du -k. |
|
.TP |
|
\fB\-dus\fR iso_rr_pattern [***] |
|
List size of directories and files in the ISO image |
|
which match one of the patterns. |
|
Similar to shell command du -sk. |
|
.TP |
|
\fB\-dux\fR disk_pattern [***] |
|
Recursively list size of directories and files in the local filesystem |
|
which match one of the patterns, similar to shell command du -k. |
|
.TP |
|
\fB\-dusx\fR disk_pattern [***] |
|
List size of directories and files in the local filesystem |
|
which match one of the patterns. |
|
Similar to shell command du -sk. |
|
.TP |
|
\fB\-findx\fR disk_path [-name pattern] [-type t] -- |
|
Like -find but operating on local filesystem and not on the ISO image. |
|
This is subject to the settings of -follow. |
|
.br |
|
-findx accepts the -exec actions as does -find. But it will |
|
always perform action "echo". |
|
.TP |
|
.B Command compatibility emulations: |
|
.PP |
|
Writing of ISO 9660 on CD is traditionally done by program mkisofs |
|
as ISO 9660 image producer and cdrecord as burn program. |
|
xorriso does not strive for their comprehensive emulation. |
|
Nevertheless it is ready to perform some of its core tasks under control |
|
of commands which in said programs trigger comparable actions. |
|
The scope is for now only a single first data track to be written to blank or |
|
overwriteable media. If possible the media will get closed afterwards. |
|
Multi-session is yet only possible via xorriso's own commands. |
|
.TP |
|
\fB\-as\fR personality option [options] -- |
|
.br |
|
Performs its variable length option list as sparse emulation of the program |
|
depicted by the personality word. This is only allowed if no image changes |
|
are pending. The input drive is given up. |
|
.br |
|
|
|
Personality "\fBmkisofs\fR" accepts the options listed with: |
|
.br |
|
-as mkisofs -help -- |
|
.br |
|
Among them: -R (always on), -J, -graft-points, -o, -path-list, -print-size, -V, |
|
-v, -version, pathspecs as with xorriso -add. A lot of options are not |
|
supported and lead to failure of the mkisofs emulation. Some are ignored, |
|
but better do not rely on this tolerance. |
|
.br |
|
-graft-points is equivalent to -pathspecs on. Note that pathspecs without "=" |
|
are interpreted differently than with xorriso option -add. Directories get |
|
merged with the root directory of the ISO image, other filetypes get mapped |
|
into that root directory. |
|
.br |
|
Other than with the "cdrecord" personality there is no automatic -commit at |
|
the end of a "mkisofs" option list. Verbosity settings -v (= "UPDATE") and |
|
-quiet (= "SORRY") persist. The output file, eventually chosen with -o, |
|
persists until things happen like -commit, -rollback, -dev, or end of xorriso. |
|
.br |
|
If no output file was chosen before or during a "mkisofs" option list, then |
|
standard output (-outdev "-") will get into effect before pathspecs get |
|
added. If -o points to a regular file, then it will be truncated to 0 bytes |
|
when finally writing begins. This truncation does not happen if the drive |
|
is chosen by xorriso options before or after -as mkisofs. |
|
Directories and symbolic links are no valid -o targets. |
|
.br |
|
Writing to stdout is possible only if -as "mkisofs" was among the start |
|
arguments or if other start arguments pointed the output drive to |
|
standard output. |
|
.br |
|
Personalites "\fBgenisoimage\fR" and "\fBgenisofs\fR" |
|
are aliases for "mkisofs". |
|
.br |
|
|
|
Personality "\fBcdrecord\fR" accepts the options listed with: |
|
.br |
|
-as cdrecord -help -- |
|
.br |
|
Among them: -v, dev=, speed=, blank=, fs=, -eject, -atip, padsize=, |
|
track source file path or "-" for standard input as track source. |
|
.br |
|
It ignores most other options of cdrecord and cdrskin but refuses on |
|
-audio, -scanbus, -multi, -msinfo, --grow_overwriteable_iso, |
|
and on blanking modes unknown to xorriso. |
|
.br |
|
dev= must be given as xorriso device address. Adresses like 0,0,0 or ATA:1,1,0 |
|
are not supported. |
|
.br |
|
If a track source is given, then an automatic -commit happens at the end of |
|
the "cdrecord" option list. |
|
.br |
|
A much more elaborate libburn based cdrecord emulator is the program cdrskin. |
|
.br |
|
Personalites "\fBwodim\fR" and "\fBcdrskin\fR" are aliases for "cdrecord". |
|
.TP |
|
.B Scripting, dialog and program control features: |
|
.TP |
|
\fB\-no_rc\fR |
|
.br |
|
Only if used as first command line argument this option |
|
prevents reading and interpretation of eventual startup |
|
files. See section FILES below. |
|
.TP |
|
\fB\-options_from_file\fR fileaddress |
|
Reads lines from fileaddress and executes them as dialog lines. |
|
.TP |
|
\fB\-help\fR |
|
.br |
|
Print helptext. |
|
.TP |
|
\fB\-version\fR |
|
Print program name and version. |
|
.TP |
|
\fB\-history\fR textline |
|
Copy textline into libreadline history. |
|
.TP |
|
\fB\-status\fR [mode|filter] |
|
Print the current settings of xorriso. |
|
Modes: |
|
.br |
|
short... print only important or altered settings |
|
.br |
|
long ... print all settings including defaults |
|
.br |
|
long_history like long plus history lines |
|
.br |
|
Filters begin with '-' and are compared literally against the |
|
output lines of -status:long_history. A line is put out only |
|
if its start matches the filter text. No wildcards. |
|
.TP |
|
\fB\-status_history_max\fR number |
|
Set maximum number of history lines to be reported with -status "long_history". |
|
.TP |
|
\fB\-temp_mem_limit\fR number["k"|"m"] |
|
Set the maximum size of temporary memory to be used for image dependent |
|
buffering. Currently this applies to pattern expansion only. |
|
.br |
|
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB. |
|
.TP |
|
\fB\-print\fR text |
|
Print a text to result channel. |
|
.TP |
|
\fB\-prompt\fR text |
|
Show text at beginning of output line and |
|
wait for the user to hit the Enter key |
|
resp. to send a line via stdin. |
|
.TP |
|
\fB\-end\fR |
|
.br |
|
End program immediately |
|
.TP |
|
\fB#\fR any text |
|
In dialog or file execution mode only and only as first |
|
non-whitespace in line: |
|
Do not execute the line but eventually store it in history. |
|
.TP |
|
.B Support for frontend programs talking into stdin and listening at stdout: |
|
.TP |
|
\fB\-pkt_output\fR "on"|"off" |
|
Consolidate text output on stdout and classify each |
|
line by a channel indicator: |
|
.br |
|
'R:' for result lines, |
|
.br |
|
'I:' for notes and error messages, |
|
.br |
|
'M:' for -mark texts. |
|
.br |
|
Next is a decimal number of which only bit 0 has a meaning for now. |
|
0 means no newline at end of payload, 1 means that the newline character at |
|
the end of the output line belongs to the payload. After another colon follows |
|
the payload text. |
|
.br |
|
Example: |
|
.br |
|
I:1: enter option and arguments : |
|
.TP |
|
\fB\-logfile\fR channel fileaddress |
|
Copy output of a channel to the given file. |
|
.TP |
|
\fB\-mark\fR text |
|
If text is not empty it will get put out each time an |
|
action has been completed. |
|
.TP |
|
\fB\-prog\fR text |
|
Use text as this program's name in subsequent messages |
|
.TP |
|
\fB\-prog_help\fR text |
|
Use text as this program's name and perform -help. |
|
.br |
|
.SH EXAMPLES |
|
.SS |
|
.B As superuser learn about available drives |
|
Consider to give rw permissions to those users or groups |
|
which shall be able to use the drives with xorriso. |
|
.br |
|
\fB$\fR xorriso -devices |
|
.br |
|
0 -dev '/dev/sr0' rwrw-- : '_NEC ' 'DVD_RW ND-4570A' |
|
.br |
|
1 -dev '/dev/sr1' rwrw-- : 'HL-DT-ST' 'DVDRAM GSA-4082B' |
|
.br |
|
2 -dev '/dev/sr2' rwrw-- : 'PHILIPS ' 'SPD3300L' |
|
.SS |
|
.B Blank media and compose a new ISO image as batch run |
|
Aquire drive /dev/sr2, blank media resp. invalidate existing ISO image. |
|
Add the files from hard disk directories /home/me/sounds and /pictures. |
|
Omit some unwanted stuff by removing it from the image directory tree. |
|
Re-add some wanted stuff. |
|
.br |
|
Because no -dialog "on" is given, the program will then end by committing the |
|
session to media. |
|
.br |
|
\fB$\fR xorriso -outdev /dev/sr2 \\ |
|
.br |
|
-blank fast \\ |
|
.br |
|
-pathspecs on \\ |
|
.br |
|
-add \\ |
|
.br |
|
/sounds=/home/me/sounds \\ |
|
.br |
|
/pictures \\ |
|
.br |
|
-- \\ |
|
.br |
|
-rm_r \\ |
|
.br |
|
/sounds/indecent \\ |
|
.br |
|
'/pictures/*private*' \\ |
|
.br |
|
/pictures/confidential \\ |
|
.br |
|
-- \\ |
|
.br |
|
-add \\ |
|
.br |
|
/pictures/confidential/work* |
|
.br |
|
Note that '/pictures/*private*' is a pattern for iso_rr_paths |
|
while /pictures/confidential/work* gets expanded by the shell |
|
with addresses from the hard disk. |
|
.SS |
|
.B A dialog session doing about the same |
|
.br |
|
-pathspecs is already given as start argument. The other activities |
|
are done as dialog input. The pager gets set to 20 lines of 80 characters. |
|
.br |
|
The drive is aquired by option -dev rather than -outdev in order to see |
|
the message about its current content. By option -blank this content is |
|
made ready for being overwritten and the loaded ISO image is made empty. |
|
.br |
|
In order to be able to eject the media, the session needs to be committed |
|
explicitely. |
|
.br |
|
.B $ xorriso -pathspecs on -dialog on -page 20 80 |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-dev /dev/sr2 |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-blank fast |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-add /sounds=/home/me/sounds /pictures |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-rm_r /sounds/indecent /pictures/*private* /pictures/confidential |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-add /pictures/confidential/work_office /pictures/confidential/work_factory |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-du / |
|
.br |
|
enter option and arguments : |
|
.br |
|
.B \-commit -eject all -end |
|
.br |
|
.SS |
|
.B Manipulating an existing ISO image on the same media |
|
Load image from drive. |
|
Remove (i.e. hide) directory /sounds and its subordinates. |
|
Rename directory /pictures/confidential to /pictures/restricted. |
|
Change access permissions of directory /pictures/restricted. |
|
Add new directory trees /sounds and /movies. Burn to the same media and eject. |
|
.br |
|
\fB$\fR xorriso -dev /dev/sr2 \\ |
|
.br |
|
-rm_r /sounds -- \\ |
|
.br |
|
-mv \\ |
|
.br |
|
/pictures/confidential \\ |
|
.br |
|
/pictures/restricted \\ |
|
.br |
|
-- \\ |
|
.br |
|
-chmod go-rwx /pictures/restricted -- \\ |
|
.br |
|
-pathsspecs on \\ |
|
.br |
|
-add \\ |
|
.br |
|
/sounds=/home/me/prepared_for_dvd/sounds_dummy \\ |
|
.br |
|
/movies=/home/me/prepared_for_dvd/movies \\ |
|
.br |
|
-- \\ |
|
.br |
|
-commit -eject all |
|
.SS |
|
.B Copy modified ISO image from one media to another |
|
Load image from input drive. Do the same manipulations as in the previous |
|
example. Aquire output drive and blank it. Burn the modified image as |
|
first and only session to the output drive. |
|
.br |
|
\fB$\fR xorriso -indev /dev/sr2 \\ |
|
.br |
|
-rm_r /sounds -- \\ |
|
.br |
|
... |
|
.br |
|
-outdev /dev/sr0 -blank fast \\ |
|
.br |
|
-commit -eject all |
|
.SS |
|
.B Write a ISO image into a pipe (single-session only) |
|
\fB$\fR xorriso -outdev - \\ |
|
... |
|
| gzip >image.iso.gz |
|
.SS |
|
.B Adjust thresholds for verbosity, exit value and program abort |
|
Be quite verbous, exit 32 if severity "FAILURE" was encountered, |
|
do not abort prematurely but forcibly go on until the end of commands. |
|
.br |
|
\fB$\fR xorriso ... \\ |
|
.br |
|
-report_about UPDATE \\ |
|
.br |
|
-return_with FAILURE 32 \\ |
|
.br |
|
-abort_on NEVER \\ |
|
.br |
|
... |
|
.SS |
|
.B Perform a single session run as of cdrtools traditions |
|
This shall illustrate how xorriso can act in either role. |
|
Between both processes there can be performed arbitrary transportation |
|
or filtering. |
|
.br |
|
\fB$\fR xorriso -as mkisofs -J -R /home/prepared_for_iso/tree | \\ |
|
.br |
|
xorriso -as cdrecord -v dev=/dev/sr0 blank=fast -eject - |
|
.SS |
|
.B Examples of input timestrings |
|
.br |
|
As printed by program date: |
|
.B 'Thu Nov 8 14:51:13 CET 2007' |
|
.br |
|
The same without ignored parts: |
|
.B 'Nov 8 14:51:13 2007' |
|
.br |
|
The same as expected by date: |
|
.B 110814512007.13 |
|
.br |
|
Four weeks in the future: |
|
.B +4w |
|
.br |
|
The current time: |
|
.B +0 |
|
.br |
|
Three hours ago: |
|
.B \-3h |
|
.br |
|
Seconds since Jan 1 1970: |
|
.B =1194531416 |
|
.br |
|
.SH FILES |
|
.SS |
|
.B Startup files: |
|
.br |
|
If not -no_rc is given as the first argument then xorriso attempts on startup |
|
to read and execute lines from the following files: |
|
.br |
|
/etc/default/xorriso |
|
.br |
|
/etc/opt/xorriso/rc |
|
.br |
|
/etc/xorriso/xorriso.conf |
|
.br |
|
$HOME/.xorrisorc |
|
.br |
|
The files are read in the sequence given above, but none of them is required |
|
for xorriso to function properly. |
|
.br |
|
.SH SEE ALSO |
|
.TP |
|
For mounting xorriso generated ISO 9660 images |
|
.br |
|
.BR mount(8) |
|
.TP |
|
Libreadline, a comfortable input line facility |
|
.BR readline(3) |
|
.TP |
|
Other programs which produce ISO 9660 images |
|
.br |
|
.BR mkisofs(8), |
|
.BR genisoimage(8) |
|
.TP |
|
Other programs which burn sessions to optical media |
|
.BR growisofs(1), |
|
.BR cdrecord(1), |
|
.BR wodim(1), |
|
.BR cdrskin(1) |
|
.br |
|
.SH AUTHOR |
|
Thomas Schmitt <scdbackup@gmx.net> |
|
.br |
|
for libburnia-project.org |
|
.SH CREDITS |
|
xorriso is in part based on work by Vreixo Formoso who provides libisofs |
|
together with Mario Danic who also leads the libburnia team. |
|
Thanks to Andy Polyakov who invented emulated growing, |
|
to Derek Foreman and Ben Jansens who once founded libburn. |
|
.br |
|
Compliments towards Joerg Schilling whose cdrtools served me for ten years. |
|
|
|
|