Documentation of the new commands

HISTORY

@@ -16,8 +16,14 @@ SnapRAID HISTORY
  * Added a new locate command to map physical file offsets within the
    parity volume. This feature facilitates diagnostic analysis of the parity
    distribution. It supports the -t, --tail option to filter files located
-   specifically at the end of the parity file. This option handles size
-   suffixes K, M, and G using decimal SI units [Ralf1108].
+   specifically at the end of the parity file [Ralf1108].
+ * Added new option `-W, --force-realloc-tail SIZE` for the `sync` command.
+   This option works like `--force-realloc` but applies only to the
+   specified tail portion (last SIZE bytes) of the parity file.
+   Its main purpose and result is to shrink the size of the parity file by
+   reclaiming unused space ("holes") that may exist in the parity due to
+   previous fragmentation, allowing to compact the parity toward the beginning
+   [Ralf1108].
  * Added detection of the smartctl executable. Improves reliability when running
    under sudo or in environments where /sbin and /usr/sbin are not in PATH.
  * Avoided saving the content file when it was not strictly necessary.
@@ -54,7 +60,7 @@ SnapRAID HISTORY
    dependent on the hard disk vendor.
  * Added a new "smartignore" configuration option to ignore specific SMART
    attributes.
- * Supported UUID in macOS [Nasado]
+ * Supported UUID in macOS [Nasado].
  * Windows binaries built with gcc 11.5.0 using the MXE cross compiler at
    commit 8c4378fa2b55bc28515b23e96e05d03e671d9b90 with targets
    i686-w64-mingw32.static and x86_64-w64-mingw32.static and optimization -O2.
@@ -92,12 +98,12 @@ SnapRAID HISTORY
    files and the final state of the files like 'recovered' or 'unrecovered'.
    The previous behavior is available with the -b, --filter-block-error option.
  * Improved the speed of the filtering in 'fix' and 'check'. This phase
-   happens after the "Selecting..." message.  [UhClem]
+   happens after the "Selecting..." message [UhClem].
 
 11.5 2020/05
 ============
  * Removed the default -march=native to allow deployment in any machine.
- * Fixed typos [Andrea Gelmini]
+ * Fixed typos [Andrea Gelmini].
 
 11.4 2020/05
 ============

doc/snapraid.1

@@ -29,6 +29,10 @@ snapraid [\-c, \-\-conf CONFIG]
 	[\-s, \-\-spin\-down\-on\-error] [\-w, \-\-bw\-limit RATE]
 .PD 0
 .PP
+.PD
+	[\-t, \-\-tail]
+.PD 0
+.PP
 .PD
 	[\-Z, \-\-force\-zero] [\-E, \-\-force\-empty]
 .PD 0
@@ -42,7 +46,7 @@ snapraid [\-c, \-\-conf CONFIG]
 .PD 0
 .PP
 .PD
-	[\-R, \-\-force\-realloc]
+	[\-R, \-\-force\-realloc] [\-W, \-\-force\-realloc\-tail]
 .PD 0
 .PP
 .PD
@@ -66,7 +70,7 @@ snapraid [\-c, \-\-conf CONFIG]
 .PD 0
 .PP
 .PD
-	|list|dup|pool|devices|touch|rehash
+	|list|dup|pool|devices|touch|rehash|locate
 .PD 0
 .PD
 .PP
@@ -995,6 +999,13 @@ You can check the rehash state using \`status\`.
 During the rehash, SnapRAID maintains full functionality,
 with the only exception that \`dup\` cannot detect duplicated
 files using a different hash.
+.SS locate 
+Locate files stored in the parity disks. For each matching file, it
+prints its location within the parity file and the number of fragments
+it occupies.
+.PP
+You can use the \-t, \-\-tail option to restrict the operation to files
+using only the specified tail portion of the parity.
 .SH OPTIONS 
 SnapRAID provides the following options:
 .TP
@@ -1105,7 +1116,14 @@ stopped even when a command fails.
 .B \-w, \-\-bw\-limit RATE
 Applies a global bandwidth limit for all disks. The RATE is
 the number of bytes per second. You can specify a multiplier
-such as K, M, or G (e.g., \-\-bw\-limit 1G).
+such as K, M, G, or T (e.g., \-\-bw\-limit 1G).
+.TP
+.B \-t, \-\-tail SIZE
+Limit file listing to those using no more than the specified
+tail size of the parity disks.
+You can use multipliers such as K, M, G, or T (e.g. \-\-tail 1G).
+This option is only valid when used together with the \`locate\`
+command.
 .TP
 .B \-A, \-\-stats
 Enables an extended status view that shows additional information.
@@ -1202,6 +1220,24 @@ WARNING! This option is for experts only, and it is highly
 recommended not to use it.
 You DO NOT have data protection during the \`sync\` operation.
 .TP
+.B \-W, \-\-force\-realloc\-tail SIZE
+Works like \-R, \-\-force\-realloc, but limited to the specified
+tail portion (last SIZE bytes) of each parity file.
+It forces reallocation (movement) of any file fragments/blocks
+currently stored in that tail section, allowing them to be
+placed anywhere in the parity file where free space is
+available (including existing holes).
+The main purpose of this option is to shrink the on\-disk size
+of the parity file. If the reallocation successfully clears
+the entire tail section (no blocks remain using it), the
+parity file is truncated, reclaiming the unused tail space.
+You can use multipliers such as K, M, G, or T (e.g.
+\-\-force\-realloc\-tail 1G).
+WARNING! This option is for experts only, and it is highly
+recommended not to use it.
+You DO NOT have data protection during the \`sync\` operation
+for the affected files.
+.TP
 .B \-l, \-\-log FILE
 Writes a detailed log to the specified file.
 If this option is not specified, unexpected errors are printed

doc/snapraid.d

@@ -9,16 +9,17 @@ Synopsis
 	:	[-p, --plan PERC|bad|new|full]
 	:	[-o, --older-than DAYS] [-l, --log FILE]
 	:	[-s, --spin-down-on-error] [-w, --bw-limit RATE]
+	:	[-t, --tail]
 	:	[-Z, --force-zero] [-E, --force-empty]
 	:	[-U, --force-uuid] [-D, --force-device]
 	:	[-N, --force-nocopy] [-F, --force-full]
-	:	[-R, --force-realloc]
+	:	[-R, --force-realloc] [-W, --force-realloc-tail]
 	:	[-S, --start BLKSTART] [-B, --count BLKCOUNT]
 	:	[-L, --error-limit NUMBER]
 	:	[-A, --stats]
 	:	[-v, --verbose] [-q, --quiet]
 	:	status|smart|probe|up|down|diff|sync|scrub|fix|check
-	:	|list|dup|pool|devices|touch|rehash
+	:	|list|dup|pool|devices|touch|rehash|locate
 
 	:snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT]
 
@@ -717,6 +718,14 @@ Commands
 	with the only exception that `dup` cannot detect duplicated
 	files using a different hash.
 
+  locate
+	Locate files stored in the parity disks. For each matching file, it
+	prints its location within the parity file and the number of fragments
+	it occupies.
+
+	You can use the -t, --tail option to restrict the operation to files
+	using only the specified tail portion of the parity.
+
 Options
 	SnapRAID provides the following options:
 
@@ -827,7 +836,14 @@ Options
 	-w, --bw-limit RATE
 		Applies a global bandwidth limit for all disks. The RATE is
 		the number of bytes per second. You can specify a multiplier
-		such as K, M, or G (e.g., --bw-limit 1G).
+		such as K, M, G, or T (e.g., --bw-limit 1G).
+
+	-t, --tail SIZE
+		Limit file listing to those using no more than the specified
+		tail size of the parity disks.
+		You can use multipliers such as K, M, G, or T (e.g. --tail 1G).
+		This option is only valid when used together with the `locate`
+		command.
 
 	-A, --stats
 		Enables an extended status view that shows additional information.
@@ -924,6 +940,24 @@ Options
 		recommended not to use it.
 		You DO NOT have data protection during the `sync` operation.
 
+	-W, --force-realloc-tail SIZE
+		Works like -R, --force-realloc, but limited to the specified
+		tail portion (last SIZE bytes) of each parity file.
+		It forces reallocation (movement) of any file fragments/blocks
+		currently stored in that tail section, allowing them to be
+		placed anywhere in the parity file where free space is
+		available (including existing holes).
+		The main purpose of this option is to shrink the on-disk size
+		of the parity file. If the reallocation successfully clears
+		the entire tail section (no blocks remain using it), the
+		parity file is truncated, reclaiming the unused tail space.
+		You can use multipliers such as K, M, G, or T (e.g.
+		--force-realloc-tail 1G).
+		WARNING! This option is for experts only, and it is highly
+		recommended not to use it.
+		You DO NOT have data protection during the `sync` operation
+		for the affected files.
+
 	-l, --log FILE
 		Writes a detailed log to the specified file.
 		If this option is not specified, unexpected errors are printed

doc/snapraid.txt

@@ -13,16 +13,17 @@ snapraid [-c, --conf CONFIG]
 	[-p, --plan PERC|bad|new|full]
 	[-o, --older-than DAYS] [-l, --log FILE]
 	[-s, --spin-down-on-error] [-w, --bw-limit RATE]
+	[-t, --tail]
 	[-Z, --force-zero] [-E, --force-empty]
 	[-U, --force-uuid] [-D, --force-device]
 	[-N, --force-nocopy] [-F, --force-full]
-	[-R, --force-realloc]
+	[-R, --force-realloc] [-W, --force-realloc-tail]
 	[-S, --start BLKSTART] [-B, --count BLKCOUNT]
 	[-L, --error-limit NUMBER]
 	[-A, --stats]
 	[-v, --verbose] [-q, --quiet]
 	status|smart|probe|up|down|diff|sync|scrub|fix|check
-	|list|dup|pool|devices|touch|rehash
+	|list|dup|pool|devices|touch|rehash|locate
 
 snapraid [-V, --version] [-H, --help] [-C, --gen-conf CONTENT]
 
@@ -773,6 +774,16 @@ During the rehash, SnapRAID maintains full functionality,
 with the only exception that `dup` cannot detect duplicated
 files using a different hash.
 
+5.17 locate
+-----------
+
+Locate files stored in the parity disks. For each matching file, it
+prints its location within the parity file and the number of fragments
+it occupies.
+
+You can use the -t, --tail option to restrict the operation to files
+using only the specified tail portion of the parity.
+
 
 6 OPTIONS
 =========
@@ -886,7 +897,14 @@ SnapRAID provides the following options:
     -w, --bw-limit RATE
         Applies a global bandwidth limit for all disks. The RATE is
         the number of bytes per second. You can specify a multiplier
-        such as K, M, or G (e.g., --bw-limit 1G).
+        such as K, M, G, or T (e.g., --bw-limit 1G).
+
+    -t, --tail SIZE
+        Limit file listing to those using no more than the specified
+        tail size of the parity disks.
+        You can use multipliers such as K, M, G, or T (e.g. --tail 1G).
+        This option is only valid when used together with the `locate`
+        command.
 
     -A, --stats
         Enables an extended status view that shows additional information.
@@ -983,6 +1001,24 @@ SnapRAID provides the following options:
         recommended not to use it.
         You DO NOT have data protection during the `sync` operation.
 
+    -W, --force-realloc-tail SIZE
+        Works like -R, --force-realloc, but limited to the specified
+        tail portion (last SIZE bytes) of each parity file.
+        It forces reallocation (movement) of any file fragments/blocks
+        currently stored in that tail section, allowing them to be
+        placed anywhere in the parity file where free space is
+        available (including existing holes).
+        The main purpose of this option is to shrink the on-disk size
+        of the parity file. If the reallocation successfully clears
+        the entire tail section (no blocks remain using it), the
+        parity file is truncated, reclaiming the unused tail space.
+        You can use multipliers such as K, M, G, or T (e.g.
+        --force-realloc-tail 1G).
+        WARNING! This option is for experts only, and it is highly
+        recommended not to use it.
+        You DO NOT have data protection during the `sync` operation
+        for the affected files.
+
     -l, --log FILE
         Writes a detailed log to the specified file.
         If this option is not specified, unexpected errors are printed