.\" -*- nroff -*-
.\" 
.\" Copyright 1995 Yggdrasil Computing, Incorporated.
.\" written by H. Peter Anvin <hpa@storm.net>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
.\" USA.
.\"
.TH CDWRITE 1 "Linux User's Manual" "Version 2.0"
.SH NAME
cdwrite \- record audio or data Compact Discs
.SH SYNOPSIS
.B cdwrite
[\-ehvyV] [\-s 
.IR speed ]
[\-D
.IR device ]
[\-\-eject] [\-\-help] [\-\-version]
[\-\-dummy] [\-\-verbose] [\-\-speed 
.IR speed ]
[\-\-device
.IR device ]
[\-\-philips] [\-\-ims] [\-\-kodak] [\-\-hp] [\-\-yamaha] [[\-adpnPN]
[\-b
.IR bytes ]
[\-\-audio] [\-\-data] [\-\-preemp] [\-\-nopreemp]
[\-\-pad] [\-\-nopad]
[\-\-bytes
.IR bytes ]
.I source
...]
.SH DESCRIPTION
.B cdwrite
is used to record data or audio Compact Discs on an Orange Book CD-R
recorder.  This version will only write single session, Red/Yellow
Book compatible discs.  These discs are suitable for direct mass
production by CD manufacturers, as well as direct use in regular
players.
.PP
Each
.I source
is a file (or a dash \- indicating standard input) containing the data
for a single track.  Unlike previous versions of
.BR cdwrite ,
reading from standard input must be indicated explicitly.
.SS GLOBAL OPTIONS
.TP
.I "\-e, \-\-eject"
Eject the disk on completion.  If no source files are specified, eject
the disk, then exit.
.TP
.I "\-h, \-\-help"
Print a short help message, then exit.
.TP
.I "\-v, \-\-verbose"
Present a verbose display, including a progress display as each track
writes.
.TP
.I "\-y, \-\-dummy"
Makes the CD recorder go through all the motions of a write
procedure, but with the laser turned off.  Used for testing.
.TP
.I "\-V, \-\-version"
Print the program version, then exit.
.TP
.I "\-s speed, \-\-speed speed"
Sets the writing speed (# is an integer; 1 = single speed, 2 = double
speed, etc.).  Specifying a speed your CD writer cannot handle may
have unpredictable effects.  The default is double speed (on HP, the
default is ``maximum speed'', which is drive dependent; it is double
speed for the HP 4020i.)
.TP
.I "\-D device, \-\-device device"
Sets the device name for the CD writer.  The 
.I device
argument must refer to a generic SCSI device name (typically starting with
.IR /dev/sg ).
Default is
.IR /dev/cdwriter ,
which is assumed to be a symbolic link to the appropriate standard
device name.
.TP
.I "\-\-philips, \-\-ims, \-\-kodak"
Sets Philips/IMS/Kodak mode.
.TP
.I "\-\-yamaha"
Sets Yamaha mode.
.TP
.I "\-\-hp"
Sets Hewlett-Packard mode. 
.SS TRACK OPTIONS
All track options except
.I "\-b, \-\-bytes"
affect all subsequent tracks unless cancelled by another option.
.TP
.I "\-a, \-\-audio"
Indicates subsequent tracks should be written in Red Book audio
format.  The data for this track should be 2-channel, 16-bit, signed
(2's complement) digital audio sampled at a rate of 44100 Hz.  Each
sample should be written in the following byte order: MSB left, LSB
left, MSB right, LSB right.  The track should be a multiple of 2352
bytes (588 samples).
.TP
.I " "
The audio format conversion program
.B sox
can be used to create data in this format by specifying the
.B cdr
output format.  If used on a littleendian system, such as Linux/i386,
.B sox
requires the
.I \-x
option on the output file as well.
.TP
.I "\-d, \-\-data"
Indicates subsequent tracks should be written in Yellow Book (CD-ROM)
format.  The data for this track should be a multiple of 2048 bytes,
and will typically be an ISO 9660 filesystem image.  The program
.B mkisofs
can be used to generate such an image.
.TP
.I " "
This is the default.
.TP
.I "\-p, \-\-preemp"
Indicates that subsequent audio tracks have been mastered with
preemphasis.  Preemphasis provides a larger dynamic range at the
expense of added distortion of high-volume segments.  This option does
not affect the data written to the disc; the preemphasis must be
reflected in the input data.  This option has no effect on data
tracks.
.TP
.I "\-n, \-\-nopreemp"
Indicates that subsequent audio tracks have been mastered with linear
data.  This is the default.
.TP
.I "\-P, \-\-pad"
Add 30 kilobytes (15 sectors) of nulls to the end of each data track.
This is a workaround for a bug in Linux up to and including at least
version 1.2.8, which would at times not correctly read the last few
sectors written.  This option has no effect on audio tracks.
.TP
.I "\-N, \-\-nopad"
Do not pad data tracks.  This is the default.
.TP
.I "\-b bytes, \-\-bytes bytes"
Specifies the length of the data for the next track only.  If the
source for a track is not a regular file, this option should be used
to specify the length of the input.  The
.B isosize
program, usually included in the
.B cdwrite
distribution, can be used to determine the length of an ISO 9660
filesystem image.
.TP
.I " "
This option is typically used when writing an ISO 9660 filesystem
image which has previously been written to a raw block device.
.SH EXAMPLES
For all examples, it will be assumed
.I /dev/cdwriter
is the generic SCSI device for the CD writer, unless other is indicated.
.PP
To write a pure CD-ROM, using data (usually an ISO 9660 filesystem
image) from the file
.IR cdimage.iso :
.PP
	cdwrite \-v cdimage.iso
.PP
To write a pure CD-ROM, with padding, using an ISO 9660 filesystem
from
.IR /dev/sda3 ,
to the CD writer connected to
.IR /dev/sg2 :
.PP
	cdwrite \-v \-D /dev/sg2 \-\-pad \-b `isosize /dev/sda3` /dev/sda3
.PP
To write a pure audio CD, at double speed, with each track contained
in a file named
.IR track01.cdr ,
.IR track02.cdr ,
etc:
.PP
	cdwrite \-v \-\-speed 2 \-\-audio track*.cdr
.PP
To simulate writing a mixed-mode CD with an ISO 9660 filesystem from
.I /dev/sda3
on the first track, the other tracks being audio tracks with
preemphasis from the files
.IR track01.cdr ,
.IR track02.cdr ,
etc:
.PP
	cdwrite \-vy \-b `isosize /dev/sda3` \-d /dev/sda3 \-ap track*.cdr
.SH SUPPORTED HARDWARE
So far,
.B cdwrite
has been tested on and is known to work on:
.br
Philips CDD-521, CDD-522, using an Adaptec 1542 SCSI controller.  This
unit is also sold under the IMS brand name.  All CDD-52x models should
work.
.br
Kodak 522 (an OEM version of the Philips CDD-522.)
.br
Yamaha CDR100, using a BusLogic SCSI controller (audio untested.)  All
CDR10x models should work.
.br
HP 4020i (C4324/C4325).
.PP
.B cdwrite
is known
.I not
to work on:
.br
All Sony models.
.PP
If you have tested a different model of CD writer, please send your
results to
.I <hpa@storm.net>
for reference.  Please do not email the
author to ask about writers not listed here; however, a Web page will
be made available at
.I http://terminus.storm.net/~hpa/cdwrite_comp.html
for your reference.
.SH AUTHORS
Originally written by Adam Richter
.IR <adam@yggdrasil.com> .
.br
Currently maintained by H. Peter Anvin
.IR <hpa@storm.net> .
.br
Progress reporting by Dan Quinlan
.IR <quinlan@bucknell.edu> .
.br
Improved buffering by Ross Biro
.IR <ross.biro@linux.org> . 
.br
Yamaha support by Leonard N. Zubkoff
.IR <lnz@dandelion.com> .
.br
HP support mostly by Eric Smith
.IR <eric@goonsquad.spies.com> .
Also thanks to all the alpha testers.
.SH HINTS
When generating a CD-ROM, it is often useful to write the filesystem
image directly to a hard disk partition rather than a file; this makes
it easy to verify the proper setup of the filesystem before writing,
and improves throughput.  See the second example above.
.SH CAVEATS
Unless your SCSI controller and driver support disconnect/reconnects,
you will probably not be able to write a CD correctly if the CD writer
and hard disk are on the same SCSI bus.  It is not recommended that IDE
drives are used on CD-writing system; if they are, it is imperative that
interruptible operation is enabled using the
.B hdparm
command.
.PP
It is not recommended to use more than single speed when reading data
off a filesystem (as opposed to a raw disk partition).  Although it is
possible to write a CD from a pipe process, there is always the risk
of stalls if the source process falls behind.
.PP
It is recommended that your system is left as lightly loaded as
possible during the write operation, since CD writing is a realtime
operation.  If
.B cdwrite
is run as root, it will automatically elevate its priority to reduce
the likelihood of fatal interruptions.
.PP
.B cdwrite
does not verify that the input data will fit on the media.  In the
case of media overrun, the resulting disc is usually unreadable.
.PP
A Compact Disc can have no more than 100 tracks.
.PP
When creating a disc with both audio and data tracks, it is
conventional to place the data on track 1.  Some CD players or CD-ROM
drives may respond incorrectly to any other arrangement, although the
specifications permit it.
.PP
Many systems are not able to read more than a single data track, or
need special software to do so.
.PP
Some CD players have problems reading ``gold'' CD's, and some have
problems reading the outermost tracks (i.e. very long CD's).
.PP
Compiling
.B cdwrite
depends on the header files included in the Linux kernel source under
the directory
.IR /usr/src/linux/drivers .
If you update your kernel, there is a possibility you may have to
recompile
.BR cdwrite .
.SH SEE ALSO
.BR hdparm (1),
.BR mkisofs (1),
.BR sox (1).