NAL_BUFFER_NEW(2) distcache NAL_BUFFER_NEW(2)NAME
NAL_BUFFER_new, NAL_BUFFER_free, NAL_BUFFER_set_size, NAL_BUFFER_empty,
NAL_BUFFER_full, NAL_BUFFER_notempty, NAL_BUFFER_notfull, NAL_BUF‐
FER_used, NAL_BUFFER_unused, NAL_BUFFER_data, NAL_BUFFER_size, NAL_BUF‐
FER_write, NAL_BUFFER_read, NAL_BUFFER_write_ptr, NAL_BUFFER_takedata,
NAL_BUFFER_wrote - libnal buffer functions
SYNOPSIS
#include <libnal/nal.h>
NAL_BUFFER *NAL_BUFFER_new(void);
void NAL_BUFFER_free(NAL_BUFFER *buf);
void NAL_BUFFER_reset(NAL_BUFFER *buf);
int NAL_BUFFER_set_size(NAL_BUFFER *buf, unsigned int size);
int NAL_BUFFER_empty(const NAL_BUFFER *buf);
int NAL_BUFFER_full(const NAL_BUFFER *buf);
int NAL_BUFFER_notempty(const NAL_BUFFER *buf);
int NAL_BUFFER_notfull(const NAL_BUFFER *buf);
unsigned int NAL_BUFFER_used(const NAL_BUFFER *buf);
unsigned int NAL_BUFFER_unused(const NAL_BUFFER *buf);
unsigned int NAL_BUFFER_size(const NAL_BUFFER *buf);
const unsigned char *NAL_BUFFER_data(const NAL_BUFFER *buf);
unsigned int NAL_BUFFER_write(NAL_BUFFER *buf, const unsigned char *ptr,
unsigned int size);
unsigned int NAL_BUFFER_read(NAL_BUFFER *buf, unsigned char *ptr,
unsigned int size);
unsigned char *NAL_BUFFER_write_ptr(NAL_BUFFER *buf);
void NAL_BUFFER_wrote(NAL_BUFFER *buf, unsigned int size);
DESCRIPTIONNAL_BUFFER_new() allocates and initialises a new NAL_BUFFER object.
NAL_BUFFER_free() destroys a NAL_BUFFER object.
NAL_BUFFER_reset() will, if necessary, cleanup any prior state in buf
so that it can be reused. Internally, there are various optimisations
and benefits to using NAL_BUFFER_reset() instead of NAL_BUFFER_free()
and NAL_BUFFER_new() - the implementation can try to avoid repeated
reallocation and reinitialisation of state.
NAL_BUFFER_set_size() sets the size of the buffer in buf to size bytes.
NAL_BUFFER_empty(), NAL_BUFFER_full(), NAL_BUFFER_notempty(), and
NAL_BUFFER_notfull() are functions that return a boolean result accord‐
ing to the size of the buffer in buf and how much of that buffer is
occupied by data.
NAL_BUFFER_used() indicates how much of buf's storage is occupied by
data and NAL_BUFFER_unused() indicates how much space is available for
more data.
NAL_BUFFER_size() indicates the size of buf's storage as specified by
the last (successful) call to NAL_BUFFER_set_size(). This should always
match the total of NAL_BUFFER_used() and NAL_BUFFER_unused().
NAL_BUFFER_data() provides a const pointer to buf's internal storage
for reading. This return value is valid until buf is either destroyed
or resized via NAL_BUFFER_set_size().
NAL_BUFFER_write() writes into buf as much as possible of the data
specified by ptr and size.
NAL_BUFFER_read() reads from buf as much data as possible into the
storage area specified by ptr and size.
NAL_BUFFER_write_ptr() returns a pointer for direct write operations
into the internal storage of buf. This pointer must be used with care,
see "NOTES".
NAL_BUFFER_wrote() allows an application to indicate how much data was
directly written into buf following NAL_BUFFER_write_ptr(), see
"NOTES".
RETURN VALUESNAL_BUFFER_new() returns a valid NAL_BUFFER object on success, NULL
otherwise.
NAL_BUFFER_free() and NAL_BUFFER_reset() have no return value.
NAL_BUFFER_empty(), NAL_BUFFER_full(), NAL_BUFFER_notempty(), and
NAL_BUFFER_notfull() return boolean results (non-zero for true).
NAL_BUFFER_set_size() returns non-zero for success, zero for failure.
NAL_BUFFER_used(), NAL_BUFFER_unused(), and NAL_BUFFER_size() return
the number of bytes of data stored, available, or allocated (respec‐
tively) in buf.
NAL_BUFFER_data() returns a pointer to the head of the data buffer in
buf.
NAL_BUFFER_write() returns the number of bytes successfully written to
buf. This may be less than size if there was less space than that
available for writing. NAL_BUFFER_read() likewise returns the number of
bytes read from buf which can be less than size if there was less data
than that available for reading.
NAL_BUFFER_write_ptr() returns a pointer to the first unused byte of
the data buffer in buf to allow writing.
NAL_BUFFER_wrote() has no return value.
NOTES
The principal use of NAL_BUFFER objects is in manipulating the read and
send buffers of a NAL_CONNECTION object, as returned from NAL_CONNEC‐
TION_get_read(2) and NAL_CONNECTION_get_send(2). This includes resizing
these buffers directly (instead of NAL_CONNECTION_set_size(2) which
sets both buffers jointly), reading data from the buffer, writing data
to the buffer, or enquiring as to the state of the buffer (empty, full,
bytes used, space available, current size, etc).
Use of the NAL_BUFFER_write_ptr() and NAL_BUFFER_wrote() functions is
not generally recommended as they directly manipulate the internals of
a NAL_BUFFER object. The return value of NAL_BUFFER_write_ptr() is only
valid for writing so long as no other operations on buf occur before
the subsequent call to NAL_BUFFER_wrote(), and this can create diffi‐
culties in state-machine logic or multi-threading situations (if
accesses to a buffer are locked, but logic occuring between these two
function calls is not locked). The NAL_BUFFER_unused() function should
be used to determine the maximum range available to write to at the
location returned by NAL_BUFFER_write_ptr().
SEE ALSONAL_ADDRESS_new(2) - Functions for the NAL_ADDRESS type.
NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION type.
NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.
NAL_SELECTOR_new(2) - Functions for the NAL_SELECTOR type.
distcache(8) - Overview of the distcache architecture.
http://www.distcache.org/ - Distcache home page.
AUTHOR
This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
graphic Appliances Incorporated. Since the project was released into
open source, it has a home page and a project environment where devel‐
opment, mailing lists, and releases are organised. For problems with
the software or this man page please check for new releases at the
project web-site below, mail the users mailing list described there, or
contact the author at geoff@geoffthorpe.net.
Home Page: http://www.distcache.org
1.4.5 2004.03.23 NAL_BUFFER_NEW(2)
