[PATCH qemu-server v2 3/3] agent: file-read: Allow specifying byte offset to start reading at

[Markus Ebner]

The previous implementation only allowed reads of fixed size starting
at byte offset 0. This made the Proxmox's agent/file-read unsuitable
for reading large files.
The new offset parameter allows specifying a byte offset position
relative to the start of the file (offset 0) from which the following
read should be performed. The implementation's behavior follows the
lseek semantics - directly following qemu-guest-agent's behavior:

- fseek() does not perform validation against the file size
- Seeking beyond the end of the file is not an error but explicitly
  allowed and specified behavior
- Subsequent fread() calls at positions beyond the file size return
  zero bytes

Additionally, this is equivalent to the behavior of POSIX pread().
Reading a large file block-by-block thus becomes (pseudo-code):
let content = [];
while(response.truncated) {
    response = proxmox.agent_file_read(offset = content.length);
    content .= response.content;
}

To be backwards compatible, offset defaults to 0.

Signed-off-by: Markus Ebner <i...@ebner-markus.de>
---
 src/PVE/API2/Qemu/Agent.pm | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/src/PVE/API2/Qemu/Agent.pm b/src/PVE/API2/Qemu/Agent.pm
index 1f5962e9..ba96d77e 100644
--- a/src/PVE/API2/Qemu/Agent.pm
+++ b/src/PVE/API2/Qemu/Agent.pm
@@ -485,6 +485,13 @@ __PACKAGE__->register_method({
                 type => 'string',
                 description => 'The path to the file',
             },
+            offset => {
+                type => 'integer',
+                optional => 1,
+                minimum => 0,
+                default => 0,
+                description => "Offset to start reading at",
+            },
         },
     },
     returns => {
@@ -506,6 +513,7 @@ __PACKAGE__->register_method({
         my ($param) = @_;
         my $count = int($param->{count} // $MAX_READ_SIZE);
         my $decode = $param->{decode} // 1;
+        my $offset = $param->{offset} // 0;
 
         my $vmid = $param->{vmid};
         my $conf = PVE::QemuConfig->load_config($vmid);
@@ -513,6 +521,16 @@ __PACKAGE__->register_method({
         my $qgafh =
             agent_cmd($vmid, $conf, "file-open", { path => $param->{file} }, 
"can't open file");
 
+        if ($offset > 0) {
+            my $seek = mon_cmd(
+                $vmid, "guest-file-seek",
+                handle => $qgafh,
+                offset => int($offset),
+                whence => 'set',
+            );
+            check_agent_error($seek, "can't seek to offset position");
+        }
+
         my $bytes_read = 0;
         my $eof = 0;
         my $read_size = 1024 * 1024;
-- 
2.53.0