120 lines
4.8 KiB
Groff
120 lines
4.8 KiB
Groff
.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 <ndbuf/ndbuf.h>
|
|
|
|
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 <stdarg.h>
|
|
|
|
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 <http://vapaa.xyz>
|
|
|
|
.SH AUTHOR
|
|
Alexander Vdolainen (alex@vapaa.xyz)
|