« back to all changes in this revision
Viewing changes to doc/libcdio.info
- browse files at revision 4
- compare with another revision
- download diff
- download tarball
- view history from revision 4
- Committer: Bazaar Package Importer
- Author(s): Martin Pitt
- Date: 2005-11-15 16:53:23 UTC
- mfrom: (3.1.1 etch)
- Revision ID: james.westby@ubuntu.com-20051115165323-peroku75syl2j36u
Tags: 0.76-1ubuntu1
* Sync to new Debian version, manually apply Ubuntu patches:
- debian/control: Remove dpkg-awk build dependency.
- debian/rules: hardcode $LIBCDEV. This keeps the diff small (compared to
the original patch of changing every ${libcdev} occurence).
- debian/control: Remove dpkg-awk build dependency.
- debian/rules: hardcode $LIBCDEV. This keeps the diff small (compared to
the original patch of changing every ${libcdev} occurence).
- files added:
- debian/libcdio-cdda-dev.install
- example/C++
- lib/cdda_interface
- lib/driver
- lib/driver/FreeBSD
- lib/driver/MSWindows
- lib/driver/image
- lib/iso9660
- lib/paranoia
- package
- src/cd-paranoia
- src/cd-paranoia/doc
- src/cd-paranoia/doc/en
- src/cd-paranoia/doc/jp
- files removed:
- ABOUT-NLS
- lib/FreeBSD
- lib/MSWindows
- lib/image
- files modified:
- ChangeLog
added
removed
doc/libcdio.info
1
This is libcdio.info, produced by makeinfo version 4.5 from
1
This is libcdio.info, produced by makeinfo version 4.8 from
2
2
libcdio.texi.
3
3
4
4
INFO-DIR-SECTION Libraries
8
8
9
9
This file documents GNU CD Input and Control Library
10
10
11
Copyright (C) 2003, 2004 Herbert Valerio Riedel <<hvr@gnu.org>> and
12
Rocky Bernstein <<rocky@panix.com>>
11
Copyright (C) 2003, 2004, 2005 Rocky Bernstein <<rocky@panix.com>> and
12
Herbert Valerio Riedel <<hvr@gnu.org>>
13
13
14
14
Permission is granted to copy, distribute and/or modify this document
15
15
under the terms of the GNU Free Documentation License, Version 1.1 or
24
24
development."
25
25
26
26
27
Indirect:
28
libcdio.info-1: 976
29
libcdio.info-2: 50771
27
File: libcdio.info, Node: Top, Next: History, Prev: (dir), Up: (dir)
28
29
The GNU Compact Disc Input and Control Library (`libcdio')
30
**********************************************************
31
32
This file documents GNU CD input and control library
33
34
Copyright (C) 2003, 2004, 2005 Rocky Bernstein and Herbert Valerio
35
Riedel
36
37
* Menu:
38
39
* History:: How this came about
40
* Previous Work:: The problem and previous work
41
* Purpose:: What is in this package (and what's not)
42
* CD Formats:: A tour through the CD-specification spectrum
43
* CD Image Formats:: A tour through various CD-image formats
44
* CD Units:: The units that make up a CD
45
* How to use:: Okay enough babble, lemme at the library!
46
* Utility Programs:: Diagnostic programs that come with this library
47
* CD-ROM Access and Drivers:: CD-ROM Access and Drivers
48
* Internal Program Organization:: Looking under the hood
49
50
Appendices
51
* ISO-9660 Character Sets::
52
* Glossary::
53
* GNU General Public License::
54
* GNU Free Documentation License::
55
56
Indices
57
* General Index:: Overall index
58
59
60
File: libcdio.info, Node: History, Next: Previous Work, Prev: Top, Up: Top
61
62
1 History
63
*********
64
65
As a result of the repressive Digital Millennium Copyright Act (DMCA) I
66
became aware of Video CD's (VCD's). Video CD's are not subject to the
67
DMCA and therefore enjoy the protection afforded by copyright but no
68
more. But in order for VCD's to be competitive with DVD's, good tools
69
(including GPL tools) are needed for authoring and playing them. And so
70
through VCD's I became aware of the excellent Video CD tools by Herbert
71
Valerio Riedel which form the `vcdimager' package.
72
73
Although vcdimager is great for authoring, examining and extracting
74
parts of a Video CD, it is not a VCD player. And when I looked at the
75
state of Video CD handling in existing VCD players: `xine', `MPlayer',
76
and `vlc', I was a bit disappointed. None handled playback control,
77
menu selections, or playing still frames and segments from track 1.
78
79
Version 0.7.12 of vcdimager was very impressive, however it lacked
80
exportable libraries that could be used in other projects. So with the
81
blessing and encouragement of Herbert Valerio Riedel, I took to extract
82
and create libraries from this code base. The result was two libraries:
83
one to extract information from a VCD which I called libvcdinfo, and
84
another to do the reading and control of a VCD. Well, actually, at this
85
point I should say that a Video CD is really just Video put on a
86
existing well-established Compact Disc or CD format. So the library for
87
this is called `libcdio' rather than `libvcdio'.
88
89
While on the topic of the name `libcdio', I should also explain that
90
the library really doesn't handle writing or output (the final "o" in
91
the name). However it was felt that if I put libcdi that might be
92
confused with a particular CD format called CD-I.
93
94
Later on, the ISO-9660 filesystem handling component from `vcdimager'
95
was extracted, expanded and made a separate library. Next the ability
96
to add MMC commands was added, and then CD paranoia support. And from
97
there, the rest is history.
98
99
100
File: libcdio.info, Node: Previous Work, Next: Purpose, Prev: History, Up: Top
101
102
2 The problem and previous work
103
*******************************
104
105
If around the year 2002 you were to look at the code for a number of
106
open-source CD or media players that work on several platforms such as
107
vlc, MPlayer, xine, or xmms to name but a few, you'd find the code to
108
read a CD sprinkled with conditional compilation for this or that
109
platform. That is there was _no_ OS-independent programmer library for
110
CD reading and control even though the technology was over 10 years
111
old; yet there are media players which strive for OS independence.
112
113
One early CD player, `xmcd' by Ti Kan, was I think a bit better than
114
most in that it tried to _encapsulate_ the kinds of CD control
115
mechanisms (SCSI, Linux ioctl, Toshiba, etc.) in a "CD Audio Device
116
Interface Library" called libdi. However this library is for Audio
117
CD's only and I don't believe this library has been used outside of
118
xmcd.
119
120
Another project, Simple DirectMedia Layer also encapsulates CD reading.
121
122
SDL is a library that allows you portable low-level access to a
123
video framebuffer, audio output, mouse, and keyboard. With SDL, it
124
is easy to write portable games which run on ...
125
126
Many of the media players mentioned above do in fact can make use of
127
the SDL library but for _video_ output only. Because the encapsulation
128
is over _many_ kinds of I/O (video, joysticks, mice, as well as CD's),
129
I believe that the level of control provided for CD a little bit
130
limited. (However to be fair, it may have only been intended for games
131
and may be suitable for that). Applications that just want the CD
132
reading and control portion I think will find quite a bit overhead.
133
134
Another related project is Jo"rg Schilling's SCSI library. You can use
135
that to make a non-SCSI CD-ROM act like one that understands SCSI MMC
136
commands which is a neat thing to do. However it is a little weird to
137
have to install drivers just so you can run a particular user-level
138
program. Installing drivers often requires special privileges and
139
permissions and it is pervasive on a system. It is a little sad that
140
along the way to creating such a SCSI library a library similar to
141
`libcdio' wasn't created which could be used. Were that the case, this
142
library certainly never would have been written.
143
144
At the OS level there is the "A Linux CD-ROM Standard" by David van
145
Leeuwen from around 1999. This defines a set of definitions and ioctl's
146
that mask hardware differences of various Compact Disc hardware. It is
147
a great idea, however this "standard" lacked adoption on OS's other
148
than GNU/Linux. Or maybe it's the case that the standard on other OS's
149
lacked adoption on GNU/Linux. For example on FreeBSD there is a "Common
150
Access Method" (CAM) used for all SCSI access which seems not to be
151
adopted in GNU/Linux.(1)
152
153
Finally at the hardware level where a similar chaos exists, there has
154
been an attempt to do something similar with the MMC (multimedia
155
commands). This attempts to provide a uniform command set for CD
156
devices PostScript does for printer commands.(2) In contrast to
157
PostScript where there one in theory can write a PostScript program in
158
a uniform ASCII representation and send that to a printer, for MMC
159
although there are common internal structures defined, there is no
160
common syntax for representing the structures or an OS-independent
161
library or API for issuing MMC-commands which a programmer would need
162
to use. Instead each Operating System has its own interface. For
163
example Adaptec's ASPI or the Microsoft's DeviceIoControl on Microsoft
164
Windows, or IOKit for Apple's OS/X, or FreeBSD's CAM. I've been
165
positively awed at how many different variations and differing levels
166
of complexity there are for doing basically the same thing. How easy it
167
is to issue an MMC command from a program varies from easy to very
168
difficult. And mastering the boilerplate code to issue an MMC command
169
on one OS really doesn't help much in figuring out how to do it on
170
another OS. So in `libcdio' we provide a common (and hopefully simple)
171
API to issue MMC commands.
172
173
---------- Footnotes ----------
174
175
(1) And I'm thankful for that since, at least for MMC commands, it is
176
inordinately complicated and in some places arcane.
177
178
(2) I wrote "attempts" because over time the command set has changed
179
and now there are several different commands to do a particular
180
function like read a CD table of contents and some hardware understands
181
some of the version of the commands set but might not others
182
183
184
File: libcdio.info, Node: Purpose, Next: CD Formats, Prev: Previous Work, Up: Top
185
186
3 What is in this package (and what's not)
187
******************************************
188
189
The library, `libcdio', encapsulates CD-ROM reading and control.
190
Applications wishing to be oblivious of the OS- and device-dependent
191
properties of a CD-ROM can use this library.
192
193
Also included is a library, `libiso9660', for working with ISO-9660
194
filesystems, `libcdio_paranoia', and `libcdio_cdda' libraries for
195
applications which want to use cdparanoia's error-correction and jitter
196
detection.
197
198
Some support for disk-image types like cdrdao's TOC, CDRWIN's BIN/CUE
199
and Ahead Nero's NRG format is available, so applications that use this
200
library also have the ability to read disc images as though they were
201
CDs.
202
203
`libcdio' also provides a way to issue SCSI "MultiMedia Commands"
204
(MMC). MMC is supported by many hardware CD-ROM manufacturers; and in
205
some cases where a CD-ROM doesn't understand MMC directly, some
206
Operating Systems (such as GNU/Linux, Solaris, or FreeBSD or Microsoft
207
Windows ASPI to name a few) provide the MMC emulation.(1)
208
209
Immediate of the library in this package are the Video CD authoring and
210
ripping tools, VCDImager (`http://vcdimager.org'), a navigation-capable
211
Video CD plugin and CD-DA plugins for the media players xine
212
(`http://xinehq.de') and videolan's vlc (`http://videolan.org/vlc').
213
214
A version of the CD-DA extraction tool cdparanoia
215
(`http://www.xiph.org/paranoia' and its library which corrects for
216
CD-ROM jitter are part of the distribution.
217
218
Also included in the libcdio package is a utility program `cd-info'
219
which displays CD information: number of tracks, CD-format and if
220
possible basic information about the format. If libcddb
221
(`http://libcddb.sourceforge.net') is available, the `cd-info' program
222
will display CDDB matches on CD-DA discs. And if a new enough version
223
of libvcdinfo is available (from the vcdimager project), then `cd-info'
224
shows basic VCD information.
225
226
Other utility programs in the libcdio package are:
227
228
``cdda-player''
229
shows off `libcdio' audio and CD-ROM control commands. It can play
230
a track, eject or load media and show the the status of a CD-DA
231
that is might be currently played via the audio control commands.
232
It can be run in batch mode or has a simple curses-based interface.
233
234
If libcddb is available or a CD has CD-Text and your CD-ROM drive
235
supports CD-Text, track/album information about the CD can be
236
shown.
237
238
``cd-drive''
239
shows what drivers are available and some basic properties of
240
cd-drives attached to the system. (But media may have to be
241
inserted in order to get this info.) lists out drive capabilities
242
243
`cd-read'
244
performs low-level block reading of a CD or CD image,
245
246
``iso-info''
247
displays ISO-9660 information from an ISO-9660 image. Below is some
248
sample output
249
250
iso-info version 0.72
251
Copyright (c) 2003, 2004, 2005 R. Bernstein
252
This is free software; see the source for copying conditions.
253
There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A
254
PARTICULAR PURPOSE.
255
__________________________________
256
ISO 9660 image: ../test/joliet.iso
257
Application: K3B THE CD KREATOR VERSION 0.11.12 (C) 2003 SEBASTIAN TRUEG AND THE K3B TEAM
258
Preparer : K3b - Version 0.11.12
259
Publisher : Rocky Bernstein
260
System : LINUX
261
Volume : K3b data project
262
Volume Set : K3b data project
263
__________________________________
264
ISO-9660 Information
265
/:
266
Oct 22 2004 19:44 .
267
Oct 22 2004 19:44 ..
268
Oct 22 2004 19:44 libcdio
269
270
/libcdio/:
271
Oct 22 2004 19:44 .
272
Oct 22 2004 19:44 ..
273
Mar 12 2004 02:18 COPYING
274
Jun 26 2004 07:01 README
275
Aug 12 2004 06:22 README.libcdio
276
Oct 22 2004 19:44 test
277
278
/libcdio/test/:
279
Oct 22 2004 19:44 .
280
Oct 22 2004 19:44 ..
281
Jul 25 2004 06:52 isofs-m1.cue
282
283
``iso-read''
284
extracts files from an ISO-9660 image.
285
286
287
At present, there is no support for writing CD's. Nor is there any
288
support for reading or writing DVDs. For some of these, there are other
289
libraries (e.g. libdi, libscg, or libdvdread) may be helpful.
290
291
I'm not theoretically opposed to putting support like this into
292
libcdio. However at present there are already many gaps in this
293
package, so narrowing its scope in order to focus on these things I
294
think is a good idea.
295
296
---------- Footnotes ----------
297
298
(1) This concept of software emulation of a common hardware command
299
language is common for printers such as using ghostscript to private
300
postscript emulation for a non-postscript printer.
301
302
303
File: libcdio.info, Node: CD Formats, Next: CD Image Formats, Prev: Purpose, Up: Top
304
305
4 CD Formats
306
************
307
308
Much of what I write in this section can be found elsewhere. See for
309
example `http://www.pctechguide.com/08cd-rom.htm' or
310
`http://www.pcguide.com/ref/cd/format.htm'
311
312
We give just enough background here to cover Compact Discs and Compact
313
Disc formats that are handled by this library.
314
315
The Sony and Philips Corporations invented and Compact Disc (CD) in the
316
early 1980s. The specifications for the layout is often referred to by
317
the color of the cover on the specification.
318
319
* Menu:
320
321
* Red Book:: Red Book (CD-DA) CD Text, CDDB
322
* Yellow Book:: Yellow Book (CD-ROM Digital Data)
323
* Green Book:: Green Book (CD-i)
324
* White Book:: White Book (DV, Video CD)
325
326
327
File: libcdio.info, Node: Red Book, Next: Yellow Book, Up: CD Formats
328
329
4.1 Red Book (CD-DA)
330
====================
331
332
* Menu:
333
334
* CD Text:: CD Text and CD+G
335
* CDDB:: Internet CD Database (CDDB)
336
337
The first type of CD that was produced was the Compact Disc Digital
338
Audio (CD-DA) or just plain "audio CD". The specification, ICE 908, is
339
commonly called the "Red Book". Music CD's are recorded in this format
340
which basically allows for around 74 minutes of audio per disc and for
341
that information to be split up into tracks. Tracks are broken up into
342
"sectors" and each sector contains up to 2,352 bytes. To play one 44.1
343
kHz CD-DA sampled audio second, 75 sectors are used.
344
345
The minute/second/frame numbering of sectors or MSF format is based on
346
the fact that 75 sectors are used in a second of playing of sound. (And
347
for almost every other CD format and application the MSF format doesn't
348
make that much sense).
349
350
In `libcdio' when you you want to read an audio sector, you call
351
`cdio_read_audio_sector()' or `cdio_read_audio_sectors()'.
352
353
In addition the the audio data "channel" a provision for other
354
information or _subchannel_ information) can be stored in a sector.
355
Other subchannels include a Media Catalog Number (also abbreviated as
356
MCN and sometimes a UPC), or album meta data (also called CD-Text).
357
Karioke graphics can also be stored in a format called _CD+G_.
358
359
360
File: libcdio.info, Node: CD Text, Next: CDDB, Up: Red Book
361
362
4.1.1 CD Text, CD+G
363
-------------------
364
365
CD Text is an extension to the CD-DA standard that adds the ability to
366
album and track meta data (titles, artist/performer names, song titles)
367
and and graphical (e.g. Karioke) information. For an alternative way
368
to get album and track meta-data see *Note CDDB::.
369
370
Information is stored in such a way that it doesn't interfere with the
371
normal operation of any CD players or CDROM drives. There are two
372
different parts of the CD where the data can be stored.
373
374
The first place the information can be recorded is in the R-W sub codes
375
in the lead in area of the CD giving a data capacity of about 5,000
376
ASCII characters (or 2,500 Kanji or Unicode characters). This
377
information is stored as a single block of data and is the format used
378
in virtually all of the CD Text CDs shipping today. The method for
379
reading this data from a CDROM drive is covered under the Sony proposal
380
to the MMC specification. The format of the data is partially covered
381
in the MMC specification.
382
383
The second place the information can be recorded is in the R-W sub
384
codes in the program area of the CD giving a data capacity of roughly
385
31MB. This information is stored in a format that follows the
386
Interactive Text Transmission System (ITTS) which is the same data
387
transmission standard used by such things as Digital Audio Broadcasting
388
(DAB), and virtually the same as the data standard for the MiniDisc.
389
Traditionally the R-W sub codes have been used for text and graphics in
390
applications such as CD+G (CD w/graphics) or in the case of most audio
391
CDs, not at all. The methods for reading this data from a CD-ROM drive
392
is covered by the programming specs from the individual drive
393
manufacturers. In the case of ATAPI drives, the SFF8020 spec covers the
394
reading of the RW subcodes.
395
396
Not all drives support reading the RW subcodes from the program area.
397
However for those that do, `libcdio' provides a way to get at this
398
information via `cdtext_get()' and its friends.
399
400
401
File: libcdio.info, Node: CDDB, Prev: CD Text, Up: Red Book
402
403
4.1.2 Internet CD Database (CDDB)
404
---------------------------------
405
406
CDDB is an database on the Internet of of CD album/track, artist, and
407
genre information similar to CD Text information. Using track
408
information (number of tracks and length of the tracks), devices that
409
have access to the Internet can query for meta information and
410
contribute information for CD's where there is no existing information.
411
When storage is available (such as you'd expect for any program using
412
`libcdio', the information is often saved for later use when the
413
Internet is not available; people tend request the same information
414
since they via programs play the same music.
415
416
Obtaining CD meta information when none is encoded in an audio CD is
417
useful in media players or making one's own compilations from audio CDs.
418
419
There are currently two popular CDDB services on the Internet. The
420
original database has been renamed Gracenote and is a profit making
421
entity. FreeDB (`http://freedb.org' is an open source CD information
422
resource that is free for developers and the public to use.
423
424
As there already is an excellent library for handling CDDB libcddb
425
(`http://libcddb.sourceforge.net' we suggest using that. Our utility
426
program `cd-info' will make use it if it is available and it's what we
427
use in our applications that need it.
428
429
430
File: libcdio.info, Node: Yellow Book, Next: Green Book, Prev: Red Book, Up: CD Formats
431
432
4.2 Yellow Book (CD-ROM Digital Data)
433
=====================================
434
435
The CD-ROM specification or the "Yellow Book" followed a few years
436
later (Standards ISO/IEC 10149), and describes the extension of CD's to
437
store computer data, i.e. CD-ROM (Compact Disk Read Only Memory).
438
439
The specification in the Yellow Book defines two modes: Mode 1 and Mode
440
2.
441
442
* Menu:
443
444
* ISO 9660::
445
* Mode 1:: Mode 1 Format
446
* Mode 2:: Mode 2 Format
447
448
449
File: libcdio.info, Node: ISO 9660, Next: Mode 1, Up: Yellow Book
450
451
4.2.1 ISO 9660
452
--------------
453
454
* Menu:
455
456
* ISO 9660 Level 1::
457
* ISO 9660 Level 2::
458
* ISO 9660 Level 3::
459
* Joliet Extensions::
460
* Rock Ridge Extensions::
461
462
The Yellow Book doesn't specify how data is to be stored on a CD-ROM.
463
It was feared that different companies would implement proprietary data
464
storage formats using this specification, resulting in incompatible
465
data CDs. To prevent this, representatives of major manufacturers met
466
at the High Sierra Hotel and Casino in Lake Tahoe, NV, in 1985, to
467
define a standard for storing data on CDs. This format was nicknamed
468
High Sierra Format. In a slightly modified form it was later adopted as
469
ISO the ISO 9660 standard. This standard is further broken down into 3
470
"levels", the higher the level, the more permissive.
471
472
473
File: libcdio.info, Node: ISO 9660 Level 1, Next: ISO 9660 Level 2, Up: ISO 9660
474
475
4.2.1.1 ISO 9660 Level 1
476
........................
477
478
Level 1 ISO 9660 defines names in the 8+3 convention so familiar to
479
MS-DOS: eight characters for the filename, a period, and then three
480
characters for the file type, all in upper case. The allowed characters
481
are A-Z, 0-9, ".", and "_".Level 1 ISO 9660 requires that files occupy
482
a contiguous range of sectors. This allows a file to be specified with
483
a start block and a count. The maximum directory depth is 8. For a
484
table of the characters, see *Note ISO-9660 Character Sets::.
485
486
487
File: libcdio.info, Node: ISO 9660 Level 2, Next: ISO 9660 Level 3, Prev: ISO 9660 Level 1, Up: ISO 9660
488
489
4.2.1.2 ISO 9660 Level 2
490
........................
491
492
Level 2 ISO 9660 allows far more flexibility in filenames, but isn't
493
usable on some systems, notably MS-DOS.
494
495
496
File: libcdio.info, Node: ISO 9660 Level 3, Next: Joliet Extensions, Prev: ISO 9660 Level 2, Up: ISO 9660
497
498
4.2.1.3 ISO 9660 Level 3
499
........................
500
501
Level 3 ISO-9660 allows non-contiguous files, useful if the file was
502
written in multiple packets with packet-writing software.
503
504
There have been a number of extensions to the ISO 9660 CD-ROM file
505
format. One extension is Microsoft's Joliet specification, designed to
506
resolve a number of deficiencies in the original ISO 9660 Level 1 file
507
system, and in particular to support the long file names used in
508
Windows 95 and subsequent versions of Windows.
509
510
Another extension is the Rock Ridge Interchange Protocol (RRIP), which
511
enables the recording of sufficient information to support POSIX File
512
System semantics.
513
514
515
File: libcdio.info, Node: Joliet Extensions, Next: Rock Ridge Extensions, Prev: ISO 9660 Level 3, Up: ISO 9660
516
517
4.2.1.4 Joliet Extensions
518
.........................
519
520
Joliet extensions were an upward-compatible extension to the ISO 9660
521
specification that removes the limitation initially put in to deal with
522
the limited filename conventions found in Microsoft DOS OS. In
523
particular, the Joliet specification allows for long filenames and
524
allows for UCS-BE (Big-endian Unicode) encoding of filenames which
525
include mixed case letter, accented characters spaces and various
526
symbols.
527
528
The way all of this is encoded is by adding a second directory and
529
filesystem structure in addition to or in parallels to original ISO
530
9600 filesystem. The root node of the ISO 9660 filesystem is found via
531
the _Primary Volume Descriptor_ or _PVD_. The root of the Joliet-encode
532
filesystem is found in a Supplementary Volume Descriptor or _SVD_
533
defined in the ISO 9660 specification. The SVD structure is almost
534
identical to a PVD with a couple of unused fields getting used and with
535
the filename encoding changed to UCS-BE.
536
537
538
File: libcdio.info, Node: Rock Ridge Extensions, Prev: Joliet Extensions, Up: ISO 9660
539
540
4.2.1.5 Rock Ridge Extensions
541
.............................
542
543
Using the Joliet Extension one overcome the limitedness of the original
544
ISO-9660 naming scheme. But another and probably better method is to
545
use the Rock Ridge Extension. Not only can one store a filename as one
546
does in a POSIX OS, but the other file attributes, such as the various
547
timestamps (creation, modification, access), file attributes (user,
548
group, file mode permissions, device type, symbolic links) can be
549
stored. This is much as one would do in XA attributes; however the two
550
are not completely interchangeable in the information they store: XA
551
does _not_ address filename limitations, and the Rock Ridge extensions
552
don't indicate if a sector is in Mode 1 or Mode 2 format.
553
554
The Rock Ridge extension makes use of a hook that was defined as part
555
of the ISO 9660 standard.
556
557
558
File: libcdio.info, Node: Mode 1, Next: Mode 2, Prev: ISO 9660, Up: Yellow Book
559
560
4.2.2 Mode 1 (2048 data bytes per sector)
561
-----------------------------------------
562
563
Mode 1 is the data storage mode used by to store computer data. There
564
are 3 layers of error correction. A Compact Disc using only this format
565
can hold at most 650 MB. The data is laid out in basically the same way
566
as in and audio CD format, except that the 2,352 bytes of data in each
567
block are broken down further. 2,048 of these bytes are for "real"
568
data. The other 304 bytes are used for an additional level of error
569
detecting and correcting code. This is necessary because data CDs
570
cannot tolerate the loss of a handful of bits now and then, the way
571
audio CDs can.
572
573
In `libcdio' when you you want to read a mode1 sector you call the
574
`cdio_read_mode1_sector()' or `cdio_read_mode1_sectors()'.
575
576
577
File: libcdio.info, Node: Mode 2, Prev: Mode 1, Up: Yellow Book
578
579
4.2.3 Mode 2 (2336 data bytes per sector)
580
-----------------------------------------
581
582
Mode 2 data CDs are the same as mode 1 CDs except that the error
583
detecting and correcting codes are omitted. So still there are 2 layers
584
of error correction. A Compact Disc using only this mode can thus hold
585
at most 742 MB. Similar to audio CDs, the mode 2 format provides a more
586
flexible vehicle for storing types of data that do not require high
587
data integrity: for example, graphics and video can use this format.
588
But in contrast to the Red Book standard, different modes can be mixed
589
together; this is the basis for the extensions to the original data CD
590
standards known as CD-ROM Extended Architecture, or CD-ROM XA. CD-ROM
591
XA formats currently in use are CD-I Bridge formats, Photo CD and Video
592
CD plus Sony's Playstation.
593
594
In `libcdio' when you you want to read a mode1 sector you call the
595
`cdio_read_mode2_sector()' or `cdio_read_mode2_sectors()'.
596
597
598
File: libcdio.info, Node: Green Book, Next: White Book, Prev: Yellow Book, Up: CD Formats
599
600
4.3 Green Book (CD-i)
601
=====================
602
603
This was a CD-ROM format developed by Philips for CD-i (an obsolete
604
embedded CD-ROM application allowing limited user user interaction with
605
films, games and educational applications). The format is ISO 9660
606
compliant and introduced mode 2 form 2 addressing. It also contains XA
607
(Extended Architecture) attributes.
608
609
Although some Green Book discs contain CD-i applications which can only
610
be played on a CD-i player, others have films or music videos. Video
611
CDs in Green-Book format are labeled "Digital Video on CD." The Green
612
Book for video is largely superseded by White book CD-ROM which draws
613
on this specification.
614
615
616
File: libcdio.info, Node: White Book, Prev: Green Book, Up: CD Formats
617
618
4.4 White Book (DV, Video CD)
619
=============================
620
621
The White Book was released by Sony, Philips, Matsushita, and JVC in
622
1993, defines the Video CD specification. The White Book is also known
623
as Digital Video (DV).
624
625
A Video CD contains one data track recorded in CD-ROM XA Mode 2 Form 2.
626
It is always the first track on the disc (Track 1). The ISO-9660 file
627
structure and a CD-i application program are recorded in this track, as
628
well as the Video CD Information Area which gives general information
629
about the Video Compact Disc. After the data track, video is written in
630
one or more subsequent tracks within the same session. These tracks are
631
also recorded in Mode 2 Form 2.
632
633
In `libcdio' when you you want to read a mode2 format 2 audio sector
634
you call the `cdio_read_mode2_sector()' or `cdio_read_mode2_sectors()'
635
setting `b_form2' to `true'.
636
637
638
File: libcdio.info, Node: CD Image Formats, Next: CD Units, Prev: CD Formats, Up: Top
639
640
5 CD Image Formats
641
******************
642
643
* Menu:
644
645
* CDRDAO TOC Format::
646
* CDRWIN BIN/CUE Format::
647
* NRG Format::
648
649
In both the `cdrdao' and bin/cue formats there is one meta-file with
650
extensions `.toc' or `.cue' respectively and one or more files (often
651
with the extension `.bin') which contains the content of tracks. The
652
format of the track data is often interchangeable between the two
653
formats. For example, in `libcdio''s regression tests we make use of
654
this to reduce the size of the test data and just provide alternate
655
meta-data files (`.toc' or `.cue').
656
657
In contrast to the first two formats, the NRG format consists of a
658
single file. This has the advantage of being a self-contained unit: in
659
the other two formats it is possible for the meta file to refer to a
660
file that can't be found. A disadvantage of the NRG format is that the
661
meta data can't be easily viewed or modified say in a text file as it
662
can be with the first two formats. In conjunction with this
663
disadvantage is another disadvantage that the format is not documented,
664
so how `libcdio' interprets an NRG image is based on inference. It is
665
recommended that one of the other forms be used instead of NRG where
666
possible.
667
668
669
File: libcdio.info, Node: CDRDAO TOC Format, Next: CDRWIN BIN/CUE Format, Up: CD Image Formats
670
671
5.1 CDRDAO TOC Format
672
=====================
673
674
This is `cdrdao''s CD-image description format. Since this program is
675
GPL and everything about it is in the open, it is the preferred format
676
to use. (Alas, at present it isn't as well supported in `libcdio' as
677
the BIN/CUE format.)
678
679
The _toc_-file describes what data is written to the media in the
680
CD-ROM; it allows control over track/index positions, pre-gaps and
681
sub-channel information. It is a text file, so a text editor can be
682
used to create, view or modify it.
683
684
The `cdrdao(1) manual page', contains more information about this
685
format.
686
687
5.1.1 CDRDAO Grammar
688
--------------------
689
690
Below are the lexical tokens and grammar for a cdrdao TOC. It was taken
691
from the cdrdao's pacct grammar; the token and nonterminal names are
692
the same.
693
694
#lexclass START
695
#token Eof "@"
696
#token "[\t\r\ ]+"
697
#token Comment "//~[\n@]*"
698
#token "\n"
699
#token BeginString "\""
700
#token Integer "[0-9]+"
701
#tokclass AudioFile { "AUDIOFILE" "FILE" }
702
703
#lexclass STRING
704
#token EndString "\""
705
#token StringQuote "\\\""
706
#token StringOctal "\\[0-9][0-9][0-9]"
707
#token String "\\"
708
#token String "[ ]+"
709
#token String "~[\\\n\"\t ]*"
710
711
712
<toc> ::= ( "CATALOG" <string> | <tocType> )* { <cdTextGlobal> }
713
( <track> )+ Eof
714
715
<track> ::= "TRACK" <trackMode>
716
{ <subChannelMode> }
717
( "ISRC" <string> | { "NO" } "COPY" | { "NO" } "PRE_EMPHASIS"
718
| "TWO_CHANNEL_AUDIO" | "FOUR_CHANNEL_AUDIO" )*
719
{ <cdTextTrack> }
720
{ "PREGAP" <msf> }
721
( <subTrack> | "START" { msf } | "END" { msf } )+
722
( "INDEX" <msf> )*
723
724
<subTrack> ::=
725
AudioFile <string> { "SWAP" } { "#" <sLong> } <samples>
726
| "DATAFILE" <string> { "#" <sLong> { <dataLength> } }
727
| "FIFO" <string> <dataLength>
728
| "SILENCE" <samples>
729
| "ZERO" { dataMode } { <subChannelMode> } <dataLength>
730
731
732
<string> ::= BeginString ( String | StringQuote | StringOctal )+
733
EndString
734
735
<stringEmpty> ::= BeginString ( String | StringQuote | StringOctal )*
736
EndString
737
738
<uLong> ::= Integer
739
740
<sLong> ::= Integer
741
742
<msf> ::= Integer ":" Integer ":" Integer
743
744
<samples> ::= <msf> | <uLong>
745
746
<dataLength> ::= <msf> | <uLong>
747
748
<dataMode> ::= "AUDIO" | "MODE0" | "MODE1" | "MODE1_RAW" | "MODE2"
749
| "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX"
750
751
<trackMode> ::= "AUDIO" | "MODE1" | "MODE1_RAW" | "MODE2"
752
| "MODE2_RAW" | "MODE2_FORM1" | "MODE2_FORM2" | "MODE2_FORM_MIX"
753
754
<subChannelMode> ::= "RW" | "RW_RAW"
755
756
<tocType> ::= "CD_DA" | "CD_ROM" | "CD_ROM_XA" | "CD_I"
757
758
<packType> ::= "TITLE" | "PERFORMER" | "SONGWRITER" | "COMPOSER" | "ARRANGER"
759
| "MESSAGE" | "DISC_ID" | "GENRE" | "TOC_INFO1" | "TOC_INFO2"
760
| "RESERVED1" | "RESERVED2" | "RESERVED3" | "RESERVED4" | "UPC_EAN" |
761
"ISRC" | "SIZE_INFO"
762
763
<binaryData> ::= "{"
764
{ Integer ( "," Integer )* }
765
"}"
766
767
<cdTextItem> ::= <packType> ( <stringEmpty> | <binaryData> )
768
769
<cdTextBlock> ::= "LANGUAGE" Integer "{" ( <cdTextItem> )* "}"
770
771
<cdTextLanguageMap> ::=
772
"LANGUAGE_MAP" "{"
773
( Integer ":" ( Integer | "EN" ) )+
774
"}"
775
776
<cdTextTrack> ::= "CD_TEXT" "{" ( <cdTextBlock> )* "}"
777
778
<cdTextGlobal> ::= "CD_TEXT" "{" { <cdTextLanguageMap> } ( <cdTextBlock> )* "}"
779
780
781
File: libcdio.info, Node: CDRWIN BIN/CUE Format, Next: NRG Format, Prev: CDRDAO TOC Format, Up: CD Image Formats
782
783
5.2 CDRWIN BIN/CUE Format
784
=========================
785
786
The format referred to as _CDRWIN BIN/CUE Format_ in this manual is a
787
popular CD image format used in the PC world. Not unlike `cdrdao''s TOC
788
file, the _cue_ file describes the track layout, i.e. how the sectors
789
are to be placed on the CD media. The _cue_ file usually contains a
790
reference to a file traditionally having the `.bin' extension in its
791
filename, the _bin_ file. This _bin_ file contains the sector data
792
payload which is to be written to the CD medium according to the
793
description in the _cue_ file.
794
795
The following is an attempt to describe the subset of the `.cue' file
796
syntax used in `libcdio' and vcdimager in an EBNF-like notation:
797
798
5.2.1 BIN/CUE Grammar
799
---------------------
800
801
<cue-document> ::= +( <file-line> +<track-expr> )
802
803
<digit> ::= "0" | "1" ... "8" | "9"
804
<number> ::= +<digit>
805
<msf> ::= <digit><digit> ":" <digit><digit> ":" <digit><digit>
806
807
<file-line> ::= "FILE" <pathname-expr> <file-type> <EOL>
808
809
<pathname-expr> ::= [ "\"" ] <pathname-str-without-spaces> [ "\"" ]
810
| "\"" <pathname-str> "\""
811
812
<file-type> ::= "BINARY"
813
814
<track-expr> ::= <track-line> [ <flag-line> ]
815
[ <pregap-line> ] *<index-line> [ <postgap-line> ]
816
817
<flag-line> ::= "FLAGS" *<flag-type> <EOL>
818
<flag-type> ::= "DCP"
819
820
<track-line> ::= "TRACK" <number> <track-type> <EOL>
821
822
<pregap-line> ::= "PREGAP" <msf> <EOL>
823
824
<index-line> ::= "INDEX" <number> <msf> <EOL>
825
826
<postgap-line> ::= "POSTGAP" <msf> <EOL>
827
828
<track-type> ::= "AUDIO" | "MODE1/2048" | "MODE1/2352"
829
| "MODE2/2336" | "MODE2/2352"
830
831
<comment-line> ::= "REM" *<char> <EOL>
832
833
834
File: libcdio.info, Node: NRG Format, Prev: CDRWIN BIN/CUE Format, Up: CD Image Formats
835
836
5.3 NRG Format
837
==============
838
839
The format referred to as _NRG Format_ in this manual is another
840
popular CD image format. It is available only on Nero software on a
841
Microsoft Windows Operating System. It is proprietary and not generally
842
published, so the information we have comes from guessing based on
843
sample CD images. So support for this is incomplete and using this
844
format is not recommended.
845
846
Unlike `cdrdao''s TOC file the BIN/CUE format everything is contained
847
in one file. that one can edit Meta information such as the number of
848
tracks and track format is contained at the end of the file. This
849
information is not intended to be edited through a text editor.
850
851
852
File: libcdio.info, Node: CD Units, Next: How to use, Prev: CD Image Formats, Up: Top
853
854
6 The units that make up a CD
855
*****************************
856
857
* Menu:
858
859
* Tracks:: Tracks
860
* Sectors:: Block addressing (MSF, LSN, LBA)
861
862
863
File: libcdio.info, Node: Tracks, Next: Sectors, Up: CD Units
864
865
6.1 tracks -- disc subdivisions
866
===============================
867
868
In this section we describe CD properties and terms that we make use of
869
in `libcdio'.
870
871
A CD is formated into a number of _tracks_, and a CD can hold at most
872
99 such tracks. This is defined by `CDIO_CD_MAX_TRACKS' in
873
`cdio/sector.h'. Between the tracks CD specifications require a "2
874
second" in gap (called a _lead-in gap_. This is unused space with no
875
"data" similar to the space between tracks on an old phonograph. The
876
word "second" here really refers to a measure of space and not really
877
necessarily an amount of time. However in the special case that the CD
878
encodes an audio CD or CD-DA, the amount of time to play a gap of this
879
size will take 2 seconds.
880
881
The beginning (or inner edge) of the CD is supposed to have a "2
882
second" lead-in gap and there is supposed to be another "2 second"
883
_lead-out_ gap at the end (or outer edge) of the CD.
884
885
People have discovered that they can put useful data in the various
886
gaps and their equipment can read this, violating the standards but
887
allowing a CD to store more data.
888
889
In order to determine the number of tracks on a CD and where they
890
start, commands are used to get this table-of-contents or _TOC_
891
information. Asking about the start of the _lead-out track_ gives the
892
amount of data stored on the Compact Disk. To make it easy to specify
893
this leadout track, special constant 0xAA (decimal 170) is used to
894
indicate it. This is safe since this is higher than the largest legal
895
track position. In `libcdio', `CDIO_CDROM_LEADOUT_TRACK' is defined to
896
be this special value.
897
898
899
File: libcdio.info, Node: Sectors, Prev: Tracks, Up: CD Units
900
901
6.2 block addressing (MSF, LSN, LBA)
902
====================================
903
904
A track is broken up into a number of 2352-byte _blocks_ which we
905
sometimes call _sectors_ or _frames_. Whereas tracks have to have a gap
906
between them, a block or sector does not. (In `libcdio' the block size
907
constant is defined using `CDIO_CD_FRAMESIZE_RAW').
908
909
A Compact Disc has a limit on the number of blocks or sectors. This
910
values is defined by constant `CDIO_CD_MAX_LSN' in `cdio/sector.h'.
911
912
One can addressing a block in one of three formats. The oldest format
913
is by it's minute/second/frame number, also referred to as _MSF_ and
914
written in time-like format MM:SS:FF (e.g. 30:01:40). It is best suited
915
in audio (Red Book) applications. In `libcdio', the type `msf_t' can be
916
used to declare variables to hold such values. Minute, second and frame
917
values are one byte _and stored BCD notation_.(1) There are `libcdio'
918
conversion routines `cdio_from_bcd8()' and `cdio_to_bcd8()' to convert
919
the minute, second, and frame values into or out of integers. If you
920
want to print a field in a BCD-encoded MSF, one can use the format
921
specifier `%x' _(not `%d')_ and things will come out right.
922
923
In the MSF notation, there are 75 "frames" in a "second," and the
924
familiar (if awkward) 60 seconds in a minute. _Frame_ here is what we
925
called a _block_ above. The CD specification defines "frame" to be
926
_another_ unit which makes up a block. Very confusing. A frame is also
927
sometimes called a sector, analogous to hard-disk terminalogy.
928
929
Even more confusing is using this time-like notation for an address or
930
for a length. Too often people confuse the MSF notation this with an
931
amount of time. A "second" (or `CDIO_CD_FRAMES_PER_SEC' blocks) in this
932
notation is only a second of playing time for something encoded as
933
CD-DA. It does _not_ necessarily represent the amount time that it will
934
take to play a of Video CD--usually you need more blocks than this. Nor
935
does it represent the amount of data used to play a second of an
936
MP3--usually you need fewer blocks than this. It is also not the amount
937
of time your CD-ROM will take to read a "second" of data off a Compact
938
Disc: for example a 12x CD player will read 12x `CDIO_CD_FRAMES_PER_SEC'
939
`CDIO_CD_FRAMSIZE_RAW'-byte blocks in a one second of time.
940
941
When programming, unless one is working with a CD-DA (and even here,
942
only in a time-like fashion), is generally more cumbersome to use an
943
MSF rather than a LBA or LSN described below, since subtraction of two
944
MSF's has the awkwardness akin to subtraction using Roman Numerals.
945
946
Probably the simplest way to address a block is to use its _LSN_ or
947
"logical sector number." This just numbers the blocks usually from 0
948
on. _fix me: LSNs can be negative up to the pregap size?_ The Lead-in
949
and Lead-out gaps described above have LSNs just like any other space
950
on a CD. The last unit of address is a _LBA_. It is the same as a LSN
951
but the 150 blocks associated with the initial lead-in is are not
952
counted. So to convert a LBA into an LSN you just add 150. Why the
953
distinction between LBA and LSN? I don't know, perhaps this has
954
something to do with "multisession" CDs.
955
956
---------- Footnotes ----------
957
958
(1) Perhaps this is a `libcdio' design flaw. It was originally done I
959
guess because it was convenient for VCDs.
960
961
962
File: libcdio.info, Node: How to use, Next: Utility Programs, Prev: CD Units, Up: Top
963
964
7 How to use
965
************
966
967
The `libcdio' package comes with a number of small example programs in
968
the directory `example' which demonstrate different aspects of the
969
library and show how to use the library. The source code to all of the
970
examples here are contained on the package.
971
972
Other sources for examples would be the larger utility programs
973
`cd-drive', `cd-info', `cd-read', `iso-info', and `iso-read' which are
974
all in the `src' directory of the `libcdio' package. See also *Note
975
Utility Programs::.
976
977
* Menu:
978
979
* Example 1:: list out tracks and LSNs
980
* Example 2:: list drivers available and default CD device
981
* Example 3:: figure out what kind of CD (image) we've got
982
* Example 4:: use libiso9660 to extract a file from an ISO-9660 image
983
* Example 5:: list CD-Text and CD disc mode info
984
* Example 6:: run a MMC INQUIRY command
985
* Example 7:: using the CD Paranoia library for CD-DA reading
986
* All sample programs:: list of all programs in the example directory
987
988
989
File: libcdio.info, Node: Example 1, Next: Example 2, Up: How to use
990
991
7.1 Example 1: list out tracks and LSNs
992
=======================================
993
994
Here we will give an annotated example which can be found in the
995
distribution as `example/tracks.c'.
996
997
1: #include <stdio.h>
998
2: #include <sys/types.h>
999
3: #include <cdio/cdio.h>
1000
4: int
1001
5: main(int argc, const char *argv[])
1002
6: {
1003
7: CdIo_t *p_cdio = cdio_open ("/dev/cdrom", DRIVER_DEVICE);
1004
8: track_t first_track_num = cdio_get_first_track_num(p_cdio);
1005
9: track_t i_tracks = cdio_get_num_tracks(p_cdio);
1006
10: int j, i=first_track_num;
1007
11:
1008
12: printf("CD-ROM Track List (%i - %i)\n", first_track_num, i_tracks);
1009
13
1010
14: printf(" #: LSN\n");
1011
15:
1012
16: for (j = 0; j < i_tracks; i++, j++) {
1013
17: lsn_t lsn = cdio_get_track_lsn(p_cdio, i);
1014
18: if (CDIO_INVALID_LSN != lsn)
1015
19: printf("%3d: %06d\n", (int) i, lsn);
1016
20: }
1017
21: printf("%3X: %06d leadout\n", CDIO_CDROM_LEADOUT_TRACK,
1018
22: cdio_get_track_lsn(p_cdio, CDIO_CDROM_LEADOUT_TRACK));
1019
23: cdio_destroy(p_cdio);
1020
24: return 0;
1021
25: }
1022
1023
Already from the beginning on line 2 we see something odd. The
1024
`#include <sys/types.h>' is needed because `libcdio' assumes type
1025
definitions exist for `uint32_t', `uint16_t' and so on. Alternatively
1026
you change line 2 to:
1027
1028
#define HAVE_SYS_TYPES_H
1029
1030
and `<cdio/cdio.h>' will insert line 2. If you use GNU autoconf to
1031
configure your program, add `sys/types.h' to `AC_HAVE_HEADERS' and _it_
1032
will arrange for `HAVE_SYS_TYPES_H' to get defined. If you don't have
1033
`<sys/types.h>' but have some other include that defines these types,
1034
put that instead of line 2. Or you could roll your own typedefs. (Note:
1035
In the future, this will probably get "fixed" by requiring glib.h.)
1036
1037
Okay after getting over the hurdle of line 2, the next line pretty
1038
straightforward: you need to include this to get cdio definitions. One
1039
of the types that is defined via line 3 is `CdIo_t' and a pointer that
1040
is used pretty much in all operations. Line 6 initializes the variable
1041
`cdio' which we will be using in all of the subsequent libcdio calls.
1042
It does this via a call to `cdio_open()'.
1043
1044
The second parameter of `cdio_open' is DRIVER_UNKNOWN. For any given
1045
installation a number of Compact Disc device drivers may be available.
1046
In particular it's not uncommon to have several drivers that can read
1047
CD disk-image formats as well as a driver that handles some CD-ROM
1048
piece of hardware. Using DRIVER_UNKNOWN as that second parameter we let
1049
the library select a driver amongst those that are available; generally
1050
the first hardware driver that is available is the one selected.
1051
1052
If there is no CD in any of the CD-ROM drives or one does not have
1053
access to the CD-ROM, it is possible that `libcdio' will find a CD
1054
image in the directory you run this program and will pick a suitable
1055
CD-image driver. If this is not what you want, but always want some
1056
sort of CD-ROM driver (or failure if none), then use DRIVER_DEVICE
1057
instead of DRIVER_UNKNOWN.
1058
1059
Note that in contrast to what is typically done using ioctls to read a
1060
CD, you don't issue any sort of CD-ROM read TOC command--that is all
1061
done by the driver. Of course, the information that you get from
1062
reading the TOC is often desired: many tracks are on the CD, or what
1063
number the first one is called. This is done through calls on lines 8
1064
and 9.
1065
1066
For each track, we call a cdio routine to get the logical sector
1067
number, `cdio_get_track_lsn()' on line 17 and print the track number
1068
and LSN value. Finally we print out the "lead-out track" information
1069
and we finally call `cdio_destroy()' in line 23 to indicate we're done
1070
with the CD.
1071
1072
1073
File: libcdio.info, Node: Example 2, Next: Example 3, Prev: Example 1, Up: How to use
1074
1075
7.2 Example 2: list drivers available and default CD device
1076
===========================================================
1077
1078
One thing that's a bit hoaky in Example 1 is hard-coding the name of
1079
the device used: `/dev/cdrom'. Although often this is the name of a
1080
CD-ROM device on GNU/Linux and possibly some other Unix derivatives,
1081
there are many OSs for which use a different device name.
1082
1083
In the next example, we'll let the driver give us the name of the CD-ROM
1084
device that is right for it.
1085
1086
1: #include <stdio.h>
1087
2: #include <sys/types.h>
1088
3: #include <cdio/cdio.h>
1089
4: int
1090
5: main(int argc, const char *argv[])
1091
6: {
1092
7: CdIo_t *p_cdio = cdio_open (NULL, DRIVER_DEVICE);
1093
8: driver_id_t driver_id;
1094
9:
1095
10: if (NULL != p_cdio) {
1096
11: printf("The driver selected is %s\n", cdio_get_driver_name(p_cdio));
1097
12: printf("The default device for this driver is %s\n\n",
1098
13: cdio_get_default_device(p_cdio));
1099
14: cdio_destroy(p_cdio);
1100
15: } else {
1101
16: printf("Problem in trying to find a driver.\n\n");
1102
17: }
1103
18:
1104
19: for (driver_id=CDIO_MIN_DRIVER; driver_id<=CDIO_MAX_DRIVER; driver_id++)
1105
20: if (cdio_have_driver(driver_id))
1106
21: printf("We have: %s\n", cdio_driver_describe(driver_id));
1107
22: else
1108
23: printf("We don't have: %s\n", cdio_driver_describe(driver_id));
1109
24: return 0;
1110
25: }
1111
1112
1113
File: libcdio.info, Node: Example 3, Next: Example 4, Prev: Example 2, Up: How to use
1114
1115
7.3 Example 3: figure out what kind of CD (image) we've got
1116
===========================================================
1117
1118
In this example is a somewhat simplified program to show the use of
1119
`cdio_guess_cd_type()' to figure out the kind of CD image we've got.
1120
This can be found in the distribution as `example/sample3.c'.
1121
1122
#ifdef HAVE_CONFIG_H
1123
# include "config.h"
1124
#endif
1125
#include <stdio.h>
1126
#include <string.h>
1127
#include <sys/types.h>
1128
#include <cdio/cdio.h>
1129
#include <cdio/cd_types.h>
1130
1131
static void
1132
print_analysis(cdio_iso_analysis_t cdio_iso_analysis,
1133
cdio_fs_anal_t fs, int first_data, unsigned int num_audio,
1134
track_t i_tracks, track_t first_track_num, CdIo_t *cdio)
1135
{
1136
switch(CDIO_FSTYPE(fs)) {
1137
case CDIO_FS_AUDIO:
1138
break;
1139
case CDIO_FS_ISO_9660:
1140
printf("CD-ROM with ISO 9660 filesystem");
1141
if (fs & CDIO_FS_ANAL_JOLIET) {
1142
printf(" and joliet extension level %d", cdio_iso_analysis.joliet_level);
1143
}
1144
if (fs & CDIO_FS_ANAL_ROCKRIDGE)
1145
printf(" and rockridge extensions");
1146
printf("\n");
1147
break;
1148
case CDIO_FS_ISO_9660_INTERACTIVE:
1149
printf("CD-ROM with CD-RTOS and ISO 9660 filesystem\n");
1150
break;
1151
case CDIO_FS_HIGH_SIERRA:
1152
printf("CD-ROM with High Sierra filesystem\n");
1153
break;
1154
case CDIO_FS_INTERACTIVE:
1155
printf("CD-Interactive%s\n", num_audio > 0 ? "/Ready" : "");
1156
break;
1157
case CDIO_FS_HFS:
1158
printf("CD-ROM with Macintosh HFS\n");
1159
break;
1160
case CDIO_FS_ISO_HFS:
1161
printf("CD-ROM with both Macintosh HFS and ISO 9660 filesystem\n");
1162
break;
1163
case CDIO_FS_UFS:
1164
printf("CD-ROM with Unix UFS\n");
1165
break;
1166
case CDIO_FS_EXT2:
1167
printf("CD-ROM with Linux second extended filesystem\n");
1168
break;
1169
case CDIO_FS_3DO:
1170
printf("CD-ROM with Panasonic 3DO filesystem\n");
1171
break;
1172
case CDIO_FS_UNKNOWN:
1173
printf("CD-ROM with unknown filesystem\n");
1174
break;
1175
}
1176
switch(CDIO_FSTYPE(fs)) {
1177
case CDIO_FS_ISO_9660:
1178
case CDIO_FS_ISO_9660_INTERACTIVE:
1179
case CDIO_FS_ISO_HFS:
1180
printf("ISO 9660: %i blocks, label `%.32s'\n",
1181
cdio_iso_analysis.isofs_size, cdio_iso_analysis.iso_label);
1182
break;
1183
}
1184
if (first_data == 1 && num_audio > 0)
1185
printf("mixed mode CD ");
1186
if (fs & CDIO_FS_ANAL_XA)
1187
printf("XA sectors ");
1188
if (fs & CDIO_FS_ANAL_MULTISESSION)
1189
printf("Multisession");
1190
if (fs & CDIO_FS_ANAL_HIDDEN_TRACK)
1191
printf("Hidden Track ");
1192
if (fs & CDIO_FS_ANAL_PHOTO_CD)
1193
printf("%sPhoto CD ",
1194
num_audio > 0 ? " Portfolio " : "");
1195
if (fs & CDIO_FS_ANAL_CDTV)
1196
printf("Commodore CDTV ");
1197
if (first_data > 1)
1198
printf("CD-Plus/Extra ");
1199
if (fs & CDIO_FS_ANAL_BOOTABLE)
1200
printf("bootable CD ");
1201
if (fs & CDIO_FS_ANAL_VIDEOCD && num_audio == 0) {
1202
printf("Video CD ");
1203
}
1204
if (fs & CDIO_FS_ANAL_SVCD)
1205
printf("Super Video CD (SVCD) or Chaoji Video CD (CVD)");
1206
if (fs & CDIO_FS_ANAL_CVD)
1207
printf("Chaoji Video CD (CVD)");
1208
printf("\n");
1209
}
1210
1211
int
1212
main(int argc, const char *argv[])
1213
{
1214
CdIo_t *p_cdio = cdio_open (NULL, DRIVER_UNKNOWN);
1215
cdio_fs_anal_t fs=0;
1216
1217
track_t i_tracks;
1218
track_t first_track_num;
1219
lsn_t start_track; /* first sector of track */
1220
lsn_t data_start =0; /* start of data area */
1221
1222
int first_data = -1; /* # of first data track */
1223
int first_audio = -1; /* # of first audio track */
1224
unsigned int num_data = 0; /* # of data tracks */
1225
unsigned int num_audio = 0; /* # of audio tracks */
1226
unsigned int i;
1227
1228
if (NULL == p_cdio) {
1229
printf("Problem in trying to find a driver.\n\n");
1230
return 1;
1231
}
1232
1233
first_track_num = cdio_get_first_track_num(p_cdio);
1234
i_tracks = cdio_get_num_tracks(p_cdio);
1235
1236
/* Count the number of data and audio tracks. */
1237
for (i = first_track_num; i <= i_tracks; i++) {
1238
if (TRACK_FORMAT_AUDIO == cdio_get_track_format(p_cdio, i)) {
1239
num_audio++;
1240
if (-1 == first_audio) first_audio = i;
1241
} else {
1242
num_data++;
1243
if (-1 == first_data) first_data = i;
1244
}
1245
}
1246
1247
/* try to find out what sort of CD we have */
1248
if (0 == num_data) {
1249
printf("Audio CD\n");
1250
} else {
1251
/* we have data track(s) */
1252
int j;
1253
cdio_iso_analysis_t cdio_iso_analysis;
1254
1255
memset(&cdio_iso_analysis, 0, sizeof(cdio_iso_analysis));
1256
1257
for (j = 2, i = first_data; i <= i_tracks; i++) {
1258
lsn_t lsn;
1259
track_format_t track_format = cdio_get_track_format(p_cdio, i);
1260
1261
lsn = cdio_get_track_lsn(p_cdio, i);
1262
1263
switch ( track_format ) {
1264
case TRACK_FORMAT_AUDIO:
1265
case TRACK_FORMAT_ERROR:
1266
break;
1267
case TRACK_FORMAT_CDI:
1268
case TRACK_FORMAT_XA:
1269
case TRACK_FORMAT_DATA:
1270
case TRACK_FORMAT_PSX:
1271
;
1272
}
1273
1274
start_track = (i == 1) ? 0 : lsn;
1275
1276
/* save the start of the data area */
1277
if (i == first_data)
1278
data_start = start_track;
1279
1280
/* skip tracks which belong to the current walked session */
1281
if (start_track < data_start + cdio_iso_analysis.isofs_size)
1282
continue;
1283
1284
fs = cdio_guess_cd_type(p_cdio, start_track, i, &cdio_iso_analysis);
1285
1286
print_analysis(cdio_iso_analysis, fs, first_data, num_audio,
1287
i_tracks, first_track_num, p_cdio);
1288
1289
if ( !(CDIO_FSTYPE(fs) == CDIO_FS_ISO_9660 ||
1290
CDIO_FSTYPE(fs) == CDIO_FS_ISO_HFS ||
1291
CDIO_FSTYPE(fs) == CDIO_FS_ISO_9660_INTERACTIVE) )
1292
/* no method for non-ISO9660 multisessions */
1293
break;
1294
}
1295
}
1296
cdio_destroy(p_cdio);
1297
return 0;
1298
}
1299
1300
1301
File: libcdio.info, Node: Example 4, Next: Example 5, Prev: Example 3, Up: How to use
1302
1303
7.4 Example 4: use libiso9660 to extract a file from an ISO-9660 image
1304
======================================================================
1305
1306
Next a program to show using `libiso9660' to extract a file from an
1307
ISO-9660 image. This can be found in the distribution as
1308
`example/iso3.c'. A more complete and expanded version of this is
1309
`iso-read', part of this distribution.
1310
1311
/* This is the ISO 9660 image. */
1312
#define ISO9660_IMAGE_PATH "../"
1313
#define ISO9660_IMAGE ISO9660_IMAGE_PATH "test/copying.iso"
1314
1315
#define LOCAL_FILENAME "copying"
1316
1317
#ifdef HAVE_CONFIG_H
1318
# include "config.h"
1319
#endif
1320
1321
#include <sys/types.h>
1322
#include <cdio/cdio.h>
1323
#include <cdio/iso9660.h>
1324
1325
#include <stdio.h>
1326
1327
#ifdef HAVE_ERRNO_H
1328
#include <errno.h>
1329
#endif
1330
#ifdef HAVE_STRING_H
1331
#include <string.h>
1332
#endif
1333
#ifdef HAVE_UNISTD_H
1334
#include <unistd.h>
1335
#endif
1336
#ifdef HAVE_SYS_TYPES_H
1337
#include <sys/types.h>
1338
#endif
1339
1340
#define my_exit(rc) \
1341
fclose (p_outfd); \
1342
free(p_statbuf); \
1343
iso9660_close(p_iso); \
1344
return rc; \
1345
1346
int
1347
main(int argc, const char *argv[])
1348
{
1349
iso9660_stat_t *p_statbuf;
1350
FILE *p_outfd;
1351
int i;
1352
1353
iso9660_t *p_iso = iso9660_open (ISO9660_IMAGE);
1354
1355
if (NULL == p_iso) {
1356
fprintf(stderr, "Sorry, couldn't open ISO 9660 image %s\n", ISO9660_IMAGE);
1357
return 1;
1358
}
1359
1360
p_statbuf = iso9660_ifs_stat_translate (p_iso, LOCAL_FILENAME);
1361
1362
if (NULL == p_statbuf)
1363
{
1364
fprintf(stderr,
1365
"Could not get ISO-9660 file information for file %s\n",
1366
LOCAL_FILENAME);
1367
iso9660_close(p_iso);
1368
return 2;
1369
}
1370
1371
if (!(p_outfd = fopen (LOCAL_FILENAME, "wb")))
1372
{
1373
perror ("fopen()");
1374
free(p_statbuf);
1375
iso9660_close(p_iso);
1376
return 3;
1377
}
1378
1379
/* Copy the blocks from the ISO-9660 filesystem to the local filesystem. */
1380
for (i = 0; i < p_statbuf->size; i += ISO_BLOCKSIZE)
1381
{
1382
char buf[ISO_BLOCKSIZE];
1383
1384
memset (buf, 0, ISO_BLOCKSIZE);
1385
1386
if ( ISO_BLOCKSIZE != iso9660_iso_seek_read (p_iso, buf, p_statbuf->lsn
1387
+ (i / ISO_BLOCKSIZE),
1388
1) )
1389
{
1390
fprintf(stderr, "Error reading ISO 9660 file at lsn %lu\n",
1391
(long unsigned int) p_statbuf->lsn + (i / ISO_BLOCKSIZE));
1392
my_exit(4);
1393
}
1394
1395
1396
fwrite (buf, ISO_BLOCKSIZE, 1, p_outfd);
1397
1398
if (ferror (p_outfd))
1399
{
1400
perror ("fwrite()");
1401
my_exit(5);
1402
}
1403
}
1404
1405
fflush (p_outfd);
1406
1407
/* Make sure the file size has the exact same byte size. Without the
1408
truncate below, the file will a multiple of ISO_BLOCKSIZE.
1409
*/
1410
if (ftruncate (fileno (p_outfd), p_statbuf->size))
1411
perror ("ftruncate()");
1412
1413
my_exit(0);
1414
}
1415
1416
1417
File: libcdio.info, Node: Example 5, Next: Example 6, Prev: Example 4, Up: How to use
1418
1419
7.5 Example 5: list CD-Text and disc mode info
1420
==============================================
1421
1422
Next a program to show using `libcdio' to list CD-TEXT data. This can
1423
be found in the distribution as `example/cdtext.c'.
1424
1425
/* Simple program to list CD-Text info of a Compact Disc using libcdio. */
1426
#ifdef HAVE_CONFIG_H
1427
# include "config.h"
1428
#endif
1429
#include <stdio.h>
1430
#include <sys/types.h>
1431
#include <cdio/cdio.h>
1432
#include <cdio/cdtext.h>
1433
1434
1435
static void
1436
print_cdtext_track_info(CdIo_t *p_cdio, track_t i_track, const char *message) {
1437
const cdtext_t *cdtext = cdio_get_cdtext(p_cdio, 0);
1438
if (NULL != cdtext) {
1439
cdtext_field_t i;
1440
1441
printf("%s\n", message);
1442
1443
for (i=0; i < MAX_CDTEXT_FIELDS; i++) {
1444
if (cdtext->field[i]) {
1445
printf("\t%s: %s\n", cdtext_field2str(i), cdtext->field[i]);
1446
}
1447
}
1448
}
1449
1450
}
1451
1452
static void
1453
print_disc_info(CdIo_t *p_cdio, track_t i_tracks, track_t i_first_track) {
1454
track_t i_last_track = i_first_track+i_tracks;
1455
discmode_t cd_discmode = cdio_get_discmode(p_cdio);
1456
1457
printf("%s\n", discmode2str[cd_discmode]);
1458
1459
print_cdtext_track_info(p_cdio, 0, "\nCD-Text for Disc:");
1460
for ( ; i_first_track < i_last_track; i_first_track++ ) {
1461
char psz_msg[50];
1462
sprintf(msg, "CD-Text for Track %d:", i_first_track);
1463
print_cdtext_track_info(p_cdio, i_first_track, psz_msg);
1464
}
1465
}
1466
1467
int
1468
main(int argc, const char *argv[])
1469
{
1470
track_t i_first_track;
1471
track_t i_tracks;
1472
CdIo_t *p_cdio;
1473
cdio = cdio_open (NULL, DRIVER_UNKNOWN);
1474
i_first_track = cdio_get_first_track_num(p_cdio);
1475
i_tracks = cdio_get_num_tracks(p_cdio);
1476
1477
if (NULL == p_cdio) {
1478
printf("Couldn't find CD\n");
1479
return 1;
1480
} else {
1481
print_disc_info(p_cdio, i_tracks, i_first_track);
1482
}
1483
1484
cdio_destroy(p_cdio);
1485
1486
return 0;
1487
}
1488
1489
1490
File: libcdio.info, Node: Example 6, Next: Example 7, Prev: Example 5, Up: How to use
1491
1492
7.6 Example 6: Using MMC to run an `INQURY' command
1493
===================================================
1494
1495
Now a program to show issuing a simple MMC command (`INQUIRY'). This
1496
MMC command retrieves the vendor, model and firmware revision number of
1497
a CD drive. For this command to work, usually a CD to be loaded into
1498
the drive; odd since the CD itself is not used.
1499
1500
This can be found in the distribution as `example/mmc1.c'.
1501
1502
#ifdef HAVE_CONFIG_H
1503
# include "config.h"
1504
#endif
1505
#include <stdio.h>
1506
#include <sys/types.h>
1507
#include <cdio/cdio.h>
1508
#include <cdio/scsi_mmc.h>
1509
#include <string.h>
1510
1511
/* Set how long to wait for MMC commands to complete */
1512
#define DEFAULT_TIMEOUT_MS 10000
1513
1514
int
1515
main(int argc, const char *argv[])
1516
{
1517
CdIo_t *p_cdio;
1518
1519
p_cdio = cdio_open (NULL, DRIVER_UNKNOWN);
1520
1521
if (NULL == p_cdio) {
1522
printf("Couldn't find CD\n");
1523
return 1;
1524
} else {
1525
int i_status; /* Result of MMC command */
1526
char buf[36] = { 0, }; /* Place to hold returned data */
1527
scsi_mmc_cdb_t cdb = {{0, }}; /* Command Descriptor Buffer */
1528
1529
CDIO_MMC_SET_COMMAND(cdb.field, CDIO_MMC_GPCMD_INQUIRY);
1530
cdb.field[4] = sizeof(buf);
1531
1532
i_status = scsi_mmc_run_cmd(p_cdio, DEFAULT_TIMEOUT_MS,
1533
&cdb, SCSI_MMC_DATA_READ,
1534
sizeof(buf), &buf);
1535
if (i_status == 0) {
1536
char psz_vendor[CDIO_MMC_HW_VENDOR_LEN+1];
1537
char psz_model[CDIO_MMC_HW_MODEL_LEN+1];
1538
char psz_rev[CDIO_MMC_HW_REVISION_LEN+1];
1539
1540
memcpy(psz_vendor, buf + 8, sizeof(psz_vendor)-1);
1541
psz_vendor[sizeof(psz_vendor)-1] = '\0';
1542
memcpy(psz_model,
1543
buf + 8 + CDIO_MMC_HW_VENDOR_LEN,
1544
sizeof(psz_model)-1);
1545
psz_model[sizeof(psz_model)-1] = '\0';
1546
memcpy(psz_rev,
1547
buf + 8 + CDIO_MMC_HW_VENDOR_LEN +CDIO_MMC_HW_MODEL_LEN,
1548
sizeof(psz_rev)-1);
1549
psz_rev[sizeof(psz_rev)-1] = '\0';
1550
1551
printf("Vendor: %s\nModel: %s\nRevision: %s\n",
1552
psz_vendor, psz_model, psz_rev);
1553
} else {
1554
printf("Couldn't get INQUIRY data (vendor, model, and revision\n");
1555
}
1556
}
1557
1558
cdio_destroy(p_cdio);
1559
1560
return 0;
1561
}
1562
1563
1564
File: libcdio.info, Node: Example 7, Next: All sample programs, Prev: Example 6, Up: How to use
1565
1566
7.7 Example 7: Using the CD Paranoia library for CD-DA reading
1567
==============================================================
1568
1569
#ifdef HAVE_CONFIG_H
1570
# include "config.h"
1571
#endif
1572
1573
#include <cdio/cdda.h>
1574
#include <cdio/cd_types.h>
1575
#include <stdio.h>
1576
1577
#ifdef HAVE_STDLIB_H
1578
#include <stdlib.h>
1579
#endif
1580
1581
int
1582
main(int argc, const char *argv[])
1583
{
1584
cdrom_drive_t *d = NULL; /* Place to store handle given by cd-paranoia. */
1585
char **ppsz_cd_drives; /* List of all drives with a loaded CDDA in it. */
1586
1587
/* See if we can find a device with a loaded CD-DA in it. */
1588
ppsz_cd_drives = cdio_get_devices_with_cap(NULL, CDIO_FS_AUDIO, false);
1589
1590
if (ppsz_cd_drives) {
1591
/* Found such a CD-ROM with a CD-DA loaded. Use the first drive in
1592
the list. */
1593
d=cdio_cddap_identify(*ppsz_cd_drives, 1, NULL);
1594
} else {
1595
printf("Unable find or access a CD-ROM drive with an audio CD in it.\n");
1596
exit(1);
1597
}
1598
1599
/* Don't need a list of CD's with CD-DA's any more. */
1600
cdio_free_device_list(ppsz_cd_drives);
1601
1602
/* We'll set for verbose paranoia messages. */
1603
cdio_cddap_verbose_set(d, CDDA_MESSAGE_PRINTIT, CDDA_MESSAGE_PRINTIT);
1604
1605
if ( 0 != cdio_cddap_open(d) ) {
1606
printf("Unable to open disc.\n");
1607
exit(1);
1608
}
1609
1610
/* Okay now set up to read up to the first 300 frames of the first
1611
audio track of the Audio CD. */
1612
{
1613
cdrom_paranoia_t *p = cdio_paranoia_init(d);
1614
lsn_t i_first_lsn = cdio_cddap_disc_firstsector(d);
1615
1616
if ( -1 == i_first_lsn ) {
1617
printf("Trouble getting starting LSN\n");
1618
} else {
1619
lsn_t i_cursor;
1620
track_t i_track = cdio_cddap_sector_gettrack(d, i_first_lsn);
1621
lsn_t i_last_lsn = cdio_cddap_track_lastsector(d, i_track);
1622
1623
/* For demo purposes we'll read only 300 frames (about 4
1624
seconds). We don't want this to take too long. On the other
1625
hand, I suppose it should be something close to a real test.
1626
*/
1627
if ( i_last_lsn - i_first_lsn > 300) i_last_lsn = i_first_lsn + 299;
1628
1629
printf("Reading track %d from LSN %ld to LSN %ld\n", i_track,
1630
(long int) i_first_lsn, (long int) i_last_lsn);
1631
1632
/* Set reading mode for full paranoia, but allow skipping sectors. */
1633
paranoia_modeset(p, PARANOIA_MODE_FULL^PARANOIA_MODE_NEVERSKIP);
1634
1635
paranoia_seek(p, i_first_lsn, SEEK_SET);
1636
1637
for ( i_cursor = i_first_lsn; i_cursor <= i_last_lsn; i_cursor ++) {
1638
/* read a sector */
1639
int16_t *p_readbuf=cdio_paranoia_read(p, NULL);
1640
char *psz_err=cdio_cddap_errors(d);
1641
char *psz_mes=cdio_cddap_messages(d);
1642
1643
if (psz_mes || psz_err)
1644
printf("%s%s\n", psz_mes ? psz_mes: "", psz_err ? psz_err: "");
1645
1646
if (psz_err) free(psz_err);
1647
if (psz_mes) free(psz_mes);
1648
if( !p_readbuf ) {
1649
printf("paranoia read error. Stopping.\n");
1650
break;
1651
}
1652
}
1653
}
1654
cdio_paranoia_free(p);
1655
}
1656
1657
cdio_cdda_close(d);
1658
1659
exit(0);
1660
}
1661
1662
Those who are die-hard cdparanoia programmers will notice that the
1663
`libcdio' paranoia names are similar but a little bit different. In
1664
particular instead of `paranoia_read' we have above
1665
`cdio_paranoia_read' and instead of `cdda_open' we have
1666
`cdio_cddap_open'.
1667
1668
This was done intentionally so that it is possible for the original
1669
paranoia program can co-exist both in source code and linked libraries
1670
and not conflict with `libcdio''s paranoia source and libraries.
1671
1672
In general in place of any paranoia routine that begins `paranoia_',
1673
use `cdio_paranoia_' and in place of any paranoia routine that begins
1674
`cdda_', use `cdio_cddap_'. But for a limited time `libcdio' will
1675
accept the old paranoia names which may be useful for legacy paranoia
1676
code. The way this magic works is by defining the old paranoia name to
1677
be the `libcdio' name.
1678
1679
In the unusual case where you do want to use both the original paranoia
1680
and `libcdio' routines in a single source, the C preprocessor symbol
1681
`DO_NOT_WANT_PARANOIA_COMPATIBILITY' can be `define''d and this
1682
disables the `#define' substitution done automatically. The may still
1683
be a problem with conflicting structure definitions like
1684
`cdrom_drive_t'.
1685
1686
1687
File: libcdio.info, Node: All sample programs, Prev: Example 7, Up: How to use
1688
1689
7.8 A list of all sample programs in the `example' directory
1690
============================================================
1691
1692
The `example' directory contains some simple examples of the use of the
1693
`libcdio' library.
1694
1695
A larger more-complicated example are the `cd-drive', `cd-info',
1696
`cd-read', `iso-info' and `iso-info' programs in the `src' directory.
1697
1698
Descriptions of the sample are as follows...
1699
1700
``iso1.c''
1701
A program to show using `libiso9660' to list files in a
1702
directory of an ISO-9660 image.
1703
1704
``C++/iso1.cpp''
1705
The same program as `iso1.c' written in C++.
1706
1707
``iso2.c''
1708
A program to show using `libiso9660' to extract a file from a
1709
CDRWIN cue/bin CD image.
1710
1711
``C++/iso2.cpp''
1712
The same program as `iso2.c' written in C++.
1713
1714
``iso3.c''
1715
A program to show using libiso9660 to extract a file from an
1716
ISO-9660 image.
1717
1718
``C++/iso3.cpp''
1719
The same program as `iso3.c' written in C++.
1720
1721
``cdtext.c''
1722
A program to show CD-Text and CD disc mode info.
1723
1724
``drives.c''
1725
A program to show drivers installed and what the default CD-ROM
1726
drive is and what CD drives are available.
1727
1728
``paranoia.c''
1729
A program to show using libcdio's version of the CD-DA paranoia.
1730
1731
``paranoia2.c''
1732
A program to show using libcdio's version of the CD-DA paranoia
1733
library. But in this version, we'll open a cdio object before
1734
calling paranoia's open. I imagine in many cases such as media
1735
players this may be what will be done since, one may want to get
1736
CDDB/CD-Text info beforehand.
1737
1738
``mmc1.c''
1739
A program to show issuing a simple MMC command (`INQUIRY').
1740
1741
``C++/mmc1.cpp''
1742
The same program as `mmc1.c' written in C++.
1743
1744
``mmc2.c''
1745
A more involved MMC command to list CD and drive features from a
1746
SCSI-MMC `GET_CONFIGURATION' command.
1747
1748
``C++/mmc2.cpp''
1749
The same program as `mmc2.c' written in C++.
1750
1751
``tracks.c''
1752
A simple program to list track numbers and logical sector numbers
1753
of a Compact Disc using `libcdio'.
1754
1755
``sample2.c''
1756
A simple program to show drivers installed and what the default
1757
CD-ROM drive is.
1758
1759
``sample3.c''
1760
A simple program to show the use of `cdio_guess_cd_type()'.
1761
Figures out the kind of CD image we've got.
1762
1763
``sample4.c''
1764
A slightly improved sample3 program: we handle cdio logging and
1765
take an optional CD-location.
1766
1767
1768
1769
File: libcdio.info, Node: Utility Programs, Next: CD-ROM Access and Drivers, Prev: How to use, Up: Top
1770
1771
8 Diagnostic programs (`cd-drive', `cd-info', `cd-read', `iso-info', `iso-read')
1772
********************************************************************************
1773
1774
* Menu:
1775
1776
* cd-drive:: list out CD-ROM drive information
1777
* cd-info:: list out CD or CD-image information
1778
* cd-read:: read blocks of a CD or CD image
1779
* iso-info:: list out ISO-9600 image information
1780
* iso-read:: extract a file from an ISO 9660 image
1781
1782
1783
File: libcdio.info, Node: cd-drive, Next: cd-info, Up: Utility Programs
1784
1785
8.1 `cd-drive'
1786
==============
1787
1788
`cd-drive' lists out drive information, what features drive supports,
1789
and information about what hardware drivers are available.
1790
1791
1792
File: libcdio.info, Node: cd-info, Next: cd-read, Prev: cd-drive, Up: Utility Programs
1793
1794
8.2 `cd-info'
1795
=============
1796
1797
`cd-info' will print out the structure of a CD medium which could
1798
either be a Compact Disc in a CD ROM or an CD image. It can try to
1799
analyze the medium to give characteristics of the medium, such as how
1800
many tracks are in the CD and the format of each track, whether a CD
1801
contains a Video CD, CD-DA, PhotoCD, whether a track has an ISO-9660
1802
filesystem.
1803
1804
1805
File: libcdio.info, Node: cd-read, Next: iso-info, Prev: cd-info, Up: Utility Programs
1806
1807
8.3 `cd-read'
1808
=============
1809
1810
`cd-info' can be used to read blocks a CD medium which could either be
1811
a Compact Disc in a CD ROM or an CD image. You specify the beginning
1812
and ending LSN and what mode format to use in the reading.
1813
1814
1815
File: libcdio.info, Node: iso-info, Next: iso-read, Prev: cd-read, Up: Utility Programs
1816
1817
8.4 `iso-info'
1818
==============
1819
1820
`iso-info' can be used to print out the structure of an ISO 9660 image.
1821
1822
1823
File: libcdio.info, Node: iso-read, Prev: iso-info, Up: Utility Programs
1824
1825
8.5 `iso-read'
1826
==============
1827
1828
`iso-info' can be used to extract a file in an ISO-9660 image.
1829
1830
1831
File: libcdio.info, Node: CD-ROM Access and Drivers, Next: Internal Program Organization, Prev: Utility Programs, Up: Top
1832
1833
9 CD-ROM Access and Drivers
1834
***************************
1835
1836
* Menu:
1837
1838
* MMC:: ``SCSI'' Multimedia Commands (MMC)
1839
* GNU/Linux:: GNU/Linux ioctl
1840
* Microsoft:: Microsoft Windows ioctl and ASPI
1841
* Solaris:: Solaris ATAPI and SCSI
1842
* FreeBSD:: FreeBSD ioctl and CAM
1843
* OS X:: OSX (non-exclussive access)
1844
1845
1846
File: libcdio.info, Node: MMC, Next: GNU/Linux, Up: CD-ROM Access and Drivers
1847
1848
9.1 Multimedia Commands (MMC)
1849
=============================
1850
1851
In contrast to the rest of the sections in this chapter, MMC
1852
(Multimedia commands) is not a driver per se, although many of the
1853
CD-ROM drivers do in fact issue MMC commands. MMC commands gives (in
1854
theory) a broad and uniform way to access a CD-ROM drive.
1855
1856
If your CD-ROM drive understands MMC commands this is probably gives
1857
the most flexibility in control. SCSI and ATAPI CD-ROM devices
1858
generally support a fairly large set of MMC commands.
1859
1860
The name "SCSI MMC" is often found in the literature in specifications
1861
and on the Internet. The "SCSI" part is probably a little bit
1862
misleading because a drive can understand "SCSI MMC" commands but not
1863
use a SCSI interface--ATAPI CD-ROMs are one such broad class of
1864
examples. In fact there are drivers to "encapsulate" non-SCSI drives or
1865
a non-MMC-compliant drives and make them act like MMC drives. I believe
1866
that many OS SCSI "pass-through" mechanisms do roughly the same thing.
1867
1868
The name "SCSI MMC" is no doubt due to the fact that these commands
1869
grew out of the SCSI command set and thus were bundled in them.
1870
1871
For clarity and precision we will use the term "MMC" rather than "SCSI
1872
MMC".
1873
1874
One of the problems with MMC is that there are so many different
1875
"standards". In particular there are MMC
1876
`ftp://ftp.t10.org/t10/drafts/mmc/', MMC 2
1877
`ftp://ftp.t10.org/t10/drafts/mmc2/', MMC 3
1878
`ftp://ftp.t10.org/t10/drafts/mmc3/', MMC 4
1879
`ftp://ftp.t10.org/t10/drafts/mmc4/', and MMC 5
1880
`ftp://ftp.t10.org/t10/drafts/mmc5/' standards several "drafts" for
1881
each standard. The good news about ATAPI drives is that they too
1882
understand some sort of MMC subset. The bad news (as I understand it)
1883
is that they do not understand any full MMC command set.
1884
1885
Another problem with the MMC commands related to the variations in
1886
standards is the variation in the commands themselves and there are
1887
perhaps two or three ways to do many of the basic commands like read a
1888
CD frame.
1889
1890
There seems to be a fascination with the number of bytes a command
1891
takes in the MMC-specification world. (Size matters?) So often the name
1892
of an operation will have a suffix with the number of bytes of the
1893
command (actually in MMC jargon this is called a "CDB" or command
1894
descriptor block). So for example there is a 6-byte "MODE SELECT" often
1895
called "MODE SELECT 6" and a 10-byte "MODE SELECT" often called "MODE
1896
SELECT 10". Presumably the 6-byte command came first and it was
1897
discovered that there was some deficiency causing the longer command.
1898
In `libcdio' where there are two formats we add the suffix in the name,
1899
e.g. `CDIO_MMC_GPCMD_MODE_SELECT_6' or `CDIO_MMC_GPCMD_MODE_SELECT_10'.
1900
1901
If the fascination and emphasis in the MMC specifications of CDB size
1902
is a bit odd, equally so is the fact that this too often has bled
1903
through at the OS programming API. However in `libcdio', you just give
1904
the opcode in `scsi_mmc_run_cmd()' and we'll do the work to figure out
1905
how many bytes of the CDB are used.
1906
1907
Down the line it is hoped that `libcdio' will have a way to remove a
1908
distinction between the various alternative and alternative-size MMC
1909
commands. In `cdio/scsi-mmc.h' you will find a little bit of this for
1910
example via the routine `scsi_mmc_get_drive_cap()'. However much more
1911
work is needed.
1912
1913
1914
File: libcdio.info, Node: GNU/Linux, Next: Microsoft, Prev: MMC, Up: CD-ROM Access and Drivers
1915
1916
9.2 GNU/Linux
1917
=============
1918
1919
The GNU/Linux uses a hybrid of methods. Somethings are done vai ioctl
1920
and some things via MMC. GNU/Linux has a rather nice and complete ioctl
1921
mechanism. On the other hand, the MMC mechanism is more universal.
1922
There are other "access modes" listed which are not really access modes
1923
and should probably be redone/rethought. They are just different ways
1924
to run the read command. But for completeness These are "READ_CD" and
1925
"READ_10".
1926
1927
1928
File: libcdio.info, Node: Microsoft, Next: Solaris, Prev: GNU/Linux, Up: CD-ROM Access and Drivers
1929
1930
9.3 Microsoft Windows ioctl and ASPI
1931
====================================
1932
1933
There are two CD drive access methods on Microsoft Windows platforms:
1934
ioctl and ASPI.
1935
1936
The ASPI interface specification was developed by Adaptec for sending
1937
commands to a SCSI host adapter (such as those controlling CD and DVD
1938
drives) and used on Window 9x/NT and later. Emulation for ATAPI drives
1939
was added so that the same sets of commands worked those even though
1940
the drives might not be SCSI nor might there even be a SCSI controller
1941
attached.
1942
1943
However in Windows NT/2K/XP, Microsoft provides their Win32 ioctl
1944
interface, and has taken steps to make using ASPI more inaccessible
1945
(e.g. requiring administrative access to use ASPI).
1946
1947
1948
File: libcdio.info, Node: Solaris, Next: FreeBSD, Prev: Microsoft, Up: CD-ROM Access and Drivers
1949
1950
9.4 Solaris ATAPI and SCSI
1951
==========================
1952
1953
There is currently only one CD drive access methods in Solaris: SCSI
1954
(called "USCSI" or "user SCSI" in Solaris). There used to be an ATAPI
1955
method and it could be resurrected if needed. USCSI was preferred since
1956
on newer releases of Solaris and Solaris environments one would needs
1957
to have root access for ATAPI.
1958
1959
1960
File: libcdio.info, Node: FreeBSD, Next: OS X, Prev: Solaris, Up: CD-ROM Access and Drivers
1961
1962
9.5 FreeBSD ioctl and CAM
1963
=========================
1964
1965
There are two CD drive access methods on Solaris: ioctl and CAM (common
1966
access method). CAM is preferred when possible, especially on newer
1967
releases. However CAM is right now sort of a hybrid and includes some
1968
ioctl code.
1969
1970
More work on this driver is needed. Volunteers?
1971
1972
1973
File: libcdio.info, Node: OS X, Prev: FreeBSD, Up: CD-ROM Access and Drivers
1974
1975
9.6 OS X (non-exclussive access)
1976
================================
1977
1978
A problem with OS/X is that if the OS thinks it understands the drive
1979
it gains exclusive access to it and thus prevents a library like this
1980
to get non-exclusive access.
1981
1982
Currently `libcdio' access the CD-ROM non-exclusively. However in order
1983
to be able to issue MMC, the current belief is that exclusive access is
1984
needed. Probably in a future `libcdio', there will be some way to
1985
specify which kind of access is desired (with the inherent consequences
1986
of each).
1987
1988
More work on this driver is needed. Volunteers?
1989
1990
1991
File: libcdio.info, Node: Internal Program Organization, Next: ISO-9660 Character Sets, Prev: CD-ROM Access and Drivers, Up: Top
1992
1993
10 Internal Program Organization
1994
********************************
1995
1996
10.0.1 file organization
1997
------------------------
1998
1999
Here is a list of `libcdio' directories.
2000
2001
* `include/cdio'
2002
2003
This contains the headers that are public. One that will probably
2004
be used quite a bit is `<cdio/cdio.h>'.
2005
2006
* `lib'
2007
2008
Code for installed libraries. See below for further breakout
2009
2010
* `lib/driver'
2011
2012
Code for various OS-specific CD-ROM drivers, image drivers, and
2013
common MMC routines.
2014
2015
This code comprises `libcdio.a' (or the shared version of it).
2016
2017
* `lib/iso9660'
2018
2019
Code for to extract or query ISO-9660 images.
2020
2021
This code comprises `libiso9660.a' (or the shared version of it).
2022
2023
* `lib/paranoia'
2024
2025
This is from cdparanoia. It is the OS- and hardware- dependent
2026
code to detect and correct jitter for CD-DA CDs.
2027
2028
* `lib/cdda_interface'
2029
2030
This is also from cdparanoia. It is the OS- and hardware-
2031
independent code to detect and correct jitter for CD-DA CDs.
2032
2033
* `doc'
2034
2035
A home for fine documentation such as this masterpiece.
2036
2037
* `example'
2038
2039
Here you will find various small example programs using `libcdio'
2040
which are largely for pedagogical purposes. You might be able to
2041
find one that is similar to what you want to do that could be
2042
extended. In fact some these are contain the kernel ideas behind of
2043
some of the larger programs in `src'.
2044
2045
* `src'
2046
2047
Various stand-alone utility programs. See below.
2048
2049
* `src/paranoia'
2050
2051
`libcdio''s version of `cdparanoia'. Except for the fact that the
2052
back-end CD-reading code has been replaced by `libcdio''s routines
2053
the code is pretty much identical.
2054
2055
* `test'
2056
2057
Regression tests
2058
2059
2060
10.0.2 `libcdio'
2061
----------------
2062
2063
`libcdio' exports one opaque type `CdIo_t'. Internally this a structure
2064
containing an enumeration for the driver, a structure containing
2065
function pointers and a generic "environment" pointer which is passed
2066
as a parameter on a function call. See `lib/driver/cdio_private.h'. The
2067
initialization routine for each driver sets up the function pointers
2068
and allocates memory for the environment. When a particular user-level
2069
cdio routine is called (e.g `cdio_get_first_track_num' for
2070
lib/driver/track.c), the environment pointer is passed to a
2071
device-specific routine which will then cast this pointer into
2072
something of the appropriate type.
2073
2074
Because function pointers are used, there can be and is quite a bit of
2075
sharing of common routines. Some of the common routines are found in
2076
the file `lib/driver/_cdio_generic.c'.
2077
2078
Another set of routines that one is likely to find shared amongst
2079
drivers are the MMC commands. These are located in
2080
`lib/driver/scsi_mmc.c'.
2081
2082
There is not only an attempt to share functions but we've tried to
2083
create a generic CD structure `generic_img_private_t' of file
2084
`lib/driver/generic.h'. By putting information into a common structure,
2085
we increase the likelihood of being able to have a common routine to
2086
perform some sort of function.
2087
2088
The generic CD structure would also be useful in a utility to convert
2089
one CD-image format to another. Basically the first image format is
2090
"parsed" into the common internal format and then from this structure
2091
it is unparsed.
2092
2093
10.0.3 `libiso9660'
2094
-------------------
2095
2096
To be completed....
2097
2098
10.0.4 Coding Conventions
2099
-------------------------
2100
2101
In `libcdio' there are a number of conventions used. If you understand
2102
some of these conventions it may facilitate understanding the code a
2103
little.
2104
2105
10.0.4.1 namespace names
2106
........................
2107
2108
For the most part, the visible external `libcdio' names follow
2109
conventions so as not to be confused with other applications or
2110
libraries. If you understand these conventions, there will be little or
2111
no chance that the names you use will conflict with `libcdio' and
2112
`libiso9660' and vice versa.
2113
2114
All of the external `libcdio' C routines start out with `cdio_', e.g.
2115
`cdio_open'; as a corollary, the `libcdio' CD-Paranoia routines start
2116
`cdio_cddap_', e.g. `cdio_cddap_open'. `libiso9660' routines start
2117
`iso9660_', e.g. `iso9660_open'.
2118
2119
`libcdio' C-Preprocessor names generally start `CDIO_', for example
2120
`CDIO_CD_FRAMESIZE_RAW'; `libiso9660' C-preprocessor names start
2121
`ISO9660_', e.g. `ISO9660_FRAMESIZE'.
2122
2123
10.0.4.2 suffixes (type and structure names)
2124
............................................
2125
2126
A few suffixes are used in type and structure names:
2127
2128
* `_e'
2129
2130
An enumeration tag. Generally though the same name will appear
2131
with the `_t' suffix and probably that should be used instead.
2132
2133
* `_s'
2134
2135
A structure tag. Generally though the same name will appear with
2136
the `_t' suffix and probably that should be used instead.
2137
2138
* `_t'
2139
2140
A type suffix.
2141
2142
2143
10.0.4.3 prefixes (variable names)
2144
..................................
2145
2146
A number of prefixes are used in variable names here's what they mean
2147
2148
* `i_'
2149
2150
An integer type of some sort. A variable of this ilk one might find
2151
being iterated over in `for' loops or used as the index of an
2152
array for example.
2153
2154
* `b_'
2155
2156
A boolean type of some sort. A variable of this ilk one might find
2157
being in an `if' condition for example.
2158
2159
* `p_'
2160
2161
A pointer of some sort. A variable of this ilk, say `p_foo' one is
2162
like likely to see `*p_foo' or `p_foo->...'.
2163
2164
* `pp_'
2165
2166
A pointer to a pointer of some sort. A variable of this ilk, say
2167
`pp_foo' one is like likely to see `**p_foo' or `p_foo[x][y]' for
2168
example
2169
2170
* `psz_'
2171
2172
A `char *' pointer of some sort. A variable of this ilk, say
2173
`psz_foo' may be used in a string operation. For example
2174
`printf(%s\n", psz_foo)' or `strdup(psz_foo)'.
2175
2176
* `ppsz_'
2177
2178
A pointer to a `char *' pointer of some sort. A variable of this
2179
ilk, say `ppsz_foo' is used for example to return a list of CD-ROM
2180
device names
2181
2182
2183
There are a some other naming conventions. Generally if a routine name
2184
starts `cdio_', e.g. `cdio_open', then it is an externally visible
2185
routine in `libcdio'. If a name starts `iso9660_', e.g.
2186
`iso9660_isdchar' then it is an externally visible routine in
2187
`libiso9660'. If a name starts `scsi_mmc_', e.g.
2188
`scsi_mmc_get_discmode', then it is an externally visible MMC routine.
2189
(We don't have a separate library for this yet.
2190
2191
Names using entirely capital letters and that start `CDIO_' are
2192
externally visible `#defines'.
2193
2194
2195
File: libcdio.info, Node: ISO-9660 Character Sets, Next: Glossary, Prev: Internal Program Organization, Up: Top
2196
2197
Appendix A ISO-9660 Character Sets
2198
**********************************
2199
2200
For a description of where are used see *Note ISO 9660 Level 1::.
2201
2202
* Menu:
2203
2204
* ISO646 d-Characters::
2205
* ISO646 a-Characters::
2206
2207
2208
File: libcdio.info, Node: ISO646 d-Characters, Next: ISO646 a-Characters, Up: ISO-9660 Character Sets
2209
2210
A.1 ISO646 d-Characters
2211
=======================
2212
2213
| 0 1 2 3 4 5 6 7
2214
--+-----------------
2215
0 | 0 P
2216
1 | 1 A Q
2217
2 | 2 B R
2218
3 | 3 C S
2219
4 | 4 D T
2220
5 | 5 E U
2221
6 | 6 F V
2222
7 | 7 G W
2223
8 | 8 H X
2224
9 | 9 I Y
2225
a | J Z
2226
b | K
2227
c | L
2228
d | M
2229
e | N
2230
f | O _
2231
2232
2233
File: libcdio.info, Node: ISO646 a-Characters, Prev: ISO646 d-Characters, Up: ISO-9660 Character Sets
2234
2235
A.2 ISO646 a-Characters
2236
=======================
2237
2238
| 0 1 2 3 4 5 6 7
2239
--+-----------------
2240
0 | 0 P
2241
1 | ! 1 A Q
2242
2 | " 2 B R
2243
3 | 3 C S
2244
4 | 4 D T
2245
5 | % 5 E U
2246
6 | & 6 F V
2247
7 | ' 7 G W
2248
8 | ( 8 H X
2249
9 | ) 9 I Y
2250
a | * : J Z
2251
b | + ; K
2252
c | , < L
2253
d | - = M
2254
e | . > N
2255
f | / ? O _
2256
2257
2258
File: libcdio.info, Node: Glossary, Next: GNU General Public License, Prev: ISO-9660 Character Sets, Up: Top
2259
2260
Appendix B Glossary
2261
*******************
2262
2263
See also `http://www.dvdrhelp.com/glossary'.
2264
2265
ASPI
2266
See Win32 ASPI
2267
2268
ATA
2269
Advanced Technology Attachment (ATA). The same things as IDE.
2270
2271
ATAPI
2272
Advanced Technology Attachment (ATA) Packet Interface. The
2273
interface provides a mechanism for transferring and executing SCSI
2274
CDBs on IDE CD Drives and DVD Drives.
2275
2276
IDE (also called ATA) was originally designed for hard drives only,
2277
but with help of ATAPI it is possible to connect other devices, in
2278
particular CD-ROMS to the IDE/EIDE connections.
2279
2280
The ATAPI CD-ROM drives understand a subset of MMC commands. In
2281
particular multi-initiator commands are neither needed nor deviced
2282
for ATAPI devices.
2283
2284
BIN/CUE
2285
A CD-image format developed by Jeff Arnold for CDRWIN software on
2286
Microsoft Windows. Many other programs subsequently support using
2287
this format. The `.CUE' file is a text file which contains CD
2288
format and track layout information, while the `.BIN' file holds
2289
the actual data of each track.
2290
2291
CD
2292
Compact Disc
2293
2294
CD-DA
2295
Compact Disc Digital Audio, described in the "Red Book" or ICE
2296
908. This commonly referred to as an audio CD and what most people
2297
think of when you play a CD as it was the first to use the CD
2298
medium.
2299
2300
CD+G
2301
Compact Disc + Graphics. An extension of the CD audio format
2302
contains a limited amount of graphics in subcode channels. This
2303
disc works in all audio players but the graphics portion is only
2304
available in a special CD+G or Karaoke player.
2305
2306
CD-i
2307
Compact Disc Interactive. An extension of the CD format designed
2308
around a set-top computer that connects to a TV to provide
2309
interactive home entertainment, including digital audio and video,
2310
video games, and software applications. Defined by the "Green
2311
Book" standard. `http://www.icdia.org/'. CD-i for video and video
2312
music has largely (if not totally) been superceded by VCDs.
2313
2314
CD-i Bridge
2315
A standard allowing CD-ROM XA discs to play on CD-i. Kodak
2316
PhotoCDs are CD-XA Bridge discs.
2317
2318
CD-ROM
2319
Compact Disc Read Only Memory or "Yellow Book" describe in
2320
Standards ISO/IEC 10149. The data stored on it can be either in
2321
the form of audio, computer or video files.
2322
2323
CD-ROM Mode 1 and Mode2
2324
The Yellow Book specifies two types of tracks, Mode 1 and Mode 2.
2325
Mode 1 is used for computer data and text and has an extra error
2326
correction layer. Mode 2 is for audio and video data and has no
2327
extra correction layer. CD-ROM/XA An expansion of the CD-ROM Mode
2328
2 format that allows both computer and audio/video to be mixed in
2329
the same track.
2330
2331
CD Text
2332
CD Text is a technology developed by Sony Corporation and Philips
2333
Electronics in 1996 that allows storing in an audio CD and its
2334
tracks information such as artist name, title, songwriter,
2335
composer, or arranger. Commercially available audio CDs sometimes
2336
contain CD Text information.
2337
2338
CD XA
2339
CD-ROM EXtended Architecture. A modification to the CD-ROM
2340
specification that defines two new types of sectors. CD-ROM XA was
2341
developed jointly by Sony, Philips, and Microsoft, and announced in
2342
August 1988. Its specifications were published in an extension to
2343
the Yellow Book. CD-i, Photo CD, Video CD and CD-EXTRA have all
2344
subsequently been based on CD-ROM XA.
2345
2346
CD-XA defines another way of formatting sectors on a CD-ROM,
2347
including headers in the sectors that describe the type (audio,
2348
video, data) and some additional info (markers, resolution in case
2349
of a video or audio sector, file numbers, etc).
2350
2351
The data written on a CD-XA is consistent with and can be in
2352
ISO-9660 file system format and therefore be readable by ISO-9660
2353
file system translators. But also a CD-I player can also read
2354
CD-XA discs even if its own `Green Book' file system only
2355
resembles ISO 9660 and isn't fully compatible.
2356
2357
Command Packet
2358
The data structure that is used to issue an ATAPI command. The same
2359
thing as a SCSI Command Descriptor Block (CDB).
2360
2361
FSF
2362
Free Software Foundation, `http://www.fsf.org/'
2363
2364
GNU
2365
GNU is not UNIX, `http://www.gnu.org/'
2366
2367
IDE
2368
Integrated Drive Electronics. This is a commonly used interface for
2369
hard disk drives and CD-ROM drives. It is less expensive than SCSI,
2370
but offers slightly less in terms of performance.
2371
2372
ISO
2373
International Standards Organization.
2374
2375
ISO 9660
2376
The ISO 9660 is an operating-system independent filesystem format
2377
for CD-ROM media and DVD-ROMs. It was standardized in 1988 and
2378
replaced the High Sierra standard for the logical format on CD-ROM
2379
media (ISO 9660 and High Sierra are identical in content, but the
2380
exact format is different).
2381
2382
There are several specification levels. In Level 1, file names
2383
must be in the 8.3 format (no more than eight characters in the
2384
name, no more than three characters in the suffix) and in capital
2385
letters. Directory names can be no longer than eight characters.
2386
There can be no more than eight nested directory levels. Level 2
2387
and 3 specifications allow file names up to 32 characters long.
2388
2389
ECMA-119
2390
(`http://www.ecma-international.org/publications/standards/Ecma-119.htm'
2391
is the European specification which is identical to ISO 9660. ISO
2392
13490 is basically ISO 9660 with multisession support.
2393
2394
Joliet extensions
2395
This ISO-9660 upward-compatible standard was developed for Windows
2396
95 and Windows NT by Microsoft as an extension of ISO 9600 which
2397
allows the use of Unicode characters and supports file names up to
2398
64 characters.
2399
2400
See `http://bmrc.berkeley.edu/people/chaffee/jolspec.html' for the
2401
Joliet Specification.
2402
2403
The name Joliet comes from the city in Illinois (U.S) that the
2404
standard was defined.
2405
2406
LBA
2407
Logical Block Addressing. Mapped integer numbers from CD Red Book
2408
Addressing MSF. The starting sector is -150 and ending sector is
2409
449849, which correlates directly to MSF: 00:00:00 to 99:59:74.
2410
Because an LBA is a single number it is often easier to work with
2411
in programming than an MSF.
2412
2413
Lead in
2414
The area of a CD where the Table Of Contents (TOC) and CD Text are
2415
stored. I think it is supposed to be around 4500 (1 min) or more
2416
sectors in length. On a CDR(W) the lead-in length is variable,
2417
because each manufacturer will have a different starting position
2418
indicated by the ATIP start of lead-in position that is recorded in
2419
the ATIP groove on the disk.
2420
2421
LSN
2422
Logical Sector Number. Mapped integer numbers from CD Red Book
2423
Addressing MSF. The starting sector is 0 and ending sector is
2424
449699, which correlates to MSF: 00:00:00 to 99:59:74. Because an
2425
LSN is a single number it is often easier to work with in
2426
programming than an MSF. Because it starts at 0 rather than -150
2427
as is the case of an LBA it can be represented as an unsigned
2428
value.
2429
2430
MCN
2431
Media Catalog Number. A identification number on an audio CD. Also
2432
called a UPC. Another identification number is ISRC.
2433
2434
MMC
2435
MMC (Multimedia Commands). A SCSI programming specification made by
2436
the SCSI committee T10 organization `http://www.t10.org/'. MMC
2437
are raw commands for communicating with CDROM drives, CD-Rewriters,
2438
DVD-Rewriters, etc.
2439
2440
Many manufacturers have adopted this standard and it also applies
2441
to ATAPI versions of their drives.
2442
2443
Mixed Mode CD
2444
A Mixed Mode is a CD that contains tracks of differing CD-ROM Mode
2445
formats. In particular the first track may contain both computer
2446
data (Yellow Book) CD ROM data while the remaining tracks are
2447
audio or video data. Video CD's can be Mixed Mode CDs.
2448
2449
Multisession
2450
A way of writing to a CD that allows more data to be added to
2451
readable discs at a later time.
2452
2453
Nero NRG format file
2454
A proprietary CD image file format use by a popular program for
2455
Microsoft Windows, Ahead Nero. The specification of this format is
2456
not to our knowlege published.
2457
2458
Rock Ridge Extensions
2459
An extension to the ISO-9660 standard which adds POSIX information
2460
to files.
2461
2462
SCSI
2463
Small Computer System Interface. A set of ANSI standard electronic
2464
interfaces (originally developed at Apple Computer) that allow
2465
personal computers to communicate with peripheral hardware such as
2466
CD-ROM drives, disk drives, printers, etc.
2467
2468
SCSI CDB
2469
SCSI Command Descriptor Block. The data structure that is used to
2470
issue a SCSI command.
2471
2472
SCSI Pass Through Interface.
2473
Yet another way of issuing MMC commands for accessing a CD-ROM. As
2474
with MMC or ASPI, the CD-ROM doesn't necessarily have to be a
2475
SCSI-attached drive. See also MMC and ASPI.
2476
2477
Session
2478
A fully readable complete recording that contains one or more
2479
tracks of computer data or audio on a CD.
2480
2481
SVCD
2482
Super VCD
2483
2484
An improvement of Video CD 2.0 specification which includes most
2485
notably a switch from MPEG-1 (constant bit rate encoding) to
2486
MPEG-2 (variable bit rate encoding) for the video stream.
2487
2488
Also added was higher video-stream resolution, up to 4 overlay
2489
graphics and text ("OGT") sub-channels for user switchable
2490
subtitle displaying, closed caption text, and command lists for
2491
controlling the SVCD virtual machine.
2492
2493
See `http://www.dvdrhelp.com/svcd'
2494
2495
TOC
2496
(Compact Disc) Table of Contents. The TOC contains the starting
2497
track number, last track number individual track starting time,
2498
and some track flags (copy protection, linear audio preemphasis,
2499
track format: CDDA or data). Every CD must have at least 1 TOC,
2500
the first TOC is always recorded at the start of the CD (lead-in
2501
area). A multi-session CD may have several TOCs.
2502
2503
Track
2504
A unit of data of a CD. The size of a track can vary; it can occupy
2505
the entire contents of the CD. Most CD standards however require
2506
that tracks have a 150 frame (or "2 second") lead-in gap.
2507
2508
VCD
2509
The Video Compact Disc ("Video CD" or "VCD") is a standardized
2510
digital video storage format. It is based on the commonly available
2511
Compact Disc technology, which allows for low-cost video authoring.
2512
Video CD's can be played in most DVD standalone player, dedicated
2513
VCD players and finally, modern Personal Computers with multimedia
2514
support.
2515
2516
A Video CD is made up of CD-ROM XA sectors, i.e. CD-ROM mode 2
2517
form 1 & 2 sectors. Non-MPEG data is stored in mode 2 form 1
2518
sectors with a user data area of 2048 byte, which have a similiar
2519
L2 error correction and detection (ECC/EDC) to CD-ROM mode 1
2520
sectors. While realtime MPEG streams is stored in CD-ROM mode 2
2521
form 2 sectors, which by have no L2 ECC, yield a ~14% greater user
2522
data area consisting of 2324 bytes(1)
2523
2524
`http://www.dvdrhelp.com/vcd'
2525
2526
Win32 ASPI
2527
The ASPI interface specification was developed by Adaptec for
2528
sending commands to a SCSI host adapter (such as those controlling
2529
CD and DVD drives) and used on Window 9x/NT and later. Emulation
2530
for ATAPI drives was added so that the same sets of commands
2531
worked those even though the drives might not be SCSI nor might
2532
there even be a SCSI controller attached.
2533
2534
However in Windows NT/2K/XP, Microsoft provides their Win32 ioctl
2535
interface, and has take steps to make using ASPI more inaccessible
2536
(e.g. requiring adminstrative access to use ASPI).
2537
2538
See also MMC
2539
2540
Win32 ioctl driver
2541
Ioctl (Input Output ConTroLs). A Win32 function, implemented in all
2542
Microsoft Windows. It is used for sending commands to devices
2543
using defined codes and structures.
2544
2545
XA
2546
See CD-ROM XA
2547
2548
2549
---------- Footnotes ----------
2550
2551
(1) actually raw mode 2 sectors have a 2336 byte user data area, but
2552
parts of it are used for error codes and headers when using the mode 2
2553
form 1 or form 2 configurations.
2554
2555
2556
File: libcdio.info, Node: GNU General Public License, Next: GNU Free Documentation License, Prev: Glossary, Up: Top
2557
2558
Appendix C GNU General Public License
2559
*************************************
2560
2561
Version 2, June 1991
2562
2563
Copyright (C) 1989, 1991 Free Software Foundation, Inc.
2564
59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
2565
2566
Everyone is permitted to copy and distribute verbatim copies
2567
of this license document, but changing it is not allowed.
2568
2569
Preamble
2570
========
2571
2572
The licenses for most software are designed to take away your freedom
2573
to share and change it. By contrast, the GNU General Public License is
2574
intended to guarantee your freedom to share and change free
2575
software--to make sure the software is free for all its users. This
2576
General Public License applies to most of the Free Software
2577
Foundation's software and to any other program whose authors commit to
2578
using it. (Some other Free Software Foundation software is covered by
2579
the GNU Library General Public License instead.) You can apply it to
2580
your programs, too.
2581
2582
When we speak of free software, we are referring to freedom, not price.
2583
Our General Public Licenses are designed to make sure that you have
2584
the freedom to distribute copies of free software (and charge for this
2585
service if you wish), that you receive source code or can get it if you
2586
want it, that you can change the software or use pieces of it in new
2587
free programs; and that you know you can do these things.
2588
2589
To protect your rights, we need to make restrictions that forbid anyone
2590
to deny you these rights or to ask you to surrender the rights. These
2591
restrictions translate to certain responsibilities for you if you
2592
distribute copies of the software, or if you modify it.
2593
2594
For example, if you distribute copies of such a program, whether gratis
2595
or for a fee, you must give the recipients all the rights that you
2596
have. You must make sure that they, too, receive or can get the source
2597
code. And you must show them these terms so they know their rights.
2598
2599
We protect your rights with two steps: (1) copyright the software, and
2600
(2) offer you this license which gives you legal permission to copy,
2601
distribute and/or modify the software.
2602
2603
Also, for each author's protection and ours, we want to make certain
2604
that everyone understands that there is no warranty for this free
2605
software. If the software is modified by someone else and passed on, we
2606
want its recipients to know that what they have is not the original, so
2607
that any problems introduced by others will not reflect on the original
2608
authors' reputations.
2609
2610
Finally, any free program is threatened constantly by software patents.
2611
We wish to avoid the danger that redistributors of a free program will
2612
individually obtain patent licenses, in effect making the program
2613
proprietary. To prevent this, we have made it clear that any patent
2614
must be licensed for everyone's free use or not licensed at all.
2615
2616
The precise terms and conditions for copying, distribution and
2617
modification follow.
2618
2619
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
2620
0. This License applies to any program or other work which contains a
2621
notice placed by the copyright holder saying it may be distributed
2622
under the terms of this General Public License. The "Program",
2623
below, refers to any such program or work, and a "work based on
2624
the Program" means either the Program or any derivative work under
2625
copyright law: that is to say, a work containing the Program or a
2626
portion of it, either verbatim or with modifications and/or
2627
translated into another language. (Hereinafter, translation is
2628
included without limitation in the term "modification".) Each
2629
licensee is addressed as "you".
2630
2631
Activities other than copying, distribution and modification are
2632
not covered by this License; they are outside its scope. The act
2633
of running the Program is not restricted, and the output from the
2634
Program is covered only if its contents constitute a work based on
2635
the Program (independent of having been made by running the
2636
Program). Whether that is true depends on what the Program does.
2637
2638
1. You may copy and distribute verbatim copies of the Program's
2639
source code as you receive it, in any medium, provided that you
2640
conspicuously and appropriately publish on each copy an appropriate
2641
copyright notice and disclaimer of warranty; keep intact all the
2642
notices that refer to this License and to the absence of any
2643
warranty; and give any other recipients of the Program a copy of
2644
this License along with the Program.
2645
2646
You may charge a fee for the physical act of transferring a copy,
2647
and you may at your option offer warranty protection in exchange
2648
for a fee.
2649
2650
2. You may modify your copy or copies of the Program or any portion
2651
of it, thus forming a work based on the Program, and copy and
2652
distribute such modifications or work under the terms of Section 1
2653
above, provided that you also meet all of these conditions:
2654
2655
a. You must cause the modified files to carry prominent notices
2656
stating that you changed the files and the date of any change.
2657
2658
b. You must cause any work that you distribute or publish, that
2659
in whole or in part contains or is derived from the Program
2660
or any part thereof, to be licensed as a whole at no charge
2661
to all third parties under the terms of this License.
2662
2663
c. If the modified program normally reads commands interactively
2664
when run, you must cause it, when started running for such
2665
interactive use in the most ordinary way, to print or display
2666
an announcement including an appropriate copyright notice and
2667
a notice that there is no warranty (or else, saying that you
2668
provide a warranty) and that users may redistribute the
2669
program under these conditions, and telling the user how to
2670
view a copy of this License. (Exception: if the Program
2671
itself is interactive but does not normally print such an
2672
announcement, your work based on the Program is not required
2673
to print an announcement.)
2674
2675
These requirements apply to the modified work as a whole. If
2676
identifiable sections of that work are not derived from the
2677
Program, and can be reasonably considered independent and separate
2678
works in themselves, then this License, and its terms, do not
2679
apply to those sections when you distribute them as separate
2680
works. But when you distribute the same sections as part of a
2681
whole which is a work based on the Program, the distribution of
2682
the whole must be on the terms of this License, whose permissions
2683
for other licensees extend to the entire whole, and thus to each
2684
and every part regardless of who wrote it.
2685
2686
Thus, it is not the intent of this section to claim rights or
2687
contest your rights to work written entirely by you; rather, the
2688
intent is to exercise the right to control the distribution of
2689
derivative or collective works based on the Program.
2690
2691
In addition, mere aggregation of another work not based on the
2692
Program with the Program (or with a work based on the Program) on
2693
a volume of a storage or distribution medium does not bring the
2694
other work under the scope of this License.
2695
2696
3. You may copy and distribute the Program (or a work based on it,
2697
under Section 2) in object code or executable form under the terms
2698
of Sections 1 and 2 above provided that you also do one of the
2699
following:
2700
2701
a. Accompany it with the complete corresponding machine-readable
2702
source code, which must be distributed under the terms of
2703
Sections 1 and 2 above on a medium customarily used for
2704
software interchange; or,
2705
2706
b. Accompany it with a written offer, valid for at least three
2707
years, to give any third party, for a charge no more than your
2708
cost of physically performing source distribution, a complete
2709
machine-readable copy of the corresponding source code, to be
2710
distributed under the terms of Sections 1 and 2 above on a
2711
medium customarily used for software interchange; or,
2712
2713
c. Accompany it with the information you received as to the offer
2714
to distribute corresponding source code. (This alternative is
2715
allowed only for noncommercial distribution and only if you
2716
received the program in object code or executable form with
2717
such an offer, in accord with Subsection b above.)
2718
2719
The source code for a work means the preferred form of the work for
2720
making modifications to it. For an executable work, complete
2721
source code means all the source code for all modules it contains,
2722
plus any associated interface definition files, plus the scripts
2723
used to control compilation and installation of the executable.
2724
However, as a special exception, the source code distributed need
2725
not include anything that is normally distributed (in either
2726
source or binary form) with the major components (compiler,
2727
kernel, and so on) of the operating system on which the executable
2728
runs, unless that component itself accompanies the executable.
2729
2730
If distribution of executable or object code is made by offering
2731
access to copy from a designated place, then offering equivalent
2732
access to copy the source code from the same place counts as
2733
distribution of the source code, even though third parties are not
2734
compelled to copy the source along with the object code.
2735
2736
4. You may not copy, modify, sublicense, or distribute the Program
2737
except as expressly provided under this License. Any attempt
2738
otherwise to copy, modify, sublicense or distribute the Program is
2739
void, and will automatically terminate your rights under this
2740
License. However, parties who have received copies, or rights,
2741
from you under this License will not have their licenses
2742
terminated so long as such parties remain in full compliance.
2743
2744
5. You are not required to accept this License, since you have not
2745
signed it. However, nothing else grants you permission to modify
2746
or distribute the Program or its derivative works. These actions
2747
are prohibited by law if you do not accept this License.
2748
Therefore, by modifying or distributing the Program (or any work
2749
based on the Program), you indicate your acceptance of this
2750
License to do so, and all its terms and conditions for copying,
2751
distributing or modifying the Program or works based on it.
2752
2753
6. Each time you redistribute the Program (or any work based on the
2754
Program), the recipient automatically receives a license from the
2755
original licensor to copy, distribute or modify the Program
2756
subject to these terms and conditions. You may not impose any
2757
further restrictions on the recipients' exercise of the rights
2758
granted herein. You are not responsible for enforcing compliance
2759
by third parties to this License.
2760
2761
7. If, as a consequence of a court judgment or allegation of patent
2762
infringement or for any other reason (not limited to patent
2763
issues), conditions are imposed on you (whether by court order,
2764
agreement or otherwise) that contradict the conditions of this
2765
License, they do not excuse you from the conditions of this
2766
License. If you cannot distribute so as to satisfy simultaneously
2767
your obligations under this License and any other pertinent
2768
obligations, then as a consequence you may not distribute the
2769
Program at all. For example, if a patent license would not permit
2770
royalty-free redistribution of the Program by all those who
2771
receive copies directly or indirectly through you, then the only
2772
way you could satisfy both it and this License would be to refrain
2773
entirely from distribution of the Program.
2774
2775
If any portion of this section is held invalid or unenforceable
2776
under any particular circumstance, the balance of the section is
2777
intended to apply and the section as a whole is intended to apply
2778
in other circumstances.
2779
2780
It is not the purpose of this section to induce you to infringe any
2781
patents or other property right claims or to contest validity of
2782
any such claims; this section has the sole purpose of protecting
2783
the integrity of the free software distribution system, which is
2784
implemented by public license practices. Many people have made
2785
generous contributions to the wide range of software distributed
2786
through that system in reliance on consistent application of that
2787
system; it is up to the author/donor to decide if he or she is
2788
willing to distribute software through any other system and a
2789
licensee cannot impose that choice.
2790
2791
This section is intended to make thoroughly clear what is believed
2792
to be a consequence of the rest of this License.
2793
2794
8. If the distribution and/or use of the Program is restricted in
2795
certain countries either by patents or by copyrighted interfaces,
2796
the original copyright holder who places the Program under this
2797
License may add an explicit geographical distribution limitation
2798
excluding those countries, so that distribution is permitted only
2799
in or among countries not thus excluded. In such case, this
2800
License incorporates the limitation as if written in the body of
2801
this License.
2802
2803
9. The Free Software Foundation may publish revised and/or new
2804
versions of the General Public License from time to time. Such
2805
new versions will be similar in spirit to the present version, but
2806
may differ in detail to address new problems or concerns.
2807
2808
Each version is given a distinguishing version number. If the
2809
Program specifies a version number of this License which applies
2810
to it and "any later version", you have the option of following
2811
the terms and conditions either of that version or of any later
2812
version published by the Free Software Foundation. If the Program
2813
does not specify a version number of this License, you may choose
2814
any version ever published by the Free Software Foundation.
2815
2816
10. If you wish to incorporate parts of the Program into other free
2817
programs whose distribution conditions are different, write to the
2818
author to ask for permission. For software which is copyrighted
2819
by the Free Software Foundation, write to the Free Software
2820
Foundation; we sometimes make exceptions for this. Our decision
2821
will be guided by the two goals of preserving the free status of
2822
all derivatives of our free software and of promoting the sharing
2823
and reuse of software generally.
2824
2825
NO WARRANTY
2826
11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
2827
WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
2828
LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
2829
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
2830
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
2831
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
2832
FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE
2833
QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
2834
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
2835
SERVICING, REPAIR OR CORRECTION.
2836
2837
12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
2838
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
2839
MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
2840
LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
2841
INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
2842
INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
2843
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
2844
OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
2845
OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
2846
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
2847
2848
END OF TERMS AND CONDITIONS
2849
Appendix: How to Apply These Terms to Your New Programs
2850
=======================================================
2851
2852
If you develop a new program, and you want it to be of the greatest
2853
possible use to the public, the best way to achieve this is to make it
2854
free software which everyone can redistribute and change under these
2855
terms.
2856
2857
To do so, attach the following notices to the program. It is safest to
2858
attach them to the start of each source file to most effectively convey
2859
the exclusion of warranty; and each file should have at least the
2860
"copyright" line and a pointer to where the full notice is found.
2861
2862
ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
2863
Copyright (C) YYYY NAME OF AUTHOR
2864
2865
This program is free software; you can redistribute it and/or modify
2866
it under the terms of the GNU General Public License as published by
2867
the Free Software Foundation; either version 2 of the License, or
2868
(at your option) any later version.
2869
2870
This program is distributed in the hope that it will be useful,
2871
but WITHOUT ANY WARRANTY; without even the implied warranty of
2872
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
2873
GNU General Public License for more details.
2874
2875
You should have received a copy of the GNU General Public License
2876
along with this program; if not, write to the Free Software
2877
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2878
2879
Also add information on how to contact you by electronic and paper mail.
2880
2881
If the program is interactive, make it output a short notice like this
2882
when it starts in an interactive mode:
2883
2884
Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
2885
Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
2886
This is free software, and you are welcome to redistribute it
2887
under certain conditions; type `show c' for details.
2888
2889
The hypothetical commands `show w' and `show c' should show the
2890
appropriate parts of the General Public License. Of course, the
2891
commands you use may be called something other than `show w' and `show
2892
c'; they could even be mouse-clicks or menu items--whatever suits your
2893
program.
2894
2895
You should also get your employer (if you work as a programmer) or your
2896
school, if any, to sign a "copyright disclaimer" for the program, if
2897
necessary. Here is a sample; alter the names:
2898
2899
Yoyodyne, Inc., hereby disclaims all copyright interest in the program
2900
`Gnomovision' (which makes passes at compilers) written by James Hacker.
2901
2902
SIGNATURE OF TY COON, 1 April 1989
2903
Ty Coon, President of Vice
2904
2905
This General Public License does not permit incorporating your program
2906
into proprietary programs. If your program is a subroutine library,
2907
you may consider it more useful to permit linking proprietary
2908
applications with the library. If this is what you want to do, use the
2909
GNU Library General Public License instead of this License.
2910
2911
2912
File: libcdio.info, Node: GNU Free Documentation License, Next: General Index, Prev: GNU General Public License, Up: Top
2913
2914
Appendix D GNU Free Documentation License
2915
*****************************************
2916
2917
Version 1.1, March 2000
2918
2919
Copyright (C) 2000 Free Software Foundation, Inc.
2920
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
2921
2922
Everyone is permitted to copy and distribute verbatim copies
2923
of this license document, but changing it is not allowed.
2924
2925
0. PREAMBLE
2926
2927
The purpose of this License is to make a manual, textbook, or other
2928
written document "free" in the sense of freedom: to assure everyone
2929
the effective freedom to copy and redistribute it, with or without
2930
modifying it, either commercially or noncommercially. Secondarily,
2931
this License preserves for the author and publisher a way to get
2932
credit for their work, while not being considered responsible for
2933
modifications made by others.
2934
2935
This License is a kind of "copyleft", which means that derivative
2936
works of the document must themselves be free in the same sense.
2937
It complements the GNU General Public License, which is a copyleft
2938
license designed for free software.
2939
2940
We have designed this License in order to use it for manuals for
2941
free software, because free software needs free documentation: a
2942
free program should come with manuals providing the same freedoms
2943
that the software does. But this License is not limited to
2944
software manuals; it can be used for any textual work, regardless
2945
of subject matter or whether it is published as a printed book.
2946
We recommend this License principally for works whose purpose is
2947
instruction or reference.
2948
2949
1. APPLICABILITY AND DEFINITIONS
2950
2951
This License applies to any manual or other work that contains a
2952
notice placed by the copyright holder saying it can be distributed
2953
under the terms of this License. The "Document", below, refers to
2954
any such manual or work. Any member of the public is a licensee,
2955
and is addressed as "you".
2956
2957
A "Modified Version" of the Document means any work containing the
2958
Document or a portion of it, either copied verbatim, or with
2959
modifications and/or translated into another language.
2960
2961
A "Secondary Section" is a named appendix or a front-matter
2962
section of the Document that deals exclusively with the
2963
relationship of the publishers or authors of the Document to the
2964
Document's overall subject (or to related matters) and contains
2965
nothing that could fall directly within that overall subject.
2966
(For example, if the Document is in part a textbook of
2967
mathematics, a Secondary Section may not explain any mathematics.)
2968
The relationship could be a matter of historical connection with
2969
the subject or with related matters, or of legal, commercial,
2970
philosophical, ethical or political position regarding them.
2971
2972
The "Invariant Sections" are certain Secondary Sections whose
2973
titles are designated, as being those of Invariant Sections, in
2974
the notice that says that the Document is released under this
2975
License.
2976
2977
The "Cover Texts" are certain short passages of text that are
2978
listed, as Front-Cover Texts or Back-Cover Texts, in the notice
2979
that says that the Document is released under this License.
2980
2981
A "Transparent" copy of the Document means a machine-readable copy,
2982
represented in a format whose specification is available to the
2983
general public, whose contents can be viewed and edited directly
2984
and straightforwardly with generic text editors or (for images
2985
composed of pixels) generic paint programs or (for drawings) some
2986
widely available drawing editor, and that is suitable for input to
2987
text formatters or for automatic translation to a variety of
2988
formats suitable for input to text formatters. A copy made in an
2989
otherwise Transparent file format whose markup has been designed
2990
to thwart or discourage subsequent modification by readers is not
2991
Transparent. A copy that is not "Transparent" is called "Opaque".
2992
2993
Examples of suitable formats for Transparent copies include plain
2994
ASCII without markup, Texinfo input format, LaTeX input format,
2995
SGML or XML using a publicly available DTD, and
2996
standard-conforming simple HTML designed for human modification.
2997
Opaque formats include PostScript, PDF, proprietary formats that
2998
can be read and edited only by proprietary word processors, SGML
2999
or XML for which the DTD and/or processing tools are not generally
3000
available, and the machine-generated HTML produced by some word
3001
processors for output purposes only.
3002
3003
The "Title Page" means, for a printed book, the title page itself,
3004
plus such following pages as are needed to hold, legibly, the
3005
material this License requires to appear in the title page. For
3006
works in formats which do not have any title page as such, "Title
3007
Page" means the text near the most prominent appearance of the
3008
work's title, preceding the beginning of the body of the text.
3009
3010
2. VERBATIM COPYING
3011
3012
You may copy and distribute the Document in any medium, either
3013
commercially or noncommercially, provided that this License, the
3014
copyright notices, and the license notice saying this License
3015
applies to the Document are reproduced in all copies, and that you
3016
add no other conditions whatsoever to those of this License. You
3017
may not use technical measures to obstruct or control the reading
3018
or further copying of the copies you make or distribute. However,
3019
you may accept compensation in exchange for copies. If you
3020
distribute a large enough number of copies you must also follow
3021
the conditions in section 3.
3022
3023
You may also lend copies, under the same conditions stated above,
3024
and you may publicly display copies.
3025
3026
3. COPYING IN QUANTITY
3027
3028
If you publish printed copies of the Document numbering more than
3029
100, and the Document's license notice requires Cover Texts, you
3030
must enclose the copies in covers that carry, clearly and legibly,
3031
all these Cover Texts: Front-Cover Texts on the front cover, and
3032
Back-Cover Texts on the back cover. Both covers must also clearly
3033
and legibly identify you as the publisher of these copies. The
3034
front cover must present the full title with all words of the
3035
title equally prominent and visible. You may add other material
3036
on the covers in addition. Copying with changes limited to the
3037
covers, as long as they preserve the title of the Document and
3038
satisfy these conditions, can be treated as verbatim copying in
3039
other respects.
3040
3041
If the required texts for either cover are too voluminous to fit
3042
legibly, you should put the first ones listed (as many as fit
3043
reasonably) on the actual cover, and continue the rest onto
3044
adjacent pages.
3045
3046
If you publish or distribute Opaque copies of the Document
3047
numbering more than 100, you must either include a
3048
machine-readable Transparent copy along with each Opaque copy, or
3049
state in or with each Opaque copy a publicly-accessible
3050
computer-network location containing a complete Transparent copy
3051
of the Document, free of added material, which the general
3052
network-using public has access to download anonymously at no
3053
charge using public-standard network protocols. If you use the
3054
latter option, you must take reasonably prudent steps, when you
3055
begin distribution of Opaque copies in quantity, to ensure that
3056
this Transparent copy will remain thus accessible at the stated
3057
location until at least one year after the last time you
3058
distribute an Opaque copy (directly or through your agents or
3059
retailers) of that edition to the public.
3060
3061
It is requested, but not required, that you contact the authors of
3062
the Document well before redistributing any large number of
3063
copies, to give them a chance to provide you with an updated
3064
version of the Document.
3065
3066
4. MODIFICATIONS
3067
3068
You may copy and distribute a Modified Version of the Document
3069
under the conditions of sections 2 and 3 above, provided that you
3070
release the Modified Version under precisely this License, with
3071
the Modified Version filling the role of the Document, thus
3072
licensing distribution and modification of the Modified Version to
3073
whoever possesses a copy of it. In addition, you must do these
3074
things in the Modified Version:
3075
3076
A. Use in the Title Page (and on the covers, if any) a title
3077
distinct from that of the Document, and from those of
3078
previous versions (which should, if there were any, be listed
3079
in the History section of the Document). You may use the
3080
same title as a previous version if the original publisher of
3081
that version gives permission.
3082
3083
B. List on the Title Page, as authors, one or more persons or
3084
entities responsible for authorship of the modifications in
3085
the Modified Version, together with at least five of the
3086
principal authors of the Document (all of its principal
3087
authors, if it has less than five).
3088
3089
C. State on the Title page the name of the publisher of the
3090
Modified Version, as the publisher.
3091
3092
D. Preserve all the copyright notices of the Document.
3093
3094
E. Add an appropriate copyright notice for your modifications
3095
adjacent to the other copyright notices.
3096
3097
F. Include, immediately after the copyright notices, a license
3098
notice giving the public permission to use the Modified
3099
Version under the terms of this License, in the form shown in
3100
the Addendum below.
3101
3102
G. Preserve in that license notice the full lists of Invariant
3103
Sections and required Cover Texts given in the Document's
3104
license notice.
3105
3106
H. Include an unaltered copy of this License.
3107
3108
I. Preserve the section entitled "History", and its title, and
3109
add to it an item stating at least the title, year, new
3110
authors, and publisher of the Modified Version as given on
3111
the Title Page. If there is no section entitled "History" in
3112
the Document, create one stating the title, year, authors,
3113
and publisher of the Document as given on its Title Page,
3114
then add an item describing the Modified Version as stated in
3115
the previous sentence.
3116
3117
J. Preserve the network location, if any, given in the Document
3118
for public access to a Transparent copy of the Document, and
3119
likewise the network locations given in the Document for
3120
previous versions it was based on. These may be placed in
3121
the "History" section. You may omit a network location for a
3122
work that was published at least four years before the
3123
Document itself, or if the original publisher of the version
3124
it refers to gives permission.
3125
3126
K. In any section entitled "Acknowledgments" or "Dedications",
3127
preserve the section's title, and preserve in the section all
3128
the substance and tone of each of the contributor
3129
acknowledgments and/or dedications given therein.
3130
3131
L. Preserve all the Invariant Sections of the Document,
3132
unaltered in their text and in their titles. Section numbers
3133
or the equivalent are not considered part of the section
3134
titles.
3135
3136
M. Delete any section entitled "Endorsements". Such a section
3137
may not be included in the Modified Version.
3138
3139
N. Do not retitle any existing section as "Endorsements" or to
3140
conflict in title with any Invariant Section.
3141
3142
If the Modified Version includes new front-matter sections or
3143
appendices that qualify as Secondary Sections and contain no
3144
material copied from the Document, you may at your option
3145
designate some or all of these sections as invariant. To do this,
3146
add their titles to the list of Invariant Sections in the Modified
3147
Version's license notice. These titles must be distinct from any
3148
other section titles.
3149
3150
You may add a section entitled "Endorsements", provided it contains
3151
nothing but endorsements of your Modified Version by various
3152
parties--for example, statements of peer review or that the text
3153
has been approved by an organization as the authoritative
3154
definition of a standard.
3155
3156
You may add a passage of up to five words as a Front-Cover Text,
3157
and a passage of up to 25 words as a Back-Cover Text, to the end
3158
of the list of Cover Texts in the Modified Version. Only one
3159
passage of Front-Cover Text and one of Back-Cover Text may be
3160
added by (or through arrangements made by) any one entity. If the
3161
Document already includes a cover text for the same cover,
3162
previously added by you or by arrangement made by the same entity
3163
you are acting on behalf of, you may not add another; but you may
3164
replace the old one, on explicit permission from the previous
3165
publisher that added the old one.
3166
3167
The author(s) and publisher(s) of the Document do not by this
3168
License give permission to use their names for publicity for or to
3169
assert or imply endorsement of any Modified Version.
3170
3171
5. COMBINING DOCUMENTS
3172
3173
You may combine the Document with other documents released under
3174
this License, under the terms defined in section 4 above for
3175
modified versions, provided that you include in the combination
3176
all of the Invariant Sections of all of the original documents,
3177
unmodified, and list them all as Invariant Sections of your
3178
combined work in its license notice.
3179
3180
The combined work need only contain one copy of this License, and
3181
multiple identical Invariant Sections may be replaced with a single
3182
copy. If there are multiple Invariant Sections with the same name
3183
but different contents, make the title of each such section unique
3184
by adding at the end of it, in parentheses, the name of the
3185
original author or publisher of that section if known, or else a
3186
unique number. Make the same adjustment to the section titles in
3187
the list of Invariant Sections in the license notice of the
3188
combined work.
3189
3190
In the combination, you must combine any sections entitled
3191
"History" in the various original documents, forming one section
3192
entitled "History"; likewise combine any sections entitled
3193
"Acknowledgments", and any sections entitled "Dedications". You
3194
must delete all sections entitled "Endorsements."
3195
3196
6. COLLECTIONS OF DOCUMENTS
3197
3198
You may make a collection consisting of the Document and other
3199
documents released under this License, and replace the individual
3200
copies of this License in the various documents with a single copy
3201
that is included in the collection, provided that you follow the
3202
rules of this License for verbatim copying of each of the
3203
documents in all other respects.
3204
3205
You may extract a single document from such a collection, and
3206
distribute it individually under this License, provided you insert
3207
a copy of this License into the extracted document, and follow
3208
this License in all other respects regarding verbatim copying of
3209
that document.
3210
3211
7. AGGREGATION WITH INDEPENDENT WORKS
3212
3213
A compilation of the Document or its derivatives with other
3214
separate and independent documents or works, in or on a volume of
3215
a storage or distribution medium, does not as a whole count as a
3216
Modified Version of the Document, provided no compilation
3217
copyright is claimed for the compilation. Such a compilation is
3218
called an "aggregate", and this License does not apply to the
3219
other self-contained works thus compiled with the Document, on
3220
account of their being thus compiled, if they are not themselves
3221
derivative works of the Document.
3222
3223
If the Cover Text requirement of section 3 is applicable to these
3224
copies of the Document, then if the Document is less than one
3225
quarter of the entire aggregate, the Document's Cover Texts may be
3226
placed on covers that surround only the Document within the
3227
aggregate. Otherwise they must appear on covers around the whole
3228
aggregate.
3229
3230
8. TRANSLATION
3231
3232
Translation is considered a kind of modification, so you may
3233
distribute translations of the Document under the terms of section
3234
4. Replacing Invariant Sections with translations requires special
3235
permission from their copyright holders, but you may include
3236
translations of some or all Invariant Sections in addition to the
3237
original versions of these Invariant Sections. You may include a
3238
translation of this License provided that you also include the
3239
original English version of this License. In case of a
3240
disagreement between the translation and the original English
3241
version of this License, the original English version will prevail.
3242
3243
9. TERMINATION
3244
3245
You may not copy, modify, sublicense, or distribute the Document
3246
except as expressly provided for under this License. Any other
3247
attempt to copy, modify, sublicense or distribute the Document is
3248
void, and will automatically terminate your rights under this
3249
License. However, parties who have received copies, or rights,
3250
from you under this License will not have their licenses
3251
terminated so long as such parties remain in full compliance.
3252
3253
10. FUTURE REVISIONS OF THIS LICENSE
3254
3255
The Free Software Foundation may publish new, revised versions of
3256
the GNU Free Documentation License from time to time. Such new
3257
versions will be similar in spirit to the present version, but may
3258
differ in detail to address new problems or concerns. See
3259
`http://www.gnu.org/copyleft/'.
3260
3261
Each version of the License is given a distinguishing version
3262
number. If the Document specifies that a particular numbered
3263
version of this License "or any later version" applies to it, you
3264
have the option of following the terms and conditions either of
3265
that specified version or of any later version that has been
3266
published (not as a draft) by the Free Software Foundation. If
3267
the Document does not specify a version number of this License,
3268
you may choose any version ever published (not as a draft) by the
3269
Free Software Foundation.
3270
3271
ADDENDUM: How to use this License for your documents
3272
====================================================
3273
3274
To use this License in a document you have written, include a copy of
3275
the License in the document and put the following copyright and license
3276
notices just after the title page:
3277
3278
Copyright (C) YEAR YOUR NAME.
3279
Permission is granted to copy, distribute and/or modify this document
3280
under the terms of the GNU Free Documentation License, Version 1.1
3281
or any later version published by the Free Software Foundation;
3282
with the Invariant Sections being LIST THEIR TITLES, with the
3283
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
3284
A copy of the license is included in the section entitled ``GNU
3285
Free Documentation License''.
3286
3287
If you have no Invariant Sections, write "with no Invariant Sections"
3288
instead of saying which ones are invariant. If you have no Front-Cover
3289
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
3290
LIST"; likewise for Back-Cover Texts.
3291
3292
If your document contains nontrivial examples of program code, we
3293
recommend releasing these examples in parallel under your choice of
3294
free software license, such as the GNU General Public License, to
3295
permit their use in free software.
3296
3297
3298
File: libcdio.info, Node: General Index, Prev: GNU Free Documentation License, Up: Top
3299
3300
General Index
3301
*************
3302
3303
[index ]
3304
* Menu:
3305
3306
* ASPI: Glossary. (line 9)
3307
* BIN/CUE, CD Image Format: CDRWIN BIN/CUE Format.
3308
(line 6)
3309
* CD Text <1>: Glossary. (line 75)
3310
* CD Text: CD Text. (line 6)
3311
* CD XA: Glossary. (line 82)
3312
* CD+G <1>: Glossary. (line 44)
3313
* CD+G: CD Text. (line 6)
3314
* CD-DA: Glossary. (line 38)
3315
* CD-i: Glossary. (line 50)
3316
* CD-i Bridge: Glossary. (line 58)
3317
* CD-ROM: Glossary. (line 62)
3318
* CDB (Command Descriptor Block): MMC. (line 48)
3319
* CDDB: CDDB. (line 6)
3320
* Command Packet: Glossary. (line 101)
3321
* FDL, GNU Free Documentation License: GNU Free Documentation License.
3322
(line 6)
3323
* frames: Sectors. (line 6)
3324
* FSF: Glossary. (line 105)
3325
* GNU: Glossary. (line 108)
3326
* GPL, GNU General Public License: GNU General Public License.
3327
(line 6)
3328
* Green Book <1>: White Book. (line 6)
3329
* Green Book: Green Book. (line 6)
3330
* ISO: Glossary. (line 116)
3331
* ISO 9660 <1>: Glossary. (line 119)
3332
* ISO 9660: ISO 9660. (line 6)
3333
* Joliet extensions <1>: Glossary. (line 138)
3334
* Joliet extensions: Joliet Extensions. (line 6)
3335
* LBA <1>: Glossary. (line 150)
3336
* LBA: Sectors. (line 6)
3337
* lead in: Glossary. (line 157)
3338
* lead out: Tracks. (line 19)
3339
* LSN <1>: Glossary. (line 165)
3340
* LSN: Sectors. (line 6)
3341
* MCN: Glossary. (line 174)
3342
* Mixed Mode CD: Glossary. (line 187)
3343
* MMC (Multimedia Commands): Glossary. (line 178)
3344
* Mode 1: Mode 1. (line 6)
3345
* Mode 2: Mode 2. (line 6)
3346
* MSF: Sectors. (line 6)
3347
* Multisession: Glossary. (line 193)
3348
* Nero NRG, CD-Image format <1>: Glossary. (line 197)
3349
* Nero NRG, CD-Image format: NRG Format. (line 6)
3350
* Red Book: Red Book. (line 6)
3351
* Rock Ridge extensions <1>: Glossary. (line 202)
3352
* Rock Ridge extensions: Rock Ridge Extensions.
3353
(line 6)
3354
* SCSI: Glossary. (line 206)
3355
* SCSI CDB: Glossary. (line 212)
3356
* SCSI Pass Through Interface.: Glossary. (line 216)
3357
* sectors: Sectors. (line 6)
3358
* subchannel: Red Book. (line 27)
3359
* Super VCD (SVCD): Glossary. (line 225)
3360
* TOC (CD Table of Contents): Glossary. (line 239)
3361
* track <1>: Glossary. (line 247)
3362
* track: Tracks. (line 6)
3363
* Video CD (VCD): Glossary. (line 252)
3364
* XA: Glossary. (line 289)
3365
3366
30
3367
31
3368
Tag Table:
32
(Indirect)
33
Node: Top976
34
Node: History1990
35
Node: Previous Work3777
36
Ref: Previous Work-Footnote-17894
37
Ref: Previous Work-Footnote-28022
38
Node: Purpose8289
39
Ref: Purpose-Footnote-111055
40
Node: CD Formats11244
41
Node: Red Book12006
42
Node: Yellow Book12697
43
Node: ISO 966013188
44
Node: ISO 9660 Level 113964
45
Node: ISO 9660 Level 214566
46
Node: ISO 9660 Level 314823
47
Node: Mode115555
48
Node: Mode216350
49
Node: Green Book17289
50
Node: White Book18030
51
Node: CD Terms18925
52
Node: How to use23163
53
Node: Example 124201
54
Node: Example 227461
55
Node: Example 328858
56
Node: Example 434321
57
Node: Example 536946
58
Node: Example 638787
59
Node: All sample programs40981
60
Node: Utility Programs42575
61
Node: cd-drive43093
62
Node: cd-info43293
63
Node: cd-read43762
64
Node: iso-info44077
65
Node: iso-read44268
66
Node: OS Considerations44434
67
Node: GNU/Linux44709
68
Node: Microsoft45000
69
Node: Solaris45754
70
Node: FreeBSD45967
71
Node: OS X46306
72
Node: ISO-9660 Character Sets46441
73
Node: ISO646 d-Characters46730
74
Node: ISO646 a-Characters47169
75
Node: CD Image Formats47608
76
Node: CDRDAO TOC Format47822
77
Node: CDRWIN BIN/CUE Format48338
78
Node: NRG Format50017
79
Node: Glossary50771
80
Node: GNU General Public License59637
81
Node: GNU Free Documentation License77598
82
Node: General Index95809
3369
Node: Top982
3370
Node: History2069
3371
Node: Previous Work4100
3372
Ref: Previous Work-Footnote-18232
3373
Ref: Previous Work-Footnote-28355
3374
Node: Purpose8622
3375
Ref: Purpose-Footnote-113097
3376
Node: CD Formats13286
3377
Node: Red Book14078
3378
Node: CD Text15466
3379
Node: CDDB17512
3380
Node: Yellow Book18887
3381
Node: ISO 966019434
3382
Node: ISO 9660 Level 120271
3383
Node: ISO 9660 Level 220889
3384
Node: ISO 9660 Level 321162
3385
Node: Joliet Extensions21936
3386
Node: Rock Ridge Extensions23047
3387
Node: Mode 123985
3388
Node: Mode 224854
3389
Node: Green Book25867
3390
Node: White Book26629
3391
Node: CD Image Formats27562
3392
Node: CDRDAO TOC Format28846
3393
Node: CDRWIN BIN/CUE Format32239
3394
Node: NRG Format33982
3395
Node: CD Units34745
3396
Node: Tracks34975
3397
Node: Sectors36627
3398
Ref: Sectors-Footnote-139863
3399
Node: How to use39976
3400
Node: Example 141082
3401
Node: Example 244716
3402
Node: Example 346134
3403
Node: Example 451597
3404
Node: Example 554277
3405
Node: Example 656132
3406
Node: Example 758293
3407
Node: All sample programs62405
3408
Node: Utility Programs64838
3409
Node: cd-drive65392
3410
Node: cd-info65631
3411
Node: cd-read66108
3412
Node: iso-info66431
3413
Node: iso-read66630
3414
Node: CD-ROM Access and Drivers66804
3415
Node: MMC67228
3416
Node: GNU/Linux70576
3417
Node: Microsoft71141
3418
Node: Solaris71958
3419
Node: FreeBSD72430
3420
Node: OS X72854
3421
Node: Internal Program Organization73516
3422
Node: ISO-9660 Character Sets80038
3423
Node: ISO646 d-Characters80353
3424
Node: ISO646 a-Characters80800
3425
Node: Glossary81247
3426
Ref: Glossary-Footnote-193215
3427
Node: GNU General Public License93389
3428
Node: GNU Free Documentation License112457
3429
Node: General Index132314
83
3430
84
3431
End Tag Table
Loggerhead is a web-based interface for Breezy
Version: 2.0.1