libisoburn/xorriso/xorriso.1

.\"                                      Hey, EMACS: -*- nroff -*-
.\"
.\" IMPORTANT NOTE:
.\"
.\"        The original of this file is kept in xorriso/xorriso.texi
.\"        This here was generated by program xorriso/make_xorriso_1
.\"
.\"
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH XORRISO 1 "Version 1.1.5, Aug 25, 2011"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.nh
.SH NAME
xorriso \- creates, loads, manipulates and writes ISO 9660 filesystem images
with Rock Ridge extensions.
.SH SYNOPSIS
.B xorriso
.RI [ settings | actions ]
.br
.SH DESCRIPTION
.PP
\fBxorriso\fR
is a program which copies file objects from POSIX compliant
filesystems into Rock Ridge enhanced ISO 9660 filesystems and 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.
.br
Vice versa \fBxorriso\fR is able to copy file objects out of ISO 9660
filesystems.
.PP
A special property of \fBxorriso\fR is that it needs neither an external
ISO 9660
formatter program nor an external burn program for CD, DVD or BD but rather
incorporates the libraries of libburnia\-project.org .
.SS
.B Overview of features:
.br
Operates on an existing ISO image or creates a new one.
.br
Copies files from disk filesystem into the ISO image.
.br
Copies files from ISO image to disk filesystem (see osirrox).
.br
Renames or deletes file objects in the ISO image.
.br
Changes file properties in the ISO image.
.br
Updates ISO subtrees incrementally to match given disk subtrees.
.br
Writes result either as completely new image or as add\-on session
to optical media or filesystem objects.
.br
Can activate ISOLINUX and GRUB boot images via El Torito and MBR.
.br
Can perform multi\-session tasks as emulation of mkisofs and cdrecord.
.br
Can record and restore hard links and ACL.
.br
Content may get zisofs compressed or filtered by external processes.
.br
Can issue commands to mount older sessions on GNU/Linux or FreeBSD.
.br
Can check media for damages and copy readable blocks to disk.
.br
Can attach MD5 checksums to each data file and the whole session.
.br
Scans for optical drives, blanks re\-useable optical media.
.br
Reads its instructions from command line arguments, dialog, and files.
.br
Provides navigation commands for interactive ISO image manipulation.
.br
Adjustable thresholds for abort, exit value, and problem reporting.
.SS
.B General information paragraphs:
.br
Session model
.br
Media types and states
.br
Creating, Growing, Modifying, Blind Growing
.br
Libburn drives
.br
Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr
.br
Command processing
.br
Dialog, Readline, Result pager
.sp 1
Maybe you first want to have a look at section EXAMPLES near the end of
this text before reading the next few hundred lines of background information.
.SS
\fBSession model:\fR
.br
Unlike other filesystems, 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
\fBsession\fR.
.br
The data content of the session is called filesystem \fBimage\fR.
.PP
The written image in its session can then be mounted by the operating system
for being used read\-only. GNU/Linux is able to mount ISO images from block
devices, which may represent optical media, other media or via a loop device
even from regular disk files. FreeBSD mounts ISO images from devices that
represent arbitrary media or from regular disk files.
.PP
This session usage model has been extended on CD media by the concept of
\fBmulti\-session\fR ,
which 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.
.PP
\fBxorriso\fR provides growing as well as an own method named
\fBmodifying\fR which produces a completely new ISO image from the old
one and the modifications.
See paragraph Creating, Growing, Modifying, Blind Growing below.
.PP
\fBxorriso\fR adopts the concept of multi\-session by loading an
image directory tree if present,
by allowing to manipulate it by several actions,
and by writing the new image to the target media.
.br
The first session of a \fBxorriso\fR run begins by the definition of
the input drive with the ISO image or by the definition of an output drive.
The session ends by command \-commit which triggers writing. A \-commit is
done automatically when the program ends regularly.
.PP
After \-commit a new session begins with the freshly written one as input.
A new input drive can only be chosen as long as the loaded ISO image was
not altered. Pending alteration can be revoked by command \-rollback.
.PP
Writing a session to the target is supposed to be very expensive in terms of
time and of consumed space on appendable or write\-once media. Therefore all
intended manipulations of a particular ISO image should be done in a single
session. But in principle it is possible
to store intermediate states and to continue with image manipulations.
.SS
.B Media types and states:
There are two families of media in the MMC standard:
.br
\fBMulti\-session media\fR are CD\-R, CD\-RW, DVD\-R, DVD+R, DVD+R/DL, BD\-R, and
unformatted DVD\-RW. These media provide a table of content which
describes their existing sessions. See option \fB\-toc\fR.
.br
Similar to multi\-session media are DVD\-R DL and minimally blanked DVD\-RW.
They allow only a single session of which the size must be known in advance.
\fBxorriso\fR will write onto them only if option \-close is set to "on".
.br
\fBOverwriteable media\fR are DVD\-RAM, DVD+RW, BD\-RE, and formatted DVD\-RW.
They allow random write access but do not provide information about their
session history. If they contain one or more ISO 9660 sessions and if the
first session was written by \fBxorriso\fR, then a table of content can
be emulated. Else only a single overall session will be visible.
.br
DVD\-RW media can be formatted by \-format "full". 
They can be made unformatted by \-blank "deformat".
.br
Regular files and block devices are handled as overwriteable media.
Pipes and other writeable file types are handled as blank multi\-session media.
.PP
These media can assume several states in which they offer different
capabilities.
.br
\fBBlank\fR media can be written from scratch. They contain no ISO image
suitable for \fBxorriso\fR.
.br
Blank is the state of newly purchased optical media.
With used CD\-RW and DVD\-RW it can be achieved by action \-blank "as_needed".
Overwriteable media are considered blank if they are new or if they have
been marked as blank by \fBxorriso\fR.
Action \-blank "as_needed" can be used to do this marking on overwriteable
media, or to apply mandatory formatting to new media if necessary.
.br
\fBAppendable\fR media accept further sessions. Either they are MMC
multi\-session media in appendable state, or they are overwriteable media
which contain an ISO image suitable for \fBxorriso\fR.
.br
Appendable is the state after writing a session with option \-close off.
.br
\fBClosed\fR media cannot be written. They may contain an ISO image suitable
for \fBxorriso\fR.
.br
Closed is the state of DVD\-ROM media and of multi\-session media which were
written with option \-close on. If the drive is read\-only hardware then it will
probably show any media as closed CD\-ROM resp. DVD\-ROM.
.br
Overwriteable media assume this state in such read\-only drives or if they
contain unrecognizable data in the first 32 data blocks.
.br
Read\-only drives may or may not show session histories of multi\-session
media. Often only the first and the last session are visible. Sometimes
not even that. Option \-rom_toc_scan might or might not help in such cases.
.SS
.B Creating, Growing, Modifying, Blind Growing:
.br
A new empty ISO image gets \fBcreated\fR
if there is no input drive with a valid ISO 9660 image when the first time
an output drive is defined. This is achieved by 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 write method 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 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. DVD\-RW which were treated with \-blank deformat_quickest,
DVD\-R DL, named pipes, character devices, sockets.
On the other hand modified sessions cannot be written to appendable media
but to blank media only.
.br
So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target media.
.br
Modifying takes place if input drive and output drive are not the same and
if option \-grow_blindly is set to its default "off".
This is achieved by options \-indev and \-outdev.
.PP
If option \-grow_blindly is set to a non\-negative number and if \-indev and
\-outdev are both set to different drives, then \fBblind growing\fR is
performed. It produces an add\-on session which is ready for being written
to the given block address. This is the usage model of
.br
 mkisofs \-M $indev \-C $msc1,$msc2 \-o $outdev
.br
which gives much room for wrong parameter combinations and should thus only be
employed if a strict distinction between ISO formatter \fBxorriso\fR
and the burn program is desired. \-C $msc1,$msc2 is equivalent to:
.br
 \-load sbsector $msc1 \-grow_blindly $msc2
.SS
.B Libburn drives:
.br
Input drive, i.e. source of an existing or empty ISO image, can be any random
access readable libburn drive: optical media with readable data,
blank optical media, regular files, block devices.
.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 methods
of modifying and blind growing. They all are suitable for newly created images.
.br
All drive file objects have to offer rw\-permission to the user of
\fBxorriso\fR.
Even those which will not be useable for reading an ISO image.
.PP
MMC compliant (i.e. optical) drives on GNU/Linux usually get addressed by
the path of their block device or of their generic character device. E.g.
.br
  \-dev /dev/sr0
.br
  \-dev /dev/hdc
.br
  \-dev /dev/sg2
.br
On FreeBSD the device files have names like
.br
  \-dev /dev/cd0
.br
On OpenSolaris:
.br
  \-dev /dev/rdsk/c4t0d0s2
.br
Get a list of accessible drives by command
.br
  \-device_links
.br
It might be necessary to do this as
\fBsuperuser\fR
in order to see all drives and to then allow rw\-access for the intended users.
Consider to bundle the authorized users in a group like old "floppy".
.PP
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and
their path in the filesystem. E.g.:
.br
  \-dev stdio:/dev/sdc
.br
The default setting of \-drive_class allows to address files outside the
/dev tree without that prefix. E.g.:
.br
  \-dev /tmp/pseudo_drive
.br
If path leads to a regular file or to a block device then the emulated drive
is random access readable and can be used for the method of growing if it
already contains a valid ISO 9660 image. Any other file type is not readable
via "stdio:" and can only be used as target for the method of modifying or
blind growing.
Non\-existing paths in existing directories are handled as empty regular files.
.PP
A very special kind of pseudo drive are open file descriptors. They are
depicted by "stdio:/dev/fd/" and descriptor number (see man 2 open).
.br
Addresses "\-" or "stdio:/dev/fd/1" depict standard output, which normally is
the output channel for result texts.
To prevent a fatal intermingling of ISO image and text messages, all result
texts get redirected to stderr if \-*dev "\-" or "stdio:/dev/fd/1" is among
the start arguments of the program.
.br
Standard output is currently suitable for creating one session
per program run without dialog. Use in other situations is discouraged
and several restrictions apply: 
.br
It is not allowed to use standard output as pseudo drive if it was not
among the start arguments. Do not try to fool this ban via backdoor addresses
to stdout.
.br
If stdout is used as drive, then \-use_readline is permanently disabled.
Use of backdoors can cause severe memory and/or tty corruption.
.PP
Be aware that especially the superuser can write into any accessible file or
device by using its path with the "stdio:" prefix. By default any address
in the /dev tree without prefix "stdio:" will work only if it leads to a MMC
drive.
.br
One may use option
\fB\-ban_stdio_write\fR
to surely prevent this risk and to allow only MMC drives.
.br
One may prepend "mmc:" to a path to surely disallow any automatic "stdio:".
.br
By option \-drive_class one may ban certain paths or allow access without
prefix "stdio:" to other paths.
.SS
.B Rock Ridge, POSIX, X/Open, El Torito, ACL, xattr:
.br
\fBRock Ridge\fR
is the name of a set of additional information which enhance
an ISO 9660 filesystem so that it can represent a POSIX compliant filesystem
with ownership, access permissions, symbolic links, and other attributes.
.br
This is what \fBxorriso\fR uses for a decent representation of the disk
files within the ISO image. Rock Ridge information is produced with any
\fBxorriso\fR image.
.PP
\fBxorriso\fR is not named "porriso" because POSIX only guarantees
14 characters
of filename length. It is the X/Open System Interface standard XSI which
demands a file name length of up to 255 characters and paths of up to 1024
characters. Rock Ridge fulfills this demand.
.PP
An \fBEl Torito\fR
boot record points the BIOS bootstrapping facility to one or more boot
images, which are binary program files stored in the ISO image.
The content of the boot image files is not in the scope of El Torito.
.br
Most bootable GNU/Linux CDs are equipped with ISOLINUX or GRUB boot images.
\fBxorriso\fR is able to create or maintain an El Torito object which
makes such an image bootable. For details see option \-boot_image.
.br
It is possible to make ISO images bootable from USB stick or other
hard\-disk\-like media by \-boot_image argument system_area= . This installs
a Master Boot Record which may get adjusted according to the needs
of GRUB resp. ISOLINUX.
An \fBMBR\fR contains boot code and a partition table. It does not hamper
CDROM booting. The new MBR of a follow\-up session can get in effect
only on overwriteable media.
.br
Emulation \-as mkisofs supports the example options out of the ISOLINUX wiki,
the options used in GRUB script grub\-mkrescue, and the example in the
FreeBSD AvgLiveCD wiki.
.br
There is support for boot facilities other than PC BIOS:
EFI, MIPS Big Endian (SGI), MIPS Little Endian (DEC), SUN SPARC.
.br
.PP
\fBACL\fR
are an advanced way of controlling access permissions to file objects. Neither
ISO 9660 nor Rock Ridge specify a way to record ACLs. So libisofs has
introduced a standard conformant extension named AAIP for that purpose.
It uses this extension if enabled by option
\fB\-acl\fR.
.br
AAIP enhanced images are supposed to be mountable normally, but one cannot
expect that the mounted filesystem will show and respect the ACLs.
For now, only \fBxorriso\fR is able to retrieve those ACLs.
It can bring them into
effect when files get restored to an ACL enabled file system or it can
print them in a format suitable for tool setfacl.
.br
Files with ACL show as group permissions the setting of entry "mask::" if
that entry exists. Nevertheless the non\-listed group members get handled
according to entry "group::". When removing ACL from a file,
\fBxorriso\fR brings "group::" into effect.
.br
Recording and restoring of ACLs from and to local files works currently
only on GNU/Linux and FreeBSD.
.PP
\fBxattr\fR (aka EA, or extattr)
are pairs of name and value which can be attached to file objects. AAIP is
able to represent them and \fBxorriso\fR allows to record and restore
pairs which
have names out of the user namespace. I.e. those which begin with "user.",
like "user.x" or "user.whatever". Name has to be a 0 terminated string.
Value may be any array of bytes which does not exceed the size of 4095 bytes.
xattr processing happens only if it is enabled by option
\fB\-xattr\fR.
.br
As with ACL, currently only \fBxorriso\fR is able to retrieve xattr
from AAIP enhanced images, to restore them to xattr capable file systems,
or to print them. 
.br
Recording and restoring of xattr from and to local files works currently
only on GNU/Linux and FreeBSD, where they are known as extattr. 
.SS
.B Command processing:
.br
Commands are either actions which happen immediately or settings which
influence following actions. So their sequence does matter.
.br
Commands consist of a command word,
followed by zero or more parameter words. If the list of parameter words
is of variable length (indicated by "[...]" or "[***]") then it has to be
terminated by either the \fBlist delimiter\fR, or the end of argument list,
or an end of an input line.
.PP
At program start the list delimiter is the word "\-\-".
This may be changed by option \-list_delimiter in order to allow
"\-\-" as argument in a list of variable length.
It is advised to reset the delimiter to "\-\-" immediately
afterwards.
.br
For brevity the list delimiter is referred as "\-\-"
throughout this text.
.br
The list delimiter is silently tolerated if it appears after the parameters of
a command with a fixed list length. It is handled as normal text if it
appears among the arguments of such a command.
.PP
\fBPattern expansion\fR
converts a list of pattern words into a list of existing file addresses.
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
It is a property of some particular commands and not a general
feature. It gets controlled by commands \-iso_rr_pattern and \-disk_pattern.
Commands which may 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 quoted input lines where words are recognized
similar to the quotation rules of a shell parser.
.br
\fBxorriso\fR is not a shell, although it might appear so on first glimpse.
Be aware that the interaction of quotation marks and pattern symbols like "*"
differs from the usual shell parsers. In \fBxorriso\fR, a quotation mark
does not make a pattern symbol literal.
.PP
\fBQuoted input\fR
converts whitespace separated text pieces into words.
The double quotation mark " and the single quotation mark ' can be used to
enclose whitespace and make it part of words (e.g. of file names). Each mark
type can enclose the marks of the other type. A trailing backslash \\ outside
quotations or an open quotation cause the next input line to be appended.
.br
Quoted input accepts any ASCII character except NUL (0) as content of quotes.
Nevertheless it can be cumbersome for the user to produce those characters
at all. Therefore quoted input and program arguments allow optional
\fBBackslash Interpretation\fR
which can represent all ASCII characters except NUL (0) by backslash codes
as in $'...' of bash.
.br
It is not enabled by default. See option \-backslash_codes.
.PP
When the program starts then it first looks for argument \-no_rc. If this is
not present then it looks for its startup files and
reads their content as command input lines. Then it interprets
the program arguments as commands and parameters. Finally it enters
dialog mode if command \-dialog "on" 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 a quoted input line, parses it into words, and performs
them as commands with their parameters. It provides assisting services
to make dialog more comfortable.
.PP
Readline is an enhancement for the input line. You may know it already from
the bash shell. Whether it is available in \fBxorriso\fR depends on the
availability
of package readline\-dev at the time when \fBxorriso\fR was built from
its sourcecode.
.br
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 built\-in result text pager which may be convenient in
dialog. After an action has put out the given number of terminal lines,
the pager prompts the user for a line of input.
.br
An empty line lets \fBxorriso\fR 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. Nevertheless within option \-as
the dashes of the emulated options are mandatory.
.br
Normally any number of leading dashes is ignored with command words and
inner dashes are interpreted as underscores.
.TP
.B Aquiring source and target drive:
.PP
The effect of aquiring a drive may depend on several options in the
next paragraph "Influencing the behavior of image loading".
If desired, their enabling commands have to be performed before the
commands which aquire the drive.
.TP
\fB\-dev\fR address
Set input and output drive to the same address and load an ISO image if it
is present.
If there is no ISO image then create a blank one.
Set the image expansion method to growing.
.br
This is only allowed as long as no changes are pending in the currently
loaded ISO image. If changes are pending, then one has to perform \-commit
or \-rollback first.
.br
Special address string "\-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
.br
An empty address string "" gives up the current device
without aquiring a new one.
.TP
\fB\-indev\fR address
Set input drive and load an ISO image if present.
If the new input drive differs
from \-outdev then switch from growing to modifying or to blind growing.
It depends on the setting of \-grow_blindly which of both gets activated.
The same rules and restrictions apply as with \-dev.
.TP
\fB\-outdev\fR address
Set output drive and if it differs from the input drive then switch from
growing to modifying or to blind growing. Unlike \-dev and \-indev this action
does not load a new ISO image. So it can be performed even if there are pending
changes.
.br
\-outdev can be performed without previous \-dev or \-indev. In that case an
empty ISO image with no changes pending is created. It can either be populated
by help of \-map, \-add et.al. or it can be discarded silently if \-dev or \-indev
are performed afterwards.
.br
Special address string "\-" means standard output, to which several restrictions
apply. See above paragraph "Libburn drives".
.br
An empty address string "" gives up the current output drive
without aquiring a new one. No writing is possible without an output drive.
.TP
\fB\-grow_blindly\fR "off"|predicted_nwa
If predicted_nwa is a non\-negative number then perform blind growing rather
than modifying if \-indev and \-outdev are set to different drives.
"off" or "\-1" switch to modifying, which is the default.
.br
predicted_nwa is the block address where the add\-on session of blind
growing will finally end up. It is the responsibility of the user to ensure
this final position and the presence of the older sessions. Else the
overall ISO image will not be mountable or will produce read errors when
accessing file content. \fBxorriso\fR will write the session to the address
as obtained from examining \-outdev and not necessarily to predicted_nwa.
.br
During a run of blind growing, the input drive is given up before output
begins. The output drive is given up when writing is done.
.TP
.B Influencing the behavior of image loading:
.PP
The following options should normally be performed before loading an image
by aquiring an input drive. In rare cases it is desirable to activate
them only after image loading.
.TP
\fB\-load\fR entity id
Load a particular (possibly outdated) ISO session from \-dev or \-indev.
Usually all available sessions are shown with option \-toc.
.br
entity depicts the kind of addressing. id depicts the particular