.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.37
.\"
.\" 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 "Net::SSH::Perl::Buffer 3"
.TH Net::SSH::Perl::Buffer 3 "2008-10-02" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::SSH::Perl::Buffer \- Low\-level read/write buffer class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Net::SSH::Perl::Buffer (@args);
\&    my $buffer = Net::SSH::Perl::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"
\&\fINet::SSH::Perl::Buffer\fR implements the low-level binary
buffer needed by the \fINet::SSH::Perl\fR suite. Specifically,
a \fINet::SSH::Perl::Buffer\fR object is what makes up the
data segment of a packet transferred between server and
client (a \fINet::SSH::Perl::Packet\fR object).
.PP
Buffers contain integers, strings, characters, etc. Because
of the use of \s-1GMP\s0 integers in \s-1SSH\s0, buffers can also contain
multiple-precision integers (represented internally by
\&\fIMath::GMP\fR objects).
.PP
Note: the method documentation here is in what some might
call a slightly backwards order. The reason for this is that
the get and put methods (listed first) are probably what
most users/developers of \fINet::SSH::Perl\fR need to care
about; they're high-level methods used to get/put data
from the buffer. The other methods (\fILOW-LEVEL \s-1METHODS\s0\fR)
are much more low\-level, and typically you won't need to
use them explicitly.
.SH "GET AND PUT METHODS"
.IX Header "GET AND PUT METHODS"
All of the \fIget_*\fR and \fIput_*\fR methods respect the
internal offset state in the buffer object. This means
that, for example, if you call \fIget_int16\fR twice in a
row, you can be ensured that you'll get the next two
16\-bit integers in the buffer. You don't need to worry
about the number of bytes a certain piece of data takes
up, for example.
.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_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\->get_mp_int"
.IX Subsection "$buffer->get_mp_int"
Returns a bigint object representing a multiple precision
integer read from the buffer. Depending on the protocol,
the object is either of type \fIMath::GMP\fR (\s-1SSH1\s0) or
\&\fIMath::Pari\fR (\s-1SSH2\s0).
.PP
You determine which protocol will be in use when you
\&\fIuse\fR the module: specify \fI\s-1SSH1\s0\fR or \fI\s-1SSH2\s0\fR to load
the proper \fIget\fR and \fIput\fR routines for bigints:
.PP
.Vb 1
\&    use Net::SSH::Perl::Buffer qw( SSH1 );
.Ve
.Sh "$buffer\->put_mp_int($mp_int)"
.IX Subsection "$buffer->put_mp_int($mp_int)"
Appends a multiple precision integer to the buffer.
Depending on the protocol in use, \fI$mp_int\fR should
be either a \fIMath::GMP\fR object (\s-1SSH1\s0) or a \fIMath::Pari\fR
object (\s-1SSH2\s0). The format in which the integer is
stored in the buffer differs between the protocols,
as well.
.SH "LOW-LEVEL METHODS"
.IX Header "LOW-LEVEL METHODS"
.Sh "Net::SSH::Perl::Buffer\->new"
.IX Subsection "Net::SSH::Perl::Buffer->new"
Creates a new buffer object and returns it. The buffer is
empty.
.PP
This method takes no arguments.
.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\->dump"
.IX Subsection "$buffer->dump"
Returns a hex dump of the buffer.
.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"
Please see the Net::SSH::Perl manpage for author, copyright,
and license information.