[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v2 4/5] sysemu/block-backend: Document blk_read()/blk_pwrite(
From: |
Eric Blake |
Subject: |
Re: [PATCH v2 4/5] sysemu/block-backend: Document blk_read()/blk_pwrite() |
Date: |
Fri, 15 May 2020 12:43:41 -0500 |
User-agent: |
Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.7.0 |
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é <address@hidden>
---
+/**
+ * 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
- [PATCH v2 0/5] block: Documentation improvment, Philippe Mathieu-Daudé, 2020/05/15
- [PATCH v2 1/5] qemu/osdep: Document qemu_memalign() and friends, Philippe Mathieu-Daudé, 2020/05/15
- [PATCH v2 2/5] qemu/bitmap: Document bitmap_new() returned pointer, Philippe Mathieu-Daudé, 2020/05/15
- [PATCH v2 3/5] block/block: Document BlockSizes fields, Philippe Mathieu-Daudé, 2020/05/15
- [PATCH v2 4/5] sysemu/block-backend: Document blk_read()/blk_pwrite(), Philippe Mathieu-Daudé, 2020/05/15
- Re: [PATCH v2 4/5] sysemu/block-backend: Document blk_read()/blk_pwrite(),
Eric Blake <=
- [PATCH v2 5/5] sysemu/block-backend: Document blk_get_max_iov() returned value, Philippe Mathieu-Daudé, 2020/05/15