diff --git a/Makefile.am b/Makefile.am index 409ce47..0cac84b 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,8 +1,9 @@ ## Sample for libndbuf automaken stuff -## (c) alex@vapaa.xyz +## Distributed under GNU LGPL v2.1 or later +## Originally written by Alexander Vdolainen (c) 2017 ## Process this file with automake to produce Makefile.in -SUBDIRS = include +SUBDIRS = include man clean-local: diff --git a/configure.ac b/configure.ac index 828aa87..9bdfd38 100644 --- a/configure.ac +++ b/configure.ac @@ -16,4 +16,5 @@ AC_OUTPUT([ Makefile libndbuf.pc include/Makefile +man/Makefile ]) diff --git a/man/Makefile.am b/man/Makefile.am new file mode 100644 index 0000000..c8b0198 --- /dev/null +++ b/man/Makefile.am @@ -0,0 +1,2 @@ +man_MANS = ndbuf_new.3 ndbuf_new_palloc.3 ndbuf_new_wmops.3 ndbuf_new_frombuf.3 \ + ndbuf_free.3 diff --git a/man/ndbuf_free.3 b/man/ndbuf_free.3 new file mode 120000 index 0000000..d546da9 --- /dev/null +++ b/man/ndbuf_free.3 @@ -0,0 +1 @@ +ndbuf_new.3 \ No newline at end of file diff --git a/man/ndbuf_new.3 b/man/ndbuf_new.3 new file mode 100644 index 0000000..fbded18 --- /dev/null +++ b/man/ndbuf_new.3 @@ -0,0 +1,132 @@ +.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 +.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 +.SH AUTHOR +Alexander Vdolainen (alex@vapaa.xyz) diff --git a/man/ndbuf_new_frombuf.3 b/man/ndbuf_new_frombuf.3 new file mode 120000 index 0000000..d546da9 --- /dev/null +++ b/man/ndbuf_new_frombuf.3 @@ -0,0 +1 @@ +ndbuf_new.3 \ No newline at end of file diff --git a/man/ndbuf_new_palloc.3 b/man/ndbuf_new_palloc.3 new file mode 120000 index 0000000..d546da9 --- /dev/null +++ b/man/ndbuf_new_palloc.3 @@ -0,0 +1 @@ +ndbuf_new.3 \ No newline at end of file diff --git a/man/ndbuf_new_wmops.3 b/man/ndbuf_new_wmops.3 new file mode 120000 index 0000000..d546da9 --- /dev/null +++ b/man/ndbuf_new_wmops.3 @@ -0,0 +1 @@ +ndbuf_new.3 \ No newline at end of file