[PATCH 2/2] doc: allreadwrite: document scatter/gatter functions

From: Jesse Young <jlyo_at_jlyo.org>
Date: Sun, 13 Jun 2021 20:46:01 -0500

---
 Document scatter/gatter functions as well as unsanitize_read() in the
 allreadwrite.h header.
 doc/libstddjb/allreadwrite.html    | 53 ++++++++++++++++++++++++++++++
 src/include/skalibs/allreadwrite.h |  5 ++-
 2 files changed, 55 insertions(+), 3 deletions(-)
diff --git a/doc/libstddjb/allreadwrite.html b/doc/libstddjb/allreadwrite.html
index 2619153..1c31022 100644
--- a/doc/libstddjb/allreadwrite.html
+++ b/doc/libstddjb/allreadwrite.html
_at__at_ -51,6 +51,18 _at__at_ and
 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/write.html">write()</a>.
 </p>
 
+<p>
+<code> typedef ssize_t iovfunc_t (int fd, struct iovec const *v, unsigned int vlen) </code> <br />
+This is the simplified type of IO functions such as
+<a href="https://www.opengroup.org/onlinepubs/9699919799/functions/readv.html">readv()</a>
+and
+<a href="https://www.opengroup.org/onlinepubs/9699919799/functions/writev.html">writev()</a>,
+where the content to perform IO on is specified as a
+<a href="siovec.html">scatter/gather array</a> of <em>vlen</em>
+elements instead of a single string.
+</p>
+
+
 <p>
 <code> typedef size_t alliofunc_t (int fd, char *buf, size_t len) </code> <br />
 This is the type of an IO operation that expects <em>all</em> of its
_at__at_ -82,6 +94,11 _at__at_ semantics are appropriate, so EPIPE is a good candidate to signal EOF
 on reading.)
 </p>
 
+<p>
+<code> ssize_t unsanitize_read (ssize_t r) </code> <br />
+Returns the inverse of <code>sanitize_read</code>.
+</p>
+
 <p>
 <code> size_t allreadwrite (iofunc_t *f, int fd, char *s, size_t len) </code> <br />
 *<em>f</em> must be a basic reading or writing function such as
_at__at_ -94,6 +111,14 _at__at_ blocking mode; if <em>fd</em> is in non-blocking mode, it might
 set errno to EWOULDBLOCK or EAGAIN.
 </p>
 
+<p>
+<code> size_t allreadwritev (iovfunc_t *f, int fd, struct iovec const *v, unsigned int vlen) </code> <br />
+Like <code> allreadwrite </code>
+but the content to perform IO on is specified as a
+<a href="siovec.html">scatter/gather array</a> of <em>vlen</em>
+elements instead of a single string.
+</p>
+
 <p>
 <code> ssize_t fd_read (int fd, char *s, size_t len) </code> <br />
 <a href="safewrappers.html">Safe wrapper</a> around the
_at__at_ -107,6 +132,20 _at__at_ function.
 <a href="https://www.opengroup.org/onlinepubs/9699919799/functions/write.html">write()</a>
 function.
 </p>
+<p>
+
+<code> ssize_t fd_readv (int fd, struct iovec const *v, unsigned int vlen) </code> <br />
+<a href="safewrappers.html">Safe wrapper</a> around the
+<a href="https://www.opengroup.org/onlinepubs/9699919799/functions/readv.html">readv()</a>
+function.
+</p>
+
+<p>
+<code> ssize_t fd_writev (int fd, struct iovec const *v, unsigned int vlen) </code> <br />
+<a href="safewrappers.html">Safe wrapper</a> around the
+<a href="https://www.opengroup.org/onlinepubs/9699919799/functions/writev.html">writev()</a>
+function.
+</p>
 
 <p>
 <code> ssize_t fd_recv (int fd, char *s, size_t len, unsigned int flags) </code> <br />
_at__at_ -138,5 +177,19 _at__at_ around <tt>fd_write()</tt> if necessary, until either <em>len</em> bytes are
 written or an error occurs.
 </p>
 
+<p>
+<code> size_t allreadv (int fd, struct iovec *v, unsigned int vlen) </code> <br />
+Like <tt>allread</tt>, but the bytes from <em>fd</em> are read into a
+<a href="siovec.html">scatter/gather array</a> of <em>vlen</em>
+elements instead of a single string.
+</p>
+
+<p>
+<code> size_t allwritev (int fd, struct iovec const *v, unsigned int vlen) </code> <br />
+Like <tt>allwrite</tt>, but the content to write is taken from a
+<a href="siovec.html">scatter/gather array</a> of <em>vlen</em>
+elements instead of a single string.
+</p>
+
 </body>
 </html>
diff --git a/src/include/skalibs/allreadwrite.h b/src/include/skalibs/allreadwrite.h
index 254d766..3df1ed1 100644
--- a/src/include/skalibs/allreadwrite.h
+++ b/src/include/skalibs/allreadwrite.h
_at__at_ -14,6 +14,8 _at__at_ extern size_t allreadwritev (iovfunc_t_ref, int, struct iovec const *, unsigned
 
 extern ssize_t fd_read (int, char *, size_t) ;
 extern ssize_t fd_write (int, char const *, size_t) ;
+extern ssize_t fd_readv (int, struct iovec const *, unsigned int) ;
+extern ssize_t fd_writev (int, struct iovec const *, unsigned int) ;
 
 extern ssize_t fd_recv (int, char *, size_t, unsigned int) ;
 extern ssize_t fd_send (int, char const *, size_t, unsigned int) ;
_at__at_ -23,7 +25,4 _at__at_ extern size_t allwrite (int, char const *, size_t) ;
 extern size_t allreadv (int, struct iovec const *, unsigned int) ;
 extern size_t allwritev (int, struct iovec const *, unsigned int) ;
 
-extern ssize_t fd_readv (int, struct iovec const *, unsigned int) ;
-extern ssize_t fd_writev (int, struct iovec const *, unsigned int) ;
-
 #endif
-- 
2.32.0
Received on Mon Jun 14 2021 - 03:46:01 CEST

This archive was generated by hypermail 2.4.0 : Mon Jun 14 2021 - 03:46:33 CEST