91 lines
4.3 KiB
Groff
91 lines
4.3 KiB
Groff
.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/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)
|