ndbuf_new refined;

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
+ndbuf_new, ndbuf_new_palloc, ndbuf_new_frombuf, ndbuf_new_wmops, ndbuf_free - allocate and free buffer structure
-.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>
+.B "#include <ndbuf/ndbuf.h>"
-.sp
+.PP
+.nf
 ndbuf_t *ndbuf_new(void);
-
+ndbuf_t *ndbuf_new_palloc(uint32_t len);
-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_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);
-ndbuf_t *ndbuf_new_wmops(const struct ndbuf_memops *, const size_t);
+void ndbuf_free(ndbuf_t *b);
-
+void ndbuf_free_item(ndbuf_t *b, void *item, size_t item_size);
-void ndbuf_free(ndbuf_t *);
+.PP
-
-void ndbuf_free_item(ndbuf_t *b, void *ip, size_t is);
-
 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
+.fi
-.sp
 .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.
+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.
-.br
+.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.
+using library defaults. A default memory chunk is preallocated. No special flags are set.
-.br
+.PP
 
-.br
+.TP
-.B ndbuf_new_palloc(uint32_t)
+.B ndbuf_new_palloc(uint32_t len)
-will create a
+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.
+with an initial buffer of the specified length (in bytes). Other defaults apply; no special flags are set.
-.br
+.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
+that uses the provided buffer pointer
-.B ndbuf_t
+.I buf
-freeing if provided. A few flags will be set:
+of length
-.br
+.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
+flag set, indicating the buffer is non-reallocatable. See
-.B ndbuf_setflags(3)
+.BR ndbuf_setflags(3)
-man page for further flags exaplanations.
+for flag details.
-.br
+.PP
 
-.br
+.TP
-.B ndbuf_new_wmops(const struct ndbuf_memops *, const size_t)
+.B ndbuf_new_wmops(const struct ndbuf_memops *mops, const size_t block_size)
-is used to create a
+Create a
 .B ndbuf_t
-with a custom provided memory options and custom memory block size. Provided structure should has a few functions pointers:
+that uses the caller-provided memory-operation callbacks and a custom block size. The
-.br
+.I mops
+structure must provide the following function pointers:
+.IP 
 .B alloc(size_t)
-is used to allocate a memory block
+Function to allocate a memory block of the given size.
-.br
+.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.
+flag is set to securely erase memory.
-.br
+.IP
 .B free(void *)
-is used to free allocated memory.
+Free a previously allocated memory block.
-.br
+.IP
-No specific flags are set upon a call.
+No special flags are set by this call.
-.br
+.PP
 
-.br
+.TP
-.B ndbuf_free(ndbuf_t *)
+.B ndbuf_free(ndbuf_t *b)
-is used to free a corresponding
+Free the
-.B ndbuf_t
+.I ndbuf_t
-structure, and connected raw buffer data as well, excepting the following cases:
+structure and, unless prevented by flags or missing free callbacks, free the associated buffer data. The underlying buffer is not freed if:
-.br
+.IP
+The
 .B NDBUF_NREA
 flag is set and no
-.B freebuf()
+.I freebuf
-function pointer is provided.
+callback was provided in
-.br
+.B ndbuf_new_frombuf().
+.IP
+The
 .B NDBUF_RORB
 flag is set.
-.br
+.PP
 
-.br
+.TP
-.B void ndbuf_free_item(ndbuf_t*, void*, size_t)
+.B ndbuf_free_item(ndbuf_t *b, void item, size_t item_size)
-will free allocated item via escan function, if flag
+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. 
+flag is set and
-.br
+.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
+family of functions returns a pointer to the newly created
-.B ndbuf_t
+.B ndbuf_t.
-structure or
+On failure they return
-.B NULL
+.B NULL.
-otherwise (if any error occurs, or invalid options are given).
+No specific
-.br
+.I errno
-No specific errno code is set in case of error.
+value is set by these functions.
-.br
+.SH ERRORS
-.SH BUGS
+These functions return NULL on allocation or initialization failure. Callers should check the return value before use.
-Not known yet.
+.SH EXAMPLES
-.SH EXAMPLE
+.PP
-None.
+.nf
-.SH APPLICATION USAGE
+/ Create a default buffer */
-None.
+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)