| Message ID | 20200515091924.14380-5-philmd@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | block: Documentation improvment | expand |
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); >
diff --git a/include/sysemu/block-backend.h b/include/sysemu/block-backend.h index 7996cb61bb..b693dfb8f0 100644 --- a/include/sysemu/block-backend.h +++ b/include/sysemu/block-backend.h @@ -155,7 +155,31 @@ BlockAIOCB *blk_aio_pwrite_zeroes(BlockBackend *blk, int64_t offset, int bytes, BdrvRequestFlags flags, BlockCompletionFunc *cb, void *opaque); int blk_make_zero(BlockBackend *blk, BdrvRequestFlags flags); + +/** + * 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); + +/** + * 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, + * 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);
The blk_read()/blk_pwrite() return value is not obvious, document it. Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> --- v2: 's/ - /: /' (stefanha) --- include/sysemu/block-backend.h | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+)