Re: [PATCH v2 4/5] sysemu/block-backend: Document blk_read()/blk_pwrite()

[Eric Blake <eblake@redhat.com>]

On 5/15/20 4:19 AM, Philippe Mathieu-Daudé wrote:
> The blk_read()/blk_pwrite() return value is not obvious,

s/read/pread/ here and in the subject

> document it.
> 
> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com>
> ---

> +/**
> + * blk_pread:
> + *
> + * @blk: the block backend where the buffer content is going to be read from
> + * @offset: position in bytes to read at
> + * @buf: the data buffer
> + * @bytes: number of bytes to read
> + *
> + * Returns: the number of bytes read on success, or a negative errno otherwise.
> + */
>   int blk_pread(BlockBackend *blk, int64_t offset, void *buf, int bytes);

"the number of bytes read" is ambiguous - it sounds too much like the 
read() syscall where short reads are successful.  But blk_pread() never 
does short reads, on success, the result is exactly 'bytes'.

> +
> +/**
> + * blk_pwrite:
> + *
> + * @blk: the block backend where the buffer content is going to be written to
> + * @offset: position in bytes to write at
> + * @buf: the data buffer
> + * @bytes: number of bytes of @buf to write
> + * @flags: request flags
> + *
> + * Returns: the number of bytes consumed on success,

Ditto - we don't support short writes, so on success, it is always 'bytes'.

> + *          or a negative errno otherwise.
> + */
>   int blk_pwrite(BlockBackend *blk, int64_t offset, const void *buf, int bytes,
>                  BdrvRequestFlags flags);
>   int64_t blk_getlength(BlockBackend *blk);
> 

-- 
Eric Blake, Principal Software Engineer
Red Hat, Inc.           +1-919-301-3226
Virtualization:  qemu.org | libvirt.org