181 lines
7.9 KiB
Plaintext
181 lines
7.9 KiB
Plaintext
/**
|
|
@author Mario Danic, Thomas Schmitt
|
|
|
|
@mainpage Libburnia Documentation Index
|
|
|
|
@section intro Introduction
|
|
|
|
Libburnia is an open-source project for reading, mastering and writing
|
|
optical discs.
|
|
For now this means CD-R, CD-RW, DVD-RAM, DVD+RW, DVD+R, DVD+R/DL, DVD-RW,
|
|
DVD-R, BD-RE.
|
|
|
|
Not supported yet are DVD-R/DL, HD-DVD, BD-R (blue ray). Testers for
|
|
DVD-R/DL are wanted, though. BD-R programming efforts would be made
|
|
if an interested tester contacts us.
|
|
|
|
The project comprises of several more or less interdependent parts which
|
|
together strive to be a usable foundation for application development.
|
|
These are libraries, language bindings, and middleware binaries which emulate
|
|
classical (and valuable) Linux tools.
|
|
|
|
Our scope is currently Linux 2.4 and 2.6 only. For ports to other systems
|
|
we would need : login on a development machine resp. a live OS on CD or DVD,
|
|
advise from a system person about the equivalent of Linux sg or FreeBSD CAM,
|
|
volunteers for testing of realistic use cases.
|
|
|
|
We have a well tested code base for burning data and audio CDs and many DVD
|
|
types. The burn API is quite comprehensively documented and can be used to
|
|
build a presentable application.
|
|
We have a functional binary which emulates the core use cases of cdrecord in
|
|
order to prove that usability, and in order to allow you to explore libburn's
|
|
scope by help of existing cdrecord frontends.
|
|
|
|
ISO 9660 filesystems with Rock Ridge and Joliet extensions can be created
|
|
and manipulated quite freely. This capability together with our burn capability
|
|
makes possible a single binary application which covers all steps of image
|
|
composition, updating and writing. Quite unique in the Linux world.
|
|
|
|
@subsection components The project components (list subject to growth, hopefully):
|
|
|
|
- libburn is the library by which preformatted data get onto optical media.
|
|
It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or
|
|
/dev/srM or /dev/hdX (e.g. on kernel 2.6).
|
|
libburn is the foundation of our cdrecord emulation. Its code is
|
|
independent of cdrecord. Its DVD capabilities are learned from
|
|
studying the code of dvd+rw-tools and MMC-5 specs. No code but only
|
|
the pure SCSI knowledge has been taken from dvd+rw-tools, though.
|
|
|
|
- libisofs is the library to pack up hard disk files and directories into a
|
|
ISO 9660 disk image. This may then be brought to CD via libburn.
|
|
libisofs is to be the foundation of our upcoming mkisofs emulation.
|
|
|
|
- libisoburn is an add-on to libburn and libisofs which coordinates both and
|
|
also allows to grow ISO-9660 filesystem images on multi-session
|
|
media as well as on overwriteable media via the same API.
|
|
All media peculiarities are handled automatically.
|
|
|
|
- cdrskin is a limited cdrecord compatibility wrapper for libburn.
|
|
cdrecord is a powerful GPL'ed burn program included in Joerg
|
|
Schilling's cdrtools. cdrskin strives to be a second source for
|
|
the services traditionally provided by cdrecord. Additionally it
|
|
provides libburn's DVD/BD capabilities, where only -sao is
|
|
compatible with cdrecord.
|
|
cdrskin does not contain any bytes copied from cdrecord's sources.
|
|
Many bytes have been copied from the message output of cdrecord
|
|
runs, though.
|
|
See cdrskin/README for more.
|
|
|
|
- xorriso is an application of all three libraries which creates, loads,
|
|
manipulates and writes ISO 9660 filesystem images with
|
|
Rock Ridge extensions. Manipulation is not only adding or
|
|
overwriting of files but also deletion, renaming, and attribute
|
|
changing. An incremental backup feature is provided.
|
|
See xorriso/README for more
|
|
|
|
- "test" is a collection of application gestures and examples given by the
|
|
authors of the library features. The burn API example of libburn
|
|
is named test/libburner.c . The API for media information inquiry is
|
|
demonstrated in test/telltoc.c .
|
|
Explore these examples if you look for inspiration.
|
|
|
|
We strive to be a responsive upstream.
|
|
|
|
Our libraries are committed to maintain older feature sets in newer versions.
|
|
This applies to source code headers (API) as well as to linkable objects (ABI).
|
|
The only exception from this rule is about non-release versions x.y.*[13579]
|
|
which are allowed to introduce new features, change those new features in
|
|
any way and even may revoke such new features before the next release of
|
|
x.y.*[02468]. As soon as it is released, a feature is promised to persist.
|
|
|
|
SONAMES:
|
|
libburn.so.4 (since 0.3.4, March 2007),
|
|
libisofs.so.6 (since 0.6.2, February 2008),
|
|
libisoburn.so.1 (since 0.1.0, February 2008).
|
|
|
|
|
|
@section using Using the libraries
|
|
|
|
Our build system is based on autotools.
|
|
User experience tells us that you will need at least autotools version 1.7.
|
|
|
|
To build libburn and its subprojects it should be sufficient to go into
|
|
its toplevel directory and execute
|
|
|
|
- ./bootstrap (needed if you downloaded from SVN)
|
|
|
|
- ./configure
|
|
|
|
- make
|
|
|
|
To make the libraries accessible for running resp. developing applications
|
|
|
|
- make install
|
|
|
|
Both libraries are written in C language and get built by autotools.
|
|
Thus we expect them to be useable by a wide range of Linux-implemented
|
|
languages and development tools.
|
|
|
|
|
|
@section libburner Libburner
|
|
|
|
libburner is a minimal demo application for the library libburn
|
|
(see: libburn/libburn.h) as provided on http://libburnia-project.org .
|
|
It can list the available devices, can blank a CD-RW or DVD-RW and
|
|
can burn to recordable CD and recordable single layer DVD.
|
|
|
|
It's main purpose, nevertheless, is to show you how to use libburn and also
|
|
to serve the libburnia team as reference application. libburner does indeed
|
|
define the standard way how above three gestures can be implemented and
|
|
stay upward compatible for a good while.
|
|
|
|
@subsection libburner-help Libburner --help
|
|
<pre>
|
|
Usage: test/libburner
|
|
[--drive <address>|<driveno>|"-"] [--audio]
|
|
[--blank_fast|--blank_full|--format_overwrite]
|
|
[--try_to_simulate]
|
|
[--multi] [<one or more imagefiles>|"-"]
|
|
Examples
|
|
A bus scan (needs rw-permissions to see a drive):
|
|
test/libburner --drive -
|
|
Burn a file to drive chosen by number, leave appendable:
|
|
test/libburner --drive 0 --multi my_image_file
|
|
Burn a file to drive chosen by persistent address, close:
|
|
test/libburner --drive /dev/hdc my_image_file
|
|
Blank a used CD-RW (is combinable with burning in one run):
|
|
test/libburner --drive /dev/hdc --blank_fast
|
|
Blank a used DVD-RW (is combinable with burning in one run):
|
|
test/libburner --drive /dev/hdc --blank_full
|
|
Format a DVD-RW to avoid need for blanking before re-use:
|
|
test/libburner --drive /dev/hdc --format_overwrite
|
|
Burn two audio tracks (to CD only):
|
|
lame --decode -t /path/to/track1.mp3 track1.cd
|
|
test/dewav /path/to/track2.wav -o track2.cd
|
|
test/libburner --drive /dev/hdc --audio track1.cd track2.cd
|
|
Burn a compressed afio archive on-the-fly:
|
|
( cd my_directory ; find . -print | afio -oZ - ) | \
|
|
test/libburner --drive /dev/hdc -
|
|
To be read from *not mounted* media via: afio -tvZ /dev/hdc
|
|
</pre>
|
|
libburner has two companions, telltoc and dewav, which help to perform some
|
|
peripheral tasks of burning.
|
|
|
|
telltoc prints a table of content (sessions, tracks and leadouts), it tells
|
|
about type and state of media, and also is able to provide the necessary
|
|
multi-session information for program mkisofs option -C. Especially helpful
|
|
are its predictions with "Write multi" and "Write modes" where availability
|
|
of "TAO" indicates that tracks of unpredicted length can be written.
|
|
See: test/telltoc --help.
|
|
|
|
dewav extracts raw byte-swapped audio data from files of format .wav (MS WAVE)
|
|
or .au (SUN Audio). See example in libburner --help.
|
|
|
|
@subsection libburner-source Sourceode of libburner
|
|
|
|
Click on blue names of functions, structures, variables, etc in oder to
|
|
get to the according specs of libburn API or libburner sourcecode.
|
|
|
|
@include libburner.c
|
|
*/
|