From dcf6f5e15ecee4f593eeacbe0591c1addc004d92 Mon Sep 17 00:00:00 2001 From: Michael Tokarev Date: Sun, 11 Mar 2012 18:05:12 +0400 Subject: change iov_* function prototypes to be more appropriate Reorder arguments to be more natural, readable and consistent with other iov_* functions, and change argument names, from: iov_from_buf(iov, iov_cnt, buf, iov_off, size) to iov_from_buf(iov, iov_cnt, offset, buf, bytes) The result becomes natural English: copy data to this `iov' vector with `iov_cnt' elements starting at byte offset `offset' from memory buffer `buf', processing `bytes' bytes max. (Try to read the original prototype this way). Also change iov_clear() to more general iov_memset() (it uses memset() internally anyway). While at it, add comments to the header file describing what the routines actually does. The patch only renames argumens in the header, but keeps old names in the implementation. The next patch will touch actual code to match. Now, it might look wrong to pay so much attention to so small things. But we've so many badly designed interfaces already so the whole thing becomes rather confusing or error prone. One example of this is previous commit and small discussion which emerged from it, with an outcome that the utility functions like these aren't well-understdandable, leading to strange usage cases. That's why I paid quite some attention to this set of functions and a few others in subsequent patches. Signed-off-by: Michael Tokarev --- iov.h | 42 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 37 insertions(+), 5 deletions(-) (limited to 'iov.h') diff --git a/iov.h b/iov.h index 94d2f78..0b4acf4 100644 --- a/iov.h +++ b/iov.h @@ -12,12 +12,44 @@ #include "qemu-common.h" +/** + * count and return data size, in bytes, of an iovec + * starting at `iov' of `iov_cnt' number of elements. + */ +size_t iov_size(const struct iovec *iov, const unsigned int iov_cnt); + +/** + * Copy from single continuous buffer to scatter-gather vector of buffers + * (iovec) and back like memcpy() between two continuous memory regions. + * Data in single continuous buffer starting at address `buf' and + * `bytes' bytes long will be copied to/from an iovec `iov' with + * `iov_cnt' number of elements, starting at byte position `offset' + * within the iovec. If the iovec does not contain enough space, + * only part of data will be copied, up to the end of the iovec. + * Number of bytes actually copied will be returned, which is + * min(bytes, iov_size(iov)-offset) + */ size_t iov_from_buf(struct iovec *iov, unsigned int iov_cnt, - const void *buf, size_t iov_off, size_t size); + size_t offset, const void *buf, size_t bytes); size_t iov_to_buf(const struct iovec *iov, const unsigned int iov_cnt, - void *buf, size_t iov_off, size_t size); -size_t iov_size(const struct iovec *iov, const unsigned int iov_cnt); -size_t iov_clear(const struct iovec *iov, const unsigned int iov_cnt, - size_t iov_off, size_t size); + size_t offset, void *buf, size_t bytes); + +/** + * Set data bytes pointed out by iovec `iov' of size `iov_cnt' elements, + * starting at byte offset `start', to value `fillc', repeating it + * `bytes' number of times. + * If `bytes' is large enough, only last bytes portion of iovec, + * up to the end of it, will be filled with the specified value. + * Function return actual number of bytes processed, which is + * min(size, iov_size(iov) - offset). + */ +size_t iov_memset(const struct iovec *iov, const unsigned int iov_cnt, + size_t offset, int fillc, size_t bytes); + +/** + * Produce a text hexdump of iovec `iov' with `iov_cnt' number of elements + * in file `fp', prefixing each line with `prefix' and processing not more + * than `limit' data bytes. + */ void iov_hexdump(const struct iovec *iov, const unsigned int iov_cnt, FILE *fp, const char *prefix, size_t limit); -- cgit v1.1