00001 /** 00002 @author Mario Danic, Thomas Schmitt 00003 00004 @mainpage Libburnia Documentation Index 00005 00006 @section intro Introduction 00007 00008 Libburnia is an open-source project for reading, mastering and writing 00009 optical discs. 00010 For now this means CD-R, CD-RW, DVD-RAM, DVD+RW, DVD+R, DVD+R/DL, DVD-RW, 00011 DVD-R, BD-RE. 00012 00013 Not supported yet are DVD-R/DL, HD-DVD, BD-R (blue ray). Testers for 00014 DVD-R/DL are wanted, though. BD-R programming efforts would be made 00015 if an interested tester contacts us. 00016 00017 The project comprises of several more or less interdependent parts which 00018 together strive to be a usable foundation for application development. 00019 These are libraries, language bindings, and middleware binaries which emulate 00020 classical (and valuable) Linux tools. 00021 00022 Our scope is currently Linux 2.4 and 2.6 only. For ports to other systems 00023 we would need : login on a development machine resp. a live OS on CD or DVD, 00024 advise from a system person about the equivalent of Linux sg or FreeBSD CAM, 00025 volunteers for testing of realistic use cases. 00026 00027 We have a well tested code base for burning data and audio CDs and many DVD 00028 types. The burn API is quite comprehensively documented and can be used to 00029 build a presentable application. 00030 We have a functional binary which emulates the core use cases of cdrecord in 00031 order to prove that usability, and in order to allow you to explore libburn's 00032 scope by help of existing cdrecord frontends. 00033 00034 ISO 9660 filesystems with Rock Ridge and Joliet extensions can be created 00035 and manipulated quite freely. This capability together with our burn capability 00036 makes possible a single binary application which covers all steps of image 00037 composition, updating and writing. Quite unique in the Linux world. 00038 00039 @subsection components The project components (list subject to growth, hopefully): 00040 00041 - libburn is the library by which preformatted data get onto optical media. 00042 It uses either /dev/sgN (e.g. on kernel 2.4 with ide-scsi) or 00043 /dev/srM or /dev/hdX (e.g. on kernel 2.6). 00044 libburn is the foundation of our cdrecord emulation. Its code is 00045 independent of cdrecord. Its DVD capabilities are learned from 00046 studying the code of dvd+rw-tools and MMC-5 specs. No code but only 00047 the pure SCSI knowledge has been taken from dvd+rw-tools, though. 00048 00049 - libisofs is the library to pack up hard disk files and directories into a 00050 ISO 9660 disk image. This may then be brought to CD via libburn. 00051 libisofs is to be the foundation of our upcoming mkisofs emulation. 00052 00053 - libisoburn is an add-on to libburn and libisofs which coordinates both and 00054 also allows to grow ISO-9660 filesystem images on multi-session 00055 media as well as on overwriteable media via the same API. 00056 All media peculiarities are handled automatically. 00057 00058 - cdrskin is a limited cdrecord compatibility wrapper for libburn. 00059 cdrecord is a powerful GPL'ed burn program included in Joerg 00060 Schilling's cdrtools. cdrskin strives to be a second source for 00061 the services traditionally provided by cdrecord. Additionally it 00062 provides libburn's DVD/BD capabilities, where only -sao is 00063 compatible with cdrecord. 00064 cdrskin does not contain any bytes copied from cdrecord's sources. 00065 Many bytes have been copied from the message output of cdrecord 00066 runs, though. 00067 See cdrskin/README for more. 00068 00069 - xorriso is an application of all three libraries which creates, loads, 00070 manipulates and writes ISO 9660 filesystem images with 00071 Rock Ridge extensions. Manipulation is not only adding or 00072 overwriting of files but also deletion, renaming, and attribute 00073 changing. An incremental backup feature is provided. 00074 See xorriso/README for more 00075 00076 - "test" is a collection of application gestures and examples given by the 00077 authors of the library features. The burn API example of libburn 00078 is named test/libburner.c . The API for media information inquiry is 00079 demonstrated in test/telltoc.c . 00080 Explore these examples if you look for inspiration. 00081 00082 We strive to be a responsive upstream. 00083 00084 Our libraries are committed to maintain older feature sets in newer versions. 00085 This applies to source code headers (API) as well as to linkable objects (ABI). 00086 The only exception from this rule is about non-release versions x.y.*[13579] 00087 which are allowed to introduce new features, change those new features in 00088 any way and even may revoke such new features before the next release of 00089 x.y.*[02468]. As soon as it is released, a feature is promised to persist. 00090 00091 SONAMES: 00092 libburn.so.4 (since 0.3.4, March 2007), 00093 libisofs.so.6 (since 0.6.2, February 2008), 00094 libisoburn.so.1 (since 0.1.0, February 2008). 00095 00096 00097 @section using Using the libraries 00098 00099 Our build system is based on autotools. 00100 User experience tells us that you will need at least autotools version 1.7. 00101 00102 To build libburn and its subprojects it should be sufficient to go into 00103 its toplevel directory and execute 00104 00105 - ./bootstrap (needed if you downloaded from SVN) 00106 00107 - ./configure 00108 00109 - make 00110 00111 To make the libraries accessible for running resp. developing applications 00112 00113 - make install 00114 00115 Both libraries are written in C language and get built by autotools. 00116 Thus we expect them to be useable by a wide range of Linux-implemented 00117 languages and development tools. 00118 00119 00120 @section libburner Libburner 00121 00122 libburner is a minimal demo application for the library libburn 00123 (see: libburn/libburn.h) as provided on http://libburnia-project.org . 00124 It can list the available devices, can blank a CD-RW or DVD-RW and 00125 can burn to recordable CD and recordable single layer DVD. 00126 00127 It's main purpose, nevertheless, is to show you how to use libburn and also 00128 to serve the libburnia team as reference application. libburner does indeed 00129 define the standard way how above three gestures can be implemented and 00130 stay upward compatible for a good while. 00131 00132 @subsection libburner-help Libburner --help 00133 <pre> 00134 Usage: test/libburner 00135 [--drive <address>|<driveno>|"-"] [--audio] 00136 [--blank_fast|--blank_full|--format_overwrite] 00137 [--try_to_simulate] 00138 [--multi] [<one or more imagefiles>|"-"] 00139 Examples 00140 A bus scan (needs rw-permissions to see a drive): 00141 test/libburner --drive - 00142 Burn a file to drive chosen by number, leave appendable: 00143 test/libburner --drive 0 --multi my_image_file 00144 Burn a file to drive chosen by persistent address, close: 00145 test/libburner --drive /dev/hdc my_image_file 00146 Blank a used CD-RW (is combinable with burning in one run): 00147 test/libburner --drive /dev/hdc --blank_fast 00148 Blank a used DVD-RW (is combinable with burning in one run): 00149 test/libburner --drive /dev/hdc --blank_full 00150 Format a DVD-RW to avoid need for blanking before re-use: 00151 test/libburner --drive /dev/hdc --format_overwrite 00152 Burn two audio tracks (to CD only): 00153 lame --decode -t /path/to/track1.mp3 track1.cd 00154 test/dewav /path/to/track2.wav -o track2.cd 00155 test/libburner --drive /dev/hdc --audio track1.cd track2.cd 00156 Burn a compressed afio archive on-the-fly: 00157 ( cd my_directory ; find . -print | afio -oZ - ) | \ 00158 test/libburner --drive /dev/hdc - 00159 To be read from *not mounted* media via: afio -tvZ /dev/hdc 00160 </pre> 00161 libburner has two companions, telltoc and dewav, which help to perform some 00162 peripheral tasks of burning. 00163 00164 telltoc prints a table of content (sessions, tracks and leadouts), it tells 00165 about type and state of media, and also is able to provide the necessary 00166 multi-session information for program mkisofs option -C. Especially helpful 00167 are its predictions with "Write multi" and "Write modes" where availability 00168 of "TAO" indicates that tracks of unpredicted length can be written. 00169 See: test/telltoc --help. 00170 00171 dewav extracts raw byte-swapped audio data from files of format .wav (MS WAVE) 00172 or .au (SUN Audio). See example in libburner --help. 00173 00174 @subsection libburner-source Sourceode of libburner 00175 00176 Click on blue names of functions, structures, variables, etc in oder to 00177 get to the according specs of libburn API or libburner sourcecode. 00178 00179 @include libburner.c 00180 */