outbuf -- buffered output
#include <afblib/outbuf.h>
typedef struct outbuf {
int fd;
stralloc buf;
} outbuf;
ssize_t outbuf_write(outbuf* obuf, void* buf, size_t size); int outbuf_putchar(outbuf* obuf, char ch); bool outbuf_flush(outbuf* obuf); void outbuf_free(outbuf* obuf);
These functions provide a simple and efficient interface for buffered output. They are mainly useful in connection with pipelines and network connections. In case of bidirectional communication channels, it might be useful to use the inbuf interface as well. An input and outbuf buffer can be used in parallel for the same file descriptor.
There is no such method called open or init. Instead, the structure needs to be initialized, either using an initializer, e.g.
int fd;
// fd = open(...);
outbuf obuf = {fd}; // the file descriptor is the first component
or by using a compound-literal (C99), e.g.
int fd;
outbuf obuf;
// fd = open(...);
obuf = (outbuf) {fd};
Unlike the stdio, outbuf uses no buffers of a fixed size. Instead, the outbuf buffer grows dynamically until outbuf_flush gets called. This gives, in comparison to the stdio, the programmer full control when output is sent over the file descriptor.
The function outbuf_write is works like write(2) but stores everything into the output buffer. outbuf_putchar is a convenient shorthand for single character write operations. outbuf_flush copies the contents of the output buffer to the file descriptor. outbuf_flush invokes, if neccessary, write(2) multiple times until everything is written or an error occures. In case of EINTR errors, the write operation is automatically retried again. outbuf_free frees the memory associated with the output buffer.
outbuf_write returns the number of bytes written, and -1 in case of errors. outbuf_putchar returns the character written, or -1 in case of an error. outbuf_flush returns true in case of success, and false otherwise.
Andreas F. Borchert