New option -check_media

libisoburn/trunk/xorriso/xorriso.1

@@ -2,7 +2,7 @@
 .\" 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 XORRISO 1 "Jul, 17, 2008"
+.TH XORRISO 1 "Aug 14, 2008"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -147,11 +147,11 @@ useful to store intermediate states and to continue with image manipulations.
 .B Media types and states:
 There are two families of media in the MMC standard:
 .br
-\fBMulti-session\fR media are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, and
+\fBMulti-session media\fR are CD-R, CD-RW, DVD-R, DVD+R, DVD+R/DL, and
 unformatted DVD-RW. These media provide a table of content which
 describes their existing sessions. See option \fB-toc\fR.
 .br
-\fBOverwriteable\fR media are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
+\fBOverwriteable media\fR are DVD-RAM, DVD+RW, BD-RE, and formatted DVD-RW.
 They allow random write access but do not provide information about their
 session history. If they contain one or more ISO 9660 sessions and if the
 first session was written by xorriso, then a table of content can
@@ -210,7 +210,7 @@ blank state if it was not blank already.
 .PP
 If there is a input drive with a valid ISO image, then this image gets loaded
 as foundation for manipulations and extension. The constellation of input
-and output drive determines which of two write methods will be used.
+and output drive determines which write method will be used.
 They have quite different capabilities and constraints.
 .PP
 The method of \fBgrowing\fR adds new data to the existing media. These
@@ -551,11 +551,8 @@ If other file types collide then the setting of command
 decides.
 .br
 Renaming of files has similar collision handling, but directories can only
-be replaced, not merged. Directories can hardly collide on renaming because
-of the shell-like behavior of -mv: if a file object hits an existing directory
-then it gets inserted rather than trying to replace that directory.
-Nevertheless, the overwriting rules apply if an operation of xorriso
-ever attempts to do such a replacement.
+be replaced, not merged. Note that -mv inserts the source objects into an
+eventual existing target directory rather than attempting to replace it.
 .PP
 The commands in this section alter the ISO image and not the local filesystem.
 .TP
@@ -1645,9 +1642,78 @@ addresses get compared whether they have counterparts below the other address
 and whether both counterparts match.
 .TP
 \fB\-compare_l\fR disk_prefix iso_rr_prefix disk_path [***]
-Performs -compare_r with each of the disk_path arguments. iso_rr_path will be
+Perform -compare_r with each of the disk_path arguments. iso_rr_path will be
 composed from disk_path by replacing disk_prefix by iso_rr_prefix.
 .TP
+.B Evaluation of readability and recovery:
+.PP
+It is not uncommon that optical media produce read errors. The reasons may be
+various and get obscured by error correction which is performed by the drives
+and based on extra data on the media. If a drive returns data then one can
+quite trust that they are valid. But at some degree of read problems the
+correction will fail and the drive is supposed to indicate error.
+.br
+xorriso can scan the media for readable data blocks, classify them according
+to their read speed, save them to a file, and keep track of successfuly saved
+blocks for further tries on the same media.
+.TP
+\fB\-check_media\fR [option [option ...]] --
+Try to read data blocks from the indev drive and finally report about the
+encountered quality. Several options may be used to modify the default
+behavior.
+.br
+An option consists of a keyword, a "=" character, and a value.
+.br
+Default is:
+.br
+use=indev what=tracks min_lba=-1 max_lba=-1 retry=default
+time_limit=-1 item_limit=-1
+.br
+abort_file=/var/opt/xorriso/do_abort_check_media
+.br
+data_to= sector_map= map_with_volid=off
+.br
+Non-default settings:
+.br
+"use=outdev" reads from the output drive instead of the input drive. This
+avoids reading of the ISO image tree from media.
+.br
+"what=disc" scans the payload range of a media without respecting track gaps.
+.br
+"min_lba=" omits all blocks with addresses lower than the option value.
+.br
+"max_lba=" switches to what=disc and omits all blocks above its option value.
+.br
+"retry=on" forces read retries with single blocks when the normal block
+chunk produces a read error. By default, retries are only enabled with CD
+media. "retry=off" forbits retries for all media types. 
+.br
+"abort_file=" gives the path of the file which may abort a scan run. Abort
+happens if the file exists and its mtime is not older than the start time
+of the run. Use shell command "touch" to trigger this.
+Other than an aborted program run, this will report the tested and untested
+blocks and go on with running xorriso.
+.br
+"time_limit=" gives the number of seconds after which the scan shall be
+aborted. This is useful for unattended scanning of media which may else
+overwork the drive in its effort to squeeze out some readable blocks.
+Abort may be delayed by the drive gnawing on the last single read operation.
+.br
+"item_limit=" gives the number of report list items after which to abort.
+.br
+"data_to=" copies the valid blocks to the file which is given as option value.
+.br
+"sector_map=" tries to read the file given by option value as
+"xorriso sector bitmap" and to store such a map file after the scan run.
+The bitmap tells which blocks have been read successfully in previous runs.
+It allows to do several scans on the same media, eventually with intermediate
+eject, in order to collect readable blocks whenever the drive is lucky enough
+to produce them. The stored file also contains a human readable TOC of tracks
+and their start block addresses.
+.br
+"map_with_volid=on" examines tracks whether they are ISO images and eventually
+prints their volume ids into the human readable TOC of sector_map=.
+.TP
 .B osirrox restore options:
 .PP
 Normally xorriso only writes to disk files which were given as stdio:
@@ -2341,6 +2407,12 @@ to read and execute lines from the following files:
 .br
 The files are read in the sequence given above, but none of them is required
 for xorriso to function properly.
+.TP
+.B Runtime control files:
+.br
+The default setting of -check_media abort_file= is:
+.br
+   /var/opt/xorriso/do_abort_check_media
 .br
 .SH SEE ALSO
 .TP