157 lines
4.2 KiB
Groff
157 lines
4.2 KiB
Groff
.TH NDBUF_NEW 3 "15 September 2018" "NDBUF" "Binary buffers lib manual"
|
|
.SH NAME
|
|
ndbuf_new, ndbuf_new_palloc, ndbuf_new_frombuf, ndbuf_new_wmops, ndbuf_free - allocate and free buffer structure
|
|
.SH SYNOPSIS
|
|
.B "#include <ndbuf/ndbuf.h>"
|
|
.PP
|
|
.nf
|
|
ndbuf_t *ndbuf_new(void);
|
|
ndbuf_t *ndbuf_new_palloc(uint32_t len);
|
|
ndbuf_t *ndbuf_new_frombuf(char *buf, size_t buf_len,
|
|
void (*freebuf)(char *));
|
|
ndbuf_t *ndbuf_new_wmops(const struct ndbuf_memops *mops,
|
|
const size_t block_size);
|
|
void ndbuf_free(ndbuf_t *b);
|
|
void ndbuf_free_item(ndbuf_t *b, void *item, size_t item_size);
|
|
.PP
|
|
struct ndbuf_memops {
|
|
.br
|
|
void *(*alloc)(size_t);
|
|
.br
|
|
uint32_t (*zero)(void *, size_t);
|
|
.br
|
|
void (*free)(void *);
|
|
.br
|
|
};
|
|
.fi
|
|
.SH DESCRIPTION
|
|
The
|
|
.B ndbuf_new
|
|
family of functions create and initialize an
|
|
.B ndbuf_t
|
|
structure using different allocation and memory-operation options. These routines simplify handling raw network-oriented buffers while providing hooks for custom memory management and secure wiping.
|
|
.PP
|
|
|
|
.TP
|
|
.B ndbuf_new()
|
|
Allocate and return a newly initialized
|
|
.B ndbuf_t
|
|
using library defaults. A default memory chunk is preallocated. No special flags are set.
|
|
.PP
|
|
|
|
.TP
|
|
.B ndbuf_new_palloc(uint32_t len)
|
|
Allocate and return a new
|
|
.B ndbuf_t
|
|
with an initial buffer of the specified length (in bytes). Other defaults apply; no special flags are set.
|
|
.PP
|
|
|
|
.TP
|
|
.B ndbuf_new_frombuf(char *buf, size_t buf_len, void (*freebuf)(char *))
|
|
Create a
|
|
.B ndbuf_t
|
|
that uses the provided buffer pointer
|
|
.I buf
|
|
of length
|
|
.I buf_len
|
|
as its underlying storage. If
|
|
.I freebuf
|
|
is a valid pointer to the function, it will be called to free the buffer when the ndbuf is destroyed. The returned ndbuf will have the
|
|
.B NDBUF_NREA
|
|
flag set, indicating the buffer is non-reallocatable. See
|
|
.BR ndbuf_setflags(3)
|
|
for flag details.
|
|
.PP
|
|
|
|
.TP
|
|
.B ndbuf_new_wmops(const struct ndbuf_memops *mops, const size_t block_size)
|
|
Create a
|
|
.B ndbuf_t
|
|
that uses the caller-provided memory-operation callbacks and a custom block size. The
|
|
.I mops
|
|
structure must provide the following function pointers:
|
|
.IP
|
|
.B alloc(size_t)
|
|
Function to allocate a memory block of the given size.
|
|
.IP
|
|
.B zero(void *, size_t)
|
|
Function to zero or overwrite a memory region; used when the
|
|
.B NDBUF_BURN
|
|
flag is set to securely erase memory.
|
|
.IP
|
|
.B free(void *)
|
|
Free a previously allocated memory block.
|
|
.IP
|
|
No special flags are set by this call.
|
|
.PP
|
|
|
|
.TP
|
|
.B ndbuf_free(ndbuf_t *b)
|
|
Free the
|
|
.I ndbuf_t
|
|
structure and, unless prevented by flags or missing free callbacks, free the associated buffer data. The underlying buffer is not freed if:
|
|
.IP
|
|
The
|
|
.B NDBUF_NREA
|
|
flag is set and no
|
|
.I freebuf
|
|
callback was provided in
|
|
.B ndbuf_new_frombuf().
|
|
.IP
|
|
The
|
|
.B NDBUF_RORB
|
|
flag is set.
|
|
.PP
|
|
|
|
.TP
|
|
.B ndbuf_free_item(ndbuf_t *b, void item, size_t item_size)
|
|
Free an item previously allocated via the library's escan function. If the
|
|
.B NDBUF_BURN
|
|
flag is set and
|
|
.I item_size
|
|
is non-zero, the buffer will be securely zeroed (via
|
|
.B zero()
|
|
or
|
|
.B memset()
|
|
) before being freed. This function uses the default memory ops unless custom ops were provided at creation.
|
|
.SH RETURN VALUE
|
|
On success the
|
|
.B ndbuf_new
|
|
family of functions returns a pointer to the newly created
|
|
.B ndbuf_t.
|
|
On failure they return
|
|
.B NULL.
|
|
No specific
|
|
.I errno
|
|
value is set by these functions.
|
|
.SH ERRORS
|
|
These functions return NULL on allocation or initialization failure. Callers should check the return value before use.
|
|
.SH EXAMPLES
|
|
.PP
|
|
.nf
|
|
/ Create a default buffer */
|
|
ndbuf_t *b = ndbuf_new();
|
|
if (!b) { / handle error */ }
|
|
|
|
/* Create buffer from existing memory */
|
|
char *buf = malloc(256);
|
|
ndbuf_t *b2 = ndbuf_new_frombuf(buf, 256, free);
|
|
|
|
/* Create buffer with custom memory ops */
|
|
struct ndbuf_memops mops = { custom_alloc, custom_zero, custom_free };
|
|
ndbuf_t *b3 = ndbuf_new_wmops(&mops, 4096);
|
|
.fi
|
|
.SH RATIONALE
|
|
The
|
|
.B ndbuf_new_wmops()
|
|
function is useful for environments requiring special memory handling (for example, preventing pages from being swapped, using locked memory, or providing a custom zeroing routine to avoid compiler optimizations).
|
|
.SH SEE ALSO
|
|
.BR ndbuf_setflags(3),
|
|
.BR ndbuf_escan(3)
|
|
.SH COPYRIGHT
|
|
This software licensed under GNU LGPL v2.1 or later. See COPYING for further details.
|
|
.PP
|
|
(c) Authors of libndbuf 2017-2018 <http://vapaa.xyz>
|
|
.SH AUTHOR
|
|
Alexander Vdolainen (alex@vapaa.xyz)
|