-find tests -damaged and -lba_range, new -find action report_damage

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 "Aug 15, 2008"
+.TH XORRISO 1 "Aug 17, 2008"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -832,21 +832,44 @@ where "A0" is year 2000, "B0" is 2010, etc.
 \fB\-alter_date_r\fR type timestring iso_rr_path [***]
 Like -alter_date but affecting all files below eventual directories.
 .TP
-\fB\-find\fR iso_rr_path [-name pattern] [-type t] [-exec action [params]] --
+\fB\-find\fR iso_rr_path [test [test ...]] [-exec action [params]] --
 A very restricted substitute for shell command find in the ISO image.
 It performs an action on matching file objects at or below iso_rr_path.
 .br
-Optional -name pattern is not expanded but used for comparison with
-the particular file names of the eventual directory tree underneath
-iso_rr_path. If no -name pattern is given, then any file name matches.
+Tests are optional. If they are omitted then action is applied to all file
+objects. If tests are given then action is applied only if all of them
+match the file object. Available tests are:
 .br
-The optional -type test restricts matching to files of the given type:
+-name pattern
+.br
+Pattern is not expanded but used for comparison with
+the particular file names of the eventual directory tree underneath
+iso_rr_path.
+.br
+-type type_letter
+.br
+matches only files files of the given type:
 "block", "char", "dir", "pipe", "file", "link", "socket",
 "Xotic" which eventually matches what is not matched by the other types.
 .br
 Only the first letter is interpreted.  E.g.: -find / -type d
 .br
-If a file matches then the action is performed. Default action is "echo",
+-damaged
+.br
+matches only files which use data blocks marked as damaged by a previous
+run of -check_media. The damage info vanishes when a new ISO image gets
+loaded.
+.br
+-undamaged
+.br
+matches only files which use data blocks outside the areas marked as damaged. 
+.br
+-lba_range start_lba block_count
+.br
+matches only files which use data blocks within the range of start_lba
+and start_lba+block_count-1.
+.br
+Default action is "echo",
 i.e. to print the address of the found file. Other actions are certain
 xorriso commands which get performed on the found files. These commands
 may have specific parameters. See also their particular descriptions.
@@ -904,6 +927,15 @@ E.g.:
 .br 
   -find /uh/oh -name *private* -exec rm_r --
 .br
+"report_damage" classifies files whether they hit a data block that is
+marked as damaged. The result is printed together with the eventual address
+of the first damaged byte, the maximum span of damages, file size, and the
+path of the file. 
+.br
+E.g.:
+.br
+  -find / -damaged -exec report_damage
+.br
 "find" performs another run of -find on the matching file address. It accepts
 the same params as -find, except iso_rr_path.
 E.g.:
@@ -1671,7 +1703,7 @@ time_limit=28800 item_limit=100000
 .br
 abort_file=/var/opt/xorriso/do_abort_check_media
 .br
-data_to= sector_map= map_with_volid=off
+data_to='' sector_map='' map_with_volid=off report=blocks
 .br
 Non-default settings:
 .br
@@ -1684,7 +1716,7 @@ avoids loading the ISO image tree from media.
 .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
+"retry=on" forces read retries with single blocks when the normal read
 chunk produces a read error. By default, retries are only enabled with CD
 media. "retry=off" forbits retries for all media types. 
 .br
@@ -1722,6 +1754,11 @@ sector_map= and processes this virtual outcome.
 The result list tells intervals of 2 KiB blocks with start address, number
 of blocks and quality. Qualities which begin with "+" are
 supposed to be valid readable data. Qualities with "-" are no valid data.
+.br
+"report=files" lists the files which use damaged blocks (not with use=outdev).
+The format is like with find -exec report_damage.
+.br
+"report=blocks_files" first lists damaged blocks and then affected files.
 .TP
 .B osirrox restore options:
 .PP