You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
133 lines
3.2 KiB
Groff
133 lines
3.2 KiB
Groff
.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 *);
|
|
|
|
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
|
|
.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)
|