buffer.h File Reference

String Buffer Operations. More...

`#include <stdlib.h>`
`#include <stdarg.h>`
`#include <string.h>`

Go to the source code of this file.

## Data Structures

struct | buffer

## Macros

#define | buffer_dup(b, buf)
| Make a heap allocated copy of the buffer.
#define | buffer_putstring(b, s)
| Appends the string to the end of the buffer.
#define | buffer_putliteral(b, l)
| Appends the string literal to the end of the buffer.
#define | buffer_tostring(b)
| Returns the buffer as a string.
#define | BUFFER_STACK(name, size)
| Allocate a buffer named name' on the stack of at most size' bytes.
#define | BUFFER_STACK_ABORT(name, size)
| Allocate a buffer named name' on the stack of at most size' bytes.
#define | BUFFER_STACK_PRINT(name, size, ...)
| Allocate and print to a buffer named name' on the stack of at most size' bytes.

## Functions

void | buffer_init (buffer_t *b)
| Initialize a buffer.
void | buffer_ubuf (buffer_t *b, char *buf, size_t len)
| Use the provided buffer as a starting buffer.
void | buffer_max (buffer_t *b, size_t max)
| Set the maximum size of the buffer.
void | buffer_abortonfailure (buffer_t *b, int abortonfailure)
| Set the buffer to call fatal(...) on error instead of returning an error code.
void | buffer_free (buffer_t *b)
| Free any resources and memory in use by a buffer.
int | buffer_dupl (buffer_t *b, char **buf, size_t *l)
| Make a heap allocated copy of the buffer.
int | buffer_putvfstring (buffer_t *b, const char *format, va_list ap)
| Print the formatted output to the buffer.
int | buffer_putfstring (buffer_t *b, const char *format,...) __attribute__((format(printf
| Appends the formatted output to the buffer.
int | buffer_putlstring (buffer_t *b, const char *str, size_t len)
| Appends the string to the end of the buffer.
const char * | buffer_tolstring (buffer_t *b, size_t *size)
| Returns the buffer as a string.
void | buffer_rewind (buffer_t *b, size_t n)
| Rewinds the buffer to position n.
size_t | buffer_pos (buffer_t *b)
| Get the current position in the buffer.
int | buffer_grow (buffer_t *b, size_t n)
| Make room for at least n additional chars.
int | buffer_seek (buffer_t *b, size_t pos)
| Seek to a position.

## Detailed Description

String Buffer Operations.

You can use the buffer in the same way you would print to a file. Use the buffer to do formatted printing. When you are done retrieve the final string using buffer_tostring.

## Macro Definition Documentation

## buffer_dup

#define buffer_dup | ( |  | b,
|  |  | buf )

Value:
(buffer_dupl(b,buf,NULL))
buffer_dupl
int buffer_dupl(buffer_t *b, char **buf, size_t *l)
Make a heap allocated copy of the buffer.

Make a heap allocated copy of the buffer.

Parameters

  b | The buffer to copy.
  buf | A place to store the copy pointer.

Returns
  -1 on error.

## buffer_putstring

#define buffer_putstring | ( |  | b,
|  |  | s )

Value:
(buffer_putlstring(b,s,strlen(s)))
buffer_putlstring
int buffer_putlstring(buffer_t *b, const char *str, size_t len)
Appends the string to the end of the buffer.

Appends the string to the end of the buffer.

Length derived via strlen.

Parameters

  b | The buffer to fill.
  s | The string to append.

Returns
  bytes added (excluding NUL) or -1 on error.

## buffer_putliteral

#define buffer_putliteral | ( |  | b,
|  |  | l )

Value:
(buffer_putlstring(b,l "",sizeof(l)-1))

Appends the string literal to the end of the buffer.

Length derived via sizeof.

Parameters

  b | The buffer to fill.
  l | The literal string to append.

Returns
  bytes added (excluding NUL) or -1 on error.

## buffer_tostring

#define buffer_tostring | ( |  | b | ) |

Value:
buffer_tolstring(b, NULL)
buffer_tolstring
const char * buffer_tolstring(buffer_t *b, size_t *size)
Returns the buffer as a string.

Returns the buffer as a string.

The string is no longer valid after deleting the buffer. A final ASCII NUL character is guaranteed to terminate the string.

Parameters

  b | The buffer.

Returns
  The buffer as a string with a NUL terminator.

## BUFFER_STACK

#define BUFFER_STACK | ( |  | name,
|  |  | size )

Value:
buffer_t name[1];\
char name##_ubuf[size > BUFFER_INISIZ ? size : 1]; /* Unfortunately, we can't conditionally allocate this ubuf array. Use char[1] if less than BUFFER_INISIZ */\
buffer_init(name);\
buffer_max(name, size);\
buffer_ubuf(name, name##_ubuf, size); /* if this is less than BUFFER_INISIZ, then B->initial is still used. */

Allocate a buffer named name' on the stack of at most size' bytes.

Does not abort on failure, but hits the max size and drops further bytes written. You can turn on aborts on failure manually using buffer_abortonfailure or using BUFFER_STACK_ABORT. You do not need to call buffer_free(name) because nothing is ever allocated on the heap. This is defined as a macro.

Parameters

  name | The name of the buffer.
  size | The maximum size of the buffer.

## BUFFER_STACK_ABORT

#define BUFFER_STACK_ABORT | ( |  | name,
|  |  | size )

Value:
BUFFER_STACK(name,size);\
buffer_abortonfailure(name, 1);
BUFFER_STACK
#define BUFFER_STACK(name, size)
Allocate a buffer named name' on the stack of at most size' bytes.
Definition buffer.h:203

Allocate a buffer named name' on the stack of at most size' bytes.

This works the same as BUFFER_STACK but also sets the abort flag on the buffer. This is defined as a macro.

Parameters

  name | The name of the buffer.
  size | The maximum size of the buffer.

## BUFFER_STACK_PRINT

#define BUFFER_STACK_PRINT | ( |  | name,
|  |  | size,
|  |  | ... )

Value:
BUFFER_STACK(name,size);\
buffer_putfstring(name, __VA_ARGS__);

Allocate and print to a buffer named name' on the stack of at most size' bytes.

This macro uses BUFFER_STACK to allocate the buffer. Variable arguments are passed to buffer_putfstring, starting with the format string.

Parameters

  name | The name of the buffer.
  size | The maximum size of the buffer.

## Function Documentation

## buffer_init()

void buffer_init | ( | buffer_t * | b | ) |

Initialize a buffer.

    The buffer includes a reasonably sized starting buffer as part of its
    definition.  Usually this means for small strings being built, nothing is
    ever allocated on the heap. You can specify a larger starting buffer if
    this is inadequate.

    @param b The buffer to initialize.

## buffer_ubuf()

void buffer_ubuf | ( | buffer_t * | b,
|  | char * | buf,
|  | size_t | len )

Use the provided buffer as a starting buffer.

    This function should only be called before any work is done on the buffer.
    The user buffer is only used if it is larger than the internal starting
    buffer.

    @param b   The buffer.
    @param buf A starting buffer to initially use to avoid allocating memory on the heap. (can be NULL)
    @param len The length of the buffer. (ignored if buf == NULL)

## buffer_max()

void buffer_max | ( | buffer_t * | b,
|  | size_t | max )

Set the maximum size of the buffer.

    @param b   The buffer.
    @param max The maximum amount of memory to allocate. (0 is unlimited)

## buffer_abortonfailure()

void buffer_abortonfailure | ( | buffer_t * | b,
|  | int | abortonfailure )

Set the buffer to call fatal(...) on error instead of returning an error code.

    @param b                The buffer.
    @param abortonfailure   Kill the process on errors. (you no longer have to check returns)

## buffer_free()

void buffer_free | ( | buffer_t * | b | ) |

Free any resources and memory in use by a buffer.

Parameters

  b | The buffer to free.

## buffer_dupl()

int buffer_dupl | ( | buffer_t * | b,
|  | char ** | buf,
|  | size_t * | l )

Make a heap allocated copy of the buffer.

Parameters

  b | The buffer to copy.
  buf | A place to store the copy pointer.
  l | The length of the string.

Returns
  -1 on error.

## buffer_putvfstring()

int buffer_putvfstring | ( | buffer_t * | b,
|  | const char * | format,
|  | va_list | ap )

Print the formatted output to the buffer.

The format string follows the same semantics as the UNIX vprintf function. buffer_putvfstring does not call the variable argument macros va_(start|end) on ap.

Parameters

  b | The buffer to fill.
  format | The format string.
  ap | The variable argument list for the format string.

Returns
  bytes added (excluding NUL) or -1 on error.

## buffer_putfstring()

int buffer_putfstring | ( | buffer_t * | b,
|  | const char * | format,
|  |  | ... )

Appends the formatted output to the buffer.

The format string follows the same semantics as the UNIX vprintf function.

Parameters

  b | The buffer to fill.
  format | The format string.
  ... | The variable arguments for the format string.

Returns
  bytes added (excluding NUL) or -1 on error.

## buffer_putlstring()

int buffer_putlstring | ( | buffer_t * | b,
|  | const char * | str,
|  | size_t | len )

Appends the string to the end of the buffer.

Parameters

  b | The buffer to fill.
  str | The string to append.
  len | The length of the string.

Returns
  bytes added (excluding NUL) or -1 on error.

## buffer_tolstring()

const char * buffer_tolstring | ( | buffer_t * | b,
|  | size_t * | size )

Returns the buffer as a string.

The string is no longer valid after deleting the buffer. A final ASCII NUL character is guaranteed to terminate the string.

Parameters

  b | The buffer.
  size | The size of the string is placed in this variable. Can be NULL.

Returns
  The buffer as a string with a NUL terminator.

## buffer_rewind()

void buffer_rewind | ( | buffer_t * | b,
|  | size_t | n )

Rewinds the buffer to position n.

    @param b The buffer.
    @param n The position to rewind to.

## buffer_pos()

size_t buffer_pos | ( | buffer_t * | b | ) |

Get the current position in the buffer.

    @param b The buffer.
    @return The current position.

## buffer_grow()

int buffer_grow | ( | buffer_t * | b,
|  | size_t | n )

Make room for at least n additional chars.

Parameters

  b | The buffer.
  n | Number of bytes to add to existing buffer.

Returns
  -1 on error.

## buffer_seek()

int buffer_seek | ( | buffer_t * | b,
|  | size_t | pos )

Seek to a position.

Similar to buffer_rewind(), but allows seeking past the end of the buffer. Note that seeking beyond the currently allocated memory may result in a buffer filled with garbage data (but still null-terminated).

Parameters

  b | The buffer.
  pos | Absolute position to seek to.

Returns
  -1 on error.