From b1d0950b7183df3bd00a9dfae4edac00d47766f0 Mon Sep 17 00:00:00 2001 From: Alexander Vdolainen Date: Thu, 9 Oct 2025 23:45:41 +0300 Subject: [PATCH] ndbuf_new refined; --- man/ndbuf_new.3 | 207 ++++++++++++++++++++++++++---------------------- 1 file changed, 111 insertions(+), 96 deletions(-) diff --git a/man/ndbuf_new.3 b/man/ndbuf_new.3 index 809a58a..c3ccfa4 100644 --- a/man/ndbuf_new.3 +++ b/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 -.sp +.B "#include " +.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 .SH AUTHOR Alexander Vdolainen (alex@vapaa.xyz)