New options -external_filter , -unregister_filter, -set_filter , -set_filter_r

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 "Mar 21, 2009"
+.TH XORRISO 1 "Apr 02, 2009"
 .\" Please adjust this date whenever revising the manpage.
 .\"
 .\" Some roff macros, for reference:
@@ -1082,6 +1082,74 @@ whitespace after the end quote will be ignored. Non-printables bytes and quotes
 must be represented as \\XYZ by their octal ASCII code XYZ.
 Use code \\000 for 0-bytes.
 .TP
+\fB\-external_filter\fR name option[:option] program_path [arguments] --
+Register a content filter by associating a name with a program path,
+program arguments, and some behavioral options. Once registered it can be
+applied to multiple data files in the ISO image, regardless whether their
+content resides in the loaded ISO image or in the local filesystem.
+External filter processes may produce synthetic file content by reading the
+original content from stdin and writing to stdout whatever they want.
+They must deliver the same output on the same input in repeated runs.
+.br
+Options are:
+.br
+ "suffix=..." sets a file name suffix. If it is not empty then it will be
+appended to the file name or removed from it.
+.br
+ "remove_suffix" will remove an eventual file name suffix
+rather than appending it.
+.br
+ "if_nonempty" will leave 0-sized files unfiltered.
+.br
+ "if_reduction" will try filtering and revoke it if the content size does not
+shrink.
+.br
+ "if_block_reduction" will revoke if the number of 2 kB blocks does not shrink.
+.br
+ "used=..." is ignored. Command -status shows it with the number of
+files which currently have the filter applied.
+.br
+Examples:
+.br
+ -external_filter gzip suffix=.gz:if_block_reduction \\
+.br
+                  /usr/bin/gzip --
+.br
+ -external_filter gunzip suffix=.gz:remove_suffix:if_nonempty \\
+.br
+                  /usr/bin/gunzip --
+.TP
+\fB\-unregister_filter\fR name
+Remove an -external_filter registration. This is only possible if the filter
+is not applied to any file in the ISO image.
+.TP
+\fB\-set_filter\fR name iso_rr_path [***]
+Apply an -external_filter to the given data files in the ISO image.
+If the filter suffix is not empty , then it will be appended to the file name.
+Renaming only happens if the filter really gets attached and is not revoked by
+its options. Files which already bear the suffix will not get filtered.
+If the filter has option "remove_suffix", then the filter will only be
+applied if the suffix is present and can be removed.
+Name collisons caused by suffix change will prevent filtering.
+.br
+This command will immediately run the filter once for each file
+in order to determine the output size.
+Content reading operations like -extract , -compare and image generation will
+perform further filter runs and deliver filtered content.
+.br
+At image generation time the filter output must still be the same as the
+output from the first run. Filtering for image generation does not happen
+with files from the loaded ISO image if the write method of growing is in
+effect (i.e -indev and -outdev are identical).
+.br
+The reserved filter name "--remove-all-filters" revokes filtering. A suffix
+may be appended after a "+" or "-". "-" will restrict the filter removal
+to files with that suffix and remove it from the file name. "+" will only
+process files without that suffix and add it to the name.
+.TP
+\fB\-set_filter_r\fR name isuffix iso_rr_path [***]
+Like -set_filter but affecting all data files below eventual directories.
+.TP
 \fB\-alter_date\fR type timestring iso_rr_path [***]
 Alter the date entries of a file in the ISO image. type is
 one of "a", "m", "b" for access time, modification time,
@@ -1233,7 +1301,7 @@ path of the file.
 .br
 E.g.:
 .br
-  -find / -damaged -exec report_damage
+  -find / -damaged -exec report_damage --
 .br
 "report_lba" prints files which are associated to image data blocks.
 It tells the logical block address, the block number, the byte size,
@@ -1243,7 +1311,7 @@ different extent number in column "xt".
 .br
 E.g.:
 .br
-  -find / -lba_range 302000 50000 -exec report_lba
+  -find / -lba_range 302000 50000 -exec report_lba --
 .br
 "getfacl" prints access permissions in ACL text form to the result channel.
 .br
@@ -1256,22 +1324,29 @@ ACL is given in text form as defined with option -setfacl.
 .br
 E.g.:
 .br
-  -find /workgroup -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw
+  -find /work -exec setfacl u:lisa:rw,u::rw,g::r,o::-,m::rw --
 .br
 "getfattr" prints eventual xattr name-value pairs to the result channel.
 .br
 E.g.:
 .br
-  -find / -has_xattr -exec getfattr
+  -find / -has_xattr -exec getfattr --
 .br
 "setfattr" sets or deletes xattr name value pairs.
 .br
 E.g.:
 .br
-  -find / -has_xattr -exec setfattr --remove-all ''
+  -find / -has_xattr -exec setfattr --remove-all '' --
+.br
+"set_filter" applies or removes filters (see -external_filter).
+.br
+E.g.:
+.br
+  -find / -type f -exec set_filter gzip --
 .br
 "find" performs another run of -find on the matching file address. It accepts
 the same params as -find, except iso_rr_path.
+.br
 E.g.:
 .br
   -find / -name '???' -type d -exec find -name '[abc]*' -exec chmod a-w,a+r --