legacy/libburn/trunk/cdrskin/cdrskin.1

.\"                                      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 CDRSKIN 1 "January 2, 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
cdrskin \- burns preformatted data to CD-R, CD-RW or DVD+/-RW via libburn.
.SH SYNOPSIS
.B cdrskin
.RI [ options | track_source_addresses ]
.br
.SH DESCRIPTION
.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics, 
.\" respectively.
.PP 
\fBcdrskin\fP is a program that provides some of cdrecord's options
in a compatible way for CD media. With DVD it has its own ways for now. 
You do not need to be superuser for its daily usage.
.PP
.B Overview of features:
.br
Blanking of CD-RW.
.br
Burning of data or audio tracks to CD,
.br
either in versatile Track at Once mode (TAO)
.br
or in Session at Once mode for seamless tracks.
.br
Multi session on CD (follow-up sessions in TAO only).
.br
Bus scan, burnfree, speed options, retrieving media info, padding, fifo.
.br
Burning of a single data track to DVD+RW or DVD-RW.
.br
See section EXAMPLES at the end of this text.
.PP
.B Track recording model:
.br
The input-output entities which get processed are called tracks.
A \fBtrack\fP stores a stream of bytes.
.br
Each track is initiated by one track source address argument, which may either
be "-" for standard input or the address of a readable file. If no write mode
is given explicitely then one will be chosen which matches the peculiarities
of track sources and the state of the output media.
.PP
More than one track can be burned by a single run of cdrskin. 
In the terms of the MMC standard all tracks written by the same run constitute
a \fBsession\fP.
.br
CDs can be kept appendable so that further tracks can
be written to them in subsequent runs of cdrskin (see option -multi).
Info about the addresses of burned tracks is kept in a table of
content (TOC) on media and can be retrieved via cdrskin option -toc.
These informations are also used by the operating systems' CD-ROM read drivers.
.PP
In general there are two types of tracks: data and audio. They differ in
sector size, throughput and readability via the systems' CD-ROM drivers
resp. by music CD players.
.br
If not explicitely option -audio is given, then any track is burned as type
data, unless the track source is a file with suffix ".wav" or ".au" and has a
header part which identifies it as MS-WAVE resp. SUN Audio with suitable
parameters. Such files are burned as audio tracks by default.
.PP
While audio tracks just contain a given time span of acoustic vibrations,
data tracks may have an arbitray meaning. Nevertheless, ISO-9660 filesystems
are established as a format which can represent a tree of directories and
files on all major operating systems. Such filesystem images can be
produced by programs mkisofs or genisoimage. They can also be extended by
follow-up tracks if prepared properly. See the man pages of said programs.
cdrskin is able to fulfill the needs about their option -C.
.br
Another type of data track content are archive formats which originally
have been developed for magnetic tapes. Only formats which mark a detectable
end-of-archive in their data are suitable, though. Well tested are
the archivers afio and star. Not suitable seems GNU tar.
.PP
.B Recordable CD Media:
.br
CD-R can be initially written only once and eventually extended until they
get closed (or are spoiled because they are overly full). After that they are
read-only.
.br
CD-RW media can be blanked to make them re-usable for another
round of overwriting. Usually
.B blank=fast
is the appropriate option.
Blanking damages the previous content but does not
make it completely unreadable. It is no effective privacy precaution.
Multiple cycles of blanking and overwriting with random numbers might be.
.PP
.B Recordable DVD Media:
.br
Currently only types DVD+RW and DVD-RW can be burned via cdrskin.
.br
DVD+RW media get treated as blank media regardless wether they hold data
or not. Options -audio and -multi are not allowed. Only one track is allowed.
-toc does not return information about the media content.
Speed is counted in DVD units (i.e. 1x = 1,385,000 bytes/second). Currently
there is no difference between -sao and -tao. If ever, then -tao will be the
mode which preserves the current behavior.
.br
DVD-RW need to be formatted to state "Restricted Overwrite". They then behave
much like CD-RW. This formatting can be done by option
.B blank=format_overwrite
It is necessary for unused media, for media written or blanked by cdrecord,
for media which have been written unformatted by growisofs or blanked by
dvd+rw-format -blank. If in doubt, just give it a try.
.PP
.B Drive preparation and addressing:
.br
The drives, either CD burners or DVD burners, are accessed via addresses which
are specific to libburn and the operating system. Those addresses get listed
by a run of \fBcdrskin --devices\fP.
.br
On Linux, they are device files which traditionally do not offer
w-permissions for normal users. Because libburn needs rw-permission,
it might be only the superuser who is able to get this list without further
precautions.
.br
It is consensus that \fBchmod a+rw /dev/sg0\fP or \fBchmod a+rw /dev/hdc\fP
is less security sensitive than chmod u+s /usr/bin/cdrskin. The risk for the
drive is somewhat higher but the overall system is much less at stake.
.br
.PP
If you only got one CD capable drive then you may leave out cdrskin option
\fBdev=\fP. Else you should use this option to address the drive you want.
.br
cdrskin option dev= not only accepts the listed addresses but also
traditional cdrecord SCSI addresses which on Linux consist of three
numbers: Bus,Target,Lun. There is also a related address family "ATA" which
accesses IDE drives not under control of Linux SCSI drivers:
ATA:Bus,Target,Lun.
.br
See option -scanbus for getting a list of cdrecord style addresses.
.br
Further are accepted on Linux: links to libburn-suitable device files, 
device files which have the same major and minor device number,
and device files which have the same SCSI address parameters (e.g. /dev/sr0).
.br
.SH OPTIONS
.TP
.BI \-\-help
Show non-cdrecord compatible options.
.TP
.BI \-help
Show cdrecord compatible options.
.TP
.BI \-version
Print cdrskin id line, compatibility lure line, libburn version, cdrskin
version, version timestamp, build timestamp (if available), and then exit.
.PP
Alphabetical list of options which are intended to be compatible with
original cdrecord by Joerg Schilling:
.TP
.BI \-atip
Retrieve some info about media state. With CD-RW print "Is erasable".
With DVD media print "book type:" and a media type text.
.TP 
.BI \-audio
Announces that the subsequent tracks are to be burned as audio.
The source is supposed to be uncompressed headerless PCM, 44100 Hz, 16 bit,
stereo. For little-endian byte order (which is usual on PCs) use option
-swab. Unless marked explicitely by option -data, input files with suffix
.wav are examined wether they have a header in MS-WAVE format confirming
those parameters and eventually raw audio data get extracted and burned as
audio track. Same is done for suffix .au and SUN Audio.
.TP 
.BI blank= type
Blank a CD-RW or format a DVD-RW.
This is combinable with burning in the same run of cdrskin.
The type given with blank= selects the particular behavior:
.RS
.TP
help
Print this list of blanking types.
.TP
all
Blank an entire CD.
.TP
fast
Minimally blank an entire CD.
.TP
format_overwrite
Format a DVD-RW to "Restricted Overwrite". The user should bring some patience.
(Note: this is not an original cdrecord option.)
.RE
.TP
.BI \-checkdrive
Retrieve some info about the addressed drive.
Exits with non-zero value if the drive cannot be found and opened.
.TP
.BI \-dao
Alias for option -sao. Write disk in Session at Once mode.
.TP
.BI \-data
Subsequent tracks are data tracks. This option is default and only needed
to mark the end of the range of an eventual option -audio.
.TP
.BI dev= target
Set the address of the drive to use. Valid are at least the
addresses listed with option --devices, 
X,Y,Z addresses listed with option -scanbus,
ATA:X,Y,Z addresses listed with options dev=ATA -scanbus,
and volatile libburn drive numbers (numbering starts at "0").
Other device file addresses which lead to the same drive might work too.
.br
If no dev= is given, volatile address "dev=0" is assumed. That is the first
drive found being available. Better avoid this ambiguity on systems with more
than one drive.
.br
The special target "help" lists hints about available addressing formats.
Be aware that deprecated option --old_pseudo_scsi_adr may change the meaning
of Bus,Target,Lun addresses.
.TP
.BI driveropts= opt
Set "driveropts=burnfree" to enable the drive's eventual protection mechanism
against temporary lack of source data (i.e. buffer underrun).
It is not an error to do this with a drive that has no such capabilities.
.TP
.BI \-dummy
Try to perform the drive operations without actually affecting the inserted
media. There is no guarantee that this will work with a particular drive
in a particular write mode. Blanking is prevented reliably, though.
.TP
.BI \-eject
Eject the disk after work is done.
.TP
.BI \-force
Assume that the user knows better in situations when cdrskin or libburn are
insecure about drive or media state. This includes the attempt to blank
media which are classified as unknown or unsuitable, and the attempt to use
write modes which libburn believes they are not supported by the drive.
.br
Use this only when in urgent need.
.TP
.BI fs= size
Set the fifo size to the given value. The value may have appended letters which
multiply the preceding number:
.br
"k" or "K" = 1024 , "m" or "M" = 1024k , "g" or "G" = 1024m , "s" or "S" = 2048
.br
Set size to 0 in order to disable the fifo (default is "4m").
.br
The fifo buffers an eventual 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.
The larger the fifo, the longer periods of poor source supply can be
compensated.
But a large fifo needs substantial time to fill up if not curbed via
option fifo_start_at=size.
.TP
.BI gracetime= seconds
Set the grace time before starting to write. (Default is 0)
.TP
.BI msifile= path
Run option -msinfo and copy the result line into the file given by path.
Unlike -msinfo this option does not redirect all normal output away from
standard output. But it may be combined with -msinfo to achieve this.
.br
Note: msifile=path is actually an option of wodim and not of cdrecord.
.TP
.BI \-msinfo
Retrieve multi-session info for preparing a follow-up session by option -C
of programs mkisofs or genisoimage. Print result to standard output.
This option redirects to stderr all
message output besides its own result string, which consists of two numbers.
The result string shall be used as argument of option -C with said programs.
It gives the start address of the most recent session and the predicted
start address of the next session to be appended. The string is empty if
the most recent session was not written with option -multi.
.TP
.BI \-multi
This option keeps the CD appendable after the current session has been written.
Without it the disk gets closed and may not be written any more  - unless it
is a CD-RW and gets blanked which causes loss of its content.
.br
The following sessions can only be written in -tao mode.
.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 and genisoimage expect particular info about the situation
which can be retrieved by cdrskin option -msinfo.
.br
To retrieve an archive file which was written as follow-up session,
you may use option -toc to learn about the "lba" of the desired track number. 
.TP
.BI \-nopad
Do not add trailing zeros to the data stream. Nevertheless, since there seems
to be no use for audio tracks with incomplete last sector, this option applies
only to data tracks. There it is default.
.TP
.BI \-pad
Add 30 kB of trailing zeros to each data track. (This is not sufficient to
avoid problems with various CD-ROM read drivers.)
.TP
.BI padsize= size
Add the given amount of trailing zeros to the next data track. This option
gets reset to padsize=0 after that next track is written. It may be set
again before the next track argument. About size specifiers, see option fs=.
.TP
.BI \-raw96r
Write disk in RAW/RAW96R mode. This mode allows to put more payload bytes
into a CD sector but obviously at the cost of error correction. It can only
be used for tracks of fixely predicted size. Some drives allow this mode but
then behave strange or even go bad for the next few attempts to burn a CD.
One should use it only if inavoidable.
.TP
.BI \-sao
Write disk in Session At Once mode. This mode is able to put several audio
tracks on CD without producing audible gaps between them. It can only 
be used for tracks of fixely predicted size. This implies that track arguments
which depict stdin or named pipes need to be preceeded by option tsize= or
by option tao_to_sao_tsize=.
.TP
.BI \-scanbus
Scan the system for drives. On Linux the drives at /dev/s* and at /dev/hd*
are to be scanned by two separate runs. One without dev= for /dev/s* and
one with dev=ATA for /dev/hd* devices. (Option --drives lists all available
drives in a single run.)
.br
Drives which are busy or which offer no rw-permission to the user of cdrskin
are not listed. Busy drives get reported in form of warning messages.
.br
The useful fields in a result line are:
.br
Bus,Target,Lun Number) 'Vendor' 'Mode' 'Revision'
.TP
.BI speed= number
Set speed of drive. With data CD, 1x speed corresponds to a throughput of
150 kB/s. It is not an error to set a speed higher than is suitable for drive
and media. One should stay within a realistic speed range, though.
.TP
.BI \-swab
Announce that the raw audio data source of subsequent tracks is byte swapped
versus the expectations of cdrecord. This option is suitable for audio where
the least significant byte of a 16 bit word is first (little-endian, Intel).
Most raw audio data on PC systems are available in this byte order.
Less guesswork is needed if track sources are in format MS-WAVE in a file with
suffix ".wav".
.TP
.BI \-tao
Write disk in Track At Once (TAO) mode. This mode can be used with track
sources of unpredictable size, like standard input or named pipes. It is
also the only mode that can be used for writing to appendable CD which
already hold data.
.TP
.BI \-toc
Print the table of content (TOC) which describes the tracks recorded on CD.
The output contains all info from option -atip plus lines which begin with
"track:", the track number, the word "lba:" and a number which gives the
start address of the track. Addresses are counted in CD sectors which with
SAO or TAO data tracks hold 2048 bytes each.
.RS
.TP
Example. Retrieve an afio archive from track number 2:
.br
tracknumber=2
.br
lba=$(cdrskin dev=/dev/cdrom -toc 2>&1 | \\
.br
grep '^track:[ ]*[ 0-9][0-9]' | \\
.br
tail +"$tracknumber" | head -1 | \\
.br
awk '{ print $4}' )
.br
dd if=/dev/cdrom bs=2048 skip="$lba" | \\
.br
afio -t - | less
.RE
.TP
.BI tsize= size
Announces the exact size of the next track source. This is necessary with any
write mode other than -tao if the track source is not a regular disk file, but
e.g. "-" (standard input) or a named pipe.
About size specifiers, see option fs=.
.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 CD gets truncated to the predicted size and cdrskin exits
with non-zero value.
.TP
.BI \-v
Increment verbose level by one. Startlevel is 0 with only few messages.
Level 1 prints progress report with long running operations and also causes
some extra lines to be put out with info retrieval options. 
Level 2 additionally reports about option settings derived from arguments or
startup files. Level 3 is for debugging and useful mainly in conjunction with
somebody who had a look into the program sourcecode.
.PP
Alphabetical list of options which are genuine to cdrskin and intended for
normal use:
.TP
.BI \--allow_setuid
Disable the loud warning about insecure discrepance between login user and
effective user which indicates application of chmod u+s to the program binary.
One should not do this chmod u+s , but it is an old cdrecord tradition.
.TP
.BI \--any_track
Allow source_addresses to begin with "-" (plus further characters) or to
contain a "=" character.
By default such arguments are seen as misspelled options. It is nevertheless
not possible to use one of the options listed with --list_ignored_options.
.TP
.BI \--demand_a_drive
Exit with a nonzero value if no drive can be found during a bus scan.
.TP
.BI \--devices
List the device file addresses of all accessible CD drives. In order to get
listed, a drive has to offer rw-permission for the cdrskin user and it may
not be busy. The superuser should be able to see all idle drives listed and 
busy drives reported as "SORRY" messages.
.br
Each available drive gets listed by a line containing the following fields:
.br
Number dev='Devicefile' rw-Permissions : 'Vendor' 'Model'
.br
Number and Devicefile can both be used with option dev=, but number is
volatile (numbering changes if drives become busy).
.TP
.BI fifo_start_at= size
Do not wait for full fifo but start burning as soon as the given number
of bytes is read. This option may be helpful to bring the average throughput
near to the maximum throughput of a drive. A large fs= and a small 
fifo_start_at= combine a quick burn start and a large savings buffer to
compensate for temporary lack of source data. At the beginning of burning,
the software protection against buffer underun is as weak as the size of
fifo_start_at= . So it is best if the drive offers hardware protection which
has to be enabled by driveropts=burnfree.
.TP
.BI \--list_ignored_options
List all ignored cdrecord options. The --options cannot be used as addresses
of track sources. No track source address may begin with a text equal to an
option which ends by "=". The list is ended by an empty line.
.TP
.BI \--no_rc
Only if used as first command line argument this option prevents reading and
interpretation of eventual startup files. See section FILES below.
.TP
.BI \--single_track
Accept only the last argument of the command line as track source address.
.TP 
.BI write_start_address= byte_offset
Set the address on media where to start writing the track. With DVD+RW 
byte_offset must be aligned to 2 KB blocks. With DVD-RW alignment is 32 kB.
Other media are not suitable for this option yet.
.PP
Alphabetical list of options which are only intended for very special
situations and not for  normal use:
.TP
.BI \--abort_handler
Establish default signal handling not to leave a drive in busy state
but rather to shut it down and to wait until it has ended the final operations.
This option is only needed for revoking eventual --ignore_signals or
--no_abort_handler.
.TP
.BI dev_translation= <sep><from><sep><to>
Set drive address alias. This was necessary before cdrskin-0.2.4 to manually
translate cdrecord addresses into cdrskin addresses.
.br
<sep> is a single character which may not occur in the address string
<from>. <from> is an address as expected to be given by the user via option
dev=. <to> is the address to be used instead whenever <from> is given.
More than one translation instruction can be given in one cdrskin run.
.br
E.g.: dev_translation=+ATA:1,0,0+/dev/sg1 dev_translation=+ATA:1,1,0+/dev/sg2
.TP
.BI \--drive_abort_on_busy
Linux specific: Abort process if a busy drive is encountered.
.TP
.BI \--drive_blocking
Linux specific: Try to wait for a busy drive to become free.
This is not guaranteed to work with all drivers. Some need nonblocking i/o.
.TP
.BI \--drive_not_exclusive
Linux specific: Do not ask the operating system to prevent opening busy drives.
Wether this leads to senseful behavior depends on operating system and kernel.
.TP
.BI \--drive_scsi_exclusive
Linux specific:
Try to exclusively reserve device files /dev/srN, /dev/scdM, /dev/stK of drive.
this would be helpful to protect against collisions with program growisofs.
Regrettably on Linux kernel 2.4 with ide-scsi emulation this seems not to
work. Wether it becomes helpful with new Linux systems has to be evaluated.
.TP
.BI \--fifo_disable
Disable fifo despite any fs=.
.TP
.BI \--fifo_per_track
Use a separate fifo for each track.
.TP
.BI grab_drive_and_wait= seconds
Open the addressed drive, wait the given number of seconds, release the drive,
and do normal work as indicated by the other options used. This option helps
to explore the program behavior when faced with busy drives. Just start a
second cdrskin with option --devices while grab_drive_and_wait= is still
active.
.TP
.BI \--ignore_signals
Try to ignore any signals rather than to abort the program. This is not a
very good idea. You might end up waiting a very long time for cdrskin
to finish.
.TP
.BI \--no_abort_handler
On signals exit even if the drive is in busy state. This is not a very good
idea. You might end up with a stuck drive that refuses to hand out the media.
.TP
.BI \--no_blank_appendable
Refuse to blank appendable CD-RW. This is a feature that was once builtin with
libburn. No information available for what use case it was needed.
.TP
.BI \--no_convert_fs_adr
Do only literal translations of dev=. This prevents cdrskin from test-opening
device files in order to find one that matches the given dev= specifier.
.br
Partly Linux specific:
Such opening is needed for Bus,Target,Lun addresses unless option
--old_pseudo_scsi_adr is given. It is also needed to resolve device file
addresses which are not listed with cdrskin --devices but nevertheless point
to a usable drive. (Like /dev/sr0 using the same SCSI address as /dev/sg0.)
.TP
.BI \--old_pseudo_scsi_adr
Linux specific:
Use and report literal Bus,Target,Lun addresses rather than real SCSI and
pseudo ATA addresses. This method is outdated and was never compatible with
original cdrecord.
.TP
.BI tao_to_sao_tsize= size
Set an exact fixed size for the next track to be in effect only if the track
source cannot deliver a size prediction and no tsize= was specified.
This is the fallback from bad old times when cdrskin was unable to burn
in mode -tao.
.br
.SH EXAMPLES
.SS
.B Get an overview of drives:
.br
cdrskin -scanbus
.br
cdrskin dev=ATA -scanbus
.br
cdrskin --devices
.SS
.B Get info about a particular drive or loaded media:
.br
cdrskin dev=0,1,0 -checkdrive
.br
cdrskin dev=ATA:1,0,0 -atip
.br
cdrskin dev=/dev/hdc -toc
.SS
.B Make used CD-RW writable again:
.br
cdrskin -v dev=/dev/sg1 blank=all -eject
.br
cdrskin -v dev=/dev/dvd blank=fast -eject
.SS
.B Format DVD-RW before first use with cdrskin:
.br
cdrskin -v dev=/dev/sr0 blank=format_overwrite
.SS
.B Write ISO-9660 filesystem image:
.br
cdrskin -v dev=/dev/hdc speed=12 fs=8m \\
.br
driveropts=burnfree -sao -eject \\
.br
padsize=300k my_image.iso
.SS
.B Write compressed afio archive on-the-fly:
.br
find . | afio -oZ - | \\
.br
cdrskin -v dev=0,1,0 fs=32m speed=8 driveropts=burnfree \\
.br
padsize=300k -tao -
.SS
.B Write several sessions to the same CD:
.br
cdrskin dev=/dev/hdc padsize=300k -multi 1.iso
.br
cdrskin dev=/dev/hdc padsize=300k -multi -tao 2.afio
.br
cdrskin dev=/dev/hdc padsize=300k -multi -tao 3.afio
.br
cdrskin dev=/dev/hdc padsize=300k -tao 4.afio
.SS
.B Get CD multi-session info for option -C of program mkisofs:
.br
c_values=$(cdrskin dev=/dev/sr0 -msinfo 2>/dev/null)
.br
mkisofs ... -C "$c_values" ...
.SS
.B Write audio tracks to CD:
.br
cdrskin -v dev=ATA:1,0,0 speed=48 \\
.br
driveropts=burnfree -sao \\
.br
track1.wav track2.au -audio -swab track3.raw
.br
.SH FILES
If not --no_rc is given as the first argument then cdrskin attempts on
startup to read the arguments from the following files:
.PP
.br
.B /etc/default/cdrskin
.br
.B /etc/opt/cdrskin/rc
.br
.B /etc/cdrskin/cdrskin.conf
.br
.B $HOME/.cdrskinrc
.br
.PP
The files are read in the sequence given above, but none of them is
required for cdrskin to function properly. Each readable line is treated
as one single argument. No extra blanks.
A first character '#' marks a comment, empty lines are ignored.
.SS
.B Example content of a startup file:
.br
# This is the default device
.br
dev=0,1,0
.br
# To accomodate to remnant cdrskin-0.2.2 addresses
.br
dev_translation=+1,0,0+0,1,0
.br
# Some more options
.br
fifo_start_at=0
.br
fs=16m
.br
.SH SEE ALSO
.TP
Formatting track sources for cdrskin:
.br
.BR mkisofs (8),
.BR genisoimage (8),
.BR afio (1),
.BR star (1)
.br
.TP
Other CD/DVD burn programs:
.br
.BR cdrecord (1),
.BR wodim (1)
.br
.TP
For DVD burning:
.br
.BR growisofs (1)
.br
.SH AUTHOR
cdrskin was written by Thomas Schmitt <scdbackup@gmx.net>.
.PP
This manual page was written by George Danchev <danchev@spnet.net> and
Thomas Schmitt, for the Debian project and for all others.