NAME
buffer.h - I/O buffer interface
SYNOPSIS
#include <limb/buffer.h>
DESCRIPTION
This header defines required functions to performed buffered I/O operations.
This header is a complement to skalibs' own header, intended to be used as a "replacement". However, instead of re-inventing the wheel, it depends/includes skalibs' header, and some of the functions below are actually implemented in skalibs, or macros to such functions.
Types
The following types are defined :
buffer
An opaque structure representing an I/O buffer.
Constants
The following constants are defined :
BUFFER_ZERO
Value to initialize a stack-allocated buffer to.
BUFFER_INSIZE, BUFFER_OUTSIZE, BUFFER_ERRSIZE, BUFFER_INSIZE_SMALL, BUFFER_OUTSIZE_SMALL
Buffer sizes of buffer_0, buffer_1, buffer_2, buffer_0small, and buffer_1small respectively.
PUTMSG_FLUSH, PUTMSG_TOGGLE_ESC, PUTMSG_ESC, PUTMSG_UINT_NEXT, PUTMSG_INT_NEX, PUTMSG_ERR_NEXT, PUTMSG_LEN_NEXT, PUTMSG_HEX_NEXT, PUTMSG_DUMP_NEXT, ESC
Can be used as a string given to buffer_putmsg(3) with a special meaning.
Macros
The following macros are defined :
BUFFER_INIT(fn, fd, buf, len)
Value to initialize a statck-allocated buffer to, set to use function fn
with file descriptor fd and memory pointed by buf of length len bytes
PUTMSG_UINT(n), PUTMSG_INT(n), PUTMSG_ERR(n),
PUTMSG_LEN(data,dlen), PUTMSG_HEX(data,dlen),
PUTMSG_DUMP(data,dlen)
PMUINT(n), PMINT(n), PMERR(n), PMLEN(data,dlen),
PMHEX(data,dlen), PMDMP(data,dlen)
Can be used for special processing to buffer_putmsg(3).
Objects
The following objects are defined :
buffer_0
A reading buffer connected to fd 0, aka stdin
buffer_1
A writing buffer connected to fd 1, aka stdout
buffer_2
A writing buffer connected to fd 2, akak stderr
buffer_0small
Similar to buffer_0 but with a smaller buffer size. Note that you should only use either one or the other, but never mix them both.
buffer_1small
Similar to buffer_1 but with a smaller buffer size. Note that you should only use either one or the other, but never mix them both.
buffer_0f1
Similar to buffer_0 but will first try to flush buffer_1 and only then attempt to read from stdin - A failure to flush buffer_1 will cause a failure to fill buffer_0f1 without having attempted to read from its file descriptor. Note that you should only ever use a single buffer per file descriptor.
Functions
The following functions/macros are defined :
Initialize a buffer.
Operational function to initialize a reading buffer.
Operational function to initialize a write buffer.
Writing
Flush a buffer.
To write given data in patrim(5)-encoded format.
Similar to buffer_patrim_put(3) put using vectors for actual data.
Write data of specified length to a buffer, flushing it if needed.
Similar to buffer_put(3) but with a different interface.
Write data of specified length to a buffer and flush it.
Write data of specified length to a buffer without flushing it.
To write given data encoded in base32.
To write given data encoded in base64.
To write given data from a specified offset whilst escaping characters as needed.
Similar to buffer_putescall(3) but without a starting offset into given data.
Similar but for a NUL-terminated string.
Write data of specified length to a buffer and flush it.
To write a file header of 32bit big-endian magic & pack-trimmed version.
To write given data as hexadecimal dump.
To write a message, given as an array of NUL-terminated strings.
Write data of specified length to a buffer without flushing it.
Similar to buffer_put(3) but with vectors.
Similar to buffer_putall(3) but with vectors.
Similar to buffer_putallflush(3) but with vectors.
Similar to buffer_putallnoflush(3) but with vectors.
Similar to buffer_putflush(3) but with vectors.
Similar to buffer_putnoflush(3) but with vectors.
Similar to buffer_put(3) but with a NUL-terminated string.
Similar to buffer_putall(3) put with a NUL-terminated string.
Similar to buffer_putallflush(3) but with a NUL-terminated string.
Similar to buffer_putallnoflush(3) but with a NUL-terminated string.
Similar to buffer_putflush(3) but with a NUL-terminated string.
Similar to buffer_putnofhlush(3) but with a NUL-terminated string.
Removes data from the buffer.
Peek vectors of available space to write into a buffer.
Seek into a writing buffer.
Reading
Fill a buffer.
Get data from a buffer, filling it if needed.
Similar to buffer_get(3) but with a different interface.
Get data from a buffer without filling it.
Get a file header of 32bit big-endian magic & pack-trimmed version from a buffer.
Get data from a buffer without filling it.
To read data from buffer up to a given character.
Similar to buffer_get(3) but with vectors.
Similar to buffer_getall(3) but with vectors.
Similar to buffer_getallnofill(3) but with vectors.
Similar to buffer_butnofill(3) but with vectors.
To read patrim(5)-encoded data.
Peek vectors of available data into a buffer.
Seek into a reading buffer.
"Restores" data into a buffer.
Utility
Returns the total length of a buffer.
Similar to buffer_len(3).
Returns available space in a buffer.
Returns whether or not a buffer is empty.
Returns whether or not a buffer is full.
Returns the file descriptor associated with a buffer.
Simimar to buffer_fd(3).
Returns whether or not a buffer can be filled, i.e. is not full.
Returns whether or not a buffer can be flushed, i.e. is not empty.