libburn  1.1.8
comments
Go to the documentation of this file.
00001 /**
00002    @author Mario Danic, Thomas Schmitt
00003 
00004    @mainpage Libburn Documentation Index
00005 
00006    @section intro Introduction
00007 
00008 Libburnia is an open-source project for reading, mastering and writing
00009 optical discs. This page is about its capability to handle optical media.
00010 For now this means CD-R, CD-RW, DVD-RAM, DVD+RW, DVD+R, DVD+R/DL, DVD-RW,
00011 DVD-R, DVD-R/DL, BD-R, BD-RE.
00012 
00013 Our scope is currently Linux 2.4 and 2.6, or FreeBSD, or Solaris . For ports
00014 to other systems we would need : login on a development machine resp.
00015 an OS ithat is installable on an AMD 64-bit PC, advise from a system person
00016 about the equivalent of Linux sg or FreeBSD CAM, volunteers for testing of
00017 realistic use cases.
00018 
00019 libburn is the library by which preformatted data get onto optical media.
00020 Its code is independent of cdrecord. Its DVD capabilities are learned from
00021 studying the code of dvd+rw-tools and MMC-5 specs. No code but only the pure
00022 SCSI knowledge has been taken from dvd+rw-tools, though.
00023 
00024 cdrskin is a limited cdrecord compatibility wrapper for libburn.
00025 cdrecord is a powerful GPL'ed burn program included in Joerg Schilling's
00026 cdrtools. cdrskin strives to be a second source for the services traditionally
00027 provided by cdrecord. Additionally it provides libburn's DVD/BD capabilities,
00028 where only -sao is compatible with cdrecord.
00029 cdrskin does not contain any bytes copied from cdrecord's sources.
00030 Many bytes have been copied from the message output of cdrecord runs, though.
00031 See cdrskin/README for more.
00032 
00033 The burn API example of libburn is named test/libburner.c . The API for media
00034 information inquiry is demonstrated in test/telltoc.c .
00035 Explore these examples if you look for inspiration.
00036 
00037 SONAME:
00038 libburn.so.4 (since 0.3.4, March 2007),
00039 
00040 
00041    @section using Using libburn
00042 
00043 Our build system is based on autotools.
00044 User experience tells us that you will need at least autotools version 1.7.
00045 
00046 To build libburn and its companion applications go into its toplevel directory
00047 and execute
00048 
00049 -  ./bootstrap  (needed if you downloaded from SVN)
00050 
00051 -  ./configure
00052 
00053 -  make
00054 
00055 To make the libraries accessible for running resp. developing applications 
00056 
00057 -  make install
00058 
00059 
00060 @section libburner Libburner
00061 
00062 libburner is a minimal demo application for the library libburn 
00063 (see: libburn/libburn.h) as provided on  http://libburnia-project.org .
00064 It can list the available devices, can burn to recordable CD, DVD, or BD,
00065 can blank a CD-RW or DVD-RW, and can format unformatted DVD-RW, BD-R, or BD-RE. 
00066 
00067 It's main purpose, nevertheless, is to show you how to use libburn and also
00068 to serve the libburnia team as reference application. libburner does indeed
00069 define the standard way how above gestures can be implemented and stay upward
00070 compatible for a good while.
00071 
00072    @subsection libburner-help Libburner --help
00073 <pre>
00074 Usage: test/libburner
00075        [--drive address|driveno|"-"]  [--audio]
00076        [--blank_fast|--blank_full|--format]  [--try_to_simulate]
00077        [--multi]  [one or more imagefiles|"-"]
00078 Examples
00079 A bus scan (needs rw-permissions to see a drive):
00080   test/libburner --drive -
00081 Burn a file to drive chosen by number, leave appendable:
00082   test/libburner --drive 0 --multi my_image_file
00083 Burn a file to drive chosen by persistent address, close:
00084   test/libburner --drive /dev/hdc my_image_file
00085 Blank a used CD-RW (is combinable with burning in one run):
00086   test/libburner --drive /dev/hdc --blank_fast
00087 Blank a used DVD-RW (is combinable with burning in one run):
00088   test/libburner --drive /dev/hdc --blank_full
00089 Format a DVD-RW, BD-RE or BD-R:
00090   test/libburner --drive /dev/hdc --format
00091 Burn two audio tracks (to CD only):
00092   lame --decode -t /path/to/track1.mp3 track1.cd
00093   test/dewav /path/to/track2.wav -o track2.cd
00094   test/libburner --drive /dev/hdc --audio track1.cd track2.cd
00095 Burn a compressed afio archive on-the-fly:
00096   ( cd my_directory ; find . -print | afio -oZ - ) | \
00097   test/libburner --drive /dev/hdc -
00098 To be read from *not mounted* media via: afio -tvZ /dev/hdc
00099 </pre>
00100 libburner has two companions, telltoc and dewav, which help to perform some
00101 peripheral tasks of burning.
00102 
00103 telltoc prints a table of content (sessions, tracks and leadouts), it tells
00104 about type and state of media, and also is able to provide the necessary
00105 multi-session information for program mkisofs option -C. Especially helpful
00106 are its predictions with "Write multi" and "Write modes" where availability
00107 of "TAO" indicates that tracks of unpredicted length can be written.
00108 See: test/telltoc --help.
00109 
00110 dewav extracts raw byte-swapped audio data from files of format .wav (MS WAVE)
00111 or .au (SUN Audio). See example in libburner --help.
00112 
00113    @subsection libburner-source Sourceode of libburner
00114 
00115 Click on blue names of functions, structures, variables, etc in oder to
00116 get to the according specs of libburn API or libburner sourcecode.
00117  
00118 @include libburner.c
00119 */