Polished xorriso man page

This commit is contained in:
Thomas Schmitt 2007-11-14 17:55:27 +00:00
parent 7be61dca7c
commit 69c268e902
1 changed files with 88 additions and 38 deletions

View File

@ -2,7 +2,7 @@
.\" 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 "November 11, 2007"
.TH XORRISO 1 "November 14, 2007"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
@ -61,11 +61,16 @@ Provides navigation commands for interactive ISO image manipulation.
.br
Session model
.br
Creating, Growing, Modifying
.br
Libburn drives
.br
Rock Ridge, POSIX, X/Open
.br
Command processing
.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
@ -79,7 +84,7 @@ The data content of the session is called filesystem
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
regular disk files.
from regular disk files.
.PP
This session usage model has been extended on CD media by the concept of
.B multi-session ,
@ -97,25 +102,27 @@ The multi-session model of the MMC standard applies to CD-R[W], to DVD-R, to
certain states of DVD-RW, and to DVD+R. But it does not apply to overwriteable
MMC media like DVD-RAM, DVD+RW, formatted DVD-RW, and of course not to disk
files or non-CD/DVD block devices.
.br
Program growisofs by Andy Polyakov showed how to extend this functionality
to overwriteable media or disk files which carry valid ISO 9660 filesystems.
These two expansion methods are referred as \fBgrowing\fR in this text.
.br
xorriso provides both ways of growing as well as an own method which produces
a completely new ISO image from the old one and the modifications.
See below.
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 next paragraph for details.
.PP
xorriso adopts the concept of 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.
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 and ends by command -commit which triggers
writing. A -commit is done automatically when the program ends regularly.
drive with the eventual ISO image or by the definition of an output file.
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. 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.
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
@ -124,30 +131,56 @@ 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 Creating, Growing, Modifying
.br
A new empty ISO image gets created 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 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
The unique xorriso method of \fBmodifying\fR produces compact filesystem
images with no waste by outdated data blocks and it can write modified images
to target media which are completely unsuitable for multi-session operations.
E.g. fast blanked DVD-RW, named pipes, character devices, sockets.
It is important to note that modified sessions can be written to blank
media only.
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.
See options -dev, -indev, -outdev.
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
Source of an existing ISO image can be any random access readable libburn
drive: optical media with readable data, regular files, block devices.
Input drive, i.e. source of an existing ISO image, can be any random access
readable libburn drive: optical media with readable data, regular files,
block devices.
.br
RockRidge info must be present in existing ISO images and it will be generated
Rock Ridge info must be present in existing ISO images and it will be generated
by the program unconditionally.
.PP
Target for writing can be any libburn drive.
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.
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.
@ -229,7 +262,7 @@ make a pattern symbol literal.
When the program begins then it first 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 was executed up to then.
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 command -dialog was encountered up to that moment, or by a problem
@ -479,11 +512,10 @@ Defined modes are:
"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 faster but produces media which are
only suitable for a single session. xorriso will write onto
them only if option -close is set to "on".
"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 FATAL or
@ -519,7 +551,7 @@ like with program mkisofs.
.TP
.B Settings for result writing:
.TP
RockRidge info will be generated by the program unconditionally.
Rock Ridge info will be generated by the program unconditionally.
.TP
? \fB\-J\fR
Generate Joliet info additional to Rock Ridge info.
@ -807,10 +839,10 @@ 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
Because no -dialog "on" is given, the program will then end by committing the
session to media.
.br
\fB$\fR xorriso -dev /dev/sr2 \\
\fB$\fR xorriso -outdev /dev/sr2 \\
-blank fast \\
-graft-points \\
-add \\
@ -834,6 +866,10 @@ with addresses from the hard disk.
-graft-points is already given as start argument. The other activities
are done as dialog input. The pager gets set to 20 lines of 80 chracters.
.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
@ -868,12 +904,13 @@ enter option and arguments :
.B \-commit -eject all -end
.br
.SS
.B Modifying an existing ISO image
.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 dummy as replacement of /pictures/confidential.
Add new directory tree /movies. Burn to DVD and eject.
Add new directory tree /movies. Burn to the same DVD and eject.
.br
\fB$\fR xorriso -dev /dev/sr2 \\
-rm_r /sounds -- \\
@ -887,8 +924,21 @@ Add new directory tree /movies. Burn to DVD and eject.
/sounds=/home/me/prepared_for_dvd/sounds_dummy \\
/movies=/home/me/prepared_for_dvd/movies \\
-- \\
-commit \\
-eject all
-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 \\
-rm_r /sounds -- \\
...
/movies=/home/me/prepared_for_dvd/movies \\
-- \\
-outdev /dev/sr0 \\
-blank fast \\
-commit -eject all
.SS
.B Examples of input timestrings
.br
@ -938,7 +988,7 @@ Other programs which produce ISO 9660 images
.BR mkisofs(8),
.BR genisoimage(8)
.TP
Other programs which burn images to optical media
Other programs which burn sessions to optical media
.BR growisofs(1),
.BR cdrecord(1),
.BR wodim(1),