Browse Source

Info document and man page for xorrecord

master
Thomas Schmitt 10 years ago
parent
commit
cae4e4f69b
  1. 6
      Makefile.am
  2. 1
      README
  3. 6
      xorriso/README_gnu_xorriso
  4. 7
      xorriso/convert_man_to_html.sh
  5. 3
      xorriso/emulators.c
  6. 4
      xorriso/make_docs.sh
  7. 9
      xorriso/make_xorriso_1.c
  8. 4
      xorriso/make_xorriso_standalone.sh
  9. 73
      xorriso/man_xorrecord_to_html.sh
  10. 741
      xorriso/xorrecord.1
  11. 928
      xorriso/xorrecord.info
  12. 1048
      xorriso/xorrecord.texi
  13. 8
      xorriso/xorriso.1
  14. 85
      xorriso/xorriso.info
  15. 7
      xorriso/xorriso.texi
  16. 6
      xorriso/xorriso_makefile_am.txt
  17. 2
      xorriso/xorriso_timestamp.h
  18. 5
      xorriso/xorrisofs.1
  19. 13
      xorriso/xorrisofs.info
  20. 9
      xorriso/xorrisofs.texi

6
Makefile.am

@ -222,11 +222,13 @@ nodist_pkgconfig_DATA = \
man_MANS = \
xorriso/xorriso.1 \
xorriso/xorrisofs.1
xorriso/xorrisofs.1 \
xorriso/xorrecord.1
info_TEXINFOS = \
xorriso/xorriso.texi \
xorriso/xorrisofs.texi
xorriso/xorrisofs.texi \
xorriso/xorrecord.texi
EXTRA_DIST = \
libisoburn-1.pc.in \

1
README

@ -89,6 +89,7 @@ xorriso binary depending on libburn.so, libisofs.so, libisoburn.so.
After installation documentation is available via
man xorriso
man xorrisofs
man xorrecord
Several alias links point to the xorriso binary:
xorrisofs starts xorriso with -as mkisofs emulation already enabled

6
xorriso/README_gnu_xorriso

@ -73,14 +73,14 @@ or you may execute as superuser:
For general concepts, options and usage examples see
info xorriso
info xorrisofs
info xorrecord
man 1 xorriso
man 1 xorrisofs
man 1 xorrecord
You may get a first glimpse by
You may get a first glimpse by e.g.
info ./xorriso/xorriso.info
info ./xorriso/xorrisofs.info
man ./xorriso/xorriso.1
man ./xorriso/xorrisofs.1
The installation creates several alias links pointing to the xorriso binary:
xorrisofs starts xorriso with -as mkisofs emulation already enabled

7
xorriso/convert_man_to_html.sh

@ -1,13 +1,14 @@
#!/bin/sh
#
# convert_man_to_html.sh - ts B10309
# convert_man_to_html.sh - ts B11024
#
# Generates a HTML version of man pages xorriso.1 , xorrisofs.1
# Generates a HTML version of man pages xorriso.1 , xorrisofs.1 , xorrecord.1
#
# To be executed in the libisoburn toplevel directory (eg. ./libisoburn-1.0.4)
# To be executed in the libisoburn toplevel directory (eg. ./libisoburn-1.1.8)
#
xorriso/man_xorriso_to_html.sh
xorriso/man_xorrisofs_to_html.sh
xorriso/man_xorrecord_to_html.sh

3
xorriso/emulators.c

@ -55,8 +55,9 @@ int Xorriso_cdrskin_help(struct XorrisO *xorriso, int flag)
"\t--devices\tprint list of available MMC drives and exit emulation",
"\tdev=target\tpseudo-SCSI target to use as CD-Recorder",
"\t-v\t\tincrement verbose level by one",
"\t-V\t\tincrement SCSI command transport verbose level by one",
"\t-checkdrive\tcheck if a driver for the drive is present",
"\t-inq\t\tdo an inquiry for the drive and exit emulation",
"\t-inq\t\tdo an inquiry for the drive",
"\tspeed=#\t\tset speed of drive",
"\tblank=type\tblank a CD-RW disc (see blank=help)",
"\tfs=#\t\tSet fifo size to # (0 to disable, default is 4 MB)",

4
xorriso/make_docs.sh

@ -2,12 +2,14 @@
#
# Produce man page xorriso/xorriso.1 and info file xorriso/xorriso.info
# from base file xorriso/xorriso.texi.
# Same for xorriso/xorrisofs.texi.
# Same for xorriso/xorrisofs.texi and xorriso/xorrecord.texi.
( cd xorriso ; makeinfo ./xorriso.texi )
( cd xorriso ; makeinfo ./xorrisofs.texi )
( cd xorriso ; makeinfo ./xorrecord.texi )
xorriso/make_xorriso_1 -auto
xorriso/make_xorriso_1 -auto -xorrisofs
xorriso/make_xorriso_1 -auto -xorrecord

9
xorriso/make_xorriso_1.c

@ -473,13 +473,16 @@ usage:;
exit(2);
}
for(i= 1; i < argc; i++) {
if(strcmp(argv[i], "-filter") == 0)
if(strcmp(argv[i], "-filter") == 0) {
as_filter= 1;
else if(strcmp(argv[i], "-auto") == 0)
} else if(strcmp(argv[i], "-auto") == 0) {
as_filter= 0;
else if(strcmp(argv[i], "-xorrisofs") == 0) {
} else if(strcmp(argv[i], "-xorrisofs") == 0) {
strcpy(name_in, "xorriso/xorrisofs.texi");
strcpy(name_out, "xorriso/xorrisofs.1");
} else if(strcmp(argv[i], "-xorrecord") == 0) {
strcpy(name_in, "xorriso/xorrecord.texi");
strcpy(name_out, "xorriso/xorrecord.1");
} else {
fprintf(stderr, "%s : unknown option %s\n", argv[0], argv[i]);
goto usage;

4
xorriso/make_xorriso_standalone.sh

@ -194,11 +194,15 @@ copy_files \
xorriso/xorriso.info \
xorriso/xorrisofs.texi \
xorriso/xorrisofs.info \
xorriso/xorrecord.texi \
xorriso/xorrecord.info \
xorriso/make_xorriso_1.c \
xorriso/xorriso.1 \
xorriso/xorrisofs.1 \
xorriso/xorrecord.1 \
xorriso/man_1_xorriso.html \
xorriso/man_1_xorrisofs.html \
xorriso/man_1_xorrecord.html \
"$lone_dir"/xorriso
copy_files COPYRIGHT "$lone_dir"/xorriso

73
xorriso/man_xorrecord_to_html.sh

@ -0,0 +1,73 @@
#!/bin/sh
#
# man_xorrecord_to_html.sh - ts A80118 , B10309
#
# Generates a HTML version of man page xorrecord.1
#
# To be executed in the libisoburn toplevel directory (eg. ./libisoburn-0.1.0)
#
# set -x
man_dir=$(pwd)"/xorriso"
export MANPATH="$man_dir"
manpage="xorrecord"
raw_html=$(pwd)/"xorriso/raw_man_1_xorrecord.html"
htmlpage=$(pwd)/"xorriso/man_1_xorrecord.html"
if test -r "$man_dir"/"$manpage".1
then
dummy=dummy
else
echo "Cannot find readable man page source $1" >&2
exit 1
fi
if test -e "$man_dir"/man1
then
dummy=dummy
else
ln -s . "$man_dir"/man1
fi
if test "$1" = "-work_as_filter"
then
# set -x
sed \
-e 's/<meta name="generator" content="groff -Thtml, see www.gnu.org">/<meta name="generator" content="groff -Thtml, via man -H, via xorriso\/convert_man_to_html.sh">/' \
-e 's/<meta name="Content-Style" content="text\/css">/<meta name="Content-Style" content="text\/css"><META NAME="description" CONTENT="man page of xorriso"><META NAME="keywords" CONTENT="man xorrecord, manual, xorrecord, CD, DVD, BD, cdrecord, compatible"><META NAME="robots" CONTENT="follow">/' \
-e 's/<title>XORRECORD<\/title>/<title>man 1 xorrecord<\/title>/' \
-e 's/<h1 align=center>XORRECORD<\/h1>/<h1 align=center>man 1 xorrecord<\/h1>/' \
-e 's/<body>/<body BGCOLOR="#F5DEB3" TEXT=#000000 LINK=#0000A0 VLINK=#800000>/' \
-e 's/<b>MMC, Session, Track, Media types:<\/b>/\&nbsp;<BR><b>MMC, Session, Track, Media types:<\/b>/' \
-e 's/<b>MMC, Session, Track, Media types:<\/b>/\&nbsp;<BR><b>MMC, Session, Track, Media types:<\/b>/' \
-e 's/<b>Relation to program xorriso:<\/b>/\&nbsp;<BR><b>Relation to program xorriso:<\/b>/' \
-e 's/EXAMPLES):<br>/<A HREF="#EXAMPLES">EXAMPLES<\/A>):<br>/' \
-e 's/<b>Drive addressing:<\/b>/\&nbsp;<BR><b>Drive addressing:<\/b><BR>\&nbsp;<BR>/' \
-e 's/<b>Inquiring drive and media:<\/b>/\&nbsp;<BR><b>Inquiring drive and media:<\/b><BR>\&nbsp;<BR>/' \
-e 's/<b>Settings for the burn run<\/b>/\&nbsp;<BR><b>Settings for the burn run:<\/b><BR>\&nbsp;<BR>/' \
-e 's/<b>Program version and verbosity:<\/b>/\&nbsp;<BR><b>Program version and verbosity:<\/b><BR>\&nbsp;<BR>/' \
-e 's/<b>Options not compatible to cdrecord:<\/b>/\&nbsp;<BR><b>Options not compatible to cdrecord:<\/b><BR>\&nbsp;<BR>/' \
\
-e 's/<\/body>/<BR><HR><FONT SIZE=-1><CENTER>(HTML generated from '"$manpage"'.1 on '"$(date)"' by '$(basename "$0")' )<\/CENTER><\/FONT><\/body>/' \
-e 's/&minus;/-/g' \
<"$2" >"$htmlpage"
set +x
chmod u+rw,go+r,go-w "$htmlpage"
echo "Emerged file:"
ls -lL "$htmlpage"
else
export BROWSER='cp "%s" '"$raw_html"
man -H "$manpage"
"$0" -work_as_filter "$raw_html"
rm "$raw_html"
rm "$man_dir"/man1
fi

741
xorriso/xorrecord.1

@ -0,0 +1,741 @@
.\" Hey, EMACS: -*- nroff -*-
.\"
.\" IMPORTANT NOTE:
.\"
.\" The original of this file is kept in xorriso/xorrecord.texi
.\" This here was generated by program xorriso/make_xorriso_1
.\"
.\"
.\" 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 XORRECORD 1 "Version 1.1.7, Oct 24, 2011"
.\" 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)
.nh
.SH NAME
xorrecord \- Emulation of CD/DVD/BD program cdrecord by program xorriso
.SH SYNOPSIS
.B xorrecord
[ options ] dev=device [track_source]
.br
.SH DESCRIPTION
.PP
\fBxorrecord\fR
writes preformatted data to CD, DVD, and BD media.
.br
.PP
It understands some options of program cdrecord from cdrtools by
Joerg Schilling.
Its implementation is part of program xorriso which shares no source
code with cdrtools, but rather makes use of libburn for communicating
with the drive.
.br
Another, more complete cdrecord emulator is program \fBcdrskin\fR
which uses the same burn functions as \fBxorrecord\fR.
.SS
\fBMMC, Session, Track, Media types:\fR
.br
\fBMMC\fR
is a standard out of the SCSI family which defines the interaction between
computers and optical drives. Since more than a decade all CD, DVD, or BD
recorders obey this standard regardless by what bus cabling they are
attached to the computer. libburn relies on this standard compliance and
on the capability of the operating system to perform SCSI transactions
over the particular bus cabling.
.br
A \fBSession\fR is a data region on an optical disc which usually
gets written in a single sweep. It contains at least one
\fBTrack\fR which is a contiguous string of readable blocks.
\fBxorrecord\fR produces a single session with a single data track
which consists of blocks with 2048 bytes each. It chooses the write mode
automatically according to media type, medium state, and option \-multi.
.br
On CD media there are other track types, like audio, and particular write
modes like TAO and SAO. CD and DVD\- media can put more than one track into
a session. Some of these features can be addressed by program \fBcdrskin\fR.
.br
MMC describes several recordable \fBmedia types\fR which roughly form two
families.
.br
\fBSequentially recordable media\fR
are CD\-R, CD\-RW, DVD\-R, DVD\-R DL, DVD\-RW, DVD+R, DVD+R DL, BD\-R.
Except DVD\-R DL they can store more than one session if there is still
unwritten space and if the previous session was written with option
\fB\-multi\fR. CD\-RW and DVD\-RW can be blanked in order to be re\-usable
from scratch.
.br
\fBOverwritable media\fR are DVD\-RAM, DVD+RW, formatted DVD\-RW, BD\-RE.
They offer a single session with a single track for random access writing.
There is no need to blank overwritable media before re\-use.
.br
DVD\-RW media are sold in sequentially recordable state but can be
formatted once to become overwritable. See options
\fBblank=format_overwrite\fR and \fBblank=deformat\fR.
.br
If ISO 9660 filesystems are to be stored on overwritable media, then it
is possible to emulate multiple sessions, by using option
\fB\-\-grow_overriteable_iso\fR. In this case, the need for
blanking before re\-use is emulated too.
.SS
.B Drive preparation and addressing:
.PP
The drives, CD, DVD, or BD burners, are accessed via file addresses which
are specific to libburn and the operating system. Those addresses get listed
by a run of \fBxorrecord \-\-devices\fR or \fBxorriso \-device_links\fR.
.br
On GNU/Linux and FreeBSD, the user needs rw\-permission for the device file.
On Solaris, the user needs r\-permission and privilege "sys_devices",
which is usually gained by running \fBxorrecord\fR via command pfexec.
.br
These permissions resp. privileges are needed already for listing a drive.
So it might be necessary to get the overview as superuser resp. via pfexec.
.br
\fBxorrecord\fR does not perform cdrecord option \-scanbus and does
not accept the addresses of form Bus,Target,Lun which are told by \-scanbus.
If support for these addresses is necessary, consider to use program cdrskin.
.br
It is possible to let \fBxorrecord\fR work on emulated drives.
Their addresses begin by prefix "stdio:" followed by a file address.
The emulated media behavior depends on the file type.
See man xorriso for details.
.br
If standard output is chosen as emulated drive, then all program result
texts, which usually appear on standard output, will get redirected to
standard error.
.SS
\fBRelation to program xorriso:\fR
.br
\fBxorrecord\fR is actually a command mode of program \fBxorriso\fR,
which gets entered either by xorriso command "\-as cdrecord" or by
starting the program by one of the names "xorrecord", "cdrecord",
"wodim", or "cdrskin".
.br
This command mode can be left by argument "\-\-" which leads
to generic xorriso command mode. See \fBman xorriso\fR for its description.
Other than in xorriso command mode, the sequence of the cdrecord emulation
options does not matter.
All pending actions get performed in a fixed sequence before the program
run ends resp. before cdrecord emulation ends.
.SS
.br
.SH OPTIONS
.br
.PP
.TP
.B Addressing the drive:
.TP
\fB--devices\fR
Print the list of accessible CD, DVD, or BD drives to standard output.
Drives might be inaccessible if the user lacks of permissions to use them
or if the drive is in use by another program.
.br
Each accessible drive is shown by a line like:
.br
0 \-dev '/dev/sr0' rwrw\-\- : 'TSSTcorp' 'CDDVDW SH\-S203B'
.br
The libburn address of this drive is '/dev/sr0'. 'TSSTcorp' is the
name of the vendor (in this case: Toshiba Samsung Storage Technologies
Corporation), 'CDDVDW SH\-S203B' is the model name (in this case: a DVD burner).
.TP
\fBdev=drive_address\fR
Set the libburn address of the drive to be used.
.br
E.g. on GNU/Linux: dev=/dev/sr0
.br
E.g. on FreeBSD: dev=/dev/cd0
.br
E.g. on Solaris: dev=/dev/rdsk/c2t2d0s2
.br
See also above "Drive preparation and addressing".
.br
The medium in the drive should not be mounted or be otherwise in use.
.TP
.B Inquiring drive and media:
.TP
\fB\-inq\fR
Print to standard output: vendor, model name, and firmware revision
of the drive.
.TP
\fB\-checkdrive\fR
Print unconditionally that the drive supports burnfree, SAO, and TAO.
Also print the output of option \-inq.
.TP
\fB\-atip\fR
Print the output of \-checkdrive, the most capable profile of the medium
in the drive, the list of profiles which are supported by the drive,
whether it is erasable (i.e. can be blanked), the media manufacturer, and
the medium product name.
.br
Profiles are usage models, which are often tied to a particular media type
(e.g. CD\-RW), but may also apply to a family of media. E.g. profile CD\-ROM
applies to all CD media which contain data.
.TP
\fB\-toc\fR
Print a table of content of the medium in the drive. The output is not
compatible to
cdrecord option \-toc, but rather the one of \fBxorriso\fR command \-toc.
It lists the address, vendor, model name, and firmware revision of the drive.
.br
About the medium it tells product name and manufacturer, whether there
is already content written, and if so, whether the medium is closed or
appendable. Appendable media can take another session.
The amount of readable and writable data is told.
If there are sessions, then their start block address and size is reported.
If a session contains an ISO 9660 filesystem, then its Volume Id is reported.
If the medium is writable, then the next writable block address is reported.
.br
If not option \fB\-\-grow_overriteable_iso\fR is given or no ISO 9660
file system is present on the medium, then overwritable media are reported
as being blank. This is due to the fact that they can be written from
scratch without further preparation, and that MMC does not distinguish
between data written by the most previous burn run and older data
which have not been overwritten by that burn run.
Consequently, these media are reported with 0 readable blocks, although
all their writable blocks normally are readable, too.
.TP
\fB\-msinfo\fR
Print the argument text for option \-C of programs mkisofs, genisoimage,
or xorrisofs. It consists of two numbers separated by a comma.
.br
The first number tells the first block of the first track of the last recorded
session. This is also the address used by default when operating systems
mount a medium with e.g. ISO 9660 filesystem.
.br
The second number tells the next writable address, where \fBxorrecord\fR
will begin to write the next session.
.br
This option is only valid for written, appendable media. In all other
cases it will yield no output text but will abort the program
with non\-zero exit value.
.TP
.B Settings for the burn run:
.PP
A burn run requires exactly one track source address argument, which
tells from where to read the data wich shall be put into the upcomming
session. The medium state must be either blank or appendable.
.br
Track source may be "\-" for standard input or the address of a readable
file of any type except directories. Nearly all media types accept a track
source with unpredictable byte count, like standard input or named pipes.
Nevertheless, DVD\-R DL and DVD\-RW blanked by mode deformat_quickest
demand exact in\-advance reservation of the track size, so that they either
need to be read from a source of
predictable length, or need to be accompanied by option \fBtsize=\fR or
by option \fB\-isosize\fR.
.br
Several options expect a size value as argument. A number with a trailing
letter "b" or without a trailing letter is a plain byte count. Other trailing
letters cause multiplication of the given number by a scaling factor:
.br
"k" or "K" = 1024 , "m" or "M" = 1024k , "g" or "G" = 1024m , "s" or "S" = 2048
.br
E.g. tsize=234567s means a size of 234567 * 2048 = 480393216 bytes.
.TP
\fBblank=mode\fR
Blank a CD\-RW or DVD\-RW to make it re\-usable from scratch.
Format a DVD\-RW, DVD+RW, DVD\-RAM, BD\-R, or BD\-RE if not yet formatted.
.br
This operation normally makes any recorded data on the medium unreadable.
It is combinable with burning in the same run of \fBxorrecord\fR,
or it may be performed without a track source, leaving the medium empty.
.br
The mode given with blank= selects the particular behavior:
.RS
.TP
.br
as_needed
.br
Try to make the media ready for writing from scratch. If it needs formatting,
then format it. If it is not blank, then try to apply blank=fast.
It is a reason to abort if the mediium cannot assume thoroughly writeable
state, e.g. if it is a non\-blank write\-once.
.br
This leaves unformatted DVD\-RW in unformatted blank state. To format DVD\-RW use
blank=format_overwrite. Blank unformatted BD\-R stay unformatted.
.br
(Note: blank=as_needed is not an original cdrecord option.)
.TP
.br
all
.br
Blank an entire CD\-RW or an unformatted DVD\-RW.
.TP
.br
fast
.br
Minimally blank an entire CD\-RW or blank an unformatted DVD\-RW.
.TP
.br
deformat
.br
Like blank=all but with the additional ability to blank overwriteable DVD\-RW.
This will destroy their formatting and make them sequentially recordable.
.br
(Note: blank=deformat is not an original cdrecord options)
.TP
.br
deformat_quickest
.br
Like blank=deformat but blanking DVD\-RW only minimally.
This is faster than full blanking but yields media incapable of
writing tracks of unpredicatable size.
Multi\-session will not be possible either.
.br
(Note: blank=deformat_quickest is not an original cdrecord option.)
.TP
.br
format_overwrite
.br
Format a DVD\-RW to "Restricted Overwrite". The user should bring some patience.
.br
Format unformatted DVD+RW, BD\-RE or blank BD\-R to their default size.
It is not mandatory to do this with DVD+RW and BD\-RE media, because they
will get formatted automatically on the first write attempt.
.br
BD\-R media may be written in unformatted state. This keeps disabled the
replacement of bad blocks and enables full nominal write speed. Once BD\-R
media are written, they cannot be formatted any more.
.br
For re\-formatting already formatted media or for formatting with
non\-default size, use program \fBxorriso\fR with command \fB\-format\fR.
.br
(Note: blank=format_overwrite is not an original cdrecord options)
.RE
.TP
\fB\-multi\fR
This option keeps CD, unformatted DVD\-R[W], DVD+R, or BD\-R appendable
after the current session has been written.
Without it the disc gets closed and may not be written any more \- unless it
is a \-RW and gets blanked, which causes loss of its content.
.br
This option cannot be applied to DVD\-R DL and DVD\-RW which were blanked
by type deformat_quickest.
.br
In order to have all filesystem content accessible, the eventual ISO\-9660
filesystem of a follow\-up
session needs to be prepared in a special way by the filesystem formatter
program. mkisofs, genisoimage, and xorrisofs expect particular info about
the situation which can be retrieved by \fBxorrecord\fR option \-msinfo.
.br
With overwriteable DVD or BD media, \-multi cannot mark the end of the session.
So when adding a new session, this end has to be determined from the payload.
Currently only ISO\-9660 filesystems can be used that way. See option
\fB\-\-grow_overwriteable_iso\fR.
.TP
\fB\-dummy\fR
Try to perform the drive operations without actually affecting the inserted
media. There is no warranty that this will work with a particular combination
of drive and media. Blanking is prevented reliably, though.
To avoid inadverted real burning, \-dummy refuses burn runs on anything but
CD\-R[W], DVD\-R[W], or emulated stdio\-drives.
.TP
\fB\-waiti\fR
Wait until input data is available at stdin or EOF occurs at stdin.
Only then begin to access any drives.
.br
One should use this if xorrisofs is working at the end of a pipe where the
feeder process reads from the drive before it starts writing its output into
xorrisofs. Example:
.br
xorrisofs ... \-C 0,12800 \-M /dev/sr0 ... | \\
.br
xorrecord dev=/dev/sr0 ... \-waiti \-
.br
This option works even if standard input is not the track source. If no process
is piping in, then the Enter key of your terminal will act as trigger for
\fBxorrecord\fR. Note that this input line will not be consumed by
cdrskin if standard input is not the track source. It will end up as shell
command, usually.
.TP
\fBtsize=size\fR
Announce the exact size of the track source. This is necessary with
DVD\-R DL media and with quickest blanked DVD\-RW, if the size cannot be
determined in advance from the track source. E.g. if it is standard input
or a named pipe.
.br
If the track source does not deliver the predicted amount of bytes, the
remainder of the track is padded with zeros. This is not considered an error.
If on the other hand the track source delivers more than the announced bytes
then the track on media gets truncated to the predicted size and xorrecord
exits with non\-zero value.
.TP
\fB\-isosize\fR
Try to obtain the track size from the content of the track source.
This works only if the track source bears an ISO 9660 filesystem.
Any other track source content will cause the burn run to abort.
.br
If the track source is not a regular file or block device, then this option
will work only if the program's fifo size is at least 64k. See option fs=.
.TP
\fBpadsize=size\fR
Add the given amount of trailing zeros to the upcomming track.
This feature can be disabled by size 0. Default is 300 kB in order to
work around a problem with GNU/Linux which often fails to read the last few
blocks of a CD track which was written in write mode TAO. TAO is used
by \fBxorrecord\fR if the track size cannot be predicted or if the CD
medium is not blank but appendable.
.TP
\fB\-nopad\fR
The same as padsize=0.
.TP
\fB\-pad\fR
The same as padsize=15s. This was once sufficient with older GNU/Linux
kernels. Meanwhile one should at least use padsize=128k, if not padsize=300k.
.TP
\fB\-data\fR
Explicitely announce that the track source shall be recorded as data track,
and not as audio track. This option has no effect with \fBxorrecord\fR,
because there is no support for other track formats anyway.
.TP
\fBfs=size\fR
Set the size of the program fifo buffer to the given value
rather than the default of 4m.
.br
The fifo buffers a temporary surplus of track source data in order to
provide the drive with a steady stream during times of temporary lack of track
source supply.
.br
Other than cdrecord, xorrecord enables drive buffer underrun protection by
default and does not wait with writing until the fifo is full for a first
time.
On very old CD drives and slow computers, this might cause aborted burn runs.
In this case, consider to use program \fBcdrskin\fR for CD burning.
DVD and BD drives tolerate buffer underrun without problems.
.br
The larger the fifo, the longer periods of poor source supply can be
compensated. But a large fifo can deprive the operating system of read cache
for better filesystem performance.
.TP
\fBspeed=value\fR
Set the write speed. Default is 0 = maximum speed.
Speed can be given in media type dependent x\-speed 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 appending "c" for CD, "d" for DVD, "b" for BD. "x" is optional.
.br
Example speeds:
.br
706k = 706kB/s = 4c = 4xCD
.br
5540k = 5540kB/s = 4d = 4xDVD
.br
If there is no hint about the speed unit attached, then the
medium in the drive will decide.
Default unit is CD, 1x = 176,400 raw bytes/second.
With DVD, 1x = 1,385,000 bytes/second.
With BD, 1x = 4,495,625 bytes/second.
.br
MMC drives usually activate their own idea of speed and take
the speed value given by the burn program only as a hint
for their own decision.
.TP
\fB\-eject\fR
Eject the drive tray after alll other work is done.
.TP
.B Program version and verbosity:
.TP
\fB\-version\fR
Print to standard output a line beginning by
.br
"Cdrecord 2.01\-Emulation Copyright"
.br
and further lines which report the version of xorriso and its
supporting libraries. They also state the license under which the program
is provided, and disclaim any warranty, to the extent permitted by law.
.TP
\fB\-v\fR
Increase program verbosity by one level. There are four verbosity levels
from nearly silent to debugging verbosity. The both highest levels can
be enabled by repeated \-v or by \-vv resp. \-vvv.
.TP
\fB\-V\fR
Log SCSI commands and drive replies to standard error.
This might be of interest if \fBxorrecord\fR and a particular drive
or medium do not cooperate as expected, or if you just want to know
how libburn interacts with the drive.
To understand this extremely verbous log, one needs to read SCSI
specs SPC, SBC, and MMC.
.br
Please do not add such a log to a bug report on the first hand,
unless you want to point out a particular deviation
from said specs, or if you get asked for this log by a maintainer of
\fBxorrecord\fR who feels in charge for your bug report.
.TP
\fB\-help\fR
Print a sparse list of program options to standard error
and declare not to be cdrecord.
.TP
.B Options not compatible to cdrecord:
.TP
\fB--no_rc\fR
Only if used as first command line argument this option
prevents reading and interpretation of startup files. See section FILES below.
.TP
\fB--grow_overwriteable_iso\fR
Enable emulation of multi\-session writing on overwriteable media which
contain an ISO 9660 filesystem. This emulation is learned from growisofs \-M
but adapted to the usage model of
.br
xorrecord \-msinfo
.br
xorrisofs \-C \-M | xorrecord \-waiti \-multi \-
.br
for sequential media.
.br
\-\-grow_overwriteable_iso does not hamper the use of true multi\-session media.
I.e. it is possible to use the same \fBxorrecord\fR options with both
kinds of media
and to achieve similar results if ISO 9660 filesystem images are to be written.
This option implies option \-isosize and therefore demands that the track
source is a ISO 9660 filesystem image.
.br
With overwriteable media and no option blank=fast|all present it expands an
eventual ISO 9660 filesystem on media. It is assumed that this image's inner
size description points to the end of the valuable data.
Overwriteable media with a recognizable ISO 9660 size will be regarded as
appendable rather than as blank. I.e. options \-msinfo and \-toc will work.
\-toc will always show a single session with its size increasing with
every added ISO 9660 image.
.TP
\fBstream_recording="on"|"off"|number\fR
Mode "on" requests that compliance to the desired speed setting is
preferred over management of write errors. With DVD\-RAM and BD this can
bring effective write speed near to the nominal write speed of the media.
But it will also disable the automatic use of replacement blocks
if write errors occur. It might as well be disliked or ignored by the drive.
.br
If a number is given, then error management stays enabled for all byte
addresses below that number. Any number below 16s is the same as "off".
.TP
\fBdvd_obs="default"|"32k"|"64k"\fR
Linux specific:
Set the number of bytes to be transmitted with each write operation to DVD
or BD media. Tracks get padded up to the next multiple of this write
size. A number of 64 KB may improve throughput with bus systems which
show latency problems. The default depends on media type, option
stream_recording=, and on compile time options.
.TP
\fBwrite_start_address=value\fR
Set the block address on overwritable media where to start writing the track.
With DVD+RW, DVD\-RAM or BD\-RE, byte_offset must be aligned to 2 kiB blocks,
but better is 32 kiB on DVD and 64 kiB on BD.
With formatted DVD\-RW 32 kiB alignment is mandatory.
.br
Other media are not suitable for this option.
.TP
\fBstdio_sync="on"|"off"|number\fR
Set the number of bytes after which to force output to emulated stdio: drives.
This forcing keeps the memory from being clogged with lots of
pending data for slow devices. Default "on" is the same as "16m".
Forced output can be disabled by "off".
.SH EXAMPLES
.SS
.B Overview of examples:
Get an overview of drives and their addresses
.br
Get info about a particular drive or loaded media
.br
Prepare CD-RW or DVD-RW for re-use, BD-R for bad block handling
.br
Format DVD-RW to avoid need for blanking before re-use
.br
De-format DVD-RW to make it capable of multi-session again
.br
Write a single ISO 9660 filesystem image
.br
Write multiple ISO 9660 sessions
.br
Write ISO 9660 session on-the-fly
.br
Write compressed afio archive on-the-fly
.br
.SS
.B Get an overview of drives and their addresses:
$ xorrecord \-\-devices
.SS
.B Get info about a particular drive and loaded media:
$ xorrecord dev=/dev/sr0 \-atip \-toc \-\-grow_overwriteable_iso
.SS
.B Prepare CD-RW or DVD-RW for re-use:
$ xorrecord \-v dev=/dev/sr0 blank=as_needed \-eject
.SS
.B Format DVD-RW to avoid need for blanking before re-use:
$ xorrecord \-v dev=/dev/sr0 blank=format_overwrite \-eject
.br
This command may also be used to format BD\-R media before first use,
in order to enable handling of write errors. Several hundred MB of spare
blocks will be reserved and write runs on such media will perform
with less than half nominal speed.
.SS
.B De-format DVD-RW to make it capable of multi-session again:
$ xorrecord \-v dev=/dev/sr0 blank=deformat
.SS
.B Write a single ISO 9660 filesystem image:
$ xorrecord \-v dev=/dev/sr0 speed=12 fs=8m \\
blank=as_needed \-eject padsize=300k my_image.iso
.SS
.B Write multiple ISO 9660 sessions:
This is possible with all media except minimally blanked DVD\-RW and DVD\-R DL,
which cannot do multi\-session.
.br
The first session is written like in the previous example, except that
option \-multi is used. It will contain the files of hard disk
directory ./tree1 under the ISO 9660 directory /dir1:
.br
$ xorrisofs \-o image_1.iso \-J \-graft\-points /dir1=./tree1
.br
$ xorrecord \-v dev=/dev/sr0 speed=12 fs=8m \\
.br
\-multi \-\-grow_overwritable_iso \\
.br
blank=as_needed \-eject padsize=300k image_1.iso
.br
For the second session xorrisofs needs to know the \-msinfo numbers
of the medium. Further it will read data from the medium by using the
system's read\-only CD\-ROM driver.
.br
It is advised to load the tray manually
or via dd by the CD\-ROM driver, rather than letting xorrecord do this
by its own SCSI driver. Many system CD\-ROM drivers do not take notice
of xorrecord's activities.
.br
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
.br
Now get the \-msinfo numbers:
.br
$ m=$(xorrecord dev=/dev/sr0 \-msinfo)
.br
and use them with xorrisofs to add ./tree2 to the image as /dir2:
.br
$ xorrisofs \-M /dev/sr0 \-C $m \-o image_2.iso \\
.br
\-J \-graft\-points /dir2=./tree2
.br
Now burn the new session onto the same medium. This time without blanking:
.br
$ xorrecord \-v dev=/dev/sr0 speed=12 fs=8m \\
.br
\-multi \-\-grow_overwritable_iso \\
.br
\-eject padsize=300k image_2.iso
.br
Operating systems which mount this medium will read the superblock
of the second session and show both directories /dir1 and /dir2.
.SS
.B Write ISO 9660 session on-the-fly:
It is possible to combine the run of \fBxorrisofs\fR and \fBxorrecord\fR
in a pipeline without storing the ISO 9660 image as file on hard disk:
.br
$ xorrisofs \-M /dev/sr0 \-C $m \\
.br
\-J \-graft\-points /dir2=./tree2 \\
.br
| xorrecord \-v dev=/dev/sr0 speed=12 fs=8m \\
.br
\-waiti \-multi \-\-grow_overwritable_iso \\
.br
\-eject padsize=300k \-
.br
This is also the main use case of program \fBxorriso\fR itself,
where this run would look like:
.br
$ xorriso \-dev /dev/sr0 \-joliet on \-speed 12 \-fs 8m \\
.br
\-map ./tree2 /dir2 \-commit_eject all
.SS
.B Write compressed afio archive on-the-fly:
This is possible with all media except minimally blanked DVD\-RW and DVD\-R DL.
Since the compressed output stream is of very variable speed, a larger fifo
is advised. Nevertheless, this example is not suitable for very old CD drives
which have no underrun protection and thus would abort the burn run on
temporary data shortage.
.br
$ find . | afio \-oZ \- | \\
.br
xorrecord \-v dev=/dev/sr0 speed=12 fs=64m \\
.br
\-multi padsize=300k \-
.br
afio archives do not contain references to absolute data block addresses. So
they need no special precautions for multi\-session. One may get the session
start addresses by option \-toc, and then use dd option skip= to begin reading
at one of those addresses. E.g. for listing its content:
.br
$ dd if=/dev/sr0 bs=2048 skip=64046 | afio \-tvZ \-
.br
afio will know when the end of the archive is reached.
.SH FILES
.SS
.B Startup files:
.br
If not \-\-no_rc is given as the first argument then \fBxorrecord\fR
attempts on startup to read and execute lines from the following files:
.br
/etc/default/xorriso
.br
/etc/opt/xorriso/rc
.br
/etc/xorriso/xorriso.conf
.br
$HOME/.xorrisorc
.br
The files are read in the sequence given here, but none of them is required
to exist. The lines are not interpreted as \fBxorrecord\fR options but
as generic \fBxorriso\fR commands. See man xorriso.
.SH SEE ALSO
.TP
For generic xorriso command mode
.BR xorriso(1)
.TP
Formatting track sources for xorrecord:
.BR xorrisofs(1),
.BR mkisofs(8),
.BR genisoimage(8),
.BR afio(1),
.BR star(1)
.TP
Other programs which burn sessions to optical media
.BR growisofs(1),
.BR cdrecord(1),
.BR wodim(1),
.BR cdrskin(1)
.SH BUGS
To report bugs, request help, or suggest enhancements for \fBxorriso\fR,
please send electronic mail to the public list <bug\-xorriso@gnu.org>.
If more privacy is desired, mail to <scdbackup@gmx.net>.
.br
Please describe what you expect \fBxorriso\fR to do,
the program arguments resp. commands by which you tried to achieve it,
the messages of \fBxorriso\fR, and the undesirable outcome of your
program run.
.br
Expect to get asked more questions before solutions can be proposed.
.SH AUTHOR
Thomas Schmitt <scdbackup@gmx.net>
.br
for libburnia\-project.org
.SH COPYRIGHT
Copyright (c) 2011 Thomas Schmitt
.br
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of xorriso. If you make use
of the license to derive modified versions of xorriso then you are entitled
to modify this text under that same license.
.SH CREDITS
\fBxorriso\fR is in part based on work by Vreixo Formoso who provides
libisofs together with Mario Danic who also leads the libburnia team.
Thanks to Andy Polyakov who invented emulated growing,
to Derek Foreman and Ben Jansens who once founded libburn.
.br
Compliments towards Joerg Schilling whose cdrtools served me for ten years.

928
xorriso/xorrecord.info

@ -0,0 +1,928 @@
This is xorrecord.info, produced by makeinfo version 4.8 from
./xorrecord.texi.
INFO-DIR-SECTION Archiving
START-INFO-DIR-ENTRY
* Xorrecord: (xorrecord). Emulates CD/DVD/BD program cdrecord
END-INFO-DIR-ENTRY
xorrecord - Emulation of CD/DVD/BD program cdrecord by program
xorriso
Copyright (C) 2011 - 2011 Thomas Schmitt
Permission is granted to distrubute this text freely.

File: xorrecord.info, Node: Top, Next: Overview, Up: (dir)
xorrecord 1.1.7
***************
xorrecord - Emulation of CD/DVD/BD program cdrecord by program xorriso
* Menu:
* Overview:: Overview
* Standards:: MMC, Session, Track, Media types
* Drive:: Drive preparation and addressing
* Xorriso:: Relation to program xorriso
* Options:: Options
* Examples:: Examples
* Files:: Files
* Seealso:: See also
* Bugreport:: Reporting bugs
* Legal:: Author, Copyright, Credits
* CommandIdx:: Alphabetic Command List
* ConceptIdx:: Alphabetic List of Concepts and Objects

File: xorrecord.info, Node: Overview, Next: Standards, Prev: Top, Up: Top
1 Overview
**********
`xorrecord' writes preformatted data to CD, DVD, and BD media.
It understands some options of program cdrecord from cdrtools by Joerg
Schilling. Its implementation is part of program xorriso which shares
no source code with cdrtools, but rather makes use of libburn for
communicating with the drive.
Another, more complete cdrecord emulator is program *cdrskin* which
uses the same burn functions as *xorrecord*.

File: xorrecord.info, Node: Standards, Next: Drive, Prev: Overview, Up: Top
2 MMC, Session, Track, Media types
**********************************
*MMC* is a standard out of the SCSI family which defines the
interaction between computers and optical drives. Since more than a
decade all CD, DVD, or BD recorders obey this standard regardless by
what bus cabling they are attached to the computer. libburn relies on
this standard compliance and on the capability of the operating system
to perform SCSI transactions over the particular bus cabling.
A *Session* is a data region on an optical disc which usually gets
written in a single sweep. It contains at least one *Track* which is a
contiguous string of readable blocks. `xorrecord' produces a single
session with a single data track which consists of blocks with 2048
bytes each. It chooses the write mode automatically according to media
type, medium state, and option -multi.
On CD media there are other track types, like audio, and particular
write modes like TAO and SAO. CD and DVD- media can put more than one
track into a session. Some of these features can be addressed by
program *cdrskin*.
MMC describes several recordable *media types* which roughly form two
families.
*Sequentially recordable media* are CD-R, CD-RW, DVD-R, DVD-R DL,
DVD-RW, DVD+R, DVD+R DL, BD-R. Except DVD-R DL they can store more
than one session if there is still unwritten space and if the previous
session was written with option *-multi*. CD-RW and DVD-RW can be
blanked in order to be re-usable from scratch.
*Overwritable media* are DVD-RAM, DVD+RW, formatted DVD-RW, BD-RE.
They offer a single session with a single track for random access
writing. There is no need to blank overwritable media before re-use.
DVD-RW media are sold in sequentially recordable state but can be
formatted once to become overwritable. See options
*blank=format_overwrite* and *blank=deformat*.
If ISO 9660 filesystems are to be stored on overwritable media, then it
is possible to emulate multiple sessions, by using option
*-grow_overriteable_iso*. In this case, the need for blanking before
re-use is emulated too.

File: xorrecord.info, Node: Drive, Next: Xorriso, Prev: Standards, Up: Top
3 Drive preparation and addressing
**********************************
The drives, CD, DVD, or BD burners, are accessed via file addresses
which are specific to libburn and the operating system. Those addresses
get listed by a run of `xorrecord --devices' or `xorriso -device_links'.
On GNU/Linux and FreeBSD, the user needs rw-permission for the device
file. On Solaris, the user needs r-permission and privilege
"sys_devices", which is usually gained by running `xorrecord' via
command pfexec.
These permissions resp. privileges are needed already for listing a
drive. So it might be necessary to get the overview as superuser resp.
via pfexec.
`xorrecord' does not perform cdrecord option -scanbus and does not
accept the addresses of form Bus,Target,Lun which are told by -scanbus.
If support for these addresses is necessary, consider to use program
cdrskin.
It is possible to let `xorrecord' work on emulated drives. Their
addresses begin by prefix "stdio:" followed by a file address. The
emulated media behavior depends on the file type. See man xorriso for
details.
If standard output is chosen as emulated drive, then all program result
texts, which usually appear on standard output, will get redirected to
standard error.

File: xorrecord.info, Node: Xorriso, Next: Options, Prev: Drive, Up: Top
4 Relation to program xorriso
*****************************
`xorrecord' is actually a command mode of program *xorriso*, which gets
entered either by xorriso command "-as cdrecord" or by starting the
program by one of the names "xorrecord", "cdrecord", "wodim", or
"cdrskin".
This command mode can be left by argument "--" which leads to generic
xorriso command mode. See *man xorriso* for its description. Other
than in xorriso command mode, the sequence of the cdrecord emulation
options does not matter. All pending actions get performed in a fixed
sequence before the program run ends resp. before cdrecord emulation
ends.

File: xorrecord.info, Node: Options, Next: Examples, Prev: Xorriso, Up: Top
5 Options
*********
* Menu:
* DriveAddr:: Drive addressing
* Inquire:: Inquiring drive and media
* SetBurn:: Settings for the burn run
* Verbous:: Program version and verbosity
* NonCdrecord:: Options not compatible to cdrecord

File: xorrecord.info, Node: DriveAddr, Next: Inquire, Prev: Options, Up: Options
5.1 Addressing the drive
========================
--devices
Print the list of accessible CD, DVD, or BD drives to standard
output. Drives might be inaccessible if the user lacks of
permissions to use them or if the drive is in use by another
program.
Each accessible drive is shown by a line like:
0 -dev '/dev/sr0' rwrw- : 'TSSTcorp' 'CDDVDW SH-S203B'
The libburn address of this drive is '/dev/sr0'. 'TSSTcorp' is the
name of the vendor (in this case: Toshiba Samsung Storage
Technologies Corporation), 'CDDVDW SH-S203B' is the model name (in
this case: a DVD burner).
dev=drive_address
Set the libburn address of the drive to be used.
E.g. on GNU/Linux: dev=/dev/sr0
E.g. on FreeBSD: dev=/dev/cd0
E.g. on Solaris: dev=/dev/rdsk/c2t2d0s2
See also above "Drive preparation and addressing".
The medium in the drive should not be mounted or be otherwise in
use.

File: xorrecord.info, Node: Inquire, Next: SetBurn, Prev: DriveAddr, Up: Options
5.2 Inquiring drive and media
=============================
-inq
Print to standard output: vendor, model name, and firmware revision
of the drive.
-checkdrive
Print unconditionally that the drive supports burnfree, SAO, and
TAO. Also print the output of option -inq.
-atip
Print the output of -checkdrive, the most capable profile of the
medium in the drive, the list of profiles which are supported by
the drive, whether it is erasable (i.e. can be blanked), the media
manufacturer, and the medium product name.
Profiles are usage models, which are often tied to a particular
media type (e.g. CD-RW), but may also apply to a family of media.
E.g. profile CD-ROM applies to all CD media which contain data.
-toc
Print a table of content of the medium in the drive. The output is
not compatible to cdrecord option -toc, but rather the one of
`xorriso' command -toc. It lists the address, vendor, model name,
and firmware revision of the drive.
About the medium it tells product name and manufacturer, whether
there is already content written, and if so, whether the medium is
closed or appendable. Appendable media can take another session.
The amount of readable and writable data is told. If there are
sessions, then their start block address and size is reported. If
a session contains an ISO 9660 filesystem, then its Volume Id is
reported. If the medium is writable, then the next writable block
address is reported.
If not option *-grow_overriteable_iso* is given or no ISO 9660
file system is present on the medium, then overwritable media are
reported as being blank. This is due to the fact that they can be
written from scratch without further preparation, and that MMC
does not distinguish between data written by the most previous
burn run and older data which have not been overwritten by that
burn run. Consequently, these media are reported with 0 readable
blocks, although all their writable blocks normally are readable,
too.
-msinfo
Print the argument text for option -C of programs mkisofs,
genisoimage, or xorrisofs. It consists of two numbers separated by
a comma.
The first number tells the first block of the first track of the
last recorded session. This is also the address used by default
when operating systems mount a medium with e.g. ISO 9660
filesystem.
The second number tells the next writable address, where
`xorrecord' will begin to write the next session.
This option is only valid for written, appendable media. In all
other cases it will yield no output text but will abort the program
with non-zero exit value.

File: xorrecord.info, Node: SetBurn, Next: Verbous, Prev: Inquire, Up: Options
5.3 Settings for the burn run
=============================
A burn run requires exactly one track source address argument,
which tells from where to read the data wich shall be put into the
upcomming session. The medium state must be either blank or
appendable.
Track source may be "-" for standard input or the address of a
readable file of any type except directories. Nearly all media
types accept a track source with unpredictable byte count, like
standard input or named pipes. Nevertheless, DVD-R DL and DVD-RW
blanked by mode deformat_quickest demand exact in-advance
reservation of the track size, so that they either need to be read
from a source of predictable length, or need to be accompanied by
option *tsize=* or by option *-isosize*.
Several options expect a size value as argument. A number with a
trailing letter "b" or without a trailing letter is a plain byte
count. Other trailing letters cause multiplication of the given
number by a scaling factor:
"k" or "K" = 1024 , "m" or "M" = 1024k , "g" or "G" = 1024m , "s"
or "S" = 2048
E.g. tsize=234567s means a size of 234567 * 2048 = 480393216 bytes.
blank=mode
Blank a CD-RW or DVD-RW to make it re-usable from scratch. Format
a DVD-RW, DVD+RW, DVD-RAM, BD-R, or BD-RE if not yet formatted.
This operation normally makes any recorded data on the medium
unreadable. It is combinable with burning in the same run of
`xorrecord', or it may be performed without a track source,
leaving the medium empty.
The mode given with blank= selects the particular behavior:
as_needed
Try to make the media ready for writing from scratch. If it needs
formatting, then format it. If it is not blank, then try to apply
blank=fast. It is a reason to abort if the mediium cannot assume
thoroughly writeable state, e.g. if it is a non-blank write-once.
This leaves unformatted DVD-RW in unformatted blank state. To
format DVD-RW use blank=format_overwrite. Blank unformatted BD-R
stay unformatted.
(Note: blank=as_needed is not an original cdrecord option.)
all
Blank an entire CD-RW or an unformatted DVD-RW.
fast
Minimally blank an entire CD-RW or blank an unformatted DVD-RW.
deformat
Like blank=all but with the additional ability to blank
overwriteable DVD-RW. This will destroy their formatting and make
them sequentially recordable.
(Note: blank=deformat is not an original cdrecord options)
deformat_quickest
Like blank=deformat but blanking DVD-RW only minimally. This is
faster than full blanking but yields media incapable of writing
tracks of unpredicatable size. Multi-session will not be possible
either.
(Note: blank=deformat_quickest is not an original cdrecord option.)
format_overwrite
Format a DVD-RW to "Restricted Overwrite". The user should bring
some patience.
Format unformatted DVD+RW, BD-RE or blank BD-R to their default
size. It is not mandatory to do this with DVD+RW and BD-RE media,
because they will get formatted automatically on the first write
attempt.
BD-R media may be written in unformatted state. This keeps
disabled the replacement of bad blocks and enables full nominal
write speed. Once BD-R media are written, they cannot be formatted
any more.
For re-formatting already formatted media or for formatting with
non-default size, use program *xorriso* with command *-format*.
(Note: blank=format_overwrite is not an original cdrecord options)
-multi
This option keeps CD, unformatted DVD-R[W], DVD+R, or BD-R
appendable after the current session has been written. Without it
the disc gets closed and may not be written any more - unless it
is a -RW and gets blanked, which causes loss of its content.
This option cannot be applied to DVD-R DL and DVD-RW which were
blanked by type deformat_quickest.
In order to have all filesystem content accessible, the eventual
ISO-9660 filesystem of a follow-up session needs to be prepared in
a special way by the filesystem formatter program. mkisofs,
genisoimage, and xorrisofs expect particular info about the
situation which can be retrieved by `xorrecord' option -msinfo.
With overwriteable DVD or BD media, -multi cannot mark the end of
the session. So when adding a new session, this end has to be
determined from the payload. Currently only ISO-9660 filesystems
can be used that way. See option *-grow_overwriteable_iso*.
-dummy
Try to perform the drive operations without actually affecting the
inserted media. There is no warranty that this will work with a
particular combination of drive and media. Blanking is prevented
reliably, though. To avoid inadverted real burning, -dummy
refuses burn runs on anything but CD-R[W], DVD-R[W], or emulated
stdio-drives.
-waiti
Wait until input data is available at stdin or EOF occurs at stdin.
Only then begin to access any drives.
One should use this if xorrisofs is working at the end of a pipe
where the feeder process reads from the drive before it starts
writing its output into xorrisofs. Example:
xorrisofs ... -C 0,12800 -M /dev/sr0 ... | \
xorrecord dev=/dev/sr0 ... -waiti -
This option works even if standard input is not the track source.
If no process is piping in, then the Enter key of your terminal
will act as trigger for `xorrecord'. Note that this input line
will not be consumed by cdrskin if standard input is not the track
source. It will end up as shell command, usually.
tsize=size
Announce the exact size of the track source. This is necessary with
DVD-R DL media and with quickest blanked DVD-RW, if the size
cannot be determined in advance from the track source. E.g. if it
is standard input or a named pipe.
If the track source does not deliver the predicted amount of
bytes, the remainder of the track is padded with zeros. This is
not considered an error. If on the other hand the track source
delivers more than the announced bytes then the track on media
gets truncated to the predicted size and xorrecord exits with
non-zero value.
-isosize
Try to obtain the track size from the content of the track source.
This works only if the track source bears an ISO 9660 filesystem.
Any other track source content will cause the burn run to abort.
If the track source is not a regular file or block device, then
this option will work only if the program's fifo size is at least
64k. See option fs=.
padsize=size
Add the given amount of trailing zeros to the upcomming track.
This feature can be disabled by size 0. Default is 300 kB in order
to work around a problem with GNU/Linux which often fails to read
the last few blocks of a CD track which was written in write mode
TAO. TAO is used by `xorrecord' if the track size cannot be
predicted or if the CD medium is not blank but appendable.
-nopad
The same as padsize=0.
-pad
The same as padsize=15s. This was once sufficient with older
GNU/Linux kernels. Meanwhile one should at least use padsize=128k,
if not padsize=300k.
-data
Explicitely announce that the track source shall be recorded as
data track, and not as audio track. This option has no effect with
`xorrecord', because there is no support for other track formats
anyway.
fs=size
Set the size of the program fifo buffer to the given value rather
than the default of 4m.
The fifo buffers a temporary surplus of track source data in order
to provide the drive with a steady stream during times of
temporary lack of track source supply.
Other than cdrecord, xorrecord enables drive buffer underrun
protection by default and does not wait with writing until the
fifo is full for a first time. On very old CD drives and slow
computers, this might cause aborted burn runs. In this case,
consider to use program *cdrskin* for CD burning. DVD and BD
drives tolerate buffer underrun without problems.
The larger the fifo, the longer periods of poor source supply can
be compensated. But a large fifo can deprive the operating system
of read cache for better filesystem performance.
speed=value
Set the write speed. Default is 0 = maximum speed. Speed can be
given in media type dependent x-speed 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 appending "c"
for CD, "d" for DVD, "b" for BD. "x" is optional.
Example speeds:
706k = 706kB/s = 4c = 4xCD
5540k = 5540kB/s = 4d = 4xDVD
If there is no hint about the speed unit attached, then the medium
in the drive will decide. Default unit is CD, 1x = 176,400 raw
bytes/second. With DVD, 1x = 1,385,000 bytes/second. With BD, 1x
= 4,495,625 bytes/second.
MMC drives usually activate their own idea of speed and take the
speed value given by the burn program only as a hint for their own
decision.
-eject
Eject the drive tray after alll other work is done.

File: xorrecord.info, Node: Verbous, Next: NonCdrecord, Prev: SetBurn, Up: Options
5.4 Program version and verbosity
=================================
-version
Print to standard output a line beginning by
"Cdrecord 2.01-Emulation Copyright"
and further lines which report the version of xorriso and its
supporting libraries. They also state the license under which the
program is provided, and disclaim any warranty, to the extent
permitted by law.
-v
Increase program verbosity by one level. There are four verbosity
levels from nearly silent to debugging verbosity. The both highest
levels can be enabled by repeated -v or by -vv resp. -vvv.
-V
Log SCSI commands and drive replies to standard error. This might
be of interest if *xorrecord* and a particular drive or medium do
not cooperate as expected, or if you just want to know how libburn
interacts with the drive. To understand this extremely verbous
log, one needs to read SCSI specs SPC, SBC, and MMC.
Please do not add such a log to a bug report on the first hand,
unless you want to point out a particular deviation from said
specs, or if you get asked for this log by a maintainer of
`xorrecord' who feels in charge for your bug report.
-help
Print a sparse list of program options to standard error and
declare not to be cdrecord.

File: xorrecord.info, Node: NonCdrecord, Next: ExDevices, Prev: Verbous, Up: Options
5.5 Options not compatible to cdrecord
======================================
--no_rc
Only if used as first command line argument this option prevents
reading and interpretation of startup files. See section FILES
below.
--grow_overwriteable_iso
Enable emulation of multi-session writing on overwriteable media
which contain an ISO 9660 filesystem. This emulation is learned
from growisofs -M but adapted to the usage model of
xorrecord -msinfo
xorrisofs -C -M | xorrecord -waiti -multi -
for sequential media.
-grow_overwriteable_iso does not hamper the use of true
multi-session media. I.e. it is possible to use the same
`xorrecord' options with both kinds of media and to achieve
similar results if ISO 9660 filesystem images are to be written.
This option implies option -isosize and therefore demands that the
track source is a ISO 9660 filesystem image.
With overwriteable media and no option blank=fast|all present it
expands an eventual ISO 9660 filesystem on media. It is assumed
that this image's inner size description points to the end of the
valuable data. Overwriteable media with a recognizable ISO 9660
size will be regarded as appendable rather than as blank. I.e.
options -msinfo and -toc will work. -toc will always show a
single session with its size increasing with every added ISO 9660
image.
stream_recording="on"|"off"|number
Mode "on" requests that compliance to the desired speed setting is
preferred over management of write errors. With DVD-RAM and BD
this can bring effective write speed near to the nominal write
speed of the media. But it will also disable the automatic use of
replacement blocks if write errors occur. It might as well be
disliked or ignored by the drive.
If a number is given, then error management stays enabled for all
byte addresses below that number. Any number below 16s is the same
as "off".
dvd_obs="default"|"32k"|"64k"
Linux specific: Set the number of bytes to be transmitted with
each write operation to DVD or BD media. Tracks get padded up to
the next multiple of this write size. A number of 64 KB may
improve throughput with bus systems which show latency problems.
The default depends on media type, option stream_recording=, and
on compile time options.
write_start_address=value
Set the block address on overwritable media where to start writing
the track. With DVD+RW, DVD-RAM or BD-RE, byte_offset must be
aligned to 2 kiB blocks, but better is 32 kiB on DVD and 64 kiB on
BD. With formatted DVD-RW 32 kiB alignment is mandatory.
Other media are not suitable for this option.
stdio_sync="on"|"off"|number
Set the number of bytes after which to force output to emulated
stdio: drives. This forcing keeps the memory from being clogged
with lots of pending data for slow devices. Default "on" is the
same as "16m". Forced output can be disabled by "off".

File: xorrecord.info, Node: Examples, Next: Files, Prev: Options, Up: Top
6 Examples
**********
* Menu:
* ExDevices:: Get an overview of drives and their addresses
* ExMedium:: Get info about a particular drive or loaded media
* ExBlank:: Prepare CD-RW or DVD-RW for re-use
* ExFormat:: Format DVD-RW to avoid need for blanking before re-use
* ExDeformat:: De-format DVD-RW to make it capable of multi-session again
* ExIsoSingle:: Write a single ISO 9660 filesystem image
* ExIsoMulti:: Write multiple ISO 9660 sessions
* ExIsoFly:: Write ISO 9660 session on-the-fly
* ExAfio:: Write compressed afio archive on-the-fly

File: xorrecord.info, Node: ExDevices, Next: ExMedium, Prev: NonCdrecord, Up: Examples
6.1 Get an overview of drives and their addresses
=================================================
$ xorrecord -devices

File: xorrecord.info, Node: ExMedium, Next: ExBlank, Prev: ExDevices, Up: Examples
6.2 Get info about a particular drive and loaded media
======================================================
$ xorrecord dev=/dev/sr0 -atip -toc -grow_overwriteable_iso

File: xorrecord.info, Node: ExBlank, Next: ExFormat, Prev: ExMedium, Up: Examples
6.3 Prepare CD-RW or DVD-RW for re-use
======================================
$ xorrecord -v dev=/dev/sr0 blank=as_needed -eject

File: xorrecord.info, Node: ExFormat, Next: ExDeformat, Prev: ExBlank, Up: Examples
6.4 Format DVD-RW to avoid need for blanking before re-use
==========================================================
$ xorrecord -v dev=/dev/sr0 blank=format_overwrite -eject
This command may also be used to format BD-R media before first use, in
order to enable handling of write errors. Several hundred MB of spare
blocks will be reserved and write runs on such media will perform with
less than half nominal speed.

File: xorrecord.info, Node: ExDeformat, Next: ExIsoSingle, Prev: ExFormat, Up: Examples
6.5 De-format DVD-RW to make it capable of multi-session again
==============================================================
$ xorrecord -v dev=/dev/sr0 blank=deformat

File: xorrecord.info, Node: ExIsoSingle, Next: ExIsoMulti, Prev: ExDeformat, Up: Examples
6.6 Write a single ISO 9660 filesystem image
============================================
$ xorrecord -v dev=/dev/sr0 speed=12 fs=8m \
blank=as_needed -eject padsize=300k my_image.iso

File: xorrecord.info, Node: ExIsoMulti, Next: ExIsoFly, Prev: ExIsoSingle, Up: Examples
6.7 Write multiple ISO 9660 sessions
====================================
This is possible with all media except minimally blanked DVD-RW and
DVD-R DL, which cannot do multi-session.
The first session is written like in the previous example, except that
option -multi is used. It will contain the files of hard disk directory
./tree1 under the ISO 9660 directory /dir1:
$ xorrisofs -o image_1.iso -J -graft-points /dir1=./tree1
$ xorrecord -v dev=/dev/sr0 speed=12 fs=8m \
-multi -grow_overwritable_iso \
blank=as_needed -eject padsize=300k image_1.iso
For the second session xorrisofs needs to know the -msinfo numbers of
the medium. Further it will read data from the medium by using the
system's read-only CD-ROM driver.
It is advised to load the tray manually or via dd by the CD-ROM driver,
rather than letting xorrecord do this by its own SCSI driver. Many
system CD-ROM drivers do not take notice of xorrecord's activities.
$ dd if=/dev/sr0 count=1 >/dev/null 2>&1
Now get the -msinfo numbers:
$ m=$(xorrecord dev=/dev/sr0 -msinfo)
and use them with xorrisofs to add ./tree2 to the image as /dir2:
$ xorrisofs -M /dev/sr0 -C $m -o image_2.iso \
-J -graft-points /dir2=./tree2
Now burn the new session onto the same medium. This time without
blanking:
$ xorrecord -v dev=/dev/sr0 speed=12 fs=8m \
-multi -grow_overwritable_iso \
-eject padsize=300k image_2.iso
Operating systems which mount this medium will read the superblock of
the second session and show both directories /dir1 and /dir2.

File: xorrecord.info, Node: ExIsoFly, Next: ExAfio, Prev: ExIsoMulti, Up: Examples
6.8 Write ISO 9660 session on-the-fly
=====================================
It is possible to combine the run of *xorrisofs* and `xorrecord' in a
pipeline without storing the ISO 9660 image as file on hard disk:
$ xorrisofs -M /dev/sr0 -C $m \
-J -graft-points /dir2=./tree2 \
| xorrecord -v dev=/dev/sr0 speed=12 fs=8m \
-waiti -multi -grow_overwritable_iso \
-eject padsize=300k -
This is also the main use case of program *xorriso* itself, where this
run would look like:
$ xorriso -dev /dev/sr0 -joliet on -speed 12 -fs 8m \
-map ./tree2 /dir2 -commit_eject all

File: xorrecord.info, Node: ExAfio, Prev: ExIsoFly, Up: Examples
6.9 Write compressed afio archive on-the-fly
============================================
This is possible with all media except minimally blanked DVD-RW and
DVD-R DL. Since the compressed output stream is of very variable
speed, a larger fifo is advised. Nevertheless, this example is not
suitable for very old CD drives which have no underrun protection and
thus would abort the burn run on temporary data shortage.
$ find . | afio -oZ - | \
xorrecord -v dev=/dev/sr0 speed=12 fs=64m \
-multi padsize=300k -
afio archives do not contain references to absolute data block
addresses. So they need no special precautions for multi-session. One
may get the session start addresses by option -toc, and then use dd
option skip= to begin reading at one of those addresses. E.g. for
listing its content:
$ dd if=/dev/sr0 bs=2048 skip=64046 | afio -tvZ -
afio will know when the end of the archive is reached.

File: xorrecord.info, Node: Files, Next: Seealso, Prev: Examples, Up: Top
7 Files
*******
7.1 Startup Files
=================
If not -no_rc is given as the first argument then `xorrecord' attempts
on startup to read and execute lines from the following files:
/etc/default/xorriso
/etc/opt/xorriso/rc
/etc/xorriso/xorriso.conf
$HOME/.xorrisorc
The files are read in the sequence given here, but none of them is
required to exist. The lines are not interpreted as `xorrecord' options
but as generic *xorriso* commands. See man xorriso.

File: xorrecord.info, Node: Seealso, Next: Bugreport, Prev: Files, Up: Top
8 See also
**********
For generic xorriso command mode
xorriso(1)
Formatting track sources for xorrecord
xorrisofs(1), mkisofs(8), genisoimage(8), afio(1), star(1)
Other programs which burn sessions to optical media
growisofs(1), cdrecord(1), wodim(1), cdrskin(1)

File: xorrecord.info, Node: Bugreport, Next: Legal, Prev: Seealso, Up: Top
9 Reporting bugs
****************
To report bugs, request help, or suggest enhancements for `xorriso',
please send electronic mail to the public list <bug-xorriso@gnu.org>.
If more privacy is desired, mail to <scdbackup@gmx.net>.
Please describe what you expect `xorriso' to do, the program arguments
resp. commands by which you tried to achieve it, the messages of
`xorriso', and the undesirable outcome of your program run.
Expect to get asked more questions before solutions can be proposed.

File: xorrecord.info, Node: Legal, Next: CommandIdx, Prev: Bugreport, Up: Top
10 Author, Copyright, Credits
*****************************
10.1 Author
===========
Thomas Schmitt <scdbackup@gmx.net>
for libburnia-project.org
10.2 Copyright
==============
Copyright (c) 2011 Thomas Schmitt
Permission is granted to distribute this text freely. It shall only be
modified in sync with the technical properties of xorriso. If you make
use of the license to derive modified versions of xorriso then you are
entitled to modify this text under that same license.
10.3 Credits
============
`xorriso' is in part based on work by Vreixo Formoso who provides
libisofs together with Mario Danic who also leads the libburnia team.
Thanks to Andy Polyakov who invented emulated growing, to Derek Foreman
and Ben Jansens who once founded libburn.
Compliments towards Joerg Schilling whose cdrtools served me for ten
years.

File: xorrecord.info, Node: CommandIdx, Next: ConceptIdx, Prev: Legal, Up: Top
11 Alphabetic Command List
**************************
[index]
* Menu:
* --devices get list of drives: DriveAddr. (line 8)
* --grow_overwriteable_iso emulate ISO 9660 multi-session: NonCdrecord.
(line 13)
* --no_rc do not execute xorriso startup files: NonCdrecord.
(line 8)
* -atip inquire medium state: Inquire. (line 16)
* -checkdrive inquire drive CD capabilities: Inquire. (line 12)
* -data explicitely announce a data track: SetBurn. (line 155)
* -dummy control write simulation: SetBurn. (line 97)
* -eject finally eject drive tray: SetBurn. (line 194)
* -help print sparse overview of options: Verbous. (line 32)
* -inq inquire drive identifiers: Inquire. (line 8)
* -isosize obtain track size from ISO 9660 superblock: SetBurn.
(line 131)
* -msinfo retrieve multi-session info: Inquire. (line 48)
* -multi keep media appendable after burn run: SetBurn. (line 80)
* -nopad disable adding of bytes to end of track: SetBurn. (line 147)
* -pad add 15 blocks to end of track: SetBurn. (line 150)
* -toc inquire medium content: Inquire. (line 25)
* -v increase program verbosity: Verbous. (line 16)
* -V log SCSI command transactions to stderr: Verbous. (line 21)
* -version report emulation and xorriso version: Verbous. (line 8)
* -waiti access drive only after stdin delivers data: SetBurn.
(line 105)
* blank= make media re-usabable or format media: SetBurn. (line 27)
* dev= address the drive to be used: DriveAddr. (line 20)
* dvd_obs= set write transaction payload size: NonCdrecord. (line 46)
* fs= set program fifo size: SetBurn. (line 161)
* padsize= add bytes to end of track: SetBurn. (line 139)
* speed= set write speed: SetBurn. (line 177)
* stdio_sync= control stdio buffer: NonCdrecord. (line 61)
* stream_recording= try to get full speed on DVD-RAM, BD: NonCdrecord.
(line 35)
* tsize= set a fixed track size: SetBurn. (line 119)
* write_start_address= set block address for write start: NonCdrecord.
(line 54)

File: xorrecord.info, Node: ConceptIdx, Prev: CommandIdx, Up: Top
12 Alphabetic List of Concepts and Objects
******************************************
[index]
* Menu:
* Accessing drive, wait for stdin, -waiti: SetBurn. (line 105)
* Bugs, reporting: Bugreport. (line 6)
* Data track, announce, -data: SetBurn. (line 155)
* Defect management, control, stream_recording=: NonCdrecord. (line 35)
* Drive, address, dev=: DriveAddr. (line 20)
* Drive, get list of, --devices: DriveAddr. (line 8)
* Drive, inquire CD capabilities, -checkdrive: Inquire. (line 12)
* Drive, inquire identifiers, -inq: Inquire. (line 8)
* Eject, the tray, -eject: SetBurn. (line 194)
* Examples: Examples. (line 6)
* Fifo, set size, fs=: SetBurn. (line 161)
* Full speed, on DVD-RAM and BD, stream_recording=: NonCdrecord.
(line 35)
* Media types, _definiton: Standards. (line 23)
* Media, blank, blank=: SetBurn. (line 27)
* Media, format, blank=: SetBurn. (line 27)
* Media, keep appendable, -multi: SetBurn. (line 80)
* Media, make re-usable, blank=: SetBurn. (line 27)
* medium content, inquire, -toc: Inquire. (line 25)
* medium state, inquire, -atip: Inquire. (line 16)
* MMC, _definiton: Standards. (line 6)
* multi-session info, retrieve, -msinfo: Inquire. (line 48)
* Multi-session, emulate ISO 9660, --grow_overwriteable_iso: NonCdrecord.
(line 13)
* Options, overview, -help: Verbous. (line 32)
* Overwritable media, _definiton: Standards. (line 30)
* Padding, at end of track, padsize=: SetBurn. (line 139)
* Padding, disable, -nopad: SetBurn. (line 147)
* Padding, insufficient old, -pad: SetBurn. (line 150)
* Problems, reporting: Bugreport. (line 6)
* SCSI commands, log, -V: Verbous. (line 21)
* Sequentially recordable media, _definiton: Standards. (line 25)
* Session, _definiton: Standards. (line 12)
* Speed, set for writing, speed=: SetBurn. (line 177)
* Startup files, do not execute, --no_rc: NonCdrecord. (line 8)