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