common: add deallocate helper function

For punching holes via fallocate. This will be useful for the external
backup provider API to discard parts of the source. The 'file-handle'
mechanism there uses a fuse mount, which does not implement the
BLKDISCARD ioctl, but does implement fallocate.

Signed-off-by: Fiona Ebner <f.ebner@proxmox.com>
Tested-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
Reviewed-by: Wolfgang Bumiller <w.bumiller@proxmox.com>
Link: https://lore.proxmox.com/20250404133204.239783-4-f.ebner@proxmox.com

src/PVE/Storage/Common.pm

@@ -4,6 +4,12 @@ use strict;
 use warnings;
 
 use PVE::JSONSchema;
+use PVE::Syscall;
+
+use constant {
+    FALLOC_FL_KEEP_SIZE => 0x01, # see linux/falloc.h
+    FALLOC_FL_PUNCH_HOLE => 0x02, # see linux/falloc.h
+};
 
 =pod
 
@@ -78,4 +84,27 @@ sub align_size_up : prototype($$) {
     return $aligned_size;
 }
 
+=pod
+
+=head3 deallocate
+
+    deallocate($file_handle, $offset, $length)
+
+Deallocates the range with C<$length> many bytes starting from offset C<$offset>
+for the file associated to the file handle C<$file_handle>. Dies on failure.
+
+=cut
+
+sub deallocate : prototype($$$) {
+    my ($file_handle, $offset, $length) = @_;
+
+    my $mode = FALLOC_FL_KEEP_SIZE | FALLOC_FL_PUNCH_HOLE;
+    $offset = int($offset);
+    $length = int($length);
+
+    if (syscall(PVE::Syscall::fallocate, fileno($file_handle), $mode, $offset, $length) != 0) {
+	die "fallocate: punch hole failed (offset: $offset, length: $length) - $!\n";
+    }
+}
+
 1;