ndbuf_read_raw refined
This commit is contained in:
parent
b1d0950b71
commit
1f684819a4
@ -1,65 +1,92 @@
|
||||
.TH NDBUF_READ_RAW 3 "15 September 2018" "NDBUF" "Binary buffers lib manual"
|
||||
.SH NAME
|
||||
ndbuf_read_u8 \- Read unsigned 8 bit value from buffer
|
||||
.br
|
||||
ndbuf_read_u16 \- Read unsigned 16 bit value from buffer
|
||||
.br
|
||||
ndbuf_read_u32 \- Read unsigned 32 bit value from buffer
|
||||
.br
|
||||
ndbuf_read_u64 \- Read unsigned 64 bit value from buffer
|
||||
.br
|
||||
ndbuf_read_raw \- Read raw data with pointed length
|
||||
.br
|
||||
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>
|
||||
.sp
|
||||
uint32_t ndbuf_read_u8(ndbuf_t *, uint8_t *);
|
||||
|
||||
uint32_t ndbuf_read_u16(ndbuf_t *, uint16_t *);
|
||||
|
||||
uint32_t ndbuf_read_u32(ndbuf_t *, uint32_t *);
|
||||
|
||||
uint32_t ndbuf_read_u64(ndbuf_t *, uint64_t *);
|
||||
|
||||
uint32_t ndbuf_read_raw(ndbuf_t *, void *, uint32_t);
|
||||
.br
|
||||
.sp
|
||||
.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
|
||||
Those functions reads a data from the
|
||||
The ndbuf_read_ family copies data from an
|
||||
.B ndbuf_t
|
||||
structure. Returns amount of bytes ridden or 0 in case of error.
|
||||
.br
|
||||
.B ndbuf_read_u8
|
||||
,
|
||||
.B ndbuf_read_u16
|
||||
,
|
||||
.B ndbuf_read_u32
|
||||
,
|
||||
.B ndbuf_read_u64
|
||||
functions copies an integer values from
|
||||
.B ndbuf_t
|
||||
structure to the second function argument.
|
||||
.br
|
||||
.B ndbuf_read_raw
|
||||
function copies raw data from
|
||||
.B ndbuf_t
|
||||
structure to the second argument with provided length in the third argument. Memory of appropriate length should be preallocated at the given pointer.
|
||||
.br
|
||||
.SH BUGS
|
||||
Not known yet.
|
||||
.SH EXAMPLE
|
||||
None.
|
||||
.SH APPLICATION USAGE
|
||||
None.
|
||||
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
|
||||
This family of functions might be used when the copy of the data is required, otherwise use
|
||||
.B ndbuf_escan
|
||||
family of functions.
|
||||
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
|
||||
.BI ndbuf_write_raw(3), ndbuf_escan(3)
|
||||
.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.
|
||||
.br
|
||||
.PP
|
||||
(c) Authors of libndbuf 2017-2018 <http://vapaa.xyz>
|
||||
.SH AUTHOR
|
||||
Alexander Vdolainen (alex@vapaa.xyz)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user