76 lines
3.3 KiB
Groff
76 lines
3.3 KiB
Groff
.TH NDBUF_LENGTH 3 "28 October 2021" "NDBUF" "Binary buffers library manual"
|
||
|
||
.SH NAME
|
||
ndbuf_length, ndbuf_setlength, ndbuf_alength, ndbuf_leftlength - query and manipulate ndbuf buffer lengths
|
||
|
||
.SH SYNOPSIS
|
||
.nf
|
||
#include <ndbuf/ndbuf.h>
|
||
|
||
uint32_t ndbuf_length(ndbuf_t *b);
|
||
int ndbuf_setlength(ndbuf_t *b, uint32_t len);
|
||
uint32_t ndbuf_alength(ndbuf_t *b);
|
||
uint32_t ndbuf_leftlength(ndbuf_t *b);
|
||
.nf
|
||
|
||
.SH LIBRARY
|
||
libndbuf
|
||
|
||
.SH DESCRIPTION
|
||
These utility functions provide access to length and capacity information for an ndbuf_t buffer and allow controlled adjustment of the buffer's recorded used length.
|
||
|
||
.IP "\fBuint32_t ndbuf_length(ndbuf_t *b)\fR"
|
||
Return the number of bytes currently used (occupied) in the buffer b. This represents the logical size of the data stored in the buffer and is the length that most read/scan operations consider valid.
|
||
|
||
.IP "\fBint ndbuf_setlength(ndbuf_t *b, uint32_t len)\fR"
|
||
Set the buffer's used length to len. Valid usage depends on len being less than or equal to the allocated length (ndbuf_alength(b)). If len is greater than the allocated capacity, the function may fail (returning non‑zero) or trigger a reallocation depending on the library implementation. Typical return values:
|
||
.TP
|
||
.B 0
|
||
Success; the used length was updated.
|
||
.TP
|
||
.B -1
|
||
Failure; len is invalid (e.g., greater than allowed capacity) or an allocation/reallocation error occurred.
|
||
|
||
Setting length shorter than the previous value effectively truncates the logical content. Setting length larger than the previous value but within allocated capacity increases the logical size; the newly added bytes' contents are undefined and should be initialized by the caller if required.
|
||
|
||
.IP "\fBuint32_t ndbuf_alength(ndbuf_t *b)\fR"
|
||
Return the allocated capacity (in bytes) of the buffer b. This is the total storage reserved for the buffer and is always greater than or equal to ndbuf_length(b). Use this value to determine whether appending additional data will require reallocation.
|
||
|
||
.IP "\fBuint32_t ndbuf_leftlength(ndbuf_t *b)\fR"
|
||
Return the number of bytes available to read from the current read position to the end of the used data. This is equivalent to (ndbuf_length(b) - current_read_offset), and indicates how many readable bytes remain for scanning or extraction operations.
|
||
|
||
.SH RETURN VALUES
|
||
|
||
ndbuf_length, ndbuf_alength, ndbuf_leftlength: return unsigned 32-bit byte counts as described above.
|
||
ndbuf_setlength: returns 0 on success; non-zero (commonly -1) on error.
|
||
|
||
.SH ERRORS AND VALIDATION
|
||
Invalid operations or argument values may cause ndbuf_setlength to fail. Common failure causes:
|
||
.TP
|
||
.B len > ndbuf_alength(b)
|
||
Requested used length exceeds buffer capacity (unless implementation grows buffer).
|
||
.TP
|
||
.B Allocation failure
|
||
Attempt to grow buffer to satisfy len failed due to memory allocation error.
|
||
.TP
|
||
.B Invalid buffer pointer
|
||
Passing NULL or an invalid ndbuf_t may produce undefined behavior or a failure return.
|
||
|
||
.SH EXAMPLE
|
||
NONE.
|
||
|
||
.SH SEE ALSO
|
||
.BR ndbuf_new(3) ,
|
||
.BR ndbuf_print(3) ,
|
||
.BR ndbuf_escan(3) ,
|
||
.BR ndbuf_setflags(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>
|