From dbe20a2883f3183d0e73de08080258ee99c8f706 Mon Sep 17 00:00:00 2001 From: Thomas Schmitt Date: Wed, 13 Dec 2006 19:30:31 +0000 Subject: [PATCH] Detailed man page for cdrskin. Based on work of George Danchev. --- libburn/trunk/cdrskin/cdrskin.1 | 569 ++++++++++++++++++++++++++++++++ 1 file changed, 569 insertions(+) create mode 100644 libburn/trunk/cdrskin/cdrskin.1 diff --git a/libburn/trunk/cdrskin/cdrskin.1 b/libburn/trunk/cdrskin/cdrskin.1 new file mode 100644 index 00000000..027e591f --- /dev/null +++ b/libburn/trunk/cdrskin/cdrskin.1 @@ -0,0 +1,569 @@ +.\" Hey, EMACS: -*- nroff -*- +.\" First parameter, NAME, should be all caps +.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection +.\" other parameters are allowed: see man(7), man(1) +.TH CDRSKIN 1 "December 13, 2006" +.\" Please adjust this date whenever revising the manpage. +.\" +.\" Some roff macros, for reference: +.\" .nh disable hyphenation +.\" .hy enable hyphenation +.\" .ad l left justify +.\" .ad b justify to both left and right margins +.\" .nf disable filling +.\" .fi enable filling +.\" .br insert line break +.\" .sp insert n+1 empty lines +.\" for manpage-specific macros, see man(7) +.SH NAME +cdrskin \- burns preformatted data to CD-R or CD-RW via libburn. +.SH SYNOPSIS +.B cdrskin +.RI [ options | track_source_addresses ] +.br +.SH DESCRIPTION +.PP +.\" TeX users may be more comfortable with the \fB\fP and +.\" \fI\fP escape sequences to invode bold face and italics, +.\" respectively. +.PP +\fBcdrskin\fP is a program that provides some of cdrecord's options in a compatible way. +You don't need to be root to use it. +.PP +.B Overview of features: +.br +Blanking of CD-RW. +.br +Burning of data or audio tracks to CD. +.br +Either in versatile Track at Once mode (TAO) +.br +or in Session at Once mode for seamless tracks. +.br +Multi session (follow-up sessions in TAO only). +.br +Bus scan, burnfree, speed options, retrieving media info, padding, fifo. +.br +See section EXAMPLES at the end of this text. +.PP +.B Known deficiencies: +.br +No DVD support yet. +.PP +.B Data recording model: +.br +The input-output entities which get processed are called "tracks". Each track +is depicted by one input argument, which may either be "-" for standard input +or the address of a readable file. If no write mode is given explicitely then +one will be choosen which matches the peculiarities of track input and the +state of the output media. +.PP +There can be more than one track burned by a single run of cdrskin. +CDs can be kept appendable so that further tracks can +be witten to them in subsequent runs of cdrskin (see option -multi). +Info about the addresses of burned tracks is kept in a table of +content (TOC) on media and can be retrieved via cdrskin option -toc. +These informations are also used by the operating systems' CD-ROM read drivers. +.br +.SH OPTIONS +.TP +.BI \-\-help +Show non-cdrecord compatible options. +.TP +.BI \-help +Show cdrecord compatible options. +.TP +.BI \-version +Print cdrskin id line, compatibility lure line, libburn version, cdrskin +version, version timestamp, build timestamp (if available), and then exit. +.PP +Alphabetical list of options which are intended to be compatible with +original cdrecord by Joerg Schilling: +.TP +.BI \-atip +Retrieve some info about media state. With CD-RW print "Is erasable". +.TP +.BI \-audio +Announces that the subsequent tracks are to be burned as audio. +The input is supposed to be uncompressed headerless PCM, 44100 Hz, 16 bit, +stereo. For little-endian byte order (which is usual on PCs) use option +-swab. Input files with suffix .wav are examined wether they have a header +in MS-WAVE format confirming those parameters and eventually raw audio data +get extracted automatically. Same is done for suffix .au and SUN Audio. +.TP +.BI blank= type +Blank a CD-RW disc. This is combinable with burning in the same run of cdrskin. +The type given with blank= selects the particular behavior: +.RS +.TP +help +Print this list of blanking types. +.TP +all +Blank the entire disk. +.TP +fast +Minimally blank the entire disk. +.RE +.TP +.BI \-checkdrive +Retrieve some info about the addressed drive. +Exits with non-zero value if the drive cannot be found and opened. +.TP +.BI \-dao +Alias for option -sao. Write disk in Session at Once mode. +.TP +.BI \-data +Subsequent tracks are data tracks. This option is default and only needed +to mark the end of the range of an eventual option -audio. +.TP +.BI dev= target +Sets the (pseudo-)SCSI address of the drive to use. Valid are at least the +X,Y,Z addresses listed with option -scanbus, ATA:X,Y,Z addresses listed with +options dev=ATA -scanbus, the device file addresses listed with +option --devices , volatile libburn drive numbers (numbering starts at "0"). +Other device file addresses which lead to the same drive might work too. +.br +If no dev= is given, volatile address "dev=0" is assumed. That is the first +drive found being available. Better avoid this on multi-drive systems. +.br +The special target "help" lists hints about available addressing formats. +Be aware that option --old_pseudo_scsi_adr changes the meaning of +Bus,Target,Lun addresses. +.TP +.BI driveropts= opt +Set "driveropts=burnfree" to enable the drive's eventual protection mechanism +against temporary lack of input data (i.e. buffer underrun). It is not an error +to do this with a drive that has no such capabilities. +.TP +.BI \-dummy +Try to perform the drive operations without actually affecting the inserted +media. There is no guarantee that this will work with a particular drive +in a particular write mode. Blanking is prevented reliably, though. +.TP +.BI \-eject +Eject the disk after work is done. +.TP +.BI \-force +Assume that the user knows better in situations when cdrskin or libburn are +insecure about drive or media state. This includes the attempt to blank +media which are classified as unknown or unsuitable, and the attempt to use +write modes which libburn believes they are not supported by the drive. +.br +Use this only when in urgent need. +.TP +.BI fs= size +Set the fifo size to the given value. The value may have appended letters which +multiply the preceding number: +.br +"k" or "K" = 1024 , "m" or "M" = 1024k , "g" or "G" = 1024m , "s" or "S" = 2048 +.br +Set size to 0 in order to disable the fifo (default is "4m"). +.br +The fifo buffers an eventual temporary surplus of input data in order to +provide the drive with a steady stream during times of temporary lack of input. +The larger the fifo, the longer periods of poor input can be compensated. +But a large fifo needs substantial time to fill up if not curbed via +option fifo_start_at=size. +.TP +.BI gracetime= seconds +Set the grace time before starting to write. (Default is 0) +.TP +.BI \-msinfo +Retrieve multi-session info for preparing a follow-up session by option -C +of programs mkisofs or genisoimage. Print result to standard output. +This option redirects to stderr all +message output besides its own result string, which consists of two numbers. +The result string shall be used as argument of option -C with said programs. +It gives the start address of the most recent session and the predicted +start address of the next session to be appended. The string is empty if +the most recent session was not written with option -multi. +.TP +.BI \-multi +This option keeps the CD appendable after the current session has been written. +Without it the disk gets closed and may not be written any more - unless it +is a CD-RW and gets blanked which causes loss of its content. +.br +The following sessions can only be written in -tao mode. +.br +In order to have all filesystem content accessible, the eventual ISO-9660 +filesystem of a follow-up +session needs to be prepared in a special way by the filesystem formatter +program. mkisofs and genisoimage expect particular info about the situation +which can be retrieved by cdrskin option -msinfo. +.br +To retrieve an archive file which was written as follow-up session, +you may use option -toc to learn about the "lba" of the desired track number. +.TP +.BI \-nopad +Do not add trailing zeros to the data stream. Nevertheless, since there seems +to be no use for audio tracks with incomplete last sector, this option applies +only to data tracks. There it is default. +.TP +.BI \-pad +Add 30 kB of trailing zeros to each data track. (This is not sufficient to +avoid problems with various CD-ROM read drivers.) +.TP +.BI padsize= size +Add the given amount of trailing zeros to the next data track. This option +gets reset to padsize=0 after that next track is written. It may be set +again before the next track argument. About size specifiers, see option fs=. +.TP +.BI \-raw96r +Write disk in RAW/RAW96R mode. This mode allows to put more payload bytes +into a CD sector but obviously at the cost of error correction. It can only +be used for tracks of fixely predicted size. Some drives allow this mode but +then behave strange or even go bad for the next few attempts to burn a CD. +One should use it only if inavoidable. +.TP +.BI \-sao +Write disk in Session At Once mode. This mode is able to put several audio +tracks on CD without producing audible gaps between them. It can only +be used for tracks of fixely predicted size. This implies that track arguments +which depict stdin or named pipes need to be preceeded by option tsize= or +by option tao_to_sao_tsize=. +.TP +.BI \-scanbus +Scan the system for drives. On Linux the drives at /dev/s* and at /dev/hd* +are to be scanned by two separate runs. One without dev= for /dev/s* and +one with dev=ATA for /dev/hd* devices. (Option --drives lists all available +drives in a single run.) +.br +Drives which are busy or which offer no rw-permission to the user of cdrskin +are not listed. Busy drives get reported in form of warning messages. +.br +The useful fields in a result line are: +.br +Bus,Target,Lun Number) 'Vendor' 'Mode' 'Revision' +.TP +.BI speed= number +Set speed of drive. With data CD, 1x speed corresponds to a throughput of +150 kB/s. It is not an error to set a speed higher than is suitable for drive +and media. One should stay within a realistic speed range, though. +.TP +.BI \-swab +Announce that raw audio data input of subsequent tracks is byte swapped versus +the expectations of cdrecord. This option is suitable for audio where +the least significant byte of a 16 bit word is first (little-endian, Intel). +Most raw audio data on PC systems are available in this byte order. +Less guesswork is needed if track sources are in format MS-WAVE in a file with +suffix ".wav". +.TP +.BI \-tao +Write disk in Track At Once (TAO) mode. This mode can be used with track +sources of unpredictable size, like standard input or named pipes. It is +also the only mode that can be used for writing to appendable CD which +already hold data. +.TP +.BI \-toc +Print the table of content (TOC) which describes the tracks recorded on CD. +The output contains all info from option -atip plus lines which begin with +"track: " followed by the track number, the word "lba:" and a number which +gives the start address of the track. Addresses are counted in CD sectors which +with data tracks hold 2048 bytes each. +.RS +.TP +Example. Retrieve an afio archive from track number 2: +.br +tracknumber=2 +.br +lba=$(cdrskin dev=/dev/cdrom -toc 2>&1 | \\ +.br +grep '^track: [ 0-9][0-9]' | \\ +.br +tail +"$tracknumber" | head -1 | \\ +.br +awk '{ print $4}' ) +.br +dd if=/dev/cdrom bs=2048 skip="$lba" | \\ +.br +afio -t - | less +.RE +.TP +.BI tsize= size +Announces the exact size of the next track source. This is necessary with any +write mode other than -tao if the track source is not a regular disk file, but +e.g. "-" (standard input) or a named pipe. +About size specifiers, see option fs=. +.br +If the track source does not deliver the predicted amount of bytes, the +remainder of the track is padded with zeros. This is not considered an error. +If on the other hand the track source delivers more than the announced bytes +then the track on CD gets truncated to the predicted size and cdrskin exits +with non-zero value. +.TP +.BI \-v +Increment verbose level by one. Startlevel is 0 with only few messages. +Level 1 prints progress report with long running operations and also causes +some extra lines to be put out with info retrieval options. +Level 2 additionally reports about option settings derived from arguments or +startup files. Level 3 is for debugging and useful mainly in conjunction with +somebody who had a look into the program sourcecode. +.PP +Alphabetical list of options which are genuine to cdrskin and intended for +normal use: +.TP +.BI \--any_track +Allow source_addresses to begin with "-" (plus further characters) or to +contain a "=" character. +By default such arguments are seen as misspelled options. It is nevertheless +not possible to use one of the options listed with --list_ignored_options. +.TP +.BI \--allow_setuid +Disable the loud warning about insecure discrepance between login user and +effective user which indicates application of chmod u+s to the program binary. +One should not do this chmod u+s , but it is an old cdrecord tradition. +.TP +.BI \--demand_a_drive +Exit with a nonzero value if no drive can be found during a bus scan. +.TP +.BI \--devices +List the device file addresses of all accessible drives. In order to get +listed a drive has to offer rw-permission for the cdrskin user and it may +not be busy. +Busy drives are reported as "SORRY" messages of standard error. +.br +Each available drive gets listed by a line containing the following fields: +.br +Number dev='Devicefile' rw-Permissions : 'Vendor' 'Model' +.br +Number and Devicefile can both be used with option dev=, but number is +volatile (numbering changes if drives become busy). +Normal users might not see all drives unless the superuser enabled access +by chmod o+rw +after using cdrskin --devices to get an overview of the situation. +That's why current rw-Permissions are listed. +.TP +.BI fifo_start_at= size +Do not wait for full fifo but start burning as soon as the given number +of bytes is read. This option may be helpful to bring the average throughput +near to the maximum throughput of a drive. A large fs= and a small +fifo_start_at= combine a quick burn start and a large savings buffer to +compensate for temporary lack of input data. At the beginning of burning, +the software protection against buffer underun is as weak as the size of +fifo_start_at= . So it is best if the drive offers hardware protection which +has to be enabled by driveropts=burnfree. +.TP +.BI \--no_rc +Only if used as first command line argument this option prevents reading and +interpretation of eventual startup files. See section FILES below. +.TP +.BI \--list_ignored_options +List all ignored cdrecord options. The --options cannot be used as addresses +of track sources. No track source address may begin with a text equal to an +option which ends by "=". +.TP +.BI \--single_track +Accept only the last argument of the command line as track source address. +.PP +Alphabetical list of options which are only intended for very special +situations and not for normal use: +.TP +.BI \--abort_handler +Establish default signal handling not to leave a drive in busy state +but rather to shut it down and to wait until it has ended the final operations. +This option is only needed for revoking eventual --ignore_signals or +--no_abort_handler. +.TP +.BI dev_translation= +Set input address alias. This was necessary before cdrskin-0.2.4 to manually +translate cdrecord addresses into cdrskin addresses. +.br + is a single character which may not occur in the address string +. is an address as expected to be given by the user via option +dev=. is the address to be used instead whenever is given. +More than one translation instruction can be given in one cdrskin run. +.br +E.g.: dev_translation=+ATA:1,0,0+/dev/sg1 dev_translation=+ATA:1,1,0+/dev/sg2 +.TP +.BI \--drive_abort_on_busy +Linux specific: Abort process if a busy drive is encountered. +.TP +.BI \--drive_blocking +Linux specific: Try to wait for a busy drive to become free. +This is not guaranteed to work with all drivers. Some need nonblocking i/o. +.TP +.BI \--drive_not_exclusive +Linux specific: Do not ask the operating system to prevent opening busy drives. +Wether this leads to senseful behavior depends on operating system and kernel. +.TP +.BI \--drive_scsi_exclusive +Linux specific: +Try to exclusively reserve device files /dev/srN, /dev/scdM, /dev/stK of drive. +this would be helpful to protect against collisions with program growisofs. +Regrettably on Linux kernel 2.4 with ide-scsi emulation this seems not to +work. Wether it becomes helpful with new Linux systems has to be evaluated. +.TP +.BI \--fifo_disable +Disable fifo despite any fs=. +.TP +.BI \--fifo_per_track +Use a separate fifo for each track. +.TP +.BI grab_drive_and_wait= seconds +Open the addressed drive, wait the given number of seconds, release the drive, +and do normal work as indicated by the other options used. This option helps +to explore the program behavior when faced with busy drives. Just start a +second cdrskin with option --devices while grab_drive_and_wait= is still +active. +.TP +.BI \--ignore_signals +Try to ignore any signals rather than to abort the program. This is not a +very good idea. You might end up waiting a very long time for cdrskin +to finish. +.TP +.BI \--no_abort_handler +On signals exit even if the drive is in busy state. This is not a very good +idea. You might end up with a stuck drive that refuses to hand out the media. +.TP +.BI \--no_blank_appendable +Refuse to blank appendable CD-RW. This is a feature that was once builtin with +libburn. No information available for what use case it was needed. +.TP +.BI \--no_convert_fs_adr +Do only literal translations of dev=. This prevents cdrskin from test-opening +device files in order to find one that matches the given dev= specifier. +.br +Partly Linux specific: +Such opening is needed for Bus,Target,Lun addresses unless option +--old_pseudo_scsi_adr is given. It is also needed to resolve device file +addresses which are not listed with cdrskin --devices but nevertheless point +to a usable drive. (Like /dev/sr0 using the same SCSI address as /dev/sg0.) +.TP +.BI \--old_pseudo_scsi_adr +Linux specific: +Use and report literal Bus,Target,Lun addresses rather than real SCSI and +pseudo ATA addresses. This method is outdated and was never compatible with +original cdrecord. +.TP +.BI tao_to_sao_tsize= size +Set an exact fixed size for the next track to be in effect only if the track +source cannot deliver a size prediction and no tsize= was specified. +This is the fallback from bad old times when cdrskin was unable to burn +in mode -tao. +.br +.SH EXAMPLES +.SS +.B Get an overview of drives: +.br +cdrskin -scanbus +.br +cdrskin dev=ATA -scanbus +.br +cdrskin --devices +.SS +.B Get info about a particular drive or loaded media: +.br +cdrskin dev=0,1,0 -checkdrive +.br +cdrskin dev=ATA:1,0,0 -atip +.br +cdrskin dev=/dev/hdc -toc +.SS +.B Make used CD-RW writable again: +.br +cdrskin -v dev=/dev/sg1 blank=all -eject +.br +cdrskin -v dev=/dev/dvd blank=fast -eject +.SS +.B Write ISO-9660 filesystem image: +.br +cdrskin -v dev=/dev/hdc speed=12 fs=8m \\ +.br +driveropts=burnfree -sao -eject \\ +.br +padsize=300k my_image.iso +.SS +.B Write compressed afio archive on-the-fly: +.br +find . | afio -oZ - | \\ +.br +cdrskin -v dev=0,1,0 fs=32m speed=8 driveropts=burnfree \\ +.br +padsize=300k -tao - +.SS +.B Write several sessions to the same CD +.br +cdrskin dev=/dev/hdc padsize=300k -multi 1.iso +.br +cdrskin dev=/dev/hdc padsize=300k -multi -tao 2.afio +.br +cdrskin dev=/dev/hdc padsize=300k -multi -tao 3.afio +.br +cdrskin dev=/dev/hdc padsize=300k -tao 4.afio +.SS +.B Get the multi-session info for option -C of program mkisofs +.br +c_values=$(cdrskin dev=/dev/sr0 -msinfo 2>/dev/null) +.br +mkisofs ... -C "$c_values" ... +.SS +.B Write audio tracks: +.br +cdrskin -v dev=ATA:1,0,0 speed=48 \\ +.br +driveropts=burnfree -sao \\ +.br +track1.wav track2.au -audio -swab track3.raw +.br +.SH FILES +If not --no_rc is given as the first argument then cdrskin attempts on +startup to read the arguments from the following files: +.PP +.br +.B /etc/default/cdrskin +.br +.B /etc/opt/cdrskin/rc +.br +.B /etc/cdrskin/cdrskin.conf +.br +.B $HOME/.cdrskinrc +.br +.PP +The files are read in the sequence given above, but none of them is +required for cdrskin to function properly. Each readable line is treated +as one single argument. No extra blanks. +A first character '#' marks a comment, empty lines are ignored. +.SS +.B Example content of a startup file: +.br +# This is the default device +.br +dev=0,1,0 +.br +# To accomodate to remnant cdrskin-0.2.2 addresses +.br +dev_translation=+1,0,0+0,1,0 +.br +# Some more options +.br +fifo_start_at=0 +.br +fs=16m +.br +.SH SEE ALSO +.TP +Formatting track input for cdrskin: +.br +.BR mkisofs (8), +.BR genisoimage (8), +.BR afio (1), +.BR star (1) +.br +.TP +Other CD burn programs: +.br +.BR cdrecord (1), +.BR wodim (1) +.br +.TP +For DVD burning: +.br +.BR growisofs (1) +.br +.SH AUTHOR +cdrskin was written by Thomas Schmitt . +.PP +This manual page was written by George Danchev and +Thomas Schmitt, for the Debian project and for all others. +