NAME

buffer_alloc, buffer_free, buffer_read, buffer_read_fd, buffer_release, buffer_str, buffer_reset, buffer_pop, buffer_cmp, buffer_puts, buffer_putc, buffer_printf, buffer_vprintf, buffer_getline, buffer_getline_free, buffer_get_ptr, buffer_get_len, buffer_get_size — buffer structure

SYNOPSIS

#include <libks/buffer.h>

struct buffer *
buffer_alloc(size_t init_size);

void
buffer_free(struct buffer *bf);

struct buffer *
buffer_read(const char *path);

struct buffer *
buffer_read_fd(int fd);

char *
buffer_release(struct buffer *bf);

char *
buffer_str(struct buffer *bf);

void
buffer_reset(struct buffer *bf);

size_t
buffer_pop(struct buffer *bf, size_t n);

int
buffer_cmp(const struct buffer *a, const struct buffer *b);

int
buffer_puts(struct buffer *bf, const char *str, size_t len);

int
buffer_putc(struct buffer *bf, char c);

int
buffer_printf(struct buffer *bf, const char *fmt, ...);

int
buffer_vprintf(struct buffer *bf, const char *fmt, va_list ap);

const char *
buffer_getline(const struct buffer *bf, struct buffer_getline *it);

void
buffer_getline_free(struct buffer_getline *it);

const char *
buffer_get_ptr(const struct buffer *bf);

size_t
buffer_get_len(const struct buffer *bf);

size_t
buffer_get_size(const struct buffer *bf);

DESCRIPTION

The buffer structure stores a sequence of bytes, allowing its underlying storage to transparently grow and shrink over time. It exposes an interface similar to the one provided by stdio.h used to append contents to the buffer.

The buffer_alloc() function allocates a new buffer. The underlying storage is guaranteed to have a capacity of at least init_size bytes. Providing an accurate init_size is not strictly necessary but can reduce the number of reallocations.

The buffer_free() function frees the buffer and its underlying storage. If bf is NULL, nothing is done.

The buffer_read() function allocates a new buffer and populates it with the contents of the file located at path.

The buffer_read_fd() function allocates a new buffer and populates it with the contents read from fd.

The buffer_release() function returns a pointer to the underlying storage and disassociates it with the buffer. The caller is therefore required to free the returned pointer once appropriate. As the buffer is empty upon return, it can safely be reused.

The buffer_str() function behaves like buffer_release() but ensures that the underlying storage is NUL-terminated before disassociation.

The buffer_reset() function discards the buffer contents, effectively turning it into an empty buffer.

The buffer_pop() function removes n number of bytes from the buffer. If n is greater than the buffer length, the buffer is emptied. The return value reflects the number of removed bytes.

The buffer_cmp() function compares the given two buffers and returns zero if their contents are equal or non-zero otherwise.

The buffer_puts() function appends len number of bytes from str to the buffer.

The buffer_putc() function appends the character c to the buffer.

The buffer_printf() and buffer_vprintf() function appends the formatted string to the buffer. See printf(3) for further details on how fmt is interpreted.

The buffer_getline() function iterates over all lines in the buffer. The return pointer remains valid until buffer_getline() or buffer_getline_free() is called. Upon reaching the end, NULL is returned. The it argument must be zero initialized upon the first invocation. Note that buffer_getline_free() must only be called if not all lines are iterated over.

The buffer_getline_free() function frees the iterator object.

The buffer_get_ptr() function returns a pointer to the underlying storage. The same pointer only remains valid until buffer_release(), buffer_str(), buffer_reset(), buffer_puts(), buffer_putc(), buffer_printf() or buffer_vprintf() is called.

The buffer_get_len() function returns the length of the buffer.

The buffer_get_size() function returns the size of the buffer.

RETURN VALUES

buffer_alloc(), buffer_read() buffer_read_fd(), and buffer_str() returns NULL on error and sets errno accordingly.

buffer_puts(), buffer_putc(), buffer_printf() and buffer_vprintf() returns the number printed bytes on success. On failure, non-zero is returned and errno is set accordingly.

SEE ALSO

arena_buffer(3)

AUTHORS

Anton Lindqvist <anton@basename.se>