536 lines
22 KiB
Plaintext
536 lines
22 KiB
Plaintext
|
|
--------------------------------------------------------------------------
|
|
The architecture of the xorriso application is planned as follows:
|
|
|
|
The main program module creates a xorriso object, calls startup-file reading,
|
|
argument reading, and eventual dialog shell function.
|
|
|
|
The xorriso class module implements the xorriso state object and above three
|
|
main functions. These functions rely on a common interpreter of a list of
|
|
words as described in man xorriso, paragraph "Command processing".
|
|
The list may contain more than one command with its parameters. It is intended
|
|
to be either the list of program arguments or a list parsed from a single
|
|
input line.
|
|
|
|
The interpreter converts the words command-wise into suitable parameters
|
|
for an actor function which performs the command's action resp. a setter
|
|
function which brings the command's setting into effect. The interpreter then
|
|
calls this function immediately and synchronously.
|
|
|
|
These option functions form a well documented API which may be used by
|
|
interpreters of things other than words. E.g. by a GUI module or as libxorriso.
|
|
|
|
xorriso will encapsulate libisoburn, libisofs and libburn. Although i know
|
|
it is not popular, i propose to link it with the object files of those
|
|
libraries and not against external library objects.
|
|
|
|
(Did i watch somebody having an allergy against external programs ?
|
|
I got an allergy against .so . My immune system mistakes them for .DLL .)
|
|
|
|
|
|
>>> currently a stub for xorriso is derived from the source of scdbackup_askme.
|
|
|
|
--------------------------------------------------------------------------
|
|
Emerging man page:
|
|
|
|
XORRISO(1) XORRISO(1)
|
|
|
|
|
|
NAME
|
|
xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
|
|
with Rock Ridge extensions.
|
|
|
|
SYNOPSIS
|
|
xorriso [settings|actions]
|
|
|
|
DESCRIPTION
|
|
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.
|
|
|
|
A special property of xorriso is that it needs neither an external ISO 9660
|
|
formatter program nor an external burn program but rather incorporates
|
|
the libraries of the libburnia project.
|
|
|
|
Overview of features:
|
|
|
|
Operates on an existing ISO image or creates a new one.
|
|
Copies files from filesystem into the ISO image.
|
|
Renames or deletes file objects in the ISO image.
|
|
Changes file properties in the ISO image.
|
|
Writes result as completely new image to optical media or filesystem objects.
|
|
Writes result as add-on session to appendable multi-session media,
|
|
to overwriteable media, to regular files, and to block devices.
|
|
Scans for optical drives, blanks re-useable optical media.
|
|
Reads its instructions from command line arguments, dialog, and batch files.
|
|
|
|
General information paragraphs:
|
|
Session model
|
|
Command processing
|
|
Libburn drives
|
|
Rock Ridge, POSIX, X/Open
|
|
|
|
Session model:
|
|
|
|
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 .
|
|
The data content of a session if called filesystem
|
|
.B image .
|
|
|
|
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.
|
|
|
|
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.
|
|
This session usually contains an updated directory tree for the whole media
|
|
which governs the data contents in all recorded sessions.
|
|
|
|
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 block devices.
|
|
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 "growing" in this text.
|
|
|
|
xorriso provides growing as well as an own method which produces a completely
|
|
new ISO image from the old one and the modifications. This unique xorriso
|
|
method produces compact filesystem images with no waste by outdated data blocks
|
|
and it can write modified images to targets which are completely unsuitable
|
|
for multi-session operations. E.g. fast blanked DVD-RW, named pipes,
|
|
character devices, sockets.
|
|
Therefore this method is called "modifying". Its drawback is that the target
|
|
cannot be the same media which holds the unmodified ISO image but that this
|
|
media has to be present while the new image gets written to another media.
|
|
So typically one needs either two optical drives or has to work with
|
|
filesystem objects as source and/or target media.
|
|
|
|
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.
|
|
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.
|
|
|
|
After -commit a new session begins. A new input drive can only be chosen
|
|
as long as the loaded ISO image was not altered. Alteration can be revoked
|
|
by command -rollback.
|
|
|
|
Writing a session to the target is supposed to be very expensive in terms of
|
|
time and of consumed space on appendable or write-once media. Therefore all
|
|
intended manipulations of a particular ISO image should be done in a single
|
|
session.
|
|
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.
|
|
|
|
|
|
Command processing:
|
|
|
|
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 "[...]") 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.
|
|
|
|
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.
|
|
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.
|
|
|
|
The program ends either by command -end or by the end of arguments with
|
|
no command -dialog encountered.
|
|
|
|
Libburn drives:
|
|
|
|
Source of an existing ISO image can be any random access readable libburn
|
|
drive: optical media with readable data, regular files, block devices.
|
|
RockRidge info must be present in existing ISO images and it will be generated
|
|
by the program unconditionally.
|
|
|
|
Target for writing can be any libburn drive.
|
|
Some drive types do not support the method of growing but only the method
|
|
of modifying.
|
|
|
|
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.
|
|
|
|
Optical drives on Linux usually get addressed by the path of their block
|
|
device or of their generic character device. E.g.
|
|
-dev /dev/sr0
|
|
-dev /dev/hdc
|
|
-dev /dev/sg2
|
|
Get a list of accessible drives by command
|
|
-devices
|
|
It might be necessary to do this as superuser in order to see all drives
|
|
and to then allow rw-access for the intended users.
|
|
|
|
Filesystem objects of nearly any type can be addressed by prefix "stdio:" and
|
|
their path in the filesystem. E.g.
|
|
-dev stdio:/tmp/pseudo_drive
|
|
If path leads to a regular file or to a block device then the emulated drive
|
|
is random access readable and can be used for the method of growing if it
|
|
already contains a valid ISO 9660 image. Any other file type is not readable
|
|
and can only be used as target for the method of modifying.
|
|
|
|
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 an optical drive.
|
|
|
|
|
|
Rock Ridge, POSIX, X/Open:
|
|
|
|
.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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
|
|
OPTIONS
|
|
|
|
Aquiring source and target drive:
|
|
|
|
-dev address Set input and output drive and load eventual ISO image.
|
|
Set the image expansion method to growing.
|
|
Only allowed as long as no ISO image was loaded and
|
|
altered, or after actions -rollback, or -commit.
|
|
Violation yields a SORRY event.
|
|
|
|
-indev address Set input drive and load eventual ISO image. Switch from
|
|
growing to modifying. Same restrictions as with -dev
|
|
|
|
-outdev address Set output drive and switch from growing to modifying.
|
|
>>> (Do we need the restrictions as with -dev ?
|
|
>>> I.e. do we need to know that we are doing modification
|
|
>>> before we call isoburn_prepare_*() ? )
|
|
|
|
-ban_stdio_write Allow for writing only the usage of optical drives. Disallow
|
|
to write the result into files of nearly arbitrary type.
|
|
Once set, this command cannot be revoked.
|
|
|
|
Data manipulations:
|
|
|
|
The following commands may depend on settings listed further below.
|
|
disk_path is a path to an object in the local filesystem tree.
|
|
iso_rr_path is the Rock Ridge name of a file object in the ISO image. (Do not
|
|
confuse with the lowlevel ISO 9660 names visible if Rock Ridge gets ignored.)
|
|
|
|
Note that in the ISO image you are as powerful as the superuser. Access
|
|
permissions of the existing files in the image do not apply to your write
|
|
operations. They are intended to be in effect with the read-only mounted image.
|
|
|
|
If the iso_rr_path of a newly inserted or renamed file leads to an existing
|
|
file object in the ISO image, then the following collision handling happens:
|
|
If both objects are directories then they get merged by recursively inserting
|
|
the subobjects from filesystem into ISO image. If other file types collide then
|
|
the setting of command -overwrite decides. Directories may only be deleted by
|
|
commands -rmdir or -rm_r.
|
|
|
|
The commands in this section alter the ISO image and not the local filesystem.
|
|
|
|
-add path [...] Insert the given files or directory trees from filesystem
|
|
into the ISO image.
|
|
Use the same paths on ISO unless -graft-points is set and
|
|
the paths have the form iso_rr_path=disk_path .
|
|
|
|
-path-list disk_path Like -add but read the pathspecs from file disk_path.
|
|
One pathspec per line.
|
|
|
|
-cp_r disk_path [...] iso_rr_path
|
|
Insert the given files or directory trees from filesystem
|
|
into the ISO image.
|
|
Use the same rules for generating the ISO addresses as
|
|
would be done with shell command cp -r.
|
|
|
|
( Needs enhancement in libisofs:
|
|
-cut_out disk_path startbyte bytecount iso_rr_path
|
|
Cut out a piece of file disk_path and insert it into the ISO
|
|
image under the given iso_rr_path.
|
|
This is advised for files > 2 GiB - 2 KiB if you are not
|
|
certain that all your systems with ISO filesystem driver can
|
|
handle such large files. Depending on the libisofs
|
|
implementation, files of larger size may generate SORRY
|
|
events if they are processed uncut.
|
|
When reading those files pieces from media, you will have to
|
|
concatenate them in the correct sequence:
|
|
cat /mnt/file_part1 /mnt/file_part2 > $HOME/file
|
|
)
|
|
|
|
-rm iso_rr_path [...] Delete the given files from the ISO image.
|
|
|
|
-rm_r iso_rr_path [...]
|
|
Delete the given files or directory trees from the ISO image.
|
|
|
|
-mv 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.
|
|
|
|
-chown uid iso_rr_path [...] Equivalent to chown in the ISO image.
|
|
-chgrp gid iso_rr_path [...] Equivalent to chgrp in the ISO image.
|
|
-chmod mode iso_rr_path [...] Equivalent to chmod in the ISO image.
|
|
|
|
-alter_date 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.
|
|
>>> Can we set ctime ? Do we want to set ctime ?
|
|
|
|
-mkdir iso_rr_path [...] Create empty directories if they do not exist yet.
|
|
Existence as directory generates a WARNING event, existence as
|
|
other file is a SORRY.
|
|
|
|
-rmdir iso_rr_path [...] Delete empty directories.
|
|
|
|
-- Mark end of particular action argument list.
|
|
|
|
-rollback Discard the manipulated ISO image and reload it from indrive.
|
|
|
|
|
|
Writing the result:
|
|
|
|
-commit Perform the write operation. Eventually make the outdrive
|
|
the new indrive and load the image from there. Check wether
|
|
this is what is expected and eventually warn or abort.
|
|
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.
|
|
|
|
-eject "in"|"out"|"all" Eject the media in -indev, resp. -outdev, resp. both
|
|
drives.
|
|
Note: It is not possible yet to effectively eject disk files.
|
|
|
|
-blank mode Blank media resp. invalidate ISO image on media.
|
|
This affects only the outdrive not the indrive.
|
|
If both drives are the same and if the ISO image was altered
|
|
then this command leads to a SORRY event.
|
|
Defined modes are: fast, all, format
|
|
"fast" and "all" make CD-RW and unformatted DVD-RW re-usable
|
|
or de-format overwriteable DVD-RW.
|
|
"format" converts unformatted DVD-RW into overwriteable ones.
|
|
|
|
|
|
Settings for data insertion:
|
|
|
|
RockRidge info will be generated by the program unconditionally.
|
|
|
|
-J Generate Joliet info additional to Rock Ridge info.
|
|
|
|
-f Follow symbolic links.
|
|
|
|
-uid uid User id to be used for all files when inserted into the
|
|
new ISO tree.
|
|
-gid gid Group id for the same purpose.
|
|
|
|
-graft-points For xorriso action -add this enables pathspecs of the form
|
|
target=source like with mkisofs.
|
|
|
|
|
|
Settings for result writing:
|
|
|
|
-V volid Specifies the volume ID. (I assume libisofs can do that)
|
|
|
|
-speed 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:
|
|
706k = 706kB/s = 4c = 4xCD , 5540k = 5540kB/s = 4d = 4xDVD
|
|
If there is no hint about the speed unit attached, then the
|
|
media in the outdrive will decide. Default unit is CD = 176.4k.
|
|
|
|
-dummy "on"|"off" If "on" simulate burning or refuse with SORRY event if
|
|
no simulation is possible.
|
|
|
|
-fs number["k"|"m"] Set the size of the fifo buffer which smoothens the data
|
|
stream from ISO image generation to media burning. Default
|
|
is 4 MiB. The number may be followed by letter "k" or"m"
|
|
which means unit is kiB (= 1024) or MiB (= 1024 kiB).
|
|
|
|
-close "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).
|
|
This is the contrary of cdrskin -multi.
|
|
|
|
|
|
Exception processing:
|
|
|
|
-abort_on severity Set the threshhold for events to abort the program.
|
|
Events are classified by severity :
|
|
"NEVER", "ABORT", "FATAL", "SORRY", "WARNING", "HINT",
|
|
"NOTE", "UPDATE", "DEBUG", "ALL"
|
|
Severities "NEVER" and "ALL" do not occur but mark the extreme
|
|
ends of this potentially expandable range.
|
|
It may become necessary to abort the program anyway, despite
|
|
the setting by this option. Expect not many "ABORT" events to
|
|
be ignorable.
|
|
|
|
-overwrite "on"|"off" Allow or disallow to overwrite existing files in the
|
|
ISO image by a file with the same user defined name. This is
|
|
the RockRidge name and not the plain ISO name.
|
|
With setting "off", RR name collisions cause SORRY-events.
|
|
|
|
|
|
Dialog mode control:
|
|
|
|
-dialog "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.
|
|
|
|
-page len width Describe terminal to the text pager.
|
|
|
|
-use_readline "on"|"off" If "on" then use readline for dialog. Esle use
|
|
plain stdin.
|
|
|
|
-reassure "on"|"off" If "on" then ask the user for "y" or "n" with any file
|
|
before deleting or overwriting it in the ISO image.
|
|
|
|
|
|
Drive and media related inquiry actions:
|
|
|
|
-toc Show media specific table of content. (MMC toc, not ISO.)
|
|
|
|
-devices Show list of available MMC drives.
|
|
|
|
-print-size Print the foreseeable consumption by next -commit.
|
|
|
|
-tell_media_space Print available space on output media (minus already
|
|
foreseeable consumption by next -commit.)
|
|
|
|
|
|
Navigation in ISO image and disk filesystem:
|
|
|
|
-cd iso_rr_path Change the current working directory in the emerging ISO
|
|
image as it is at the moment.
|
|
-cdx disk_path Change the current working directory on filesystem.
|
|
|
|
-pwd Tell the current working directory in the ISO image.
|
|
-pwdx ... on local filesystem.
|
|
|
|
-ls pattern List files from the current working directory in the ISO
|
|
image which match a shell pattern. (I.e. wildcards '*' '?')
|
|
-lsx pattern ... on local filesystem.
|
|
|
|
-ls_l pattern Equivalent for ls -l.
|
|
-ls_lx pattern ... on filesystem.
|
|
|
|
-find pattern Equivalent to find . -name pattern in the ISO image.
|
|
-findx pattern ... on filesystem.
|
|
|
|
|
|
Scripting, dialog and program control features:
|
|
|
|
-no_rc Only if used as first command line argument this option
|
|
prevents reading and interpretation of eventual startup
|
|
files. See section FILES below.
|
|
|
|
-help Print helptext.
|
|
|
|
-version Print program name and version.
|
|
|
|
-history textline Copy textline into libreadline history.
|
|
|
|
-status [mode|filter] Print the current settings.
|
|
Modes:
|
|
short... print only important or altered settings
|
|
long ... print settings even if they are default values
|
|
long_history like long plus history lines
|
|
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.
|
|
|
|
-status_history_max maximum number of history lines to be reported with
|
|
-status "long_history".
|
|
|
|
-options_from_file fileaddress
|
|
Reads lines from fileaddress and executes them as dialog lines.
|
|
|
|
-print text Print a text to result channel.
|
|
-prompt text Wait for the user to hit the Enter key resp. to send a line
|
|
via stdin.
|
|
|
|
-end End program immediately
|
|
|
|
# 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.
|
|
|
|
|
|
Support for frontend programs talking into stdin and listening at stdout:
|
|
|
|
-pkt_output "on"|"off" Consolidate text output on stdout and classify each
|
|
line by a channel indicator: 'R:' for result lines,
|
|
'I:' for notes and error messages, 'M:' for -mark texts.
|
|
-logfile channel fileaddress Copy output of a channel to the given file.
|
|
|
|
-mark text If text is not empty it will get put out each time an
|
|
action has been completed.
|
|
|
|
-prog text Use text as this program's name in subsequent messages
|
|
|
|
-prog_help text Use text as this program's name and perform -help.
|
|
|
|
|
|
EXAMPLES
|
|
|
|
>>> to come
|
|
|
|
|
|
FILES
|
|
|
|
Startup files:
|
|
|
|
If not -no_rc is given as the first argument then xorriso attempts on startup
|
|
to read and execute lines from the following files:
|
|
/etc/default/xorriso
|
|
/etc/opt/xorriso/rc
|
|
/etc/xorriso/cdrskin.conf
|
|
$HOME/.xorrisorc
|
|
The files are read in the sequence given above, but none of them is required
|
|
for xorriso to function properly.
|
|
|
|
|
|
SEE ALSO
|
|
|
|
For mounting xorriso generated ISO images
|
|
mount(8)
|
|
|
|
Other programs which produce ISO images
|
|
mkisofs(8), genisoimage(8)
|
|
|
|
Other programs which burn images to optical media
|
|
growisofs(1), cdrecord(1), wodim(1), cdrskin(1)
|
|
|
|
|
|
AUTHOR
|
|
|
|
xorriso is not written at all.
|
|
This man page was written by Thomas Schmitt <scdbackup@gmx.net>.
|
|
|
|
|