.\"                                      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 11, 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
Libburn drives
.br
Rock Ridge, POSIX, X/Open
.br
Command processing
.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
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.
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.
.PP
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.
.PP
xorriso adopts the concept of session by loading an eventual image directory
tree, allowing to manipulate it by several actions, and to write the new
image to the target media.
.br
The first session of a xorriso run begins by the definition of the input
drive with the eventual ISO image and ends by command -commit which triggers
writing. A -commit is done automatically when the program ends regularly.
.PP
After -commit a new session begins. A new input drive can only be chosen
as long as the loaded ISO image was not altered.
Pending alteration can be revoked by command -rollback.
.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 Libburn drives:
.br
Source of an existing ISO image can be any random access readable libburn
drive: optical media with readable data, regular files, block devices.
.br
RockRidge info must be present in existing ISO images and it will be generated
by the program unconditionally.
.PP
Target for writing can be any libburn drive.
Some drive types do not support the method of growing but only the method
of modifying.
.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 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 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.
.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. Switch from
growing to modifying. Same restrictions as with -dev
.TP
> \fB\-outdev\fR address
Set output drive and switch from growing to modifying.
.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 faster but produces media which are
only suitable for a single session. xorriso will write onto
them only if option -close is set to "on".
.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
RockRidge 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 -dev /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
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 -end
.br
.SS
.B Modifying an existing ISO image
Remove (i.e. hide) directory /sounds and its subordinates.
Rename directory /pictures/confidential to /pictures/restricted.
Change access permissions of directory /pictures/restricted.
Add dummy as replacement of /pictures/confidential.
Add new directory tree /movies. Burn to DVD and eject.
.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
.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 images 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