.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
.SH SYNOPSIS
.B #include <ndbuf/ndbuf.h>
.sp
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);

struct ndbuf_memops {
.br
  void *(*alloc)(size_t);
.br
  uint32_t (*zero)(void *, size_t);
.br
  void (*free)(void *ptr);
.br
};
.br
.sp
.SH DESCRIPTION
.B ndbuf_new
family of functions are used to create
.B ndbuf_t
structure with a different options.
.br

.br
.B ndbuf_new()
will create a
.B ndbuf_t
with defaults values and default memory chunk preallocated. No special flags are assigned during the creation.
.br

.br
.B ndbuf_new_palloc(uint32_t)
will create a
.B ndbuf_t
with defaults values, but buffer will be allocated with the given lenght. No special flags are assigned during the call.
.br

.br
.B ndbuf_new_frombuf(char *buf, size_t buf_len, void (*freebuf)(char *))
will 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
.B NDBUF_NREA
means non-reallocatable buffer. See also
.B ndbuf_setflags(3)
man page for further flags exaplanations.
.br

.br
.B ndbuf_new_wmops(const struct ndbuf_memops *, const size_t)
is used to 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
.B alloc(size_t)
is used to allocate a memory block
.br
.B zero(void *, size_t)
is used to zero/fill freed or newly allocated memory if
.B NDBUF_BURN
flag is set.
.br
.B free(void *)
is used to free allocated memory.
.br
No specific flags are set upon a call.
.br

.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
.B NDBUF_NREA
flag is set and no
.B freebuf()
function pointer is provided.
.br
.B NDBUF_RORB
flag is set.
.br

.br
.B void ndbuf_free_item(ndbuf_t*, void*, size_t)
will free allocated item via escan function, if flag
.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
.SH RETURN VALUE
.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.
.SH RATIONALE
.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 ...).
.SH SEE ALSO
.BI ndbuf_setflags(3)
.SH COPYRIGHT
This software licensed under GNU LGPL v2.1 or later. See COPYING for further details.
.br
(c) Authors of libndbuf 2017-2018 <http://vapaa.xyz>
.SH AUTHOR
Alexander Vdolainen (alex@vapaa.xyz)