.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NAL_BUFFER_NEW 2"
.TH NAL_BUFFER_NEW 2 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
NAL_BUFFER_new, NAL_BUFFER_free, NAL_BUFFER_set_size, NAL_BUFFER_empty, NAL_BUFFER_full, NAL_BUFFER_notempty, NAL_BUFFER_notfull, NAL_BUFFER_used, NAL_BUFFER_unused, NAL_BUFFER_data, NAL_BUFFER_size, NAL_BUFFER_write, NAL_BUFFER_read, NAL_BUFFER_write_ptr, NAL_BUFFER_takedata, NAL_BUFFER_wrote \- libnal buffer functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <libnal/nal.h>
.Ve
.PP
.Vb 18
\& 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);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINAL_BUFFER_new()\fR allocates and initialises a new \fB\s-1NAL_BUFFER\s0\fR object.
.PP
\&\fINAL_BUFFER_free()\fR destroys a \fB\s-1NAL_BUFFER\s0\fR object.
.PP
\&\fINAL_BUFFER_reset()\fR will, if necessary, cleanup any prior state in \fBbuf\fR so
that it can be reused. Internally, there are various optimisations and benefits
to using \fINAL_BUFFER_reset()\fR instead of \fINAL_BUFFER_free()\fR and \fINAL_BUFFER_new()\fR \-
the implementation can try to avoid repeated reallocation and reinitialisation
of state.
.PP
\&\fINAL_BUFFER_set_size()\fR sets the size of the buffer in \fBbuf\fR to \fBsize\fR bytes.
.PP
\&\fINAL_BUFFER_empty()\fR, \fINAL_BUFFER_full()\fR, \fINAL_BUFFER_notempty()\fR, and
\&\fINAL_BUFFER_notfull()\fR are functions that return a boolean result according to
the size of the buffer in \fBbuf\fR and how much of that buffer is occupied by
data.
.PP
\&\fINAL_BUFFER_used()\fR indicates how much of \fBbuf\fR's storage is occupied by data
and \fINAL_BUFFER_unused()\fR indicates how much space is available for more data.
.PP
\&\fINAL_BUFFER_size()\fR indicates the size of \fBbuf\fR's storage as specified by the last
(successful) call to \fINAL_BUFFER_set_size()\fR. This should always match the total of
\&\fINAL_BUFFER_used()\fR and \fINAL_BUFFER_unused()\fR.
.PP
\&\fINAL_BUFFER_data()\fR provides a const pointer to \fBbuf\fR's internal storage for
reading. This return value is valid until \fBbuf\fR is either destroyed or resized
via \fINAL_BUFFER_set_size()\fR.
.PP
\&\fINAL_BUFFER_write()\fR writes into \fBbuf\fR as much as possible of the data specified
by \fBptr\fR and \fBsize\fR.
.PP
\&\fINAL_BUFFER_read()\fR reads from \fBbuf\fR as much data as possible into the storage area
specified by \fBptr\fR and \fBsize\fR.
.PP
\&\fINAL_BUFFER_write_ptr()\fR returns a pointer for direct write operations into the
internal storage of \fBbuf\fR. This pointer must be used with care, see \*(L"\s-1NOTES\s0\*(R".
.PP
\&\fINAL_BUFFER_wrote()\fR allows an application to indicate how much data was directly
written into \fBbuf\fR following \fINAL_BUFFER_write_ptr()\fR, see \*(L"\s-1NOTES\s0\*(R".
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fINAL_BUFFER_new()\fR returns a valid \fB\s-1NAL_BUFFER\s0\fR object on success, \s-1NULL\s0
otherwise.
.PP
\&\fINAL_BUFFER_free()\fR and \fINAL_BUFFER_reset()\fR have no return value.
.PP
\&\fINAL_BUFFER_empty()\fR, \fINAL_BUFFER_full()\fR, \fINAL_BUFFER_notempty()\fR, and
\&\fINAL_BUFFER_notfull()\fR return boolean results (non\-zero for true).
.PP
\&\fINAL_BUFFER_set_size()\fR returns non-zero for success, zero for failure.
.PP
\&\fINAL_BUFFER_used()\fR, \fINAL_BUFFER_unused()\fR, and \fINAL_BUFFER_size()\fR return the number
of bytes of data stored, available, or allocated (respectively) in \fBbuf\fR.
.PP
\&\fINAL_BUFFER_data()\fR returns a pointer to the head of the data buffer in \fBbuf\fR.
.PP
\&\fINAL_BUFFER_write()\fR returns the number of bytes successfully written to \fBbuf\fR.
This may be less than \fBsize\fR if there was less space than that available for
writing. \fINAL_BUFFER_read()\fR likewise returns the number of bytes read from
\&\fBbuf\fR which can be less than \fBsize\fR if there was less data than that
available for reading.
.PP
\&\fINAL_BUFFER_write_ptr()\fR returns a pointer to the first unused byte of the data
buffer in \fBbuf\fR to allow writing.
.PP
\&\fINAL_BUFFER_wrote()\fR has no return value.
.SH "NOTES"
.IX Header "NOTES"
The principal use of \fB\s-1NAL_BUFFER\s0\fR objects is in manipulating the read and send
buffers of a \fB\s-1NAL_CONNECTION\s0\fR object, as returned from
\&\fINAL_CONNECTION_get_read\fR\|(2) and \fINAL_CONNECTION_get_send\fR\|(2). This includes
resizing these buffers directly (instead of \fINAL_CONNECTION_set_size\fR\|(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).
.PP
Use of the \fINAL_BUFFER_write_ptr()\fR and \fINAL_BUFFER_wrote()\fR functions is not
generally recommended as they directly manipulate the internals of a
\&\fB\s-1NAL_BUFFER\s0\fR object. The return value of \fINAL_BUFFER_write_ptr()\fR is only valid
for writing so long as no other operations on \fBbuf\fR occur before the
subsequent call to \fINAL_BUFFER_wrote()\fR, and this can create difficulties 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 \fINAL_BUFFER_unused()\fR function should be used to determine the maximum range
available to write to at the location returned by \fINAL_BUFFER_write_ptr()\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fINAL_ADDRESS_new\fR\|(2) \- Functions for the \s-1NAL_ADDRESS\s0 type.
.PP
\&\fINAL_CONNECTION_new\fR\|(2) \- Functions for the \s-1NAL_CONNECTION\s0 type.
.PP
\&\fINAL_LISTENER_new\fR\|(2) \- Functions for the \s-1NAL_LISTENER\s0 type.
.PP
\&\fINAL_SELECTOR_new\fR\|(2) \- Functions for the \s-1NAL_SELECTOR\s0 type.
.PP
\&\fIdistcache\fR\|(8) \- Overview of the distcache architecture.
.PP
\&\fIhttp://www.distcache.org/\fR \- Distcache home page.
.SH "AUTHOR"
.IX Header "AUTHOR"
This toolkit was designed and implemented by Geoff Thorpe for Cryptographic
Appliances Incorporated. Since the project was released into open source, it
has a home page and a project environment where development, 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 \fIgeoff@geoffthorpe.net\fR.
.PP
Home Page: \fIhttp://www.distcache.org\fR