From: Peter Krempa <pkrempa@redhat.com>

Document both the behaviour if requested length isn't enough to read the
file as well as the semantics of NUL-termination of the buffer.

Signed-off-by: Peter Krempa <pkrempa@redhat.com>
---
 src/util/virfile.c | 140 ++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 126 insertions(+), 14 deletions(-)

diff --git a/src/util/virfile.c b/src/util/virfile.c
index fbcaf15429..bc3faedd4e 100644
--- a/src/util/virfile.c
+++ b/src/util/virfile.c
@@ -1534,10 +1534,27 @@ saferead_lim(int fd, size_t max_len, size_t *length)
 }


-/* A wrapper around saferead_lim that merely stops reading at the
- * specified maximum size.  */
+/**
+ * virFileReadHeaderQuiet:
+ * @fd: file descriptor to read
+ * @maxlen: maximum amount of bytes to read
+ * @buf: filled with allocated buffer containing read data
+ *
+ * Reads up to @maxlen bytes from @fd and fills @buf with pointer to the
+ * read contents.
+ *
+ * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte one
+ * byte beyond the read contents of the file. The NUL byte is not included in
+ * the returned amount of bytes read. Caller is responsible for freeing the
+ * buffer.
+ *
+ * Returns number of bytes actually read from the fd on success, -1 on error
+ * and doesn't raise a libvirt error.
+ */
 int
-virFileReadHeaderFD(int fd, int maxlen, char **buf)
+virFileReadHeaderFD(int fd,
+                    int maxlen,
+                    char **buf)
 {
     size_t len;
     char *s;
@@ -1554,6 +1571,26 @@ virFileReadHeaderFD(int fd, int maxlen, char **buf)
 }


+/**
+ * virFileReadHeaderQuiet:
+ * @path: file to read
+ * @maxlen: maximum length of file to read
+ * @buf: filled with allocated buffer containing read data
+ *
+ * Reads up to @maxlen bytes from file @path and fills @buf with pointer to the
+ * read contents.
+ *
+ * If file @path is longer than @maxlen the buffer contains only first @maxlen
+ * bytes read from the file.
+ *
+ * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte one
+ * byte beyond the read contents of the file. The NUL byte is not included in
+ * the returned amount of bytes read. Caller is responsible for freeing the
+ * buffer.
+ *
+ * Returns number of bytes actually read from file on success, -1 on error
+ * and doesn't raise a libvirt error.
+ */
 int
 virFileReadHeaderQuiet(const char *path,
                        int maxlen,
@@ -1573,10 +1610,29 @@ virFileReadHeaderQuiet(const char *path,
 }


-/* A wrapper around saferead_lim that maps a failure due to
-   exceeding the maximum size limitation to EOVERFLOW.  */
+/**
+ * virFileReadLimFD:
+ * @fd: file descriptor to read
+ * @maxlen: maximum amount of bytes to read
+ * @buf: filled with allocated buffer containing read data
+ *
+ * Reads the whole contents from @fd and fills @buf with pointer to the read
+ * contents.
+ *
+ * If @fd allowed reading more than @maxlen bytes an error is returned.
+ *
+ * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte one
+ * byte beyond the read contents of the file. The NUL byte is not included in
+ * the returned amount of bytes read. Caller is responsible for freeing the
+ * buffer.
+ *
+ * Returns number of bytes actually read from @fd on success, -1 on error and
+ * doesn't raise a libvirt error.
+ */
 int
-virFileReadLimFD(int fd, int maxlen, char **buf)
+virFileReadLimFD(int fd,
+                 int maxlen,
+                 char **buf)
 {
     size_t len;
     char *s;
@@ -1599,8 +1655,29 @@ virFileReadLimFD(int fd, int maxlen, char **buf)
     return len;
 }

+
+/**
+ * virFileReadAll:
+ * @path: file to read
+ * @maxlen: maximum length of file to read
+ * @buf: filled with allocated buffer containing read data
+ *
+ * Reads the whole file @path and fills @buf with pointer to the read contents.
+ *
+ * If file @path is longer than @maxlen error is returned.
+ *
+ * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte one
+ * byte beyond the read contents of the file. The NUL byte is not included in
+ * the returned amount of bytes read. Caller is responsible for freeing the
+ * buffer.
+ *
+ * Returns number of bytes actually read from file on success, -1 on error and
+ * raises a libvirt error.
+ */
 int
-virFileReadAll(const char *path, int maxlen, char **buf)
+virFileReadAll(const char *path,
+               int maxlen,
+               char **buf)
 {
     int fd;
     int len;
@@ -1621,8 +1698,29 @@ virFileReadAll(const char *path, int maxlen, char **buf)
     return len;
 }

+
+/**
+ * virFileReadAllQuiet:
+ * @path: file to read
+ * @maxlen: maximum length of file to read
+ * @buf: filled with allocated buffer containing read data
+ *
+ * Reads the whole file @path and fills @buf with pointer to the read contents.
+ *
+ * If file @path is longer than @maxlen error is returned.
+ *
+ * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte one
+ * byte beyond the read contents of the file. The NUL byte is not included in
+ * the returned amount of bytes read. Caller is responsible for freeing the
+ * buffer.
+ *
+ * Returns number of bytes actually read from file on success, -errno on error
+ * and doesn't raise a libvirt error.
+ */
 int
-virFileReadAllQuiet(const char *path, int maxlen, char **buf)
+virFileReadAllQuiet(const char *path,
+                    int maxlen,
+                    char **buf)
 {
     int fd;
     int len;
@@ -1639,13 +1737,26 @@ virFileReadAllQuiet(const char *path, int maxlen, char **buf)
     return len;
 }

-/* Read @file into preallocated buffer @buf of size @len.
- * Return value is -errno in case of errors and size
- * of data read (no trailing zero) in case of success.
- * If there is more data then @len - 1 then data will be
- * truncated. */
+
+/**
+ * virFileReadBufQuiet:
+ * @file: file to read
+ * @buf: buffer to read files into
+ * @len: size of @buf
+ *
+ * Reads up to @len - 1 bytes of @file into @buf.
+ *
+ * The buffer @buf is guaranteed to be terminated with a NUL ('\0') byte one
+ * byte beyond the read contents of the file. The NUL byte is not included in
+ * the returned amount of bytes read.
+ *
+ * Returns number of bytes actually read from file on success, -errno on error
+ * and doesn't raise a libvirt error.
+ */
 int
-virFileReadBufQuiet(const char *file, char *buf, int len)
+virFileReadBufQuiet(const char *file,
+                    char *buf,
+                    int len)
 {
     int fd;
     ssize_t sz;
@@ -1663,6 +1774,7 @@ virFileReadBufQuiet(const char *file, char *buf, int len)
     return sz;
 }

+
 /* Truncate @path and write @str to it.  If @mode is 0, ensure that
    @path exists; otherwise, use @mode if @path must be created.
    Return 0 for success, nonzero for failure.
-- 
2.53.0

On Fri, Mar 27, 2026 at 10:54:43AM +0100, Peter Krempa via Devel wrote:
> From: Peter Krempa <pkrempa@redhat.com>
> 
> Document both the behaviour if requested length isn't enough to read the
> file as well as the semantics of NUL-termination of the buffer.
> 
> Signed-off-by: Peter Krempa <pkrempa@redhat.com>
> ---
>  src/util/virfile.c | 140 ++++++++++++++++++++++++++++++++++++++++-----
>  1 file changed, 126 insertions(+), 14 deletions(-)
> 
> diff --git a/src/util/virfile.c b/src/util/virfile.c
> index fbcaf15429..bc3faedd4e 100644
> --- a/src/util/virfile.c
> +++ b/src/util/virfile.c
> @@ -1534,10 +1534,27 @@ saferead_lim(int fd, size_t max_len, size_t *length)
>  }
> 
> 
> -/* A wrapper around saferead_lim that merely stops reading at the
> - * specified maximum size.  */
> +/**
> + * virFileReadHeaderQuiet:

s/virFileReadHeaderQuiet/virFileReadHeaderFD/