| 1 |
.\" @(#)readom.1 1.23 06/01/12 Copyright 1996-2006 J. Schilling |
| 2 |
.\" |
| 3 |
.\" Modified version of readcd.1 by J. Schilling, 11/2006 |
| 4 |
.\" |
| 5 |
.\" This program is free software; you can redistribute it and/or modify |
| 6 |
.\" it under the terms of the GNU General Public License version 2 |
| 7 |
.\" as published by the Free Software Foundation. |
| 8 |
.\" |
| 9 |
.\" The GNU General Public License's references to "object code" |
| 10 |
.\" and "executables" are to be interpreted as the output of any |
| 11 |
.\" document formatting or typesetting system, including |
| 12 |
.\" intermediate and printed output. |
| 13 |
.\" |
| 14 |
.\" This manual is distributed in the hope that it will be useful, |
| 15 |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 16 |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 17 |
.\" GNU General Public License for more details. |
| 18 |
.\" |
| 19 |
.\" You should have received a copy of the GNU General Public License along with |
| 20 |
.\" this program; see the file COPYING. If not, write to the Free Software |
| 21 |
.\" Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 22 |
.if t .ds a \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'a |
| 23 |
.if t .ds o \v'-0.55m'\h'0.00n'\z.\h'0.45n'\z.\v'0.55m'\h'-0.45n'o |
| 24 |
.if t .ds u \v'-0.55m'\h'0.00n'\z.\h'0.40n'\z.\v'0.55m'\h'-0.40n'u |
| 25 |
.if t .ds A \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'A |
| 26 |
.if t .ds O \v'-0.77m'\h'0.25n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.70n'O |
| 27 |
.if t .ds U \v'-0.77m'\h'0.30n'\z.\h'0.45n'\z.\v'0.77m'\h'-0.75n'U |
| 28 |
.if t .ds s \\(*b |
| 29 |
.if t .ds S SS |
| 30 |
.if n .ds a ae |
| 31 |
.if n .ds o oe |
| 32 |
.if n .ds u ue |
| 33 |
.if n .ds s sz |
| 34 |
.TH READOM 1 "Version 2.0" "J\*org Schilling" "Schily\'s USER COMMANDS" |
| 35 |
.SH NAME |
| 36 |
readom \- read or write data Compact Discs |
| 37 |
.SH SYNOPSIS |
| 38 |
.B readom |
| 39 |
.BI dev= device |
| 40 |
[ |
| 41 |
.I options |
| 42 |
] |
| 43 |
|
| 44 |
.SH DESCRIPTION |
| 45 |
.B Readom |
| 46 |
is used to read or write Compact Discs. |
| 47 |
.PP |
| 48 |
The |
| 49 |
.I device |
| 50 |
refers to a device location similar to the one used in the wodim command. Refer to its manpage for details. |
| 51 |
.PP |
| 52 |
Also note that this version of readom uses a modified libusal library which has |
| 53 |
a different behaviour compared to the one distributed by its original author. |
| 54 |
|
| 55 |
.SH OPTIONS |
| 56 |
.PP |
| 57 |
If no options except the |
| 58 |
.I dev= |
| 59 |
option have been specified, |
| 60 |
.B readom |
| 61 |
goes into interactive mode. |
| 62 |
Select a primary function and then follow the instructions. |
| 63 |
.PP |
| 64 |
.TP |
| 65 |
.B \-version |
| 66 |
Print version information and exit. |
| 67 |
.TP |
| 68 |
.BI dev= target |
| 69 |
Sets the SCSI target for the drive, see notes above. |
| 70 |
A typical device specification is |
| 71 |
.BI dev= 6,0 |
| 72 |
\&. |
| 73 |
If a filename must be provided together with the numerical target |
| 74 |
specification, the filename is implementation specific. |
| 75 |
The correct filename in this case can be found in the system specific |
| 76 |
manuals of the target operating system. |
| 77 |
On a |
| 78 |
.I FreeBSD |
| 79 |
system without |
| 80 |
.I CAM |
| 81 |
support, you need to use the control device (e.g. |
| 82 |
.IR /dev/rcd0.ctl ). |
| 83 |
A correct device specification in this case may be |
| 84 |
.BI dev= /dev/rcd0.ctl:@ |
| 85 |
\&. |
| 86 |
.sp |
| 87 |
On Linux, drives connected to a parallel port adapter are mapped |
| 88 |
to a virtual SCSI bus. Different adapters are mapped to different |
| 89 |
targets on this virtual SCSI bus. |
| 90 |
.sp |
| 91 |
If no |
| 92 |
.I dev |
| 93 |
option is present, |
| 94 |
.B readom |
| 95 |
will try to get the device from the |
| 96 |
.B CDR_DEVICE |
| 97 |
environment. |
| 98 |
.sp |
| 99 |
If the argument to the |
| 100 |
.B dev= |
| 101 |
option does not contain the characters ',', '/', '@' or ':', |
| 102 |
it is interpreted as an label name that may be found in the file |
| 103 |
/etc/wodim.conf (see FILES section). |
| 104 |
.TP |
| 105 |
.BI timeout= # |
| 106 |
Set the default SCSI command timeout value to |
| 107 |
.IR # " seconds. |
| 108 |
The default SCSI command timeout is the minimum timeout used for sending |
| 109 |
SCSI commands. |
| 110 |
If a SCSI command fails due to a timeout, you may try to raise the |
| 111 |
default SCSI command timeout above the timeout value of the failed command. |
| 112 |
If the command runs correctly with a raised command timeout, |
| 113 |
please report the better timeout value and the corresponding command to |
| 114 |
the author of the program. |
| 115 |
If no |
| 116 |
.I timeout |
| 117 |
option is present, a default timeout of 40 seconds is used. |
| 118 |
.TP |
| 119 |
.BI debug= "#, " -d |
| 120 |
Set the misc debug value to # (with debug=#) or increment |
| 121 |
the misc debug level by one (with -d). If you specify |
| 122 |
.I -dd, |
| 123 |
this equals to |
| 124 |
.BI debug= 2. |
| 125 |
This may help to find problems while opening a driver for libusal. |
| 126 |
as well as with sector sizes and sector types. |
| 127 |
Using |
| 128 |
.B \-debug |
| 129 |
slows down the process and may be the reason for a buffer underrun. |
| 130 |
.TP |
| 131 |
.BR kdebug= "#, " kd= # |
| 132 |
Tell the |
| 133 |
.BR usal -driver |
| 134 |
to modify the kernel debug value while SCSI commands are running. |
| 135 |
.TP |
| 136 |
.BR \-silent ", " \-s |
| 137 |
Do not print out a status report for failed SCSI commands. |
| 138 |
.TP |
| 139 |
.B \-v |
| 140 |
Increment the level of general verbosity by one. |
| 141 |
This is used e.g. to display the progress of the process. |
| 142 |
.TP |
| 143 |
.B \-V |
| 144 |
Increment the verbose level with respect of SCSI command transport by one. |
| 145 |
This helps to debug problems |
| 146 |
during the process, that occur in the CD-Recorder. |
| 147 |
If you get incomprehensible error messages you should use this flag |
| 148 |
to get more detailed output. |
| 149 |
.B \-VV |
| 150 |
will show data buffer content in addition. |
| 151 |
Using |
| 152 |
.B \-V |
| 153 |
or |
| 154 |
.B \-VV |
| 155 |
slows down the process. |
| 156 |
.TP |
| 157 |
.BI f= file |
| 158 |
Specify the filename where the output should be written or the input should |
| 159 |
be taken from. Using '-' as filename will cause |
| 160 |
.B readom |
| 161 |
to use |
| 162 |
.BR stdout " resp. " stdin . |
| 163 |
.TP |
| 164 |
.B \-w |
| 165 |
Switch to write mode. If this option is not present, |
| 166 |
.B readom |
| 167 |
reads from the specified device. |
| 168 |
.TP |
| 169 |
.B \-c2scan |
| 170 |
Scans the whole CD or the range specified by the |
| 171 |
.BI sectors= range |
| 172 |
for C2 errors. C2 errors are errors that are uncorrectable after the second |
| 173 |
stage of the 24/28 + 28/32 Reed Solomon correction system at audio level |
| 174 |
(2352 bytes sector size). If an audio CD has C2 errors, interpolation is needed |
| 175 |
to hide the errors. If a data CD has C2 errors, these errors are in most |
| 176 |
cases corrected by the ECC/EDC code that makes 2352 bytes out of 2048 data |
| 177 |
bytes. The ECC/EDC code should be able to correct about 100 C2 error bytes |
| 178 |
per sector. |
| 179 |
.sp |
| 180 |
If you find C2 errors you may want to reduce the speed using the |
| 181 |
.B speed= |
| 182 |
option as C2 errors may be a result of dynamic unbalance on the medium. |
| 183 |
.TP |
| 184 |
.B \-scanbus |
| 185 |
Scan all SCSI devices on all SCSI busses and print the inquiry |
| 186 |
strings. This option may be used to find SCSI address of the |
| 187 |
devices on a system. |
| 188 |
The numbers printed out as labels are computed by: |
| 189 |
.B "bus * 100 + target |
| 190 |
.TP |
| 191 |
.BI sectors= range |
| 192 |
Specify a sector range that should be read. |
| 193 |
The range is specified by the starting sector number, a minus sign and the |
| 194 |
ending sector number. |
| 195 |
The end sector is not included in the list, so |
| 196 |
.BR sectors= 0-0 |
| 197 |
will not read anything and may be used to check for a CD in the drive. |
| 198 |
.TP |
| 199 |
.BR speed= # |
| 200 |
Set the speed factor of the read or write process to #. |
| 201 |
# is an integer, representing a multiple of the audio speed. |
| 202 |
This is about 150 KB/s for CD-ROM and about 172 KB/s for CD-Audio. |
| 203 |
If no |
| 204 |
.I speed |
| 205 |
option is present, |
| 206 |
.B readom |
| 207 |
will use maximum speed. |
| 208 |
Only MMC compliant drives will benefit from this option. |
| 209 |
The speed of non MMC drives is not changed. |
| 210 |
.sp |
| 211 |
Using a lower speed may increase the readability of a CD or DVD. |
| 212 |
.TP |
| 213 |
.BR ts= # |
| 214 |
Set the maximum transfer size for a single SCSI command to #. |
| 215 |
The syntax for the |
| 216 |
.B ts= |
| 217 |
option is the same as for wodim fs=# or sdd bs=#. |
| 218 |
.sp |
| 219 |
If no |
| 220 |
.B ts= |
| 221 |
option has been specified, |
| 222 |
.B readom |
| 223 |
defaults to a transfer size of 256 kB. If libusal gets lower values from the |
| 224 |
operating system, the value is reduced to the maximum value that is possible |
| 225 |
with the current operating system. |
| 226 |
Sometimes, it may help to further reduce the transfer size or to enhance it, |
| 227 |
but note that it may take a long time to find a better value by experimenting |
| 228 |
with the |
| 229 |
.B ts= |
| 230 |
option. |
| 231 |
.TP |
| 232 |
.B \-notrunc |
| 233 |
Do not truncate the output file when opening it. |
| 234 |
.TP |
| 235 |
.B \-fulltoc |
| 236 |
Retrieve a full TOC from the current disk and print it in hex. |
| 237 |
.TP |
| 238 |
.B \-clone |
| 239 |
Do a clone read. Read the CD with all sub-channel data and a full TOC. |
| 240 |
The full TOC data will be put into a file with similar name as with the |
| 241 |
.B f= |
| 242 |
option but the suffix |
| 243 |
.B .toc |
| 244 |
added. |
| 245 |
.TP |
| 246 |
.B \-noerror |
| 247 |
Do not abort if the high level error checking in |
| 248 |
.B readom |
| 249 |
found an uncorrectable error in the data stream. |
| 250 |
.TP |
| 251 |
.B \-nocorr |
| 252 |
Switch the drive into a mode where it ignores read errors in data sectors that |
| 253 |
are a result of uncorrectable ECC/EDC errors before reading. |
| 254 |
If |
| 255 |
.B readom |
| 256 |
completes, the error recovery mode of the drive is switched back to the remembered |
| 257 |
old mode. |
| 258 |
.TP |
| 259 |
.BI retries= # |
| 260 |
Set the retry count for high level retries in |
| 261 |
.B readom |
| 262 |
to |
| 263 |
.IR # . |
| 264 |
The default is to do 128 retries which may be too much if you like to read a CD |
| 265 |
with many unreadable sectors. |
| 266 |
.TP |
| 267 |
.B \-overhead |
| 268 |
Meter the SCSI command overhead time. |
| 269 |
This is done by executing several commands 1000 times and printing the |
| 270 |
total time used. If you divide the displayed times by 1000, you get |
| 271 |
the average overhead time for a single command. |
| 272 |
.TP |
| 273 |
.BR meshpoints= # |
| 274 |
Print read-speed at # locations. |
| 275 |
The purpose of this option is to create a list of read speed values suitable |
| 276 |
for e.g. |
| 277 |
.BR gnuplot . |
| 278 |
The speed values are calculated assuming that 1000 bytes are one kilobyte |
| 279 |
as documented in the SCSI standard. |
| 280 |
The output data created for this purpose is written to |
| 281 |
.IR stdout . |
| 282 |
.TP |
| 283 |
.B \-factor |
| 284 |
Output the speed values for |
| 285 |
.BR meshpoints= # |
| 286 |
as factor based on |
| 287 |
.I "single speed |
| 288 |
of the current medium. |
| 289 |
This only works if |
| 290 |
.B readom |
| 291 |
is able to determine the current medium type. |
| 292 |
.SH EXAMPLES |
| 293 |
.PP |
| 294 |
For all examples below, it will be assumed that the drive is |
| 295 |
connected to the primary SCSI bus of the machine. The SCSI target id is |
| 296 |
set to 2. |
| 297 |
.PP |
| 298 |
To read the complete media from a CD-ROM writing the data to the file |
| 299 |
.IR cdimage.raw : |
| 300 |
.PP |
| 301 |
readom dev=2,0 f=cdimage.raw |
| 302 |
.PP |
| 303 |
To read sectors from range 150 ... 10000 from a CD-ROM writing the data to the file |
| 304 |
.IR cdimage.raw : |
| 305 |
.PP |
| 306 |
readom dev=2,0 sectors=150-10000 f=cdimage.raw |
| 307 |
.PP |
| 308 |
To write the data from the file |
| 309 |
.I cdimage.raw |
| 310 |
(e.g. a filesystem image from |
| 311 |
.BR genisoimage ) |
| 312 |
to a DVD-RAM, call: |
| 313 |
.PP |
| 314 |
readom dev=2,0 -w f=cdimage.raw |
| 315 |
|
| 316 |
.SH ENVIRONMENT |
| 317 |
.TP |
| 318 |
.B RSH |
| 319 |
If the |
| 320 |
.B RSH |
| 321 |
environment is present, the remote connection will not be created via |
| 322 |
.BR rcmd (3) |
| 323 |
but by calling the program pointed to by |
| 324 |
.BR RSH . |
| 325 |
Use e.g. |
| 326 |
.BR RSH= /usr/bin/ssh |
| 327 |
to create a secure shell connection. |
| 328 |
.sp |
| 329 |
Note that this forces |
| 330 |
.B wodim |
| 331 |
to create a pipe to the |
| 332 |
.B rsh(1) |
| 333 |
program and disallows |
| 334 |
.B wodim |
| 335 |
to directly access the network socket to the remote server. |
| 336 |
This makes it impossible to set up performance parameters and slows down |
| 337 |
the connection compared to a |
| 338 |
.B root |
| 339 |
initiated |
| 340 |
.B rcmd(3) |
| 341 |
connection. |
| 342 |
.TP |
| 343 |
.B RSCSI |
| 344 |
If the |
| 345 |
.B RSCSI |
| 346 |
environment is present, the remote SCSI server will not be the program |
| 347 |
.B /opt/schily/sbin/rscsi |
| 348 |
but the program pointed to by |
| 349 |
.BR RSCSI . |
| 350 |
Note that the remote SCSI server program name will be ignored if you log in |
| 351 |
using an account that has been created with a remote SCSI server program as |
| 352 |
login shell. |
| 353 |
.SH SEE ALSO |
| 354 |
.BR wodim (1), |
| 355 |
.BR genisoimage (1), |
| 356 |
.BR rcmd (3), |
| 357 |
.BR ssh (1). |
| 358 |
|
| 359 |
.SH NOTES |
| 360 |
.PP |
| 361 |
Unless you want to risk getting problems, |
| 362 |
.B readom |
| 363 |
should be run as root. If you don't want to allow users to become root on your system, |
| 364 |
.B readom |
| 365 |
may safely be installed suid root. |
| 366 |
For more information see the additional notes of your system/program |
| 367 |
distribution or README.suidroot which is part of the Cdrkit source. |
| 368 |
.PP |
| 369 |
Documentation of the |
| 370 |
.B wodim |
| 371 |
program contains more technical details which could also apply to |
| 372 |
.B readom. |
| 373 |
|
| 374 |
.SH DIAGNOSTICS |
| 375 |
.PP |
| 376 |
.PP |
| 377 |
A typical error message for a SCSI command looks like: |
| 378 |
.sp |
| 379 |
.RS |
| 380 |
.nf |
| 381 |
readom: I/O error. test unit ready: scsi sendcmd: no error |
| 382 |
CDB: 00 20 00 00 00 00 |
| 383 |
status: 0x2 (CHECK CONDITION) |
| 384 |
Sense Bytes: 70 00 05 00 00 00 00 0A 00 00 00 00 25 00 00 00 00 00 |
| 385 |
Sense Key: 0x5 Illegal Request, Segment 0 |
| 386 |
Sense Code: 0x25 Qual 0x00 (logical unit not supported) Fru 0x0 |
| 387 |
Sense flags: Blk 0 (not valid) |
| 388 |
cmd finished after 0.002s timeout 40s |
| 389 |
.fi |
| 390 |
.sp |
| 391 |
.RE |
| 392 |
The first line gives information about the transport of the command. |
| 393 |
The text after the first colon gives the error text for the system call |
| 394 |
from the view of the kernel. It usually is: |
| 395 |
.B "I/O error |
| 396 |
unless other problems happen. The next words contain a short description for |
| 397 |
the SCSI command that fails. The rest of the line tells you if there were |
| 398 |
any problems for the transport of the command over the SCSI bus. |
| 399 |
.B "fatal error |
| 400 |
means that it was not possible to transport the command (i.e. no device present |
| 401 |
at the requested SCSI address). |
| 402 |
.PP |
| 403 |
The second line prints the SCSI command descriptor block for the failed command. |
| 404 |
.PP |
| 405 |
The third line gives information on the SCSI status code returned by the |
| 406 |
command, if the transport of the command succeeds. |
| 407 |
This is error information from the SCSI device. |
| 408 |
.PP |
| 409 |
The fourth line is a hex dump of the auto request sense information for the |
| 410 |
command. |
| 411 |
.PP |
| 412 |
The fifth line is the error text for the sense key if available, followed |
| 413 |
by the segment number that is only valid if the command was a |
| 414 |
.I copy |
| 415 |
command. If the error message is not directly related to the current command, |
| 416 |
the text |
| 417 |
.I deferred error |
| 418 |
is appended. |
| 419 |
.PP |
| 420 |
The sixth line is the error text for the sense code and the sense qualifier if available. |
| 421 |
If the type of the device is known, the sense data is decoded from tables |
| 422 |
in |
| 423 |
.IR scsierrs.c " . |
| 424 |
The text is followed by the error value for a field replaceable unit. |
| 425 |
.PP |
| 426 |
The seventh line prints the block number that is related to the failed command |
| 427 |
and text for several error flags. The block number may not be valid. |
| 428 |
.PP |
| 429 |
The eight line reports the timeout set up for this command and the time |
| 430 |
that the command really needed to complete. |
| 431 |
|
| 432 |
.SH BUGS |
| 433 |
.PP |
| 434 |
The |
| 435 |
.B readom |
| 436 |
program described here is the Cdrkit spinoff from the original |
| 437 |
.B readcd |
| 438 |
application (see AUTHOR section for details). It may contain bugs not present |
| 439 |
in the original implementation. |
| 440 |
.PP |
| 441 |
It is definitely less portable than the original implementation. |
| 442 |
.PP |
| 443 |
For platform specific bugs, see the corresponding README.platform file in the |
| 444 |
Cdrkit documentation (eg. README.linux). |
| 445 |
|
| 446 |
.SH "MAILING LISTS |
| 447 |
If you want to actively take part on the development of readom, |
| 448 |
you may join the developer mailing list via this URL: |
| 449 |
.sp |
| 450 |
.B |
| 451 |
http://alioth.debian.org/mail/?group_id=31006 |
| 452 |
.PP |
| 453 |
The mail address of the list is: |
| 454 |
.B |
| 455 |
[email protected] |
| 456 |
|
| 457 |
|
| 458 |
|
| 459 |
|
| 460 |
.SH AUTHOR |
| 461 |
.nf |
| 462 |
J\*org Schilling |
| 463 |
Seestr. 110 |
| 464 |
D-13353 Berlin |
| 465 |
Germany |
| 466 |
.fi |
| 467 |
|
| 468 |
.PP |
| 469 |
This is application is a spinoff from the original implementation of readcd delivered in |
| 470 |
the cdrtools package [1] created by Joerg Schilling, who deserves the most credits |
| 471 |
for its success. However, he is not involved into the development |
| 472 |
of this spinoff and therefore he shall not be made responsible for any problem |
| 473 |
caused by it. Do not try to get support from the original author! |
| 474 |
.PP |
| 475 |
Additional information can be found on: |
| 476 |
.br |
| 477 |
https://alioth.debian.org/projects/debburn/ |
| 478 |
.PP |
| 479 |
If you have support questions, send them to |
| 480 |
.PP |
| 481 |
.B |
| 482 |
[email protected] |
| 483 |
.br |
| 484 |
.PP |
| 485 |
If you have definitely found a bug, send a mail to this list or to |
| 486 |
.PP |
| 487 |
.B |
| 488 |
[email protected] |
| 489 |
.br |
| 490 |
.PP |
| 491 |
writing at least a short description into the Subject and "Package: cdrkit" |
| 492 |
into the first line of the mail body. |
| 493 |
.SH SOURCES |
| 494 |
.PP |
| 495 |
.br |
| 496 |
[1] Cdrtools 2.01.01a08 from May 2006, http://cdrecord.berlios.de |
| 497 |
|