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().
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:
-
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.
Release all resources and free the given buffer object.
- Parameters:
-
- Return values:
-
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:
-
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 | |
|
) |
| | |
int u_buf_save |
( |
u_buf_t * |
ubuf, |
|
|
const char * |
filename | |
|
) |
| | |
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:
-
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:
-
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.