README 20.2 KB
Newer Older
1
------------------------------------------------------------------------------
2
     libburnia-project.org     scdbackup.sourceforge.net/cdrskin_eng.html
3 4
------------------------------------------------------------------------------
cdrskin. By Thomas Schmitt <scdbackup@gmx.net>
5
Integrated sub project of libburnia-project.org but also published via:
6
http://scdbackup.sourceforge.net/cdrskin_eng.html
7
http://scdbackup.sourceforge.net/cdrskin-0.5.1.tar.gz
8
Copyright (C) 2006-2008 Thomas Schmitt, provided under GPL version 2.
9 10 11
------------------------------------------------------------------------------


12 13
cdrskin is a limited cdrecord compatibility wrapper which allows to use
most of the libburn features from the command line.
14

15
Currently it is only supported on Linux with kernels >= 2.4.
16

17 18
By using this software you agree to the disclaimer at the end of this text
"This software is provided as is. There is no warranty implied and ..."
19 20 21 22


                   Compilation, First Glimpse, Installation

23
Obtain cdrskin-0.5.1.tar.gz, take it to a directory of your choice and do:
24

25 26
    tar xzf cdrskin-0.5.1.tar.gz
    cd cdrskin-0.5.1
27

28
Within that directory execute:
29

30
    ./configure --prefix=/usr
31 32
    make

33
This will already produce a cdrskin binary. But it will be necessary to
34 35 36 37 38 39 40
install libburn in order to use this binary. Installation of libburn is
beyond the scope of cdrskin. For this, see included libburn docs.

In order to surely get a standalone binary, execute

    cdrskin/compile_cdrskin.sh

41
Version identification and help texts available afterwards:
42
    cdrskin/cdrskin -version
43 44
    cdrskin/cdrskin --help
    cdrskin/cdrskin -help
45
    man cdrskin/cdrskin.1
46

47

48
Install (eventually as superuser) cdrskin to a directory where it can be found:
49 50
The command for global installation of both, libburn and cdrskin is
    make install
Thomas Schmitt's avatar
Thomas Schmitt committed
51 52 53 54
If the library libburn.so.4 is not found with a test run of cdrskin, then
try whether command
    ldconfig
makes it accessible. With the statically linked binary this should not matter.
55

56 57 58
With that static binary you may as well do the few necessary actions manually.
If cdrskin was already installed by a previous version, or by "make install"
in the course of this installation, then find out where:
59
    which cdrskin 
60 61
Copy your standalone binary to exactly the address which you get as reply.
E.g.:
62 63 64 65 66

    cp cdrskin/cdrskin /usr/bin/cdrskin

Check the version timestamps of the globally installed binary
    cdrskin -version
67

68 69 70 71 72 73
It is not necessary for the standalone cdrskin binary to have libburn
installed, since it incorporates the necessary libburn parts at compile time.
It will not collide with an installed version of libburn either.
But libpthread must be installed on the system and glibc has to match. (See
below for a way to create a statically linked binary.)

Thomas Schmitt's avatar
Thomas Schmitt committed
74 75 76 77
To install the man page, you may do: echo $MANPATH and choose one of the
listed directories to copy the man-page under its ./man1 directory. Like:
    cp cdrskin/cdrskin.1 /usr/share/man/man1/cdrskin.1

78 79 80 81
Note: The content of the cdrskin tarball is essentially the complete libburn
      of the same version number. You may thus perform above steps in a local
      SVN copy of libburn or in a unpacked libburn tarball as well.

82 83 84 85 86 87 88 89 90 91 92 93 94

                                    Usage

The user of cdrskin needs rw-permission for the CD burner device.
A list of rw-accessible drives can be obtained by

    cdrskin --devices

CD devices which offer no rw-permission are invisible to normal users.
The superuser should be able to see any usable drive and then set the
permissions as needed. If this hangs then there is a drive with
unexpected problems (locked, busy, broken, whatever). You might have to
guess the address of your (non-broken) burner by other means, then.
95
On Linux 2.4 this would be some /dev/sgN and on 2.6. some /dev/srM or /dev/hdX.
96 97 98

The output of  cdrskin --devices  might look like

99 100
    0  dev='/dev/sr0'  rwrwr- :  '_NEC'  'DVD_RW ND-4570A'
    1  dev='/dev/sr1'  rwrw-- :  'HL-DT-ST'  'DVDRAM GSA-4082B'
101 102 103

So full and insecure enabling of both for everybody would look like

104
    chmod a+rw /dev/sr0 /dev/sr1
105

106 107
This is equivalent to the traditional setup chmod a+x,u+s cdrecord.

108 109 110
I strongly discourage to run cdrskin with setuid root or via sudo !
It is not checked for the necessary degree of hacker safety.

111 112 113 114 115 116 117 118 119 120
Consider to put all authorized users into group "floppy", to chgrp the
device file to that group and to disallow w-access to others.

Helpful with Linux kernel 2.4 is a special SCSI feature:
It is possible to address a scsi(-emulated) drive via associated device files
which are not listed by option --devices but point to the same SCSI addresses
as listed device files. This addressing via e.g. /dev/sr0 or /dev/scd1 is
compatible with generic read programs like dd and with write program growisofs.
For finding /dev/sg1 from /dev/sr0, the program needs rw-access to both files.

121 122 123

                                Usage examples 

124 125 126
For options and recordable media classes see 
    man 1 cdrskin

127 128
Get an overview of cdrecord style addresses of available devices
    cdrskin -scanbus 
129
    cdrskin dev=ATA -scanbus 
130
    cdrskin --devices
131

132
Adresses reported with dev=ATA need prefix "ATA:". Address examples:
133
    dev=0,1,0  dev=ATA:1,0,0  dev=/dev/sg1  dev=/dev/hdc  dev=/dev/sr0
134
See also "Drive Addressing" below.
135 136

Obtain some info about the drive
137
    cdrskin dev=0,1,0 -checkdrive 
138 139

Obtain some info about the drive and the inserted media
140
    cdrskin dev=0,1,0 -atip -v
141

142 143
Prepare CD-RW or DVD-RW for re-use, DVD-RAM or BD-RE for first use
    cdrskin -v dev=/dev/sg1 blank=as_needed -eject
144

145
Format DVD-RW to avoid need for blanking before re-use
146 147
    cdrskin -v dev=0,1,0 blank=format_overwrite

148 149
De-format DVD-RW to make it capable of multi-session again
    cdrskin -v dev=/dev/sr0 blank=deformat_sequential
150

151
Burn image file  my_image.iso  to media
152
    cdrskin -v dev=0,1,0 speed=12 fs=8m driveropts=burnfree padsize=300k \
153
            -eject  my_image.iso 
154

155
Write multi-session to the same CD , DVD-R[W] or DVD+R[/DL]
156
    cdrskin dev=/dev/hdc padsize=300k -multi 1.iso
157 158 159
    cdrskin dev=/dev/hdc padsize=300k -multi 2.iso
    cdrskin dev=/dev/hdc padsize=300k -multi 3.iso
    cdrskin dev=/dev/hdc padsize=300k 4.iso
160

161
Get multi-session info for option -C of program mkisofs:
162 163 164 165
    c_values=$(cdrskin dev=/dev/hdc -msinfo 2>/dev/null)
    mkisofs ... -C "$c_values" ...

Burn a compressed afio archive to media on-the-fly
166
    find . | afio -oZ - | cdrskin -v dev=0,1,0 fs=32m speed=8 \
167
                                  driveropts=burnfree padsize=300k - 
168

169
Burn 6 audio tracks from files with different formats to CD (not to any DVD).
170 171
Anything except .wav or .au files has to be converted into raw format first.
See below "Audio CD" for specifications.
172 173
    ogg123 -d raw -f track01.cd /path/to/track1.ogg
    oggdec -R -o track02.cd /path/to/track2.ogg
174 175 176
    lame --decode -t /path/to/track3.mp3 track03.cd   
    madplay -o raw:track04.cd /path/to/track4.mp3
    mppdec --raw-le /path/to/track5.mpc track05.cd
177

178
    cdrskin -v dev=0,1,0 blank=fast -eject speed=48 -sao \
179
           -audio -swab track0[1-5].cd /path/to/track6.wav
180

181

182 183
                                Restrictions

184 185 186
Several advanced CD related options of cdrecord are still unsupported.
See output of command
    cdrskin --list_ignored_options
187
If you have use cases for them, please report your wishes and expectations.
188

189 190
On the other hand, the capability of multi-session and of writing streams
of unpredicted lenght surpass the current DVD capabilities of cdrecord.
191 192 193 194


                           Inspiration and Standard

195 196 197 198
cdrskin combines the command line interface standard set by cdrecord with
libburn, which is a control software for optical drives according to standard
MMC-5. For particular CD legacy commands, standards MMC-3 and MMC-1 apply.

199 200 201 202 203
For the original meaning of cdrecord options see :
    man cdrecord 
    (http://cdrecord.berlios.de/old/private/man/cdrecord-2.0.html)
Do not bother Joerg Schilling with any cdrskin problems.
(Be cursed if you install cdrskin as "cdrecord" without clearly forwarding
204 205
 this "don't bother Joerg" demand.)

206 207 208 209 210
cdrskin does not contain any bytes copied from cdrecord's sources. Many bytes
have been copied from the message output of cdrecord runs, though. I am
thankful to Joerg Schilling for every single one of them.
I have the hope that Joerg feels more flattered than annoyed by cdrskin.

211 212 213 214
Many thanks to Andy Polyakov for his dvd+rw-tools
  http://fy.chalmers.se/~appro/linux/DVD+RW/tools
which provide me with examples and pointers into MMC specs for DVD writing.

215 216 217 218 219

                                 Startup Files

If not --no_rc is the first argument then cdrskin attempts on startup to read
arguments from the following three files:
220
  /etc/default/cdrskin
221
  /etc/opt/cdrskin/rc
222
  /etc/cdrskin/cdrskin.conf
223 224
  $HOME/.cdrskinrc
The files are read in the sequence given above.
225 226
Each readable line is treated as one single argument. No extra blanks.
A first character '#' marks a comment, empty lines are ignored.
227 228

Example content of a startup file:
229 230 231 232
# This is the default device
dev=0,1,0

# Some more options
233
fifo_start_at=0
234 235 236
fs=16m


237 238
                                  Audio CD

239 240
Lorenzo Taylor enabled option -audio in cdrskin (thanks !) and reports neat
results with audio data files which are :
241
  headerless PCM (i.e. uncompressed)
242
  44100 Hz sampling rate 
Thomas Schmitt's avatar
Thomas Schmitt committed
243
  16 bits per sample
244
  stereo (2 channels)
245 246
  little-endian byte order with option -swab, or big-endian without -swab

247 248
Files with name extension .wav get examined wether they are in Microsoft WAVE
format with above parameters and eventually get extracted by cdrskin itself.
249 250 251 252 253 254 255 256 257
In the same way files with name extension .au get examined wether they are
in SUN's audio format. For both formats, track format -audio and eventual
endianness option -swab are enabled automatically.

Any other formats are to be converted to format .wav with above parameters
or to be extracted as raw CD track data by commands like those given above
under "Usage examples". Those raw files need option -audio and in most cases 
option -swab to mark them as little-endian/Intel/LSB-first 16-bit data.
Incorrect endianness setting results in random noise on CD.
258 259

I myself am not into audio. So libburn-hackers@pykix.org might be the
260
best address for suggestions, requests and bug reports.
261 262


263
                          DVD+RW , DVD-RAM , BD-RE
264

265
These random access media get treated as blank media regardless wether they
266 267
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.
268 269 270 271 272 273 274 275 276 277 278 279 280 281 282
Speed is counted in DVD units (i.e. 1x = 1,385,000 bytes/second) or BD units
(1x = 4,495,625 bytes/second). Currently there is no difference between -sao
and -tao. If ever, then -tao will be the mode which preserves the current
behavior.

BD-RE media need formatting before first use. cdrskin option "blank=as_needed"
recognizes unformatted BD-RE and applies a lengthy formatting run.

During write operations DVD-RAM and BD-RE automatically apply defect
management. This usually slows them down to half nominal speed. If drive
and media produce flawless results anyway, then one can try to reach full
nominal speed by option "stream_recording=on".
In this case bad blocks are not detected during write and not even previously
known bad blocks are avoided. So you have to make your own readability tests
and go back to half speed as soon as the first read errors show up.
283

284 285 286 287 288 289 290 291 292 293 294
Option --grow_overwriteable_iso allows -multi (although unneeded), enables
-msinfo and -toc, and makes blank=fast an invalidator for ISO filesystems
on overwriteable media.

Initial session (equivalent to growisofs -Z): 
  mkisofs ... | cdrskin --grow_overwriteable_iso blank=fast ...

Add-on session (equivalent to growisofs -M):
  cparms=$(cdrskin dev=/dev/sr0 --grow_overwriteable_iso -msinfo)
  mkisofs -C "$cparms" -M /dev/sr0 ... | \
    cdrskin dev=/dev/sr0 --grow_overwriteable_iso ... -
295

296

297
                               DVD-RW and DVD-R
298

299
DVD-RW are usable if formatted to state "Restricted Overwrite" or if in state
300
"Sequential Recording". DVD-R are always in sequential state.
301

302 303
"Sequential" is the state of unused media and of media previously blanked
or written by cdrecord. dvd+rw-format -blank can also achieve this state.
304 305
The according cdrskin option is blank=deformat_sequential .
If "Incremental Streaming" is available, then sequential media are capable
306
of multi-session like CD-R[W]. (But not capable of -audio recording.)
307 308 309
This means they need option -multi to stay appendable, need to be blanked
to be writeable from start, return useable info with -toc and -msinfo,
eventually perform appending automatically.
310
Without Incremental Streaming offered by the drive, only write mode DAO is
311
available with sequential DVD-R[W]. It only works with blank media, allows only
312
one single track, no -multi, and demands a fixely predicted track size.
313
(growisofs uses it with DVD-R[W] if option -dvd-compat is given.)
314
 
315
Overwriteable DVD-RW behave much like DVD+RW. "Restricted" refers only to the
316 317 318
granularity of random access and block size which have always to be aligned to
full 32 kB. Sequential DVD-RW are converted into overwriteable DVD-RW by
  cdrskin dev=... -v blank=format_overwrite
319
(Command  dvd+rw-format -force  can achieve Restricted Overwrite, too.)
320

321 322
Formatting or first use of freshly formatted DVD-RW can produce unusual noises
from the drive and last several minutes. Depending on mutual compatibility of
Thomas Schmitt's avatar
Thomas Schmitt committed
323
drive and media, formatting can yield unusable media. It seems that those die
324
too on blanking by cdrecord, dvd+rw-format or cdrskin. Perils of DVD-RW.
325

326
There are three DVD-RW formatting variants with cdrskin currently:
327 328

blank=format_overwrite  uses "DVD-RW Quick" formatting (MMC-type 15h)
329
and writes a first session of 128 MiB. This leads to media which are expandable
330 331
and random addressable by cdrskin.

332 333 334
blank=format_overwrite_quickest  uses "DVD-RW Quick" formatting (type 15h) too,
but leaves the media in "intermediate" state. In the first session of writing
one may only write sequentially to such a DVD. After that, it gets random
335
addressable by cdrskin. DVD-ROM drives might show ill behavior with them.
336

337 338 339
blank=format_overwrite_full  uses preferrably "Full Format" (type 00h).
This formatting lasts as long as writing a full DVD. It includes writing of
lead-out which is said to be good for DVD ROM compatibility. 
340

341
De-formatting options are available to make overwriteable DVD-RW sequential:
342 343 344 345 346

blank=deformat_sequential  performs thorough blanking of all states of DVD-RW.
blank=all and blank=fast perform the same thorough blanking, but refuse to do
this with overwriteable DVD-RW, thus preserving their formatting. The specs
allow minimal blanking but the resulting media on my drives offer no 
347 348 349
Incremental Streaming afterwards. So blank=fast will do full blanking. 

blank=deformat_sequential_quickest   is faster but might yield DAO-only media.
350 351


352
                             DVD+R and DVD+R DL 
353 354 355

From the view of cdrskin they behave much like DVD-R. Each track gets wrapped
into an own session, though.
356
DVD+R DL appear as extra large DVD+R. cdrskin does not allow to set the address
357
of the layer break where a reading drive might show some delay while switching
358
between both media layers.
359

360 361 362 363 364 365 366 367 368 369 370

                              Emulated Drives

cdrskin can use filesystem objects as emulated drives. Regular files or block
devices appear similar to DVD-RAM. Other file types resemble blank DVD-R.
Necessary precondition is option --allow_emulated_drives which is not accepted
if cdrskin took another user identity because of the setuid bit of its access
permissions.
Addresses of emulated drives begin with prefix "stdio:". E.g.
  dev=stdio:/tmp/my_pseudo_drive

371 372 373
For safety reasons the superuser is only allowed to use /dev/null as emulated
drive. See man page section FILES for a way to lift that ban.

374

375 376
------------------------------------------------------------------------------

377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393
                        Special compilation variations

You may get a (super fat) statically linked binary by :
    cdrskin/compile_cdrskin.sh -static
if your system supports static linking, at all. This will not help with kernels
which do not properly support the necessary low-level interfaces chosen by
your compile-time libraries.

A size reduced but fully functional binary may be produced by 
    cdrskin/compile_cdrskin.sh -do_strip

An extra lean binary with reduced capabilities is created by
    cdrskin/compile_cdrskin.sh -do_diet -do_strip
It will not read startup files, will abort on option  dev_translation= ,
will not have a fifo buffer, and will not be able to put out help texts or
debugging messages.

394 395 396 397 398 399 400 401 402 403 404 405 406 407

------------------------------------------------------------------------------
                      Project aspects and legal stuff
------------------------------------------------------------------------------

Important Disclaimer :

This software is provided as is. There is no warranty implied and no
protection against possible damages. You use this on your own risk.
Don't blame me or other authors of libburn if anything goes wrong.

Actually, in case of severe trouble, nearly always the drive and the media
are the cause. Any mistake of the burn program is supposed to be caught
by the drive's firmware and to lead to mere misburns.
408
The worst mishaps which hit the author imposed the need to reboot the
409
system because of drives gnawing endlessly on ill media. Permanent hardware
410
damage did not occur in 2.5 years of development. But one never knows ...
411 412 413 414 415 416 417 418

------------------------------------------------------------------------------

Interested users are invited to participate in the development of cdrskin.
Contact: scdbackup@gmx.net or libburn-hackers@pykix.org .
We will keep copyright narrow but will of course acknowledge valuable
contributions in a due way.

419 420 421
------------------------------------------------------------------------------

    This program is free software; you can redistribute it and/or modify
422 423
    it under the terms of the GNU General Public License version 2
    as published by the Free Software Foundation.
424 425 426 427 428 429 430 431 432

    This program 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 program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
433

434 435 436 437
------------------------------------------------------------------------------
Based on and sub project of:
libburnia-project.org
By Mario Danic <mario.danic@gmail.com> and Thomas Schmitt <scdbackup@gmx.net>
438
Copyright (C) 2006-2008 Mario Danic, Thomas Schmitt
439 440 441 442 443 444 445 446 447 448

libburnia-project.org is inspired by and in other components still containing
parts of
Libburn. By Derek Foreman <derek@signalmarketing.com> and
            Ben Jansens <xor@orodu.net>
Copyright (C) 2002-2006  Derek Foreman and Ben Jansens
See toplevel README for an overview of the current copyright situation in
libburnia-project.org.


449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479
------------------------------------------------------------------------------
cdrskin is currently copyright Thomas Schmitt only.
It adopts the following commitment by the toplevel copyright holders:
------------------------------------------------------------------------------

We, the copyright holders, agree on the interpretation that
dynamical linking of our libraries constitutes "use of" and
not "derivation from" our work in the sense of GPL, provided
those libraries are compiled from our unaltered code.

Thus you may link our libraries dynamically with applications
which are not under GPL. You may distribute our libraries and
application tools in binary form, if you fulfill the usual
condition of GPL to offer a copy of the source code -altered
or unaltered- under GPL.

We ask you politely to use our work in open source spirit
and with the due reference to the entire open source community.

If there should really arise the case where above clarification
does not suffice to fulfill a clear and neat request in open source
spirit that would otherwise be declined for mere formal reasons,
only in that case we will duely consider to issue a special license
covering only that special case.
It is the open source idea of responsible freedom which will be
decisive and you will have to prove that you exhausted all own
means to qualify for GPL.

For now we are firmly committed to maintain one single license: GPL.

signed for cdrskin: Thomas Schmitt