diff --git a/man/Makefile.am b/man/Makefile.am index c8ae21b..bed7333 100644 --- a/man/Makefile.am +++ b/man/Makefile.am @@ -2,5 +2,5 @@ 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_escan.3 \ - ndbuf_escan_va.3 ndbuf_escan_wot.3 + ndbuf_escan_va.3 ndbuf_escan_wot.3 ndbuf_print.3 ndbuf_print_va.3 ndbuf_print_wot.3 diff --git a/man/ndbuf_print.3 b/man/ndbuf_print.3 new file mode 100644 index 0000000..b2a0136 --- /dev/null +++ b/man/ndbuf_print.3 @@ -0,0 +1,119 @@ +.TH NDBUF_PRINT 3 "28 October 2025" "NDBUF" "Binary buffers library manual" + +.SH NAME +ndbuf_print, ndbuf_print_va, ndbuf_print_wot - format and append data into an ndbuf + +.SH SYNOPSIS +.nf +#include + +uint32_t ndbuf_print_va(ndbuf_t *b, const char *fmt, int argc, va_list ap); +uint32_t ndbuf_print_wot(ndbuf_t *b, const char *fmt, int argc, ...); + +uint32_t ndbuf_print(b, fmt, ...); +.nf + +.SH LIBRARY +libndbuf + +.SH DESCRIPTION +The ndbuf_print family formats values according to fmt and appends the resulting representation into the buffer b. These functions are the counterpart to the ndbuf_escan scanning APIs and support libndbuf's format specifiers for binary-safe and textual output. + + ndbuf_print_va: accepts a pre-initialized va_list (ap) and an explicit argument count (argc). + ndbuf_print_wot: variadic form taking an explicit argc followed by the argument list. + ndbuf_print: convenience macro that computes argc from the variadic arguments and appends the NDBUF_TERMINAT sentinel. + +The functions write to the provided ndbuf_t, growing it as necessary. They respect buffer flags that affect allocation and zero-copy behavior where applicable. + +.IP "\fBndbuf_t *b\fR" +Target buffer to which formatted output will be appended. + +.IP "\fBconst char *fmt\fR" +Null-terminated format string describing how to format the provided arguments. Specifiers follow libndbuf conventions (see FORMAT SPECIFIERS). + +.IP "\fBint argc\fR" +Number of values supplied in the argument list (number of conversion fields fmt expects). + +.IP "\fBva_list ap\fR" +Initialized variable argument list supplying source values for ndbuf_print_va. + +.SH FORMAT SPECIFIERS +The following conversion specifiers are recognized for printing: + +.IP "\fBb\fR" +8-bit unsigned integer. Argument: integer promotable to uint8_t. + +.IP "\fBw\fR" +16-bit unsigned integer. Argument: integer promotable to uint16_t. + +.IP "\fBd\fR" +32-bit unsigned integer. Argument: integer promotable to uint32_t. + +.IP "\fBq\fR" +64-bit unsigned integer. Argument: integer promotable to uint64_t. + +.IP "\fBs\fR" +NULL-terminated C string. Argument: const char *. The string bytes are appended (excluding the terminating NUL) and — depending on buffer flags — may be copied or referenced via zero-copy mechanisms. + +.IP "\fBp\fR" +Raw data with externally supplied length. Argument list: (size_t) length followed by (const void *) data pointer. The specified number of bytes are appended. + +.IP "\fBP\fR" +Length-prefixed raw data. Argument: a pointer to a length/value pair is not required; the format string indicates that the function should write the length followed by the data bytes from a supplied pointer (the exact calling convention mirrors the scanning 'P' semantics — see libndbuf source for precise ordering). + +.IP "\fBR\fR" +Append an ndbuf slice (argument: ndbuf_t *). The target buffer will incorporate the source buffer contents according to copy/zero-copy semantics and flags; if necessary, data will be copied. + +.SH RETURN VALUE +On success, the functions return the number of bytes appended to the buffer (a uint32_t). On failure (allocation error, invalid arguments, or other internal errors) the function returns 0; + +.SH ERRORS +Possible failure conditions include: +.TP +.B 0 +Indicates an error prevented appending data (allocation failure, malformed format/arguments, or other runtime error). Partial writes are not guaranteed; callers should verify buffer state if 0 is returned. +.PP +For detailed error reporting, inspect the ndbuf_t error state or enable library diagnostics. Refer to the libndbuf source for implementation-specific error codes. + +.SH USAGE NOTES + + The ndbuf_print macro automatically supplies a terminator (NDBUF_TERMINAT) and computes argc using the compiler's VA_NARG helper; ensure the variadic argument list and fmt are consistent. + Thread safety: concurrent modification of the same ndbuf_t without external synchronization is unsafe unless documented otherwise. + +.SH EXAMPLES +.nf +/* Example: append two 32-bit integers and a string */ +uint32_t a = 42, b = 100; +const char s = "hello"; +ndbuf_print(buf, "%d %d %s", a, b, s); /* macro computes argc and appends data */ + +/* Example: using va_list variant (caller prepares va_list) */ +#include + +uint32_t print_with_va(ndbuf_t *buf, const char fmt, ...) +{ +uint32_t written; +va_list ap; +va_start(ap, fmt); +/* In real use, convert or count args appropriately before calling ndbuf_print_va */ +written = ndbuf_print_va(buf, fmt, /*argc*/ 3, ap); +va_end(ap); +return written; +} +.nf + +.SH SEE ALSO +.BR ndbuf_escan(3) , +.BR ndbuf_escan_va(3) , +.BR ndbuf_new(3) , +.BR ndbuf_setflags(3) , +.BR ndbuf_free_item(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 + +.SH AUTHOR +Alexander Vdolainen (alex@vapaa.xyz) diff --git a/man/ndbuf_print_va.3 b/man/ndbuf_print_va.3 new file mode 120000 index 0000000..a4dd37d --- /dev/null +++ b/man/ndbuf_print_va.3 @@ -0,0 +1 @@ +ndbuf_print.3 \ No newline at end of file diff --git a/man/ndbuf_print_wot.3 b/man/ndbuf_print_wot.3 new file mode 120000 index 0000000..a4dd37d --- /dev/null +++ b/man/ndbuf_print_wot.3 @@ -0,0 +1 @@ +ndbuf_print.3 \ No newline at end of file