libndbuf/man/ndbuf_read_raw.3

.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)