93 lines
2.9 KiB
Groff
93 lines
2.9 KiB
Groff
.TH NDBUF_READ_RAW 3 "15 September 2018" "NDBUF" "Binary buffers lib manual"
|
||
.SH NAME
|
||
ndbuf_read_u8, ndbuf_read_u16, ndbuf_read_u32, ndbuf_read_u64,
|
||
ndbuf_read_raw - read data of specified length and type
|
||
.SH SYNOPSIS
|
||
.B "#include <ndbuf/ndbuf.h>"
|
||
.PP
|
||
.nf
|
||
uint32_t ndbuf_read_u8(ndbuf_t *b, uint8_t *val);
|
||
uint32_t ndbuf_read_u16(ndbuf_t *b, uint16_t *val);
|
||
uint32_t ndbuf_read_u32(ndbuf_t *b, uint32_t *val);
|
||
uint32_t ndbuf_read_u64(ndbuf_t *b, uint64_t *val);
|
||
uint32_t ndbuf_read_raw(ndbuf_t *b, void *dst, uint32_t len);
|
||
.fi
|
||
.SH DESCRIPTION
|
||
The ndbuf_read_ family copies data from an
|
||
.B ndbuf_t
|
||
instance into caller-provided storage. On success each function returns the number of bytes read; on error it returns 0.
|
||
|
||
.TP
|
||
.B ndbuf_read_u8(ndbuf_t *b, uint8_t *val)
|
||
Read one unsigned 8‑bit value from the current buffer position into
|
||
.I val
|
||
and advance the buffer cursor by one byte. Returned value is the number of bytes read (1) or 0 on error.
|
||
|
||
.TP
|
||
.B ndbuf_read_u16(ndbuf_t *b, uint16_t *val)
|
||
Read one unsigned 16‑bit value, store it into
|
||
.I val
|
||
and advance the cursor by two bytes. Returns 2 on success or 0 on error.
|
||
|
||
.TP
|
||
.B ndbuf_read_u32(ndbuf_t *b, uint32_t *val)
|
||
Read one unsigned 32‑bit value, store into
|
||
.I val
|
||
and advance the cursor by four bytes. Returns 4 on success or 0 on error.
|
||
|
||
.TP
|
||
.B ndbuf_read_u64(ndbuf_t *b, uint64_t *val)
|
||
Read one unsigned 64‑bit value, store into
|
||
.I val
|
||
and advance the cursor by eight bytes. Returns 8 on success or 0 on error.
|
||
|
||
.TP
|
||
.B ndbuf_read_raw(ndbuf_t *b, void *dst, uint32_t len)
|
||
Copy
|
||
.I len
|
||
bytes of raw data from the buffer to
|
||
.I dst
|
||
and advance the cursor by
|
||
.I len. The caller must ensure
|
||
.I dst
|
||
points to memory at least
|
||
.I len
|
||
bytes long. Returns the number of bytes copied or 0 on error.
|
||
.SH RETURN VALUE
|
||
On success each function returns the number of bytes read. On error they return 0; no specific
|
||
.I errno
|
||
value is set.
|
||
.SH ERRORS
|
||
Functions return 0 when the requested read would exceed the available data, when
|
||
.I b
|
||
is NULL, or on other internal errors. Callers must validate the return value before using output data.
|
||
.SH RATIONALE
|
||
Use these functions when you need a local copy of numeric or raw data. For zero-copy parsing or formatted
|
||
extraction consider the
|
||
.BR ndbuf_escan(3)
|
||
family instead.
|
||
.SH EXAMPLES
|
||
.PP
|
||
.nf
|
||
/* Read values from buffer */
|
||
uint8_t a8;
|
||
uint16_t a16;
|
||
uint32_t a32;
|
||
if (ndbuf_read_u8(b, &a8) != 1) { /* handle error */ }
|
||
if (ndbuf_read_u16(b, &a16) != 2) { /* handle error */ }
|
||
if (ndbuf_read_u32(b, &a32) != 4) { /* handle error */ }
|
||
|
||
/* Read raw payload */
|
||
char payload[128];
|
||
if (ndbuf_read_raw(b, payload, sizeof(payload)) != sizeof(payload)) { /* handle error */ }
|
||
.fi
|
||
.SH SEE ALSO
|
||
.BR ndbuf_write_raw(3),
|
||
.BR ndbuf_escan(3)
|
||
.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)
|