From 1d37a8fbbae2ef8ef21b6c32104d5170e7eba5af Mon Sep 17 00:00:00 2001 From: Alexander Vdolainen Date: Tue, 28 Oct 2025 03:42:57 +0200 Subject: [PATCH] ndbuf_rdata manuals has been added --- man/Makefile.am | 3 ++- man/ndbuf_rdata.3 | 60 ++++++++++++++++++++++++++++++++++++++++++++ man/ndbuf_rdatacur.3 | 1 + man/ndbuf_resetcur.3 | 1 + 4 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 man/ndbuf_rdata.3 create mode 120000 man/ndbuf_rdatacur.3 create mode 120000 man/ndbuf_resetcur.3 diff --git a/man/Makefile.am b/man/Makefile.am index 055b2e6..4683d9b 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -3,5 +3,6 @@ man_MANS = ndbuf_new.3 ndbuf_new_palloc.3 ndbuf_new_wmops.3 ndbuf_new_frombuf.3 ndbuf_read_u32.3 ndbuf_read_u64.3 ndbuf_write_raw.3 ndbuf_write_u8.3 ndbuf_write_u16.3 \ ndbuf_write_u32.3 ndbuf_write_u64.3 ndbuf_write_raw_head.3 ndbuf_escan.3 \ ndbuf_escan_va.3 ndbuf_escan_wot.3 ndbuf_print.3 ndbuf_print_va.3 ndbuf_print_wot.3 \ - ndbuf_length.3 ndbuf_alength.3 ndbuf_leftlength.3 ndbuf_setlength.3 + ndbuf_length.3 ndbuf_alength.3 ndbuf_leftlength.3 ndbuf_setlength.3 ndbuf_rdata.3 \ + ndbuf_rdatacur.3 ndbuf_resetcur.3 diff --git a/man/ndbuf_rdata.3 b/man/ndbuf_rdata.3 new file mode 100644 index 0000000..b08c3f9 --- /dev/null +++ b/man/ndbuf_rdata.3 @@ -0,0 +1,60 @@ +.TH NDBUF_RDATA 3 "28 October 2021" "NDBUF" "Binary buffers library manual" + +.SH NAME +ndbuf_rdata, ndbuf_rdatacur, ndbuf_resetcur - access and control the current data pointer in an ndbuf + +.SH SYNOPSIS +.nf +#include + +void *ndbuf_rdata(ndbuf_t *b); +void *ndbuf_rdatacur(ndbuf_t *b); +void ndbuf_resetcur(ndbuf_t *b); +.nf + +.SH LIBRARY +libndbuf + +.SH DESCRIPTION +These functions provide direct access to the buffer storage and to the buffer's current read/write cursor within an ndbuf_t instance, and allow resetting that cursor. + +.IP "\fBvoid *ndbuf_rdata(ndbuf_t *b)\fR" +Return a pointer to the start of the buffer's raw data storage. The returned pointer refers to the internal storage area that holds the buffer's contents. The pointer remains valid until the buffer is reallocated, freed, or otherwise mutated in a way that changes its storage location. + +.IP "\fBvoid *ndbuf_rdatacur(ndbuf_t *b)\fR" +Return a pointer to the current read/write position within the buffer (the "current" cursor). This pointer equals (ndbuf_rdata(b) + current_offset) where current_offset is the buffer's internal read/write offset. Use this pointer to read from or write to the buffer at the current cursor position; after writing directly to this location the caller should update the logical used length with ndbuf_setlength if bytes were appended. + +.IP "\fBvoid ndbuf_resetcur(ndbuf_t *b)\fR" +Reset the buffer's current read/write cursor to the start of the buffer (offset zero). This sets the current cursor so subsequent read or scan operations begin from the buffer start. Does not modify the buffer's used length; it only changes the read/write position. + +.SH RETURN VALUES AND BEHAVIOR + + ndbuf_rdata and ndbuf_rdatacur return NULL if b is NULL or if the buffer has no allocated storage. + ndbuf_rdatacur reflects the buffer's current internal cursor; reading beyond the used length leads to undefined behavior unless the caller ensures sufficient data via ndbuf_length/ndbuf_leftlength checks. + ndbuf_resetcur returns no value; it unconditionally sets the cursor to the buffer start (or to a defined initial state). + +.SH SAFETY AND OWNERSHIP + + The returned pointers reference internal buffer storage. Do not free or persist them beyond the lifetime of the ndbuf_t or across operations that may reallocate the buffer. + Direct writes into the buffer's storage bypass internal bookkeeping; after performing writes that extend used data, callers must call ndbuf_setlength to update the logical length. + Respect buffer flags (e.g., read-only or zero-copy semantics) and do not modify storage when prohibited. + +.SH THREAD SAFETY +Concurrent access to the same ndbuf_t without external synchronization is unsafe. Use locks when multiple threads may read/write the buffer and its cursor. + +.SH EXAMPLES +NONE + +.SH SEE ALSO +.BR ndbuf_length(3) , +.BR ndbuf_setlength(3) , +.BR ndbuf_leftlength(3) + +.SH COPYRIGHT +This software is licensed under the GNU Lesser General Public License version 2.1 or later. See the COPYING file in the project repository for full license text. + +.PP +(c) Authors of libndbuf 2017-2018 (http://vapaa.xyz) + +.SH AUTHOR +Alexander Vdolainen diff --git a/man/ndbuf_rdatacur.3 b/man/ndbuf_rdatacur.3 new file mode 120000 index 0000000..187a8b9 --- /dev/null +++ b/man/ndbuf_rdatacur.3 @@ -0,0 +1 @@ +ndbuf_rdata.3 \ No newline at end of file diff --git a/man/ndbuf_resetcur.3 b/man/ndbuf_resetcur.3 new file mode 120000 index 0000000..187a8b9 --- /dev/null +++ b/man/ndbuf_resetcur.3 @@ -0,0 +1 @@ +ndbuf_rdata.3 \ No newline at end of file