skalibs: the buffer header
Keywords: skalibs header buffer buffering stdio

libstddjb
libskarnet
skalibs
Software
skarnet.org

# The `buffer` library interface

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

## General information

skalibs provides convenience structures and functions to perform buffered I/O. These structures and functions abstract direct calls to `read` or `write`; they're meant to be used in place of `stdio.h` primitives. Unlike `stdio`, they can be used with non-blocking file descriptors.

A buffer is a structure containing the following fields:

- op: a pointer to a function performing I/O. This is the function that will be called anytime the buffer needs to acquire (or flush) data to its underlying fd.
- fd: the fd from which data will be read or written.
- c: a circular buffer used to store data.

Users should not need to interact directly with any of these fields. They are initialized by `buffer_init` or `BUFFER_INIT`. Ulterior interactions with the buffer should only be done with the various dedicated functions.

## Functions

`ssize_t buffer_put (buffer *b, char const *buf, size_t len)`
Write the len bytes pointed to by buf to buffer b. Returns the number of bytes written if it succeeds, or -1 and sets errno if it fails.

`ssize_t buffer_puts (buffer *b, char const *s)`
Write the string s, terminating nul-byte excepted, to buffer b. Returns the number of bytes written if it succeeds, or -1 and sets errno if it fails.

`int buffer_flush(buffer *b)`
Flushes the buffer b. Returns 1 if it succeeds, 0 and sets errno if it fails.

`ssize_t buffer_get (buffer *b, char *s, size_t len)`
Read len bytes from buffer b and write them into s. Retuns the number of bytes read if it succeeds, or -1 and sets errno if it fails.

The above are the most important and fundamental functions for buffering. Other functions can be found in the same header and their prototypes are self-explaining. More may be documented here later.