Polished xorriso man page

This commit is contained in:
Thomas Schmitt 2007-11-14 17:55:27 +00:00
parent bbfc05161c
commit b9ebb3d74a

View File

@ -2,7 +2,7 @@
.\" First parameter, NAME, should be all caps .\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1) .\" 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. .\" Please adjust this date whenever revising the manpage.
.\" .\"
.\" Some roff macros, for reference: .\" Some roff macros, for reference:
@ -61,11 +61,16 @@ Provides navigation commands for interactive ISO image manipulation.
.br .br
Session model Session model
.br .br
Creating, Growing, Modifying
.br
Libburn drives Libburn drives
.br .br
Rock Ridge, POSIX, X/Open Rock Ridge, POSIX, X/Open
.br .br
Command processing 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 .SS
.B Session model: .B Session model:
.br .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 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, 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 which may represent optical media, other media or via a loop device even
regular disk files. from regular disk files.
.PP .PP
This session usage model has been extended on CD media by the concept of This session usage model has been extended on CD media by the concept of
.B multi-session , .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 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 MMC media like DVD-RAM, DVD+RW, formatted DVD-RW, and of course not to disk
files or non-CD/DVD block devices. files or non-CD/DVD block devices.
.br
Program growisofs by Andy Polyakov showed how to extend this functionality Program growisofs by Andy Polyakov showed how to extend this functionality
to overwriteable media or disk files which carry valid ISO 9660 filesystems. to overwriteable media or disk files which carry valid ISO 9660 filesystems.
These two expansion methods are referred as \fBgrowing\fR in this text. These two expansion methods are referred as \fBgrowing\fR in this text.
.br .br
xorriso provides both ways of growing as well as an own method which produces xorriso provides both ways of growing as well as an own method named
a completely new ISO image from the old one and the modifications. \fBmodifying\fR which produces a completely new ISO image from the old
See below. one and the modifications. See next paragraph for details.
.PP .PP
xorriso adopts the concept of session by loading an eventual image directory xorriso adopts the concept of multi-session by loading an eventual image
tree, allowing to manipulate it by several actions, and to write the new directory tree, allowing to manipulate it by several actions, and to write
image to the target media. the new image to the target media.
.br .br
The first session of a xorriso run begins by the definition of the input 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 drive with the eventual ISO image or by the definition of an output file.
writing. A -commit is done automatically when the program ends regularly. The session ends by command -commit which triggers writing. A -commit is
done automatically when the program ends regularly.
.PP .PP
After -commit a new session begins. A new input drive can only be chosen After -commit a new session begins with the freshly written one as input.
as long as the loaded ISO image was not altered. A new input drive can only be chosen as long as the loaded ISO image was
Pending alteration can be revoked by command -rollback. not altered. Pending alteration can be revoked by command -rollback.
.PP .PP
Writing a session to the target is supposed to be very expensive in terms of 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 time and of consumed space on appendable or write-once media. Therefore all
@ -124,30 +131,56 @@ session.
.br .br
In some special situations (e.g. in a file-to-file situation) it can be 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. 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 .PP
The unique xorriso method of \fBmodifying\fR produces compact filesystem If there is a input drive with a valid ISO image, then this image gets loaded
images with no waste by outdated data blocks and it can write modified images as foundation for manipulations and extension. The constellation of input
to target media which are completely unsuitable for multi-session operations. and output drive determines which of two write methods will be used.
E.g. fast blanked DVD-RW, named pipes, character devices, sockets. They have quite different capabilities and constraints.
It is important to note that modified sessions can be written to blank .PP
media only. 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 .br
Modifying takes place whenever input drive and output drive are not the same. 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 So for this method one needs either two optical drives or has to work with
filesystem objects as source and/or target media. filesystem objects as source and/or target media.
.SS .SS
.B Libburn drives: .B Libburn drives:
.br .br
Source of an existing ISO image can be any random access readable libburn Input drive, i.e. source of an existing ISO image, can be any random access
drive: optical media with readable data, regular files, block devices. readable libburn drive: optical media with readable data, regular files,
block devices.
.br .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. by the program unconditionally.
.PP .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 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 .br
All drive file objects have to offer rw-permission to the user of xorriso. 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. 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 When the program begins then it first looks for its startup files and
eventually reads their content as command input lines. Then it interprets eventually reads their content as command input lines. Then it interprets
the program arguments as commands and parameters and finally it enters 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 .PP
The program ends either by command -end, or by the end of program arguments 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 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, "fast" and "all" make CD-RW and unformatted DVD-RW re-usable,
or invalidate overwriteable ISO images. or invalidate overwriteable ISO images.
"deformat" converts overwriteable DVD-RW into unformatted ones. "deformat" converts overwriteable DVD-RW into unformatted ones.
"deformat_quickest" is faster but produces media which are "deformat_quickest" is a faster way to deformat or blank DVD-RW
only suitable for a single session. xorriso will write onto but produces media which are only suitable for a single session.
them only if option -close is set to "on". xorriso will write onto them only if option -close is set to "on".
.br .br
The progress reports issued by some drives while blanking are The progress reports issued by some drives while blanking are
quite unrealistic. Do not conclude success or failure from the quite unrealistic. Do not conclude success or failure from the
reported percentages. Blanking was successful if no FATAL or reported percentages. Blanking was successful if no FATAL or
@ -519,7 +551,7 @@ like with program mkisofs.
.TP .TP
.B Settings for result writing: .B Settings for result writing:
.TP .TP
RockRidge info will be generated by the program unconditionally. Rock Ridge info will be generated by the program unconditionally.
.TP .TP
? \fB\-J\fR ? \fB\-J\fR
Generate Joliet info additional to Rock Ridge info. 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. Omit some unwanted stuff by removing it from the image directory tree.
Re-add some wanted stuff. Re-add some wanted stuff.
.br .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. session to media.
.br .br
\fB$\fR xorriso -dev /dev/sr2 \\ \fB$\fR xorriso -outdev /dev/sr2 \\
-blank fast \\ -blank fast \\
-graft-points \\ -graft-points \\
-add \\ -add \\
@ -834,6 +866,10 @@ with addresses from the hard disk.
-graft-points is already given as start argument. The other activities -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. are done as dialog input. The pager gets set to 20 lines of 80 chracters.
.br .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 In order to be able to eject the media, the session needs to be committed
explicitely. explicitely.
.br .br
@ -868,12 +904,13 @@ enter option and arguments :
.B \-commit -eject all -end .B \-commit -eject all -end
.br .br
.SS .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. Remove (i.e. hide) directory /sounds and its subordinates.
Rename directory /pictures/confidential to /pictures/restricted. Rename directory /pictures/confidential to /pictures/restricted.
Change access permissions of directory /pictures/restricted. Change access permissions of directory /pictures/restricted.
Add dummy as replacement of /pictures/confidential. 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 .br
\fB$\fR xorriso -dev /dev/sr2 \\ \fB$\fR xorriso -dev /dev/sr2 \\
-rm_r /sounds -- \\ -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 \\ /sounds=/home/me/prepared_for_dvd/sounds_dummy \\
/movies=/home/me/prepared_for_dvd/movies \\ /movies=/home/me/prepared_for_dvd/movies \\
-- \\ -- \\
-commit \\ -commit -eject all
-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 .SS
.B Examples of input timestrings .B Examples of input timestrings
.br .br
@ -938,7 +988,7 @@ Other programs which produce ISO 9660 images
.BR mkisofs(8), .BR mkisofs(8),
.BR genisoimage(8) .BR genisoimage(8)
.TP .TP
Other programs which burn images to optical media Other programs which burn sessions to optical media
.BR growisofs(1), .BR growisofs(1),
.BR cdrecord(1), .BR cdrecord(1),
.BR wodim(1), .BR wodim(1),