Buffer

Overview

The Buffer module can be thought as the dual of the String module for generic data buffers. The exposed primitives provide hooks for the typical life-cycle of a data buffer: ex-nihil creation or loading from external source, manipulation, possible data printing, raw data extraction and/or dump to non-volatile storage, and disposal.

Typedefs

typedef struct u_buf_s u_buf_t
 The basic buffer type. Internally it hides the data buffer which can be accessed via u_buf_ptr, and related size indicators (both total u_malloc'd buffer size, and the number of actually used bytes) which are accessed via u_buf_size and u_buf_len respectively.

Functions

int u_buf_append (u_buf_t *ubuf, const void *data, size_t size)
 Append data to the buffer.
int u_buf_clear (u_buf_t *ubuf)
 Clear a buffer.
int u_buf_create (u_buf_t **pubuf)
 Create a new buffer.
int u_buf_detach (u_buf_t *ubuf)
 Give up ownership of the u_buf_t data block.
int u_buf_free (u_buf_t *ubuf)
 Free a buffer.
int u_buf_load (u_buf_t *ubuf, const char *filename)
 Fill a buffer object with the content of a file.
int u_buf_printf (u_buf_t *ubuf, const char *fmt,...)
 Append a string to the given buffer.
int u_buf_reserve (u_buf_t *ubuf, size_t size)
 Enlarge the memory allocated to a given buffer.
int u_buf_save (u_buf_t *ubuf, const char *filename)
 Save buffer to file.
int u_buf_set (u_buf_t *ubuf, const void *data, size_t size)
 Set the value of a buffer.
ssize_t u_buf_len (u_buf_t *ubuf)
 Return the number of used bytes in the supplied buffer.
ssize_t u_buf_size (u_buf_t *ubuf)
 Return the total size of the data block allocated by the buffer.
void * u_buf_ptr (u_buf_t *ubuf)
 Return the pointer to the internal data block.
int u_buf_shrink (u_buf_t *ubuf, size_t newlen)
 Removes bytes from the tail of the buffer.

Function Documentation

int u_buf_append ( u_buf_t *  ubuf,
const void *  data,
size_t  size 
)

Append size bytes of data to the given buffer. If needed the buffer will be transparently enlarged.

Parameters:
ubuf an already allocated u_buf_t object
data a reference to the data block that will be appended
size the number of bytes to append
Return values:
0 on success
~0 on failure

Definition at line 77 of file buf.c.

References u_buf_reserve().

Referenced by u_buf_set().

int u_buf_clear ( u_buf_t *  ubuf  ) 

Reset the internal used bytes indicator. Note that the memory allocated by the buffer object won't be u_free'd until u_buf_free is called.

Parameters:
ubuf a previously allocated u_buf_t object
Return values:
0 on success
~0 on failure (i.e. NULL ubuf supplied)

Definition at line 233 of file buf.c.

Referenced by u_buf_load(), and u_buf_set().

int u_buf_create ( u_buf_t **  pubuf  ) 

Create a new u_buf_t object and save its reference to *ps.

Parameters:
pubuf result argument: on success it will get the new u_buf_t object
Return values:
0 on success
~0 on error

Definition at line 402 of file buf.c.

References u_zalloc().

int u_buf_detach ( u_buf_t *  ubuf  ) 

Give up ownership of the data block of the supplied u_buf_t object ubuf. Note that u_free won't be called on it, so the caller must u_free the buffer later on. Before calling u_buf_detach, use u_buf_ptr to get the pointer of the data block, and possibly u_buf_size and u_buf_len to get its total size and actually used length.

Parameters:
ubuf a previously allocated u_buf_t object
Return values:
0 on success
~0 on failure (i.e. NULL ubuf supplied)

Definition at line 174 of file buf.c.

int u_buf_free ( u_buf_t *  ubuf  ) 

Release all resources and free the given buffer object.

Parameters:
ubuf buffer object
Return values:
0 on success
~0 on error

Definition at line 324 of file buf.c.

References u_free().

ssize_t u_buf_len ( u_buf_t *  ubuf  ) 

Return the number of bytes actually used in the supplied u_buf_t object ubuf

Parameters:
ubuf a previously allocated u_buf_t object
Returns:
the number of used bytes or -1 if the u_buf_t reference is invalid

Definition at line 215 of file buf.c.

Referenced by u_buf_save().

int u_buf_load ( u_buf_t *  ubuf,
const char *  filename 
)

Open filename and copy its whole content into the given buffer ubuf

Parameters:
ubuf an already allocated u_buf_t object
filename path of the source file
Return values:
0 on success
~0 on failure

Definition at line 111 of file buf.c.

References u_buf_clear(), and u_buf_reserve().

int u_buf_printf ( u_buf_t *  ubuf,
const char *  fmt,
  ... 
)

Create a NUL-terminated string from the printf(3) like arguments and append it to the given u_buf_t object. The length of the appended string (NOT including the ending \0) will be added to the current length of the buffer (u_buf_len).

Parameters:
ubuf a previously allocated u_buf_t object
fmt printf(3) format string
... variable list of arguments used by the fmt
Return values:
0 on success
~0 on error

Definition at line 349 of file buf.c.

References u_buf_reserve().

void * u_buf_ptr ( u_buf_t *  ubuf  ) 

Return a generic pointer to the data block allocated by the u_buf_t object ubuf.

Parameters:
ubuf a previously allocated buffer object
Returns:
the pointer to the internal data block of NULL if an invalid u_buf_t reference is supplied

Definition at line 282 of file buf.c.

Referenced by u_buf_save().

int u_buf_reserve ( u_buf_t *  ubuf,
size_t  size 
)

Enlarge the buffer data block to (at least) size bytes.

Parameters:
ubuf an already allocated u_buf_t object
size the requested size in bytes
Return values:
0 on success
~0 on failure

Definition at line 41 of file buf.c.

References u_realloc().

Referenced by u_buf_append(), u_buf_load(), and u_buf_printf().

int u_buf_save ( u_buf_t *  ubuf,
const char *  filename 
)

Save the u_buf_t object ubuf to filename

Parameters:
ubuf an already allocated u_buf_t object
filename path of the destination file
Return values:
0 on success
~0 on failure

Definition at line 152 of file buf.c.

References u_buf_len(), u_buf_ptr(), and u_data_dump().

int u_buf_set ( u_buf_t *  ubuf,
const void *  data,
size_t  size 
)

Explicitly set the value of ubuf to data. If needed the buffer object will call u_buf_append to enlarge the storage needed to copy-in the data value.

Parameters:
ubuf a previously allocated u_buf_t object
data a reference to the memory block that will be copied into the buffer
size size of data in bytes
Return values:
0 on success
~0 on error

Definition at line 257 of file buf.c.

References u_buf_append(), and u_buf_clear().

int u_buf_shrink ( u_buf_t *  ubuf,
size_t  newlen 
)

Set the new length of the buffer; newlen must be less or equal to the current buffer length.

Parameters:
ubuf a previously allocated buffer object
newlen new length of the buffer
Returns:
Return values:
0 on success
~0 on error

Definition at line 302 of file buf.c.

ssize_t u_buf_size ( u_buf_t *  ubuf  ) 

Return the total size of data block allocated by the supplied u_buf_t object ubuf.

Parameters:
ubuf a previously allocated u_buf_t object
Returns:
the length in bytes of the data block (which could even be 0 in case ubuf is detached), or -1 if a NULL u_buf_t reference was supplied.

Definition at line 197 of file buf.c.

←Products
© 2005-2012 - KoanLogic S.r.l. - All rights reserved