Libburn.md

@@ -0,0 +1,60 @@
+libburn is a library by which preformatted data get onto optical media:
+CD, DVD, BD (Blu-Ray).
+On Linux it uses either `/dev/sgN` (on kernel 2.4 with `ide-scsi`, or optional
+with concurrent operation of multiple drives) or `/dev/srM` (kernel 2.6 and
+newer), `/dev/hdX` ( on kernel 2.6).
+On FreeBSD it uses `/dev/cdN`, eventually via atapicam.
+On Solaris addresses look like `/dev/rdsk/cXtYd0s2`.
+
+libburn also offers a facility for reading data blocks from its drives
+without using the normal block device i/o, which has its advantages and
+disadvantages. It seems appropriate, nevertheless, to do writing
+and reading via the same channel. On several Linux systems, the block device
+driver needs reloading of the drive tray in order to make available freshly
+written data. The libburn read function does not need such a reload.
+
+Audio CD can be written and read.
+
+The code of libburn is independent of cdrecord. Its CD SAO capabilities
+are inherited from [old libburn](http://icculus.org/burn).
+Its CD TAO capabilities are learned from MMC-1.
+Its DVD and BD 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.
+
+The underlying knowledge about drive control and media types is collected in
+[doc/cookbook.txt](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/doc/cookbook.txt).
+But it should by no means be necessary to study this in order to understand
+the API and the usage of libburn.
+
+-------------
+
+For an overview of the drive/media models see "General information paragraphs"
+in [man cdrskin](http://scdbackup.sourceforge.net/man_1_cdrskin.html)
+The API of libburn is documented in
+[libburn/libburn.h](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/libburn/libburn.h).
+
+Small demo applications named
+[libburner](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/test/libburner.c)
+and
+[telltoc](https://dev.lovelyhq.com/libburnia/libburn/raw/HEAD/test/telltoc.c)
+show how to burn and how to inquire drive and loaded medium.
+
+On base of libburn there is a cdrecord emulation named [cdrskin](Cdrskin)
+which is integral part of the libburn git repo and its releases.
+
+GUI application [xfburn](http://goodies.xfce.org/projects/applications/xfburn)
+makes use of libburn.
+
+libburn is also used by [libisoburn](Libisoburn) and its application
+[xorriso](Xorriso).
+
+libburn shares an interface object definition (`struct burn_source`)
+with [libisofs](Libisofs) by
+which a filesystem image stream can be received and written to media.
+libisoburn uses the read function of
+libburn to create a data input object for libisofs.
+
+It is advised to use the most recent release version as published on
+[release page](Releases).
+