diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2014-09-18 18:55:44 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2014-09-18 18:55:44 +0000 |
| commit | 3534b428629be185e096be99e3bd5fdfe32d5544 (patch) | |
| tree | 210ef3198ed66bc7f7b7bf6a85e4579f455e5a36 /doc/libstddjb/allreadwrite.html | |
| download | skalibs-3534b428629be185e096be99e3bd5fdfe32d5544.tar.gz skalibs-3534b428629be185e096be99e3bd5fdfe32d5544.tar.xz skalibs-3534b428629be185e096be99e3bd5fdfe32d5544.zip | |
initial commit with rc for skalibs-2.0.0.0
Diffstat (limited to 'doc/libstddjb/allreadwrite.html')
| -rw-r--r-- | doc/libstddjb/allreadwrite.html | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/doc/libstddjb/allreadwrite.html b/doc/libstddjb/allreadwrite.html new file mode 100644 index 0000000..847c4e3 --- /dev/null +++ b/doc/libstddjb/allreadwrite.html @@ -0,0 +1,145 @@ +<html> + <head> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>skalibs: the allreadwrite library interface</title> + <meta name="Description" content="skalibs: the allreadwrite library interface" /> + <meta name="Keywords" content="skalibs c unix allreadwrite library libstddjb" /> + <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">libstddjb</a><br /> +<a href="../libskarnet.html">libskarnet</a><br /> +<a href="../index.html">skalibs</a><br /> +<a href="http://skarnet.org/software/">Software</a><br /> +<a href="http://skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>allreadwrite</tt> library interface </h1> + +<p> + The following functions are declared in the <tt>skalibs/allreadwrite.h</tt> header, +and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. +</p> + +<h2> General information </h2> + +<p> + <tt>allreadwrite</tt> is a set of IO function helpers. It's the +basis for safe reading and writing, either in blocking or in +non-blocking mode. The <a href="buffer.html">buffer</a> interface +relies heavily on <tt>allreadwrite</tt>. +</p> + +<p> + Unless the IO you need is very simple, you generally should not +be using the <tt>allreadwrite</tt> functions directly; you should +use higher-level APIs such as <a href="buffer.html>buffer</a> and +<a href="bufalloc.html">bufalloc</a>. +</p> + +<h2> Function types </h2> + +<p> +<code> typedef int iofunc_t (int fd, char *buf, unsigned int len) </code> <br /> +This is the simplified type of IO functions such as +<a href="http://www.opengroup.org/onlinepubs/9699919799/functions/read.html">read()</a> +and +<a href="http://www.opengroup.org/onlinepubs/9699919799/functions/write.html">write()</a>. +Unless your system's <tt>int</tt> is 64-bit, skalibs - which has been +optimized for small systems - does not support IO operations of more than +2 GB of data, for the sake of simplicity. In any case, it's always +possible to send data in several smaller chunks. +</p> + +<p> +<code> typedef unsigned int alliofunc_t (int fd, char *buf, unsigned int len) </code> <br /> +This is the type of an IO operation that expects <em>all</em> of its +<em>len</em> bytes to be sent or received, and that will loop around a +lower-level IO function until either <em>len</em> bytes have been +transmitted or an error has occurred. The return value is the actual +number of transmitted bytes; if this value is lesser than <em>len</em>, +it means that an error has occurred and <tt>errno</tt> is set. +</p> + +<h2> Functions </h2> + +<p> +<code> int sanitize_read (int r) </code> <br /> +Reading functions such as <tt>read()</tt> and <tt>fd_read</tt> return +a positive number when they succeed, -1 when they fail, and 0 when they +read an EOF. No data available on the descriptor when reading in +non-blocking mode is treated as a failure: -1 EWOULDBLOCK. But sometimes +(namely, in asynchronous IO loops) it's preferrable to handle EOF as an +exception condition and EWOULDBLOCK as a normal condition. +<tt>sanitize_read()</tt>, when applied to the result of a basic reading +function, returns 0 if <em>r</em> is -1 and errno is EWOULDBLOCK (or +EAGAIN). If <em>r</em> is zero, it returns -1 EPIPE. Else it returns <em>r</em>. +</p> + +<p> + (No system reading function can ever set errno to EPIPE, and the +semantics are appropriate, so EPIPE is a good candidate to signal EOF +on reading.) +</p> + +<p> +<code> unsigned int allreadwrite (iofunc_t *f, int fd, char *s, unsigned int len) </code> <br /> +*<em>f</em> must be a basic reading or writing function such as +<tt>fd_read</tt> or <tt>fd_write</tt>. <tt>allreadwrite()</tt> performs +*<em>f</em> on <em>fd</em>, <em>s</em> and <em>len</em> until <em>len</em> +bytes have been read or written, or until an error occurs. It returns the +total number of handled bytes, and sets errno if this number is not +<em>len</em>. <tt>allreadwrite</tt> may block if <em>fd</em> is in +blocking mode; if <em>fd</em> is in non-blocking mode, it might +set errno to EWOULDBLOCK or EAGAIN. +</p> + +<p> +<code> int fd_read (int fd, char *s, unsigned int len) </code> <br /> +<a href="safewrappers.html">Safe wrapper</a> around the +<a href="http://www.opengroup.org/onlinepubs/9699919799/functions/read.html">read()</a> +function. +</p> + +<p> +<code> int fd_write (int fd, char const *s, unsigned int len) </code> <br /> +<a href="safewrappers.html">Safe wrapper</a> around the +<a href="http://www.opengroup.org/onlinepubs/9699919799/functions/write.html">write()</a> +function. +</p> + +<p> +<code> int fd_recv (int fd, char *s, unsigned int len, unsigned int flags) </code> <br /> +<a href="safewrappers.html">Safe wrapper</a> around the +<a href="http://www.opengroup.org/onlinepubs/9699919799/functions/recv.html">recv()</a> +function. +</p> + +<p> +<code> int fd_send (int fd, char const *s, unsigned int len, unsigned int flags) </code> <br /> +<a href="safewrappers.html">Safe wrapper</a> around the +<a href="http://www.opengroup.org/onlinepubs/9699919799/functions/send.html">send()</a> +function. +</p> + +<p> +<code> unsigned int allread (int fd, char *s, unsigned int len) </code> <br /> +Equivalent to <code> allreadwrite(&fd_read, fd, s, len) </code>: attempts +to read <em>len</em> bytes from <em>fd</em> into <em>s</em>, looping around +<tt>fd_read()</tt> if necessary, until either <em>len</em> bytes are read or +an error occurs. EOF is reported as EPIPE. +</p> + +<p> +<code> unsigned int allwrite (int fd, char const *s, unsigned int len) </code> <br /> +Equivalent to <code> allreadwrite((iofunc_t *)&fd_write, fd, s, len) </code>: +attempts to write <em>len</em> bytes from <em>s</em> to <em>fd</em>, looping +around <tt>fd_write()</tt> if necessary, until either <em>len</em> bytes are +written or an error occurs. +</p> + +</body> +</html> |