From ee2aeefa170b9806e719723f94ba933c90a9ae8b Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Wed, 4 Jan 2023 16:32:21 +0000 Subject: Add siovec doc, fix siovec_trunc, credit Ermine Signed-off-by: Laurent Bercot --- doc/libstddjb/siovec.html | 115 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 114 insertions(+), 1 deletion(-) (limited to 'doc/libstddjb') diff --git a/doc/libstddjb/siovec.html b/doc/libstddjb/siovec.html index d8eab35..7b65db4 100644 --- a/doc/libstddjb/siovec.html +++ b/doc/libstddjb/siovec.html @@ -21,7 +21,120 @@

The skalibs/siovec.h header

- TODO: write this documentation page. (Sorry!) + The following functions are declared in the skalibs/siovec.h header +and implemented in the libskarnet.a or libskarnet.so library. +

+ +

Purpose

+ +

+ These functions manipulate arrays of struct iovec containing +ranges of bytes, handling them as contiguous arrays. They're used, for +instance, in the skalibs implementation of circular buffers. +

+ +

Functions

+ +

+ size_t siovec_len (struct iovec const *v, unsigned int n)
+Returns the sum of the first n iov_len fields of the +v array - i.e. the total number of bytes contained in the +array represented by v of length n. +

+ +

+ size_t siovec_gather (struct iovec const *v, unsigned int n, char *s, size_t max)
+Gathers all the data scattered in ranges described by v of length +n into the space pointed to by s. +Specifically: the first v[0].iov_len bytes pointed to by +v[0].iov_base bytes are copied to s, then the first +v[1].iov_len bytes pointed to by v[1].iov_base are +appended to it, and so on, n times. +The function copies no more than max bytes. It +returns the total amount of bytes copied. +

+ +

+ size_t siovec_scatter (struct iovec const *v, unsigned int n, char const *s, size_t len)
+Scatters len bytes of data from s into the byte ranges +represented by array v of length n. (This is the opposite +of the siovec_gather() function.) +The first v[0].iov_len bytes of +s are copied to v[0].iov_base, then the following +v[1].iov_len bytes of s are copied to +v[1].iov_base, and so on up to len bytes or until +if the scatter array is full, i.e. siovec_len(v, n) bytes +have been copied. The function returns the total amount of bytes copied. +

+ +

+ size_t siovec_deal (struct iovec const *vj, unsigned int nj, struct iovec const *vi, unsigned int ni)
+Copies the data contained in the ranges represented by the array vi of +length ni to the ranges represented by the array vj of length +nj. +The first vi[0].iov_len bytes pointed to by vi[0].iov_base +are copied to vj[0].iov_base, up to vj[0].iov_len bytes, +moving on to vj[1].iov_base if it overflows; then the bytes pointed +to by vi[1].iov_base are copied to what space remains wherever the +writing pointer is, and so on until all the bytes in the ranges described by +vi have been copied or there is no more room left in the ranges +described by vj. +The function returns the total amount of bytes copied. +

+ +

+ size_t siovec_seek (struct iovec *v, unsigned int n, size_t len)
+Does the equivalent of p += len; if the byte ranges represented by +array v of size n were a single byte array pointed by p. +If v[0].iov_len is lesser than len, then v[0] is +zeroed out (set to { .iov_base = 0, .iov_len = 0 }), v[0].iov_len +bytes are deduced from len, and the same operation is repeated with +v[1], and so on. If every iovec gets zeroed out, the operation stops; +but if a v[i].iov_len is greater than the +remaining amount of bytes to deduce, that amount is substracted from +v[i].iov_len and added to v[i].iov_base. The function returns +the total number of bytes that have been deduced. +

+ +

+ unsigned int siovec_trunc (struct iovec *v, unsigned int n, size_t len)
+Truncates the last fields of v of size n so that the byte +ranges it represents have a total length of len or less. The +iov_len field of v[n-1] is decreased by len; if it would +be negative, then it's zeroed out and the remainder is taken from v[n-2] +instead, and so on. The function returns the new size of array v +with the tailing zeroed out members removed. It can only return 0 if len +is 0, which means all of v has been zeroed out. +

+ +

+ size_t siovec_bytechr (struct iovec const *v, unsigned int n, char c)
+Looks for the first occurence of c among the byte ranges represented by the members +of v. Returns its cumulative index, i.e. the position that c +would have if the byte ranges pointed to by members of v were a +single array. If there are no occurences of c, the function retunrs +siovec_len(v, n). +

+ +

+ size_t siovec_bytein (struct iovec const *v, unsigned int n, char const *sep, size_t seplen)
+Looks for the first occurence of any byte from the sep array of size +seplen among the byte ranges represented by the members of array v +of size n, and returns the cumulative index of the first one it finds. +

+ +

+ size_t siovec_search (struct iovec const *v, unsigned int n, char const *needle, size_t nlen)
+Looks for the string (as in array of bytes: null characters are supported) +needle of size nlen in the byte ranges represented by the +members of array v of size n, and returns the cumulative +index of the first occurrence it finds, or siovec_len(v, n) if it +cannot find one. Split strings are supported: if needle +starts at position v[i].iov_base + pos but is cut because it +reaches v[i].iov_len midstring, and the rest of needle +is available at v[i+1].iov_base, then the function will find it +(and return pos plus the sum length of all the v members +before i).

-- cgit v1.2.3