.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" 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.  \*(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-
.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 "Buffer 3pm"
.TH Buffer 3pm "2001-07-28" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Data::Buffer \- Read/write buffer class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Data::Buffer;
\&    my $buffer = Data::Buffer\->new;
.Ve
.PP
.Vb 2
\&    ## Add a 32\-bit integer.
\&    $buffer\->put_int32(10932930);
.Ve
.PP
.Vb 2
\&    ## Get it back.
\&    my $int = $buffer\->get_int32;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIData::Buffer\fR implements a low-level binary buffer in which
you can get and put integers, strings, and other data.
Internally the implementation is based on \f(CW\*(C`pack\*(C'\fR and \f(CW\*(C`unpack\*(C'\fR,
such that \fIData::Buffer\fR is really a layer on top of those
built-in functions.
.PP
All of the \fIget_*\fR and \fIput_*\fR methods respect the
internal offset state in the buffer object. This means that
you should read data out of the buffer in the same order that
you put it in. For example:
.PP
.Vb 3
\&    $buf\->put_int16(24);
\&    $buf\->put_int32(1233455);
\&    $buf\->put_int16(99);
.Ve
.PP
.Vb 3
\&    $buf\->get_int16;   # 24
\&    $buf\->get_int32;   # 1233455
\&    $buf\->get_int16;   # 99
.Ve
.PP
Of course, this assumes that you \fIknow\fR the order of the data
items in the buffer. If your setup is such that your sending
and receiving processes won't necessarily know what's inside
the buffers they receive, take a look at the \fI\s-1TEMPLATE\s0 \s-1USAGE\s0\fR
section.
.SH "USAGE"
.IX Header "USAGE"
.Sh "Data::Buffer\->new"
.IX Subsection "Data::Buffer->new"
Creates a new buffer object and returns it. The buffer is
initially empty.
.PP
This method takes no arguments.
.Sh "Data::Buffer\->new_with_init(@strs)"
.IX Subsection "Data::Buffer->new_with_init(@strs)"
Creates a new buffer object and appends to it each of the
octet strings in \fI@strs\fR.
.PP
Returns the new buffer object.
.Sh "$buffer\->get_int8"
.IX Subsection "$buffer->get_int8"
Returns the next 8\-bit integer from the buffer (which
is really just the \s-1ASCII\s0 code for the next character/byte
in the buffer).
.Sh "$buffer\->put_int8"
.IX Subsection "$buffer->put_int8"
Appends an 8\-bit integer to the buffer (which is really
just the character corresponding to that integer, in
\&\s-1ASCII\s0).
.Sh "$buffer\->get_int16"
.IX Subsection "$buffer->get_int16"
Returns the next 16\-bit integer from the buffer.
.Sh "$buffer\->put_int16($integer)"
.IX Subsection "$buffer->put_int16($integer)"
Appends a 16\-bit integer to the buffer.
.Sh "$buffer\->get_int32"
.IX Subsection "$buffer->get_int32"
Returns the next 32\-bit integer from the buffer.
.Sh "$buffer\->put_int32($integer)"
.IX Subsection "$buffer->put_int32($integer)"
Appends a 32\-bit integer to the buffer.
.Sh "$buffer\->get_char"
.IX Subsection "$buffer->get_char"
More appropriately called \fIget_byte\fR, perhaps, this
returns the next byte from the buffer.
.Sh "$buffer\->put_char($bytes)"
.IX Subsection "$buffer->put_char($bytes)"
Appends a byte (or a sequence of bytes) to the buffer.
There is no restriction on the length of the byte
string \fI$bytes\fR; if it makes you uncomfortable to call
\&\fIput_char\fR to put multiple bytes, you can instead
call this method as \fIput_chars\fR. It's the same thing.
.Sh "$buffer\->get_bytes($n)"
.IX Subsection "$buffer->get_bytes($n)"
Grabs \fI$n\fR bytes from the buffer, where \fI$n\fR is a positive
integer. Increments the internal offset state by \fI$n\fR.
.ie n .Sh "$buffer\->put_bytes($bytes [, $n ])"
.el .Sh "$buffer\->put_bytes($bytes [, \f(CW$n\fP ])"
.IX Subsection "$buffer->put_bytes($bytes [, $n ])"
Appends a sequence of bytes to the buffer; if \fI$n\fR is
unspecified, appends the entire length of \fI$bytes\fR.
Otherwise appends only the first \fI$n\fR bytes of \fI$bytes\fR.
.Sh "$buffer\->get_str"
.IX Subsection "$buffer->get_str"
Returns the next \*(L"string\*(R" from the buffer. A string here
is represented as the length of the string (a 32\-bit
integer) followed by the string itself.
.Sh "$buffer\->put_str($string)"
.IX Subsection "$buffer->put_str($string)"
Appends a string (32\-bit integer length and the string
itself) to the buffer.
.Sh "$buffer\->extract($n)"
.IX Subsection "$buffer->extract($n)"
Extracts the next \fI$n\fR bytes from the buffer \fI$buffer\fR,
increments the offset state in \fI$buffer\fR, and returns a
new buffer object containing the extracted bytes.
.SH "TEMPLATE USAGE"
.IX Header "TEMPLATE USAGE"
Generally when you use \fIData::Buffer\fR it's to communicate
with another process (perhaps a C program) that bundles up
its data into binary buffers. In those cases, it's very likely
that the data will be in some well-known order in the buffer:
in other words, it might be documented that a certain C program
creates a buffer containing:
.IP "* an int8" 4
.IX Item "an int8"
.PD 0
.IP "* a string" 4
.IX Item "a string"
.IP "* an int32" 4
.IX Item "an int32"
.PD
.PP
In this case, you would presumably know about the order of the
data in the buffer, and you could extract it accordingly:
.PP
.Vb 3
\&    $buffer\->get_int8;
\&    $buffer\->get_str;
\&    $buffer\->get_int32;
.Ve
.PP
In other cases, however, there may not be a well-defined order
of data items in the buffer. This might be the case if you're
inventing your own protocol, and you want your binary buffers
to \*(L"know\*(R" about their contents. In this case, you'll want to
use the templating features of \fIData::Buffer\fR.
.PP
When you use the \fIput_\fR methods to place data in a buffer,
\&\fIData::Buffer\fR keeps track of the types of data that you're
inserting in a template description of the buffer. This template
contains all of the information necessary for a process to
receive a buffer and extract the data in the buffer without
knowledge of the order of the items.
.PP
To use this feature, simply use the \fIinsert_template\fR method
after you've filled your buffer to completion. For example:
.PP
.Vb 4
\&    my $buffer = Data::Buffer\->new;
\&    $buffer\->put_str("foo");
\&    $buffer\->put_int32(9999);
\&    $buffer\->insert_template;
.Ve
.PP
.Vb 1
\&    ## Ship off the buffer to another process.
.Ve
.PP
The receiving process should then invoke the \fIget_all\fR method
on the buffer to extract all of the data:
.PP
.Vb 3
\&    my $buffer = Data::Buffer\->new;
\&    $buffer\->append( $received_buffer_data );
\&    my @data = $buffer\->get_all;
.Ve
.PP
@data will now contain two elements: \f(CW"foo"\fR and \f(CW9999\fR.
.SH "LOW-LEVEL METHODS"
.IX Header "LOW-LEVEL METHODS"
.Sh "$buffer\->append($bytes)"
.IX Subsection "$buffer->append($bytes)"
Appends raw data \fI$bytes\fR to the end of the in-memory
buffer. Generally you don't need to use this method
unless you're initializing an empty buffer, because
when you need to add data to a buffer you should
generally use one of the \fIput_*\fR methods.
.Sh "$buffer\->empty"
.IX Subsection "$buffer->empty"
Empties out the buffer object.
.ie n .Sh "$buffer\->bytes([ $offset\fP [, \f(CW$length\fP [, \f(CW$replacement ]]])"
.el .Sh "$buffer\->bytes([ \f(CW$offset\fP [, \f(CW$length\fP [, \f(CW$replacement\fP ]]])"
.IX Subsection "$buffer->bytes([ $offset [, $length [, $replacement ]]])"
Behaves exactly like the \fIsubstr\fR built-in function,
except on the buffer \fI$buffer\fR. Given no arguments,
\&\fIbytes\fR returns the entire buffer; given one argument
\&\fI$offset\fR, returns everything from that position to
the end of the string; given \fI$offset\fR and \fI$length\fR,
returns the segment of the buffer starting at \fI$offset\fR
and consisting of \fI$length\fR bytes; and given all three
arguments, replaces that segment with \fI$replacement\fR.
.PP
This is a very low-level method, and you generally
won't need to use it.
.PP
Also be warned that you should not intermix use of this
method with use of the \fIget_*\fR and \fIput_*\fR methods;
the latter classes of methods maintain internal state
of the buffer offset where arguments will be gotten from
and put, respectively. The \fIbytes\fR method gives no
thought to this internal offset state.
.Sh "$buffer\->length"
.IX Subsection "$buffer->length"
Returns the length of the buffer object.
.Sh "$buffer\->offset"
.IX Subsection "$buffer->offset"
Returns the internal offset state.
.PP
If you insist on intermixing calls to \fIbytes\fR with calls
to the \fIget_*\fR and \fIput_*\fR methods, you'll probably
want to use this method to get some status on that
internal offset.
.Sh "$buffer\->set_offset($offset)"
.IX Subsection "$buffer->set_offset($offset)"
Sets the internal offset state to \fI$offset\fR.
.Sh "$buffer\->reset_offset"
.IX Subsection "$buffer->reset_offset"
Sets the internal offset state to 0.
.Sh "$buffer\->dump(@args)"
.IX Subsection "$buffer->dump(@args)"
Returns a hex dump of the buffer. The dump is of the \fIentire\fR
buffer \fI$buffer\fR; in other words, \fIdump\fR doesn't respect the
internal offset pointer.
.PP
\&\fI@args\fR is passed directly through to the \fIbytes\fR method,
which means that you can supply arguments to emulate support
of the internal offset:
.PP
.Vb 1
\&    my $dump = $buffer\->dump($buffer\->offset);
.Ve
.Sh "$buffer\->insert_padding"
.IX Subsection "$buffer->insert_padding"
A helper method: pads out the buffer so that the length
of the transferred packet will be evenly divisible by
8, which is a requirement of the \s-1SSH\s0 protocol.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Benjamin Trott, ben@rhumba.pair.com
.PP
Except where otherwise noted, Data::Buffer is Copyright 2001
Benjamin Trott. All rights reserved. Data::Buffer is free
software; you may redistribute it and/or modify it under
the same terms as Perl itself.