84 lines
3.3 KiB
Groff
84 lines
3.3 KiB
Groff
|
.TH NDBUF_SETFLAGS 3 "28 October 2021" "NDBUF" "Binary buffers library manual"
|
||
|
|
|
||
|
|
.SH NAME
|
||
|
|
ndbuf_setflags, ndbuf_exflags, ndbuf_flagsreset - manage flags controlling ndbuf behaviour
|
||
|
|
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
#include <ndbuf/ndbuf.h>
|
||
|
|
|
||
|
|
void ndbuf_setflags(ndbuf_t *b, int flags);
|
||
|
|
void ndbuf_exflags(ndbuf_t *b, int flags);
|
||
|
|
|
||
|
|
#define ndbuf_flagsreset(a) ndbuf_exflags((a), 0)
|
||
|
|
.nf
|
||
|
|
|
||
|
|
.SH LIBRARY
|
||
|
|
libndbuf
|
||
|
|
|
||
|
|
.SH DESCRIPTION
|
||
|
|
These functions manipulate the flags associated with an ndbuf_t instance. Flags control behavioural aspects such as zero-copy/copyless operation, burn semantics, read/write permissions, and other implementation-specific options. See SUPPORTED FLAGS.
|
||
|
|
|
||
|
|
.IP "\fBvoid ndbuf_setflags(ndbuf_t *b, int flags)\fR"
|
||
|
|
Set the buffer's flags to the provided flags value. This replaces the current flag set with flags. Use this when you want to explicitly assign a new flags mask.
|
||
|
|
|
||
|
|
.IP "\fBvoid ndbuf_exflags(ndbuf_t *b, int flags)\fR"
|
||
|
|
Exchange (apply) flags with the buffer; semantics are implementation-dependent but commonly used to modify or merge flags. In libndbuf this function is used to set flags while optionally returning or replacing previous flags state (check the header/source for exact behavior). Typically exflags will update the buffer's flags to flags; callers expecting previous flags should obtain them via the appropriate accessor if available.
|
||
|
|
|
||
|
|
.IP "\fB#define ndbuf_flagsreset(a) ndbuf_exflags((a), 0)\fR"
|
||
|
|
Reset all flags on the buffer by calling ndbuf_exflags with 0. This macro provides a convenient way to clear all flag bits.
|
||
|
|
|
||
|
|
.SH SUPPORTED FLAGS
|
||
|
|
.IP "\fBNDBUF_BURN\fR"
|
||
|
|
Burn data before freeing.
|
||
|
|
|
||
|
|
.IP "\fBNDBUF_NREA\fR"
|
||
|
|
Make the data buffer non-reallocatable.
|
||
|
|
|
||
|
|
.IP "\fBNDBUF_UCMD\fR"
|
||
|
|
Buffer with custom memory operations provided.
|
||
|
|
|
||
|
|
.IP "\fBNDBUF_RORB\fR"
|
||
|
|
Buffer is read-only.
|
||
|
|
|
||
|
|
.IP "\fBNDBUF_MOLS\fR"
|
||
|
|
Zero-copy buffer.
|
||
|
|
|
||
|
|
|
||
|
|
.SH BEHAVIOR AND USAGE NOTES
|
||
|
|
|
||
|
|
Flags are implementation-defined bitmasks; use only the constants defined by libndbuf.
|
||
|
|
Changing flags can affect memory ownership and lifetime semantics (for example, toggling zero-copy/copyless may change whether returned pointers reference internal storage or newly allocated memory). Ensure callers understand implications before changing flags on a buffer containing live data.
|
||
|
|
These functions do not allocate memory themselves. However, changing flags that affect ownership semantics may influence subsequent operations that allocate or free memory.
|
||
|
|
There is no return value; error conditions (if any) are reported via ndbuf_t state or other library diagnostics. Passing a NULL pointer yields undefined behavior.
|
||
|
|
|
||
|
|
.SH THREAD SAFETY
|
||
|
|
Concurrent modification of flags on the same ndbuf_t without external synchronization is unsafe. Use appropriate locking when multiple threads may read or modify flags.
|
||
|
|
|
||
|
|
.SH EXAMPLES
|
||
|
|
.nf
|
||
|
|
/* Set buffer to copyless (zero-copy) and burn mode */
|
||
|
|
ndbuf_setflags(buf, NDBUF_MOLS | NDBUF_BURN);
|
||
|
|
|
||
|
|
/* Clear all flags */
|
||
|
|
ndbuf_flagsreset(buf);
|
||
|
|
|
||
|
|
/* Exchange flags - set read-only */
|
||
|
|
ndbuf_exflags(buf, NDBUF_RORB);
|
||
|
|
.nf
|
||
|
|
|
||
|
|
.SH SEE ALSO
|
||
|
|
.BR ndbuf_new(3) ,
|
||
|
|
.BR ndbuf_free_item(3) ,
|
||
|
|
.BR ndbuf_escan(3) ,
|
||
|
|
.BR ndbuf_print(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>
|