libburnia/libisoburn
2
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
4c7bf645c2
libisoburn/test/xorriso.txt

552 lines
23 KiB
Plaintext
Raw Blame History

--------------------------------------------------------------------------
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.
An empty address string gives up the current device
without aquiring a new one.
> -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.
-report_about severity Set the threshhold for events to be reported.
Events are the same as with -abort_on. Regardless what is
set by -report_about, messages get always reported if they
reach the severity threshhold of -abort_on .
> -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. 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.
-devices Show list of available MMC drives. 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.
-print-size 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.
-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>.
Reference in New Issue View Git Blame Copy Permalink