From 39ac80efda00fd6557f3396d091828017c8b4b77 Mon Sep 17 00:00:00 2001
From: Alexander Vdolainen <alex@vapaa.xyz>
Date: Tue, 28 Oct 2025 02:12:06 +0200
Subject: [PATCH] ndbuf_escan family manpage has been added

---
 man/Makefile.am       |  3 +-
 man/ndbuf_escan.3     | 90 +++++++++++++++++++++++++++++++++++++++++++
 man/ndbuf_escan_va.3  |  1 +
 man/ndbuf_escan_wot.3 |  1 +
 4 files changed, 94 insertions(+), 1 deletion(-)
 create mode 100644 man/ndbuf_escan.3
 create mode 120000 man/ndbuf_escan_va.3
 create mode 120000 man/ndbuf_escan_wot.3

diff --git a/man/Makefile.am b/man/Makefile.am
index 16368b5..c8ae21b 100644
--- a/man/Makefile.am
+++ b/man/Makefile.am
@@ -1,5 +1,6 @@
 man_MANS = ndbuf_new.3 ndbuf_new_palloc.3 ndbuf_new_wmops.3 ndbuf_new_frombuf.3 \
 	ndbuf_free.3 ndbuf_free_item.3 ndbuf_read_raw.3 ndbuf_read_u8.3 ndbuf_read_u16.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_write_u32.3 ndbuf_write_u64.3 ndbuf_write_raw_head.3 ndbuf_escan.3 \
+	ndbuf_escan_va.3 ndbuf_escan_wot.3
 
diff --git a/man/ndbuf_escan.3 b/man/ndbuf_escan.3
new file mode 100644
index 0000000..a7fbd95
--- /dev/null
+++ b/man/ndbuf_escan.3
@@ -0,0 +1,90 @@
+.TH NDBUF_ESCAN 3 "15 Septermber 2018" "NDBUF" "Binary buffers lib manual"
+.SH NAME
+ndbuf_escan, ndbuf_escan_va, ndbuf_escan_wot - parse formatted input from ndbuf
+.SH SYNOPSIS
+.nf
+#include <ndbuf.h>
+int ndbuf_escan(ndbuf_t *b, const char *fmt, ...);
+int ndbuf_escan_va(ndbuf_t *b, const char *fmt, int argc, va_list ap);
+int ndbuf_escan_wot(ndbuf_t *b, const char *fmt, int argc, ...);
+
+.nf
+.SH LIBRARY
+libndbuf
+.SH DESCRIPTION
+The ndbuf_escan, ndbuf_escan_wot, ndbuf_escan_va functions scans data from the buffer referenced by b according to the format string fmt, using a pre-built va_list ap for supplying destination pointers. It behaves similarly to a vscanf-style formatted scanner but operates on an ndbuf_t source and supports the scanning features provided by the libndbuf scanning API.
+
+The arguments are:
+.IP "\fBndbuf_t *b\fR"
+Pointer to an ndbuf buffer object from which data will be read.
+.IP "\fBconst char *fmt\fR"
+A null-terminated format string that describes the expected input and the conversion specifiers, following libndbuf's scanning conventions.
+.IP "\fBint argc\fR"
+The number of expected conversion fields (the number of destination pointers the format requires). This value is used by the implementation to validate or limit processing.
+.IP "\fBva_list ap\fR"
+An initialized variable argument list providing the destination pointers corresponding to the conversion specifiers in fmt.
+
+.SH FORMAT SPECIFIERS
+The following conversion specifiers are recognized:
+.IP "\fBb\fR"
+8 bit unsigned integer. Argument: pointer to uint8_t (or unsigned char).
+.IP "\fBw\fR"
+16 bit unsigned integer. Argument: pointer to uint16_t.
+.IP "\fBd\fR"
+32 bit unsigned integer. Argument: pointer to uint32_t.
+.IP "\fBq\fR"
+64 bit unsigned integer. Argument: pointer to uint64_t.
+.IP "\fBs\fR"
+NULL terminated C string. Argument: pointer to char **. If the ndbuf has zero-copy (copyless) mode enabled, the function will set the pointer to point into the buffer's storage (no allocation). Otherwise the function allocates a new NUL-terminated buffer and copies the string; the caller must free that allocation with ndbuf_free_item when finished.
+.IP "\fBp\fR"
+Raw data with externally supplied length. Argument list: (size_t *) for length followed by (void **) pointer-to-pointer for data. If zero-copy is enabled, the data pointer is set to point into the buffer; otherwise a new allocation is made and must be freed with ndbuf_free_item.
+.IP "\fBP\fR"
+Length-prefixed raw data. The length is read from the ndbuf contents; the caller supplies a (void **) pointer-to-pointer to receive the data. Zero-copy behavior applies as with 'p'. Allocated data must be freed with ndbuf_free_item when appropriate.
+.IP "\fBR\fR"
+Will do the same as 'P', but instead of memory chunk a new ndbuf will be created with NDBUF_BURN flag set and all contents copied. Ignores zero copy flag.
+
+
+.SH RETURN VALUE
+On success, ndbuf_escan_va returns the number of input items successfully assigned. If a matching failure occurs before any conversions, it returns EOF (or a negative error code as used by the library). The exact error convention follows libndbuf's error reporting (see ERRORS).
+
+.SH ERRORS
+The function may return:
+.TP
+.DL
+.B -1
+General failure or EOF encountered before any conversions.
+.TP
+.DL
+.B <argc
+Fewer items converted than requested; the return value indicates how many were converted.
+.PP
+Consult libndbuf's error codes and diagnostics for additional failure semantics; implementations may set internal error state on the ndbuf_t object.
+
+.SH THREAD SAFETY
+Libndbuf doesn't provide any locking for ndbuf_t structure, so all those functions should be considered not thread safe. Developer should care about that with external locking primitives.
+
+.SH SEE ALSO
+.BR ndbuf_print ,
+.BR ndbuf_new ,
+.BR ndbuf_setflags ,
+.BR ndbuf_free_item
+
+.SH EXAMPLE
+.nf
+/* Example: parse two integers from an ndbuf /
+int a, b;
+va_list ap;
+va_start(ap, / in real use: this would be inside a variadic wrapper /);
+va_arg(ap, int ) = &a; /* illustrative only; use a proper variadic wrapper /
+va_arg(ap, int ) = &b;
+int ret = ndbuf_escan_va(mybuf, "%d %d", 2, ap);
+va_end(ap);
+.nf
+
+
+.SH COPYRIGHT
+This software licensed under GNU LGPL v2.1 or later. See COPYING for further details.
+.PP
+(c) Authors of libndbuf 2017-2018 <http://vapaa.xyz>
+.SH AUTHOR
+Alexander Vdolainen (alex@vapaa.xyz)
diff --git a/man/ndbuf_escan_va.3 b/man/ndbuf_escan_va.3
new file mode 120000
index 0000000..21a6387
--- /dev/null
+++ b/man/ndbuf_escan_va.3
@@ -0,0 +1 @@
+ndbuf_escan.3
\ No newline at end of file
diff --git a/man/ndbuf_escan_wot.3 b/man/ndbuf_escan_wot.3
new file mode 120000
index 0000000..21a6387
--- /dev/null
+++ b/man/ndbuf_escan_wot.3
@@ -0,0 +1 @@
+ndbuf_escan.3
\ No newline at end of file