util: virfile: Document the various functions for reading from file/fd

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>
Reviewed-by: Pavel Hrdina <phrdina@redhat.com>

diff --git a/src/util/virfile.c b/src/util/virfile.c
index fbcaf15429ce8c9ed38ad5a93c0f127476575665..e6e5444a9048856097597cd3dc21b0f35f02edd6 100644 (file)
--- 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.  */
+/**
+ * virFileReadHeaderFD:
+ * @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.