ndbuf_new refined;
This commit is contained in:
parent
6eea614d6c
commit
b1d0950b71
207
man/ndbuf_new.3
207
man/ndbuf_new.3
@ -1,141 +1,156 @@
|
||||
.TH NDBUF_NEW 3 "15 September 2018" "NDBUF" "Binary buffers lib manual"
|
||||
.SH NAME
|
||||
ndbuf_new \- Create a new raw buffer with library defaults
|
||||
.br
|
||||
ndbuf_new_palloc \- Create a new raw buffer with predefined length
|
||||
.br
|
||||
ndbuf_new_frombuf \- Create a new raw buffer with given data
|
||||
.br
|
||||
ndbuf_new_wmops \- Create a new raw buffer with user-defined memory ops
|
||||
.br
|
||||
ndbuf_free \- Free raw buffer structure
|
||||
.br
|
||||
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>
|
||||
.sp
|
||||
.B "#include <ndbuf/ndbuf.h>"
|
||||
.PP
|
||||
.nf
|
||||
ndbuf_t *ndbuf_new(void);
|
||||
|
||||
ndbuf_t *ndbuf_new_palloc(uint32_t);
|
||||
|
||||
ndbuf_t *ndbuf_new_frombuf(char *buf, size_t buf_len, void (*freebuf)(char *));
|
||||
|
||||
ndbuf_t *ndbuf_new_wmops(const struct ndbuf_memops *, const size_t);
|
||||
|
||||
void ndbuf_free(ndbuf_t *);
|
||||
|
||||
void ndbuf_free_item(ndbuf_t *b, void *ip, size_t is);
|
||||
|
||||
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);
|
||||
void *(*alloc)(size_t);
|
||||
.br
|
||||
uint32_t (*zero)(void *, size_t);
|
||||
uint32_t (*zero)(void *, size_t);
|
||||
.br
|
||||
void (*free)(void *ptr);
|
||||
void (*free)(void *);
|
||||
.br
|
||||
};
|
||||
.br
|
||||
.sp
|
||||
.fi
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.B ndbuf_new
|
||||
family of functions are used to create
|
||||
family of functions create and initialize an
|
||||
.B ndbuf_t
|
||||
structure with a different options.
|
||||
.br
|
||||
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
|
||||
|
||||
.br
|
||||
.TP
|
||||
.B ndbuf_new()
|
||||
will create a
|
||||
Allocate and return a newly initialized
|
||||
.B ndbuf_t
|
||||
with defaults values and default memory chunk preallocated. No special flags are assigned during the creation.
|
||||
.br
|
||||
using library defaults. A default memory chunk is preallocated. No special flags are set.
|
||||
.PP
|
||||
|
||||
.br
|
||||
.B ndbuf_new_palloc(uint32_t)
|
||||
will create a
|
||||
.TP
|
||||
.B ndbuf_new_palloc(uint32_t len)
|
||||
Allocate and return a new
|
||||
.B ndbuf_t
|
||||
with defaults values, but buffer will be allocated with the given lenght. No special flags are assigned during the call.
|
||||
.br
|
||||
with an initial buffer of the specified length (in bytes). Other defaults apply; no special flags are set.
|
||||
.PP
|
||||
|
||||
.br
|
||||
.TP
|
||||
.B ndbuf_new_frombuf(char *buf, size_t buf_len, void (*freebuf)(char *))
|
||||
will create a
|
||||
Create a
|
||||
.B ndbuf_t
|
||||
with buffer point to *buf and is assume the length of this buffer is buf_len, function freebuf will be used during
|
||||
.B ndbuf_t
|
||||
freeing if provided. A few flags will be set:
|
||||
.br
|
||||
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
|
||||
means non-reallocatable buffer. See also
|
||||
.B ndbuf_setflags(3)
|
||||
man page for further flags exaplanations.
|
||||
.br
|
||||
flag set, indicating the buffer is non-reallocatable. See
|
||||
.BR ndbuf_setflags(3)
|
||||
for flag details.
|
||||
.PP
|
||||
|
||||
.br
|
||||
.B ndbuf_new_wmops(const struct ndbuf_memops *, const size_t)
|
||||
is used to create a
|
||||
.TP
|
||||
.B ndbuf_new_wmops(const struct ndbuf_memops *mops, const size_t block_size)
|
||||
Create a
|
||||
.B ndbuf_t
|
||||
with a custom provided memory options and custom memory block size. Provided structure should has a few functions pointers:
|
||||
.br
|
||||
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)
|
||||
is used to allocate a memory block
|
||||
.br
|
||||
Function to allocate a memory block of the given size.
|
||||
.IP
|
||||
.B zero(void *, size_t)
|
||||
is used to zero/fill freed or newly allocated memory if
|
||||
Function to zero or overwrite a memory region; used when the
|
||||
.B NDBUF_BURN
|
||||
flag is set.
|
||||
.br
|
||||
flag is set to securely erase memory.
|
||||
.IP
|
||||
.B free(void *)
|
||||
is used to free allocated memory.
|
||||
.br
|
||||
No specific flags are set upon a call.
|
||||
.br
|
||||
Free a previously allocated memory block.
|
||||
.IP
|
||||
No special flags are set by this call.
|
||||
.PP
|
||||
|
||||
.br
|
||||
.B ndbuf_free(ndbuf_t *)
|
||||
is used to free a corresponding
|
||||
.B ndbuf_t
|
||||
structure, and connected raw buffer data as well, excepting the following cases:
|
||||
.br
|
||||
.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
|
||||
.B freebuf()
|
||||
function pointer is provided.
|
||||
.br
|
||||
.I freebuf
|
||||
callback was provided in
|
||||
.B ndbuf_new_frombuf().
|
||||
.IP
|
||||
The
|
||||
.B NDBUF_RORB
|
||||
flag is set.
|
||||
.br
|
||||
.PP
|
||||
|
||||
.br
|
||||
.B void ndbuf_free_item(ndbuf_t*, void*, size_t)
|
||||
will free allocated item via escan function, if flag
|
||||
.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
|
||||
is set and size in't 0 memset() or zero() custom function will be called prior to free. This function is using default memory allocation/deallocation functions or (if provided) custom ones.
|
||||
.br
|
||||
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 newly created
|
||||
.B ndbuf_t
|
||||
structure or
|
||||
.B NULL
|
||||
otherwise (if any error occurs, or invalid options are given).
|
||||
.br
|
||||
No specific errno code is set in case of error.
|
||||
.br
|
||||
.SH BUGS
|
||||
Not known yet.
|
||||
.SH EXAMPLE
|
||||
None.
|
||||
.SH APPLICATION USAGE
|
||||
None.
|
||||
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()
|
||||
is recommended to use in specific environments i.e. when users are required to store and process all data buffers in a secure way (use special memory allocation to avoid memory pages swappnig, avoid memset() optimization etc ...).
|
||||
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
|
||||
.BI ndbuf_setflags(3)
|
||||
.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.
|
||||
.br
|
||||
.PP
|
||||
(c) Authors of libndbuf 2017-2018 <http://vapaa.xyz>
|
||||
.SH AUTHOR
|
||||
Alexander Vdolainen (alex@vapaa.xyz)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user