diff options
Diffstat (limited to 'readom/readom.1')
| -rw-r--r-- | readom/readom.1 | 497 |
1 files changed, 497 insertions, 0 deletions
diff --git a/readom/readom.1 b/readom/readom.1 new file mode 100644 index 0000000..3bdc47b --- /dev/null +++ b/readom/readom.1 @@ -0,0 +1,497 @@ +.\" @(#)readom.1 1.23 06/01/12 Copyright 1996-2006 J. Schilling +.\" +.\" Modified version of readcd.1 by J. Schilling, 11/2006 +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License version 2 +.\" as published by the Free Software Foundation. +.\" +.\" The GNU General Public License's references to "object code" +.\" and "executables" are to be interpreted as the output of any +.\" document formatting or typesetting system, including +.\" intermediate and printed output. +.\" +.\" This manual is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License along with +.\" this program; see the file COPYING. If not, write to the Free Software +.\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a +.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o +.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u +.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A +.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O +.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U +.if t .ds s \\(*b +.if t .ds S SS +.if n .ds a ae +.if n .ds o oe +.if n .ds u ue +.if n .ds s sz +.TH READOM 1 "Version 2.0" "J\*org Schilling" "Schily\'s USER COMMANDS" +.SH NAME +readom \- read or write data Compact Discs +.SH SYNOPSIS +.B readom +.BI dev= device +[ +.I options +] + +.SH DESCRIPTION +.B Readom +is used to read or write Compact Discs. +.PP +The +.I device +refers to a device location similar to the one used in the wodim command. Refer to its manpage for details. +.PP +Also note that this version of readom uses a modified libusal library which has +a different behaviour compared to the one distributed by its original author. + +.SH OPTIONS +.PP +If no options except the +.I dev= +option have been specified, +.B readom +goes into interactive mode. +Select a primary function and then follow the instructions. +.PP +.TP +.B \-version +Print version information and exit. +.TP +.BI dev= target +Sets the SCSI target for the drive, see notes above. +A typical device specification is +.BI dev= 6,0 +\&. +If a filename must be provided together with the numerical target +specification, the filename is implementation specific. +The correct filename in this case can be found in the system specific +manuals of the target operating system. +On a +.I FreeBSD +system without +.I CAM +support, you need to use the control device (e.g. +.IR /dev/rcd0.ctl ). +A correct device specification in this case may be +.BI dev= /dev/rcd0.ctl:@ +\&. +.sp +On Linux, drives connected to a parallel port adapter are mapped +to a virtual SCSI bus. Different adapters are mapped to different +targets on this virtual SCSI bus. +.sp +If no +.I dev +option is present, +.B readom +will try to get the device from the +.B CDR_DEVICE +environment. +.sp +If the argument to the +.B dev= +option does not contain the characters ',', '/', '@' or ':', +it is interpreted as an label name that may be found in the file +/etc/wodim.conf (see FILES section). +.TP +.BI timeout= # +Set the default SCSI command timeout value to +.IR # " seconds. +The default SCSI command timeout is the minimum timeout used for sending +SCSI commands. +If a SCSI command fails due to a timeout, you may try to raise the +default SCSI command timeout above the timeout value of the failed command. +If the command runs correctly with a raised command timeout, +please report the better timeout value and the corresponding command to +the author of the program. +If no +.I timeout +option is present, a default timeout of 40 seconds is used. +.TP +.BI debug= "#, " -d +Set the misc debug value to # (with debug=#) or increment +the misc debug level by one (with -d). If you specify +.I -dd, +this equals to +.BI debug= 2. +This may help to find problems while opening a driver for libusal. +as well as with sector sizes and sector types. +Using +.B \-debug +slows down the process and may be the reason for a buffer underrun. +.TP +.BR kdebug= "#, " kd= # +Tell the +.BR usal -driver +to modify the kernel debug value while SCSI commands are running. +.TP +.BR \-silent ", " \-s +Do not print out a status report for failed SCSI commands. +.TP +.B \-v +Increment the level of general verbosity by one. +This is used e.g. to display the progress of the process. +.TP +.B \-V +Increment the verbose level with respect of SCSI command transport by one. +This helps to debug problems +during the process, that occur in the CD-Recorder. +If you get incomprehensible error messages you should use this flag +to get more detailed output. +.B \-VV +will show data buffer content in addition. +Using +.B \-V +or +.B \-VV +slows down the process. +.TP +.BI f= file +Specify the filename where the output should be written or the input should +be taken from. Using '-' as filename will cause +.B readom +to use +.BR stdout " resp. " stdin . +.TP +.B \-w +Switch to write mode. If this option is not present, +.B readom +reads from the specified device. +.TP +.B \-c2scan +Scans the whole CD or the range specified by the +.BI sectors= range +for C2 errors. C2 errors are errors that are uncorrectable after the second +stage of the 24/28 + 28/32 Reed Solomon correction system at audio level +(2352 bytes sector size). If an audio CD has C2 errors, interpolation is needed +to hide the errors. If a data CD has C2 errors, these errors are in most +cases corrected by the ECC/EDC code that makes 2352 bytes out of 2048 data +bytes. The ECC/EDC code should be able to correct about 100 C2 error bytes +per sector. +.sp +If you find C2 errors you may want to reduce the speed using the +.B speed= +option as C2 errors may be a result of dynamic unbalance on the medium. +.TP +.B \-scanbus +Scan all SCSI devices on all SCSI busses and print the inquiry +strings. This option may be used to find SCSI address of the +devices on a system. +The numbers printed out as labels are computed by: +.B "bus * 100 + target +.TP +.BI sectors= range +Specify a sector range that should be read. +The range is specified by the starting sector number, a minus sign and the +ending sector number. +The end sector is not included in the list, so +.BR sectors= 0-0 +will not read anything and may be used to check for a CD in the drive. +.TP +.BR speed= # +Set the speed factor of the read or write process to #. +# is an integer, representing a multiple of the audio speed. +This is about 150 KB/s for CD-ROM and about 172 KB/s for CD-Audio. +If no +.I speed +option is present, +.B readom +will use maximum speed. +Only MMC compliant drives will benefit from this option. +The speed of non MMC drives is not changed. +.sp +Using a lower speed may increase the readability of a CD or DVD. +.TP +.BR ts= # +Set the maximum transfer size for a single SCSI command to #. +The syntax for the +.B ts= +option is the same as for wodim fs=# or sdd bs=#. +.sp +If no +.B ts= +option has been specified, +.B readom +defaults to a transfer size of 256 kB. If libusal gets lower values from the +operating system, the value is reduced to the maximum value that is possible +with the current operating system. +Sometimes, it may help to further reduce the transfer size or to enhance it, +but note that it may take a long time to find a better value by experimenting +with the +.B ts= +option. +.TP +.B \-notrunc +Do not truncate the output file when opening it. +.TP +.B \-fulltoc +Retrieve a full TOC from the current disk and print it in hex. +.TP +.B \-clone +Do a clone read. Read the CD with all sub-channel data and a full TOC. +The full TOC data will be put into a file with similar name as with the +.B f= +option but the suffix +.B .toc +added. +.TP +.B \-noerror +Do not abort if the high level error checking in +.B readom +found an uncorrectable error in the data stream. +.TP +.B \-nocorr +Switch the drive into a mode where it ignores read errors in data sectors that +are a result of uncorrectable ECC/EDC errors before reading. +If +.B readom +completes, the error recovery mode of the drive is switched back to the remembered +old mode. +.TP +.BI retries= # +Set the retry count for high level retries in +.B readom +to +.IR # . +The default is to do 128 retries which may be too much if you like to read a CD +with many unreadable sectors. +.TP +.B \-overhead +Meter the SCSI command overhead time. +This is done by executing several commands 1000 times and printing the +total time used. If you divide the displayed times by 1000, you get +the average overhead time for a single command. +.TP +.BR meshpoints= # +Print read-speed at # locations. +The purpose of this option is to create a list of read speed values suitable +for e.g. +.BR gnuplot . +The speed values are calculated assuming that 1000 bytes are one kilobyte +as documented in the SCSI standard. +The output data created for this purpose is written to +.IR stdout . +.TP +.B \-factor +Output the speed values for +.BR meshpoints= # +as factor based on +.I "single speed +of the current medium. +This only works if +.B readom +is able to determine the current medium type. +.SH EXAMPLES +.PP +For all examples below, it will be assumed that the drive is +connected to the primary SCSI bus of the machine. The SCSI target id is +set to 2. +.PP +To read the complete media from a CD-ROM writing the data to the file +.IR cdimage.raw : +.PP + readom dev=2,0 f=cdimage.raw +.PP +To read sectors from range 150 ... 10000 from a CD-ROM writing the data to the file +.IR cdimage.raw : +.PP + readom dev=2,0 sectors=150-10000 f=cdimage.raw +.PP +To write the data from the file +.I cdimage.raw +(e.g. a filesystem image from +.BR genisoimage ) +to a DVD-RAM, call: +.PP + readom dev=2,0 -w f=cdimage.raw + +.SH ENVIRONMENT +.TP +.B RSH +If the +.B RSH +environment is present, the remote connection will not be created via +.BR rcmd (3) +but by calling the program pointed to by +.BR RSH . +Use e.g. +.BR RSH= /usr/bin/ssh +to create a secure shell connection. +.sp +Note that this forces +.B wodim +to create a pipe to the +.B rsh(1) +program and disallows +.B wodim +to directly access the network socket to the remote server. +This makes it impossible to set up performance parameters and slows down +the connection compared to a +.B root +initiated +.B rcmd(3) +connection. +.TP +.B RSCSI +If the +.B RSCSI +environment is present, the remote SCSI server will not be the program +.B /opt/schily/sbin/rscsi +but the program pointed to by +.BR RSCSI . +Note that the remote SCSI server program name will be ignored if you log in +using an account that has been created with a remote SCSI server program as +login shell. +.SH SEE ALSO +.BR wodim (1), +.BR genisoimage (1), +.BR rcmd (3), +.BR ssh (1). + +.SH NOTES +.PP +Unless you want to risk getting problems, +.B readom +should be run as root. If you don't want to allow users to become root on your system, +.B readom +may safely be installed suid root. +For more information see the additional notes of your system/program +distribution or README.suidroot which is part of the Cdrkit source. +.PP +Documentation of the +.B wodim +program contains more technical details which could also apply to +.B readom. + +.SH DIAGNOSTICS +.PP +.PP +A typical error message for a SCSI command looks like: +.sp +.RS +.nf +readom: I/O error. test unit ready: scsi sendcmd: no error +CDB: 00 20 00 00 00 00 +status: 0x2 (CHECK CONDITION) +Sense Bytes: 70 00 05 00 00 00 00 0A 00 00 00 00 25 00 00 00 00 00 +Sense Key: 0x5 Illegal Request, Segment 0 +Sense Code: 0x25 Qual 0x00 (logical unit not supported) Fru 0x0 +Sense flags: Blk 0 (not valid) +cmd finished after 0.002s timeout 40s +.fi +.sp +.RE +The first line gives information about the transport of the command. +The text after the first colon gives the error text for the system call +from the view of the kernel. It usually is: +.B "I/O error +unless other problems happen. The next words contain a short description for +the SCSI command that fails. The rest of the line tells you if there were +any problems for the transport of the command over the SCSI bus. +.B "fatal error +means that it was not possible to transport the command (i.e. no device present +at the requested SCSI address). +.PP +The second line prints the SCSI command descriptor block for the failed command. +.PP +The third line gives information on the SCSI status code returned by the +command, if the transport of the command succeeds. +This is error information from the SCSI device. +.PP +The fourth line is a hex dump of the auto request sense information for the +command. +.PP +The fifth line is the error text for the sense key if available, followed +by the segment number that is only valid if the command was a +.I copy +command. If the error message is not directly related to the current command, +the text +.I deferred error +is appended. +.PP +The sixth line is the error text for the sense code and the sense qualifier if available. +If the type of the device is known, the sense data is decoded from tables +in +.IR scsierrs.c " . +The text is followed by the error value for a field replaceable unit. +.PP +The seventh line prints the block number that is related to the failed command +and text for several error flags. The block number may not be valid. +.PP +The eight line reports the timeout set up for this command and the time +that the command really needed to complete. + +.SH BUGS +.PP +The +.B readom +program described here is the Cdrkit spinoff from the original +.B readcd +application (see AUTHOR section for details). It may contain bugs not present +in the original implementation. +.PP +It is definitely less portable than the original implementation. +.PP +For platform specific bugs, see the corresponding README.platform file in the +Cdrkit documentation (eg. README.linux). + +.SH "MAILING LISTS +If you want to actively take part on the development of readom, +you may join the developer mailing list via this URL: +.sp +.B +http://alioth.debian.org/mail/?group_id=31006 +.PP +The mail address of the list is: +.B +debburn-devel@lists.alioth.debian.org + + + + +.SH AUTHOR +.nf +J\*org Schilling +Seestr. 110 +D-13353 Berlin +Germany +.fi + +.PP +This is application is a spinoff from the original implementation of readcd delivered in +the cdrtools package [1] created by Joerg Schilling, who deserves the most credits +for its success. However, he is not involved into the development +of this spinoff and therefore he shall not be made responsible for any problem +caused by it. Do not try to get support from the original author! +.PP +Additional information can be found on: +.br +https://alioth.debian.org/projects/debburn/ +.PP +If you have support questions, send them to +.PP +.B +debburn-devel@lists.alioth.debian.org +.br +.PP +If you have definitely found a bug, send a mail to this list or to +.PP +.B +submit@bugs.debian.org +.br +.PP +writing at least a short description into the Subject and "Package: cdrkit" +into the first line of the mail body. +.SH SOURCES +.PP +.br +[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de + |