1001 lines
35 KiB
Groff
1001 lines
35 KiB
Groff
.\" Hey, EMACS: -*- nroff -*-
|
|
.\" 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 14, 2007"
|
|
.\" 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)
|
|
.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
|
|
.B 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.
|
|
.PP
|
|
A special property of xorriso is that it needs neither an external ISO 9660
|
|
formatter program nor an external burn program for CD or DVD 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 filesystem into the ISO image.
|
|
.br
|
|
Renames or deletes file objects in the ISO image.
|
|
.br
|
|
Changes file properties in the ISO image.
|
|
.br
|
|
Can write result as completely new image to optical media or
|
|
filesystem objects.
|
|
.br
|
|
Can write result as add-on session to appendable multi-session media,
|
|
to overwriteable media, to regular files, and to block devices.
|
|
.br
|
|
Scans for optical drives, blanks re-useable optical media.
|
|
.br
|
|
Reads its instructions from command line arguments, dialog, and batch files.
|
|
.br
|
|
Provides navigation commands for interactive ISO image manipulation.
|
|
.SS
|
|
.B General information paragraphs:
|
|
.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
|
|
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.
|
|
.br
|
|
The data content of the session is called filesystem
|
|
.B image.
|
|
.PP
|
|
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
|
|
from regular disk files.
|
|
.PP
|
|
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.
|
|
.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.
|
|
.PP
|
|
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 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 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 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 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.
|
|
.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
|
|
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.
|
|
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
|
|
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
|
|
Rock Ridge info must be present in existing ISO images and it will be generated
|
|
by the program unconditionally.
|
|
.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 method
|
|
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.
|
|
.PP
|
|
MMC compliant (i.e. 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
|
|
.br
|
|
Get a list of accessible drives by command
|
|
-devices
|
|
.br
|
|
It might be necessary to do this as
|
|
.B superuser
|
|
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.:
|
|
-dev stdio:/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.
|
|
.PP
|
|
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 a MMC drive.
|
|
.br
|
|
One may use option
|
|
.B -ban_stdio_write
|
|
to surely prevent this risk and to allow only MMC drives.
|
|
.SS
|
|
.B Rock Ridge, POSIX, X/Open:
|
|
.br
|
|
.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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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.
|
|
.SS
|
|
.B Command processing:
|
|
.br
|
|
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 "[...]" or "[***]") 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.
|
|
.PP
|
|
.B Pattern expansion
|
|
is a property of some particular commands and not a general
|
|
feature. It gets controlled by command -iso_rr_pattern. Commands which
|
|
eventually 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 input lines where words are recognized similar
|
|
to the quotation rules of a shell parser.
|
|
.br
|
|
xorriso 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 xorriso, a quotation mark does not
|
|
make a pattern symbol literal.
|
|
.PP
|
|
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 "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
|
|
event which triggers the threshold of command -abort_on.
|
|
.br
|
|
.SH OPTIONS
|
|
.br
|
|
Options marked with prefix '>' are not implemented yet.
|
|
.br
|
|
Options with prefix '?' are not tested yet.
|
|
.TP
|
|
.B Aquiring source and target drive:
|
|
.TP
|
|
\fB\-dev\fR address
|
|
Set input and output drive to the same address and load eventual ISO image.
|
|
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. Eventually one has to perform -commit or -rollback first.
|
|
Violation yields a SORRY event.
|
|
.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 eventual ISO image. If the new input drive differs
|
|
from outdev then switch from growing to modifying. 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. 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 -add or it can be discarded silently if -dev or -indev are
|
|
performed afterwards.
|
|
.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\-ban_stdio_write\fR
|
|
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.
|
|
.TP
|
|
.B Data manipulations:
|
|
.PP
|
|
The following commands expect file addresses of two kinds:
|
|
.br
|
|
.B disk_path
|
|
is a path to an object in the local filesystem tree.
|
|
.br
|
|
.B 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.)
|
|
.PP
|
|
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.
|
|
.PP
|
|
If the iso_rr_path of a newly inserted file leads to an existing
|
|
file object in the ISO image, then the following
|
|
.B collision handling
|
|
happens:
|
|
.br
|
|
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.
|
|
.br
|
|
Renaming of files has similar collision handling, but directories can only
|
|
be replaced, not merged.
|
|
.PP
|
|
The commands in this section alter the ISO image and not the local filesystem.
|
|
.TP
|
|
\fB\-iso_rr_pattern\fR "on"|"ls"|"off"
|
|
Set the pattern expansion mode for the iso_rr_path arguments of several
|
|
commands which support this feature.
|
|
.br
|
|
.B Pattern expansion
|
|
converts a list of pattern words into a list of existing file addresses.
|
|
Eventual 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
|
|
Setting "off" disables this feature for all commands which are marked in this
|
|
man page by "iso_rr_path [***]" or "pattern [***]".
|
|
Setting "on" enables it for all those commands.
|
|
Setting "ls" enables it only for those which are marked by "pattern [***]".
|
|
.br
|
|
Default is "on".
|
|
.TP
|
|
\fB\-add\fR path [...]
|
|
Insert the given files or directory trees from filesystem
|
|
into the ISO image.
|
|
.br
|
|
Use the same paths on ISO unless -graft-points is set and
|
|
the paths have the form iso_rr_path=disk_path .
|
|
.TP
|
|
\fB\-path-list\fR disk_path
|
|
Like -add but read the pathspecs from file disk_path.
|
|
One pathspec per line.
|
|
.TP
|
|
> \fB\-cp_r\fR 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.
|
|
.TP
|
|
\fB\-rm\fR iso_rr_path [***]
|
|
Delete the given files from the ISO image.
|
|
.br
|
|
Note: This does not free any space on the -indev media, even if
|
|
the deletion is committed to that same media.
|
|
.br
|
|
The image size will shrink if the image is written to a different
|
|
media in modification mode.
|
|
.TP
|
|
\fB\-rm_r\fR iso_rr_path [***]
|
|
Delete the given files or directory trees from the ISO image.
|
|
See also the note with option -rm.
|
|
.TP
|
|
\fB\-mv\fR 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.
|
|
.br
|
|
If pattern expansion is enabled and if the last argument contains wildcard
|
|
characters then it must match exactly one existing file address, or else the
|
|
command fails with a SORRY event.
|
|
.TP
|
|
\fB\-chown\fR uid iso_rr_path [***]
|
|
Set ownership of file objects in the ISO image. uid may either be a decimal
|
|
number or the name of a user known to the operating system.
|
|
.TP
|
|
\fB\-chgrp\fR gid iso_rr_path [***]
|
|
Set group attribute of file objects in the ISO image. gid may either be a
|
|
decimal number or the name of a group known to the operating system.
|
|
.TP
|
|
\fB\-chmod\fR mode iso_rr_path [***]
|
|
Equivalent to shell command chmod in the ISO image.
|
|
mode is either an octal number beginning with "0" or a comma separated
|
|
list of statements of the form [ugoa]*[+-=][rwxst]* . Like: go-rwx,u+rwx .
|
|
.br
|
|
.B Personalities:
|
|
u=user, g=group, o=others, a=all
|
|
.br
|
|
.B Operators:
|
|
+ adds given permissions, - revokes given permissions,
|
|
= revokes all old permissions and then adds the given ones.
|
|
.br
|
|
.B Permissions:
|
|
r=read, w=write, x=execute|inspect, s=setuid|setgid, t=sticky bit
|
|
.br
|
|
For octal numbers see man 2 stat.
|
|
.TP
|
|
\fB\-alter_date\fR 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.
|
|
.br
|
|
timestring may be in the following formats
|
|
(see also section EXAMPLES):
|
|
.br
|
|
As expected by program date:
|
|
MMDDhhmm[[CC]YY][.ss]]
|
|
.br
|
|
As produced by program date:
|
|
[Day] MMM DD hh:mm:ss [TZON] YYYY
|
|
.br
|
|
Relative times counted from current clock time:
|
|
+|-Number["s"|"h"|"d"|"w"|"m"|"y"]
|
|
.br
|
|
where "s" means seconds, "h" hours, "d" days, "w" weeks, "m"=30d,
|
|
"y"=365.25d plus 1d added multiplication result.
|
|
.br
|
|
Absolute seconds counted from Jan 1 1970:
|
|
=Number
|
|
.br
|
|
xorriso's own timestamps:
|
|
YYYY.MM.DD[.hh[mm[ss]]]
|
|
.br
|
|
scdbackup timestamps:
|
|
YYMMDD[.hhmm[ss]]
|
|
.br
|
|
where "A0" is year 2000, "B0" is 2010, etc.
|
|
.TP
|
|
\fB\-mkdir\fR iso_rr_path [...]
|
|
Create empty directories if they do not exist yet.
|
|
Existence as directory generates a WARNING event, existence as
|
|
other file cause a SORRY event.
|
|
.TP
|
|
\fB\-rmdir\fR iso_rr_path [***]
|
|
Delete empty directories.
|
|
.TP
|
|
\fB\-\-\fR
|
|
Mark end of particular action argument list.
|
|
.TP
|
|
\fB\-rollback\fR
|
|
Discard the manipulated ISO image and reload it from -indev.
|
|
.TP
|
|
.B Writing the result:
|
|
(see also paragraph about settings below)
|
|
.TP
|
|
\fB\-commit\fR
|
|
Perform the write operation. Afterwards eventually make the
|
|
-outdev the new -indev and load the image from there.
|
|
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.
|
|
.br
|
|
|
|
Writing can last quite a while. It is not unnormal with several
|
|
types of media if there is no progress visible for the first
|
|
few minutes and if the drive gnaws on the media for a few
|
|
minutes after all data have been transmitted.
|
|
xorriso and the drives are in a client-server relationship.
|
|
The drives have much freedom about what to do with the media.
|
|
Some combinations of drives and media simply do not work,
|
|
despite the promises by vendors of drives and media.
|
|
If writing fails - or even the drive gets stuck and you need
|
|
to reboot - then try other media or another drive. The reason
|
|
for such failure is hardly ever in the code of the various
|
|
burn programs but you may well try some of those listed below
|
|
under SEE ALSO.
|
|
.TP
|
|
\fB\-eject\fR "in"|"out"|"all"
|
|
Eject the media in -indev, resp. -outdev, resp. both drives.
|
|
Note: It is not possible yet to effectively eject disk files.
|
|
.TP
|
|
\fB\-blank\fR mode
|
|
Blank media resp. invalidate ISO image on media if not -dummy
|
|
is activated.
|
|
.br
|
|
This affects only the -outdev not the -indev.
|
|
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, deformat, deformat_quickest
|
|
.br
|
|
"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 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
|
|
SORRY event occured.
|
|
.TP
|
|
\fB\-format\fR mode
|
|
Convert unformatted DVD-RW into overwriteable ones,
|
|
"de-ice" DVD+RW.
|
|
As mode submit the word "full" for now.
|
|
.br
|
|
This action has no effect on media if -dummy is activated.
|
|
.br
|
|
Be warned that re-formatting DVD+RW is considered to be risky
|
|
to the media's health. DVD+RW get formatted as far as needed
|
|
during writing, but an entirely formatted media might be better
|
|
readable in some DVD players.
|
|
.br
|
|
|
|
The progress reports issued by some drives while formatting are
|
|
quite unrealistic. Do not conclude success or failure from the
|
|
reported percentages. Formatting was successful if no FATAL or
|
|
SORRY event occured.
|
|
.TP
|
|
.B Settings for data insertion:
|
|
.TP
|
|
> \fB\-f\fR
|
|
Follow symbolic links.
|
|
.TP
|
|
\fB\-graft-points\fR
|
|
For xorriso action -add this enables pathspecs of the form
|
|
.B target=source
|
|
like with program mkisofs.
|
|
.TP
|
|
.B Settings for result writing:
|
|
.TP
|
|
Rock Ridge info will be generated by the program unconditionally.
|
|
.TP
|
|
? \fB\-J\fR
|
|
Generate Joliet info additional to Rock Ridge info.
|
|
.TP
|
|
> \fB\-V\fR volid
|
|
Specifies the volume ID.
|
|
.TP
|
|
\fB\-uid\fR uid
|
|
User id to be used for all files when the new ISO tree gets written to media.
|
|
.TP
|
|
\fB\-gid\fR gid
|
|
Group id to be used for all files when the new ISO tree gets written to media.
|
|
.TP
|
|
\fB\-speed\fR 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
|
|
.br
|
|
If there is no hint about the speed unit attached, then the
|
|
media in the -outdev will decide. Default unit is CD = 176.4k.
|
|
.br
|
|
MMC drives usually activate their own idea of speed and take
|
|
the speed value given by the burn program only as upper limit
|
|
for their own decision.
|
|
.TP
|
|
\fB\-dummy\fR "on"|"off"
|
|
If "on" simulate burning or refuse with SORRY event if
|
|
no simulation is possible. If "on" do not blank or format.
|
|
.TP
|
|
\fB-fs\fR 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, minimum 64 kiB, maximum 1 GiB.
|
|
The number may be followed by letter "k" or "m"
|
|
which means unit is kiB (= 1024) or MiB (= 1024 kiB).
|
|
.TP
|
|
\fB\-close\fR "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).
|
|
.br
|
|
This is the contrary of cdrecord, wodim, cdrskin -multi,
|
|
and is one aspect of growisofs -dvd-compat.
|
|
.TP
|
|
.B Exception processing:
|
|
.TP
|
|
\fB\-abort_on\fR severity
|
|
Set the threshold for events to abort the program.
|
|
Events are classified by severity :
|
|
"NEVER", "ABORT", "FATAL", "SORRY", "WARNING",
|
|
"HINT", "NOTE", "UPDATE", "DEBUG", "ALL"
|
|
.br
|
|
Severities "NEVER" and "ALL" do not occur but mark the extreme
|
|
ends of this potentially expandable range.
|
|
.br
|
|
It may become necessary to abort the program anyway, despite
|
|
the setting by this option. Expect not many "ABORT" events to
|
|
be ignorable.
|
|
.TP
|
|
\fB\-report_about\fR severity
|
|
Set the threshold 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 threshold of -abort_on .
|
|
.br
|
|
Event messages are sent to the info channel "I" which is usually stderr
|
|
but may be influenced by command -pkt_output.
|
|
Info messages which belong to no event get attributed severity "NOTE".
|
|
.TP
|
|
\fB\-overwrite\fR "on"|"nondir"|"off"
|
|
Allow or disallow to overwrite existing files in the
|
|
ISO image by files with the same user defined name.
|
|
.br
|
|
With setting "off", name collisions cause SORRY-events.
|
|
With setting "nondir", only directories are protected by such events, other
|
|
existing file types get treated with -rm before the new file gets added.
|
|
Setting "on" allows automatic -rm_r. I.e. a non-directory can replace an
|
|
existing directory and all its subordinates.
|
|
.TP
|
|
.B Dialog mode control:
|
|
.TP
|
|
\fB\-dialog\fR "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.
|
|
.TP
|
|
\fB\-page\fR len width
|
|
Describe terminal to the text pager.
|
|
.TP
|
|
\fB\-use_readline\fR "on"|"off"
|
|
If "on" then use readline for dialog. Else use plain stdin.
|
|
.TP
|
|
\fB\-reassure\fR "on"|"tree"|"off"
|
|
If "on" then ask the user for "y" or "n"
|
|
before deleting or overwriting any file in the ISO image.
|
|
With setting "tree" the reassuring prompt will appear for an eventual
|
|
directory only once and not for each file in its whole subtree.
|
|
Setting "off" silently kills any kind of image file object.
|
|
To really produce user prompts, option -dialog needs to be set to "on".
|
|
.br
|
|
Note that the prompt appears only in situations where file removal
|
|
is not forbidden by option -overwrite. -reassure only imposes an additional
|
|
curb for removing existing file objects.
|
|
.br
|
|
Be aware that file objects get deleted from the ISO image immediately
|
|
after confirmation. They are gone even if the running command gets aborted
|
|
and its desired effect gets revoked. In case of severe mess-up, consider to
|
|
use -rollback to revoke the whole session.
|
|
.TP
|
|
.B Drive and media related inquiry actions:
|
|
.TP
|
|
\fB\-toc\fR
|
|
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.
|
|
.TP
|
|
\fB\-devices\fR
|
|
Show list of available MMC drives with the addresses of
|
|
their libburn standard device files.
|
|
.br
|
|
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.
|
|
.br
|
|
In order to be visible a device has to offer rw-permissions
|
|
with its libburn standard device file. Thus it might be only the
|
|
.B superuser
|
|
who is able to see all drives.
|
|
.br
|
|
Drives which are occupied by other processes get not shown.
|
|
.TP
|
|
\fB\-print-size\fR
|
|
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.
|
|
.TP
|
|
\fB\-tell_media_space\fR
|
|
Print available space on output media and the free space after
|
|
subtracting already foreseeable consumption by next -commit.
|
|
.TP
|
|
.B Navigation in ISO image and disk filesystem:
|
|
.TP
|
|
\fB\-cd\fR iso_rr_path
|
|
Change the current working directory in the emerging ISO
|
|
image as it is at the moment.
|
|
.TP
|
|
\fB\-cdx\fR disk_path
|
|
Change the current working directory on filesystem.
|
|
.TP
|
|
\fB\-pwd\fR
|
|
Tell the current working directory in the ISO image.
|
|
.TP
|
|
\fB\-pwdx\fR
|
|
Tell the current working directory on local filesystem.
|
|
.TP
|
|
\fB\-ls\fR pattern [***]
|
|
List files from the current working directory in the ISO
|
|
image which match shell patterns (i.e. with wildcards '*' '?' '[a-z]').
|
|
Note that this resembles rather shell command ls -d than command ls.
|
|
.TP
|
|
> \fB\-lsx\fR pattern [...]
|
|
List files from the current working directory on local filesystem
|
|
which match shell patterns.
|
|
.TP
|
|
\fB\-ls_l\fR pattern [***]
|
|
Like -ls but also list some of the file attributes.
|
|
Output format resembles shell command ls -ldn.
|
|
.TP
|
|
> \fB\-ls_lx\fR pattern [...]
|
|
Like -lsx but also list some of the file attributes.
|
|
.TP
|
|
\fB\-du\fR pattern [***]
|
|
Recursively list size of directories and files matching one of the patterns,
|
|
similar to shell command du -k.
|
|
.TP
|
|
\fB\-du_s\fR pattern [***]
|
|
List size of directories and files matching one of the patterns,
|
|
similar to shell command du -sk.
|
|
.TP
|
|
> \fB\-find\fR pattern
|
|
Equivalent to shell command find . -name pattern in the ISO image.
|
|
.TP
|
|
> \fB\-findx\fR pattern
|
|
Equivalent to shell command find . -name pattern on filesystem.
|
|
.TP
|
|
.B Scripting, dialog and program control features:
|
|
.TP
|
|
\fB\-no_rc\fR
|
|
Only if used as first command line argument this option
|
|
prevents reading and interpretation of eventual startup
|
|
files. See section FILES below.
|
|
.TP
|
|
\fB\-help\fR
|
|
Print helptext.
|
|
.TP
|
|
\fB\-version\fR
|
|
Print program name and version.
|
|
.TP
|
|
\fB\-history\fR textline
|
|
Copy textline into libreadline history.
|
|
.TP
|
|
\fB\-status\fR [mode|filter]
|
|
Print the current settings of xorriso.
|
|
Modes:
|
|
short... print only important or altered settings
|
|
long ... print all settings including defaults
|
|
long_history like long plus history lines
|
|
.br
|
|
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.
|
|
.TP
|
|
\fB\-status_history_max\fR number
|
|
Set maximum number of history lines to be reported with -status "long_history".
|
|
.TP
|
|
\fB\-options_from_file\fR fileaddress
|
|
Reads lines from fileaddress and executes them as dialog lines.
|
|
.TP
|
|
\fB\-print\fR text
|
|
Print a text to result channel.
|
|
.TP
|
|
\fB\-prompt\fR text
|
|
Show text at beginning of output line and
|
|
wait for the user to hit the Enter key
|
|
resp. to send a line via stdin.
|
|
.TP
|
|
\fB\-end\fR
|
|
End program immediately
|
|
.TP
|
|
\fB#\fR 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.
|
|
.TP
|
|
.B Support for frontend programs talking into stdin and listening at stdout:
|
|
.TP
|
|
\fB\-pkt_output\fR "on"|"off"
|
|
Consolidate text output on stdout and classify each
|
|
line by a channel indicator:
|
|
.br
|
|
'R:' for result lines,
|
|
'I:' for notes and error messages,
|
|
'M:' for -mark texts.
|
|
.TP
|
|
\fB\-logfile\fR channel fileaddress
|
|
Copy output of a channel to the given file.
|
|
.TP
|
|
\fB\-mark\fR text
|
|
If text is not empty it will get put out each time an
|
|
action has been completed.
|
|
.TP
|
|
\fB\-temp_mem_limit\fR number["k"|"m"]
|
|
Set the maximum size of temporary memory to be used for image dependent
|
|
buffering. Currently this applies to pattern expansion only.
|
|
.br
|
|
Default is 16m = 16 MiB, minimum 64k = 64 kiB, maximum 1024m = 1 GiB.
|
|
.TP
|
|
\fB\-prog\fR text
|
|
Use text as this program's name in subsequent messages
|
|
.TP
|
|
\fB\-prog_help\fR text
|
|
Use text as this program's name and perform -help.
|
|
.br
|
|
.SH EXAMPLES
|
|
.SS
|
|
.B As superuser learn about available drives
|
|
Consider to give rw permissions to those users or groups
|
|
which shall be able to use the drives with xorriso.
|
|
.br
|
|
\fB$\fR xorriso -devices
|
|
.br
|
|
0 -dev '/dev/sr0' rwrw-- : '_NEC ' 'DVD_RW ND-4570A'
|
|
.br
|
|
1 -dev '/dev/sr1' rwrw-- : 'HL-DT-ST' 'DVDRAM GSA-4082B'
|
|
.br
|
|
2 -dev '/dev/sr2' rwrw-- : 'PHILIPS ' 'SPD3300L'
|
|
.SS
|
|
.B Blank media and compose a new ISO image as batch run
|
|
Aquire drive /dev/sr2, blank media resp. invalidate existing ISO image.
|
|
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
|
|
session to media.
|
|
.br
|
|
\fB$\fR xorriso -outdev /dev/sr2 \\
|
|
-blank fast \\
|
|
-graft-points \\
|
|
-add \\
|
|
/sounds=/home/me/sounds \\
|
|
/pictures \\
|
|
-- \\
|
|
-rm_r \\
|
|
/sounds/indecent \\
|
|
'/pictures/*private*' \\
|
|
/pictures/confidential \\
|
|
-- \\
|
|
-add \\
|
|
/pictures/confidential/work*
|
|
.br
|
|
Note that '/pictures/*private*' is a pattern for iso_rr_paths
|
|
while /pictures/confidential/work* gets expanded by the shell
|
|
with addresses from the hard disk.
|
|
.SS
|
|
.B A dialog session doing about the same
|
|
.br
|
|
-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
|
|
\fB$\fR xorriso -graft-points -dialog on -page 20 80
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-dev /dev/sr2
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-blank fast
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-add /sounds=/home/me/sounds /pictures
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-rm_r /sounds/indecent /pictures/*private* /pictures/confidential
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-add /pictures/confidential/work_office /pictures/confidential/work_factory
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-du /
|
|
.br
|
|
enter option and arguments :
|
|
.br
|
|
.B \-commit -eject all -end
|
|
.br
|
|
.SS
|
|
.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 the same DVD and eject.
|
|
.br
|
|
\fB$\fR xorriso -dev /dev/sr2 \\
|
|
-rm_r /sounds -- \\
|
|
-mv \\
|
|
/pictures/confidential \\
|
|
/pictures/restricted \\
|
|
-- \\
|
|
-chmod go-rwx /pictures/restricted -- \\
|
|
-graft-points \\
|
|
-add \\
|
|
/sounds=/home/me/prepared_for_dvd/sounds_dummy \\
|
|
/movies=/home/me/prepared_for_dvd/movies \\
|
|
-- \\
|
|
-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
|
|
As printed by program date:
|
|
.B 'Thu Nov 8 14:51:13 CET 2007'
|
|
.br
|
|
The same without ignored parts:
|
|
.B 'Nov 8 14:51:13 2007'
|
|
.br
|
|
The same as expected by date:
|
|
.B 110814512007.13
|
|
.br
|
|
Four weeks in the future:
|
|
.B +4w
|
|
.br
|
|
The current time:
|
|
.B +0
|
|
.br
|
|
Three hours ago:
|
|
.B \-3h
|
|
.br
|
|
Seconds since Jan 1 1970:
|
|
.B =1194531416
|
|
.br
|
|
.SH FILES
|
|
.SS
|
|
.B Startup files:
|
|
.br
|
|
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
|
|
.br
|
|
The files are read in the sequence given above, but none of them is required
|
|
for xorriso to function properly.
|
|
.br
|
|
.SH SEE ALSO
|
|
.TP
|
|
For mounting xorriso generated ISO 9660 images
|
|
.br
|
|
.BR mount(8)
|
|
.TP
|
|
Other programs which produce ISO 9660 images
|
|
.br
|
|
.BR mkisofs(8),
|
|
.BR genisoimage(8)
|
|
.TP
|
|
Other programs which burn sessions to optical media
|
|
.BR growisofs(1),
|
|
.BR cdrecord(1),
|
|
.BR wodim(1),
|
|
.BR cdrskin(1)
|
|
.br
|
|
.SH AUTHOR
|
|
Thomas Schmitt <scdbackup@gmx.net>
|
|
.br
|
|
for libburnia-project.org
|