From 3534b428629be185e096be99e3bd5fdfe32d5544 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Thu, 18 Sep 2014 18:55:44 +0000 Subject: initial commit with rc for skalibs-2.0.0.0 --- doc/libstddjb/allreadwrite.html | 145 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 doc/libstddjb/allreadwrite.html (limited to 'doc/libstddjb/allreadwrite.html') 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 @@ + + + + + skalibs: the allreadwrite library interface + + + + + + +

+libstddjb
+libskarnet
+skalibs
+Software
+skarnet.org +

+ +

The allreadwrite library interface

+ +

+ The following functions are declared in the skalibs/allreadwrite.h header, +and implemented in the libskarnet.a or libskarnet.so library. +

+ +

General information

+ +

+ allreadwrite 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 buffer interface +relies heavily on allreadwrite. +

+ +

+ Unless the IO you need is very simple, you generally should not +be using the allreadwrite functions directly; you should +use higher-level APIs such as bufalloc. +

+ +

Function types

+ +

+ typedef int iofunc_t (int fd, char *buf, unsigned int len)
+This is the simplified type of IO functions such as +read() +and +write(). +Unless your system's int 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. +

+ +

+ typedef unsigned int alliofunc_t (int fd, char *buf, unsigned int len)
+This is the type of an IO operation that expects all of its +len bytes to be sent or received, and that will loop around a +lower-level IO function until either len 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 len, +it means that an error has occurred and errno is set. +

+ +

Functions

+ +

+ int sanitize_read (int r)
+Reading functions such as read() and fd_read 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. +sanitize_read(), when applied to the result of a basic reading +function, returns 0 if r is -1 and errno is EWOULDBLOCK (or +EAGAIN). If r is zero, it returns -1 EPIPE. Else it returns r. +

+ +

+ (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.) +

+ +

+ unsigned int allreadwrite (iofunc_t *f, int fd, char *s, unsigned int len)
+*f must be a basic reading or writing function such as +fd_read or fd_write. allreadwrite() performs +*f on fd, s and len until len +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 +len. allreadwrite may block if fd is in +blocking mode; if fd is in non-blocking mode, it might +set errno to EWOULDBLOCK or EAGAIN. +

+ +

+ int fd_read (int fd, char *s, unsigned int len)
+Safe wrapper around the +read() +function. +

+ +

+ int fd_write (int fd, char const *s, unsigned int len)
+Safe wrapper around the +write() +function. +

+ +

+ int fd_recv (int fd, char *s, unsigned int len, unsigned int flags)
+Safe wrapper around the +recv() +function. +

+ +

+ int fd_send (int fd, char const *s, unsigned int len, unsigned int flags)
+Safe wrapper around the +send() +function. +

+ +

+ unsigned int allread (int fd, char *s, unsigned int len)
+Equivalent to allreadwrite(&fd_read, fd, s, len) : attempts +to read len bytes from fd into s, looping around +fd_read() if necessary, until either len bytes are read or +an error occurs. EOF is reported as EPIPE. +

+ +

+ unsigned int allwrite (int fd, char const *s, unsigned int len)
+Equivalent to allreadwrite((iofunc_t *)&fd_write, fd, s, len) : +attempts to write len bytes from s to fd, looping +around fd_write() if necessary, until either len bytes are +written or an error occurs. +

+ + + -- cgit v1.2.3