[PATCH] Document skalibs/siovec.h header

---
 doc/libstddjb/siovec.html | 95 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 94 insertions(+), 1 deletion(-)
diff --git a/doc/libstddjb/siovec.html b/doc/libstddjb/siovec.html
index d8eab35..6e72b6c 100644
--- a/doc/libstddjb/siovec.html
+++ b/doc/libstddjb/siovec.html
_at__at_ -21,7 +21,100 _at__at_
 <h1> The <tt>skalibs/siovec.h</tt> header </h1>
 
 <p>
- TODO: write this documentation page. (Sorry!)
+  The following functions are declared in the <tt>skalibs/siovec.h</tt> header
+and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
+</p>
+
+<h2> Purpose </h2>
+<p>
+  These functions make it easier to deal with arrays of <tt>struct iovec</tt>
+and allow to think about them as a contigous arrays of <tt>char</tt>.
+</p>
+
+<h2> Functions </h2>
+
+<p>
+<code> size_t siovec_len (struct iovec const *v, unsigned int n) </code> <br>
+Returns the sum of <tt>iov_len</tt> fields in <tt>v</tt> array. That is, the
+value returned is the total lengths of arrays represented by <tt>n</tt> elements
+of <tt>v</tt>.
+</p>
+
+<p>
+<code> size_t siovec_gather (struct iovec const *v, unsigned int n, char *s,
+  size_t max) </code> <br>
+Sequentially copies contents of arrays represented by <tt>n</tt> elements of
+<tt>v</tt> into <tt>s</tt> array. That is, <tt>v[0].iov_base</tt> bytes are
+copied to first <tt>v[0].iov_len</tt> bytes of <tt>s</tt>, bytes of
+<tt>v[1].iov_base</tt> are copied to the next <tt>v[1].iov_len</tt> bytes of
+<tt>s</tt>, and so on. This function copies no more than <tt>max</tt> bytes. It
+returns the total amount of bytes copied.
+</p>
+
+<p>
+<code> size_t siovec_scatter (struct iovec const *v, unsigned int n, char const
+  *s, size_t len) </code> <br>
+Sequentially copies contents of <tt>s</tt> into arrays represented by <tt>v</tt>
+array of length <tt>n</tt>. That is, first <tt>v[0].iov_len</tt> bytes of
+<tt>s</tt> are copied to <tt>v[0].iov_base</tt>, next <tt>v[1].iov_len</tt> are
+copied to <tt>v[1].iov_base</tt>, and so on. This function copies no more than
+<tt>len</tt> bytes. It returns the total amount of bytes copied.
+</p>
+
+<p>
+<code> size_t siovec_deal (struct iovec const *vj, unsigned int nj, struct iovec
+  const *vi, unsigned int ni) </code> <br>
+Copies contents of arrays represented by <tt>ni</tt> members of <tt>vi</tt> into
+arrays represented by <tt>nj</tt> members of <tt>vj</tt>. That is, contents of
+<tt>vi[0].iov_base</tt> are copied to <tt>vj[0].iov_base</tt>, proceeding to
+next members of <tt>vj</tt> if <tt>vj[0].iov_len &lt; vi[0].iov_len</tt>, until
+<tt>vi[0].iov_len</tt> bytes are copied or <tt>vj</tt> goes out of space. Then
+the same thing is done with <tt>vi[1]</tt> and so on. This function return the
+total amount of bytes copied.
+</p>
+
+<p>
+<code> size_t siovec_seek (struct iovec *v, unsigned int n, size_t len) </code>
+<br>
+Zeroes maximal number of first members of array <tt>v</tt> of length <tt>n</tt>
+such that their original <tt>iov_len</tt>s sum up to a number which is not more
+than <tt></tt>.  This sum is substracted from <tt>len</tt>. If there are any
+non-zeroed members of <tt>v</tt> left, <tt>iov_base</tt> of first such member is
+advanced by remainder of <tt>len</tt>, and <tt>iov_len</tt> of this member is
+decreased by the remainder. This function returns the minimum of
+<tt>siovec_len(v, n)</tt> and <tt>len</tt>.
+
+The analoguous action on a single array is advancing its pointer by <tt>len</tt>
+or the length of that array if it is less than <tt>len</tt>.
+</p>
+
+<p>
+<code> unsigned int siovec_trunc (struct iovec *v, unsigned int n, size_t len)
+</code> <br>
+Sets to zero <tt>iov_len</tt> field of first members of array <tt>v</tt> such
+that their original <tt>iov_lengths</tt> sum up to number which is not more than
+<tt>len</tt>. This sum is substracted from <tt>len</tt>. If there are any
+untouched members left, <tt>iov_len</tt> of the first such structure is
+decreased by the remainder of <tt>len</tt>. This function returns the amount of
+unmodified members.
+</p>
+
+<p>
+<code> size_t siovec_bytechr (struct iovec const *v, unsigned int n, char c)
+</code> <br>
+Looks for first occurence of <tt>c</tt> among arrays represented by the members
+of <tt>v</tt>. Returns its <em>cumulative index</em>, i.e. the index that
+character would have if arrays represented by the members of <tt>v</tt> were a
+single array. If there is no occurences of <tt>c</tt>, the function retunrs
+<tt>siovec_len(v, n)</tt>.
+</p>
+
+<p>
+<code> size_t siovec_bytein (struct iovec const *v, unsigned int n, char const
+  *sep, size_t seplen) </code> <br>
+Looks for the first occurence of any byte from <tt>sep</tt> array of size
+<tt>seplen</tt> among arrays represented by the members of <tt>v</tt>. Returns
+cumulative index of such a byte (see <tt>siovec_bytechr</tt>).
 </p>
 
 </body>
-- 
2.34.1