New command -truncate_overwritable

xorriso/xorriso.texi

@@ -69,7 +69,7 @@
 xorriso - creates, loads, manipulates and writes ISO 9660 filesystem images
 with Rock Ridge extensions.
 
-Copyright @copyright{} 2007 - 2019 Thomas Schmitt
+Copyright @copyright{} 2007 - 2020 Thomas Schmitt
 
 @quotation
 Permission is granted to distribute this text freely.
@@ -3111,6 +3111,61 @@ as reported by the drive. They would be chosen by -read_speed "min" or
 "max" if they undercut or surpass the built-in limits. These are "1x",
 "52xCD", "24xDVD", "20xBD".
 @c man .TP
+@item -list_profiles "in"|"out"|"all"
+@kindex -list_profiles   lists supported media
+@cindex Drive, list supported media, -list_profiles
+Put out a list of media types supported by -indev, -outdev, or both,
+respectively.
+The currently recognized type is marked by text "(current)".
+@c man .TP
+@item -truncate_overwritable entity id adjust
+@kindex -truncate_overwritable   activates older session
+@cindex Older session, activate, -truncate_overwritable
+On overwritable medium copy the volume descriptors of an existing session to
+the overall descriptors at LBA 0 ff. This makes all sessions
+@strong{inaccessible} which are younger than the activated one.
+A reason to do this would be read errors in the younger sessions and
+the wish to re-write or skip them.
+@*
+This operation is only allowed if no changes to the loaded filesystem are
+pending. If an -indev is acquired then it is released before the write
+operation begins and re-acquired only in case of success.
+@*
+The parameters "entity" and "id" have the same meaning as with command -load.
+They choose the existing ISO session which shall become the youngest accessible
+session. Available entity names are "session", "track", "lba", "sbsector",
+"volid". "auto" makes few sense. id is a number or search text as appropriate
+for the given entity.
+@*
+Parameter "adjust" controls the claimed size of the activated session. Text
+"new" means the size of the newly activated session as it was before this
+command. I.e. the space of the then inaccessible younger sessions will be
+re-used when appending more sessions.
+@*
+"old" means the size up to the end of the previously youngest session.
+I.e. "old" will not free the space of the then inaccessible younger sessions
+for re-use.
+@*
+A number preceded by "+" gives the number of bytes to be added to "new".
+A number without "+" gives the overall number of bytes. In any case the result
+may not be smaller than "new". Numbers may have a unit suffix: "d"=512,
+"k"=1024, "s"=2048, "m"=1024k, "g"=1024m.
+@*
+Examples:
+@*
+Activate session 4 and enable overwriting of the blocks of younger sessions:
+@*
+ -truncate_overwritable session 4 new
+@*
+Activate session 4 and claim the blocks of younger sessions as useless part of
+session 4:
+@*
+ -truncate_overwritable session 4 old
+@*
+Let session 4 claim additional 500 MiB as useless data:
+@*
+ -truncate_overwritable session 4 +500m
+@c man .TP
 @item -close_damaged "as_needed"|"force"
 @kindex -close_damaged   closes damaged track and session
 @cindex Damaged track and session, close, -close_damaged
@@ -3128,13 +3183,6 @@ appear undamaged.
 @*
 No image changes are allowed to be pending before this command is performed.
 After closing was attempted, both drives are given up.
-@c man .TP
-@item -list_profiles "in"|"out"|"all"
-@kindex -list_profiles   lists supported media
-@cindex Drive, list supported media, -list_profiles
-Put out a list of media types supported by -indev, -outdev, or both,
-respectively.
-The currently recognized type is marked by text "(current)".
 @end table
 @c man .TP
 @c man .B Settings for result writing:
@@ -7327,7 +7375,7 @@ Thomas Schmitt <scdbackup@@gmx.net>
 for libburnia-project.org
 @c man .SH COPYRIGHT
 @section Copyright
-Copyright (c) 2007 - 2019 Thomas Schmitt
+Copyright (c) 2007 - 2020 Thomas Schmitt
 @*
 Permission is granted to distribute this text freely. It shall only be
 modified in sync with the technical properties of @command{xorriso}.