.\" 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::Packet 3"
.TH Net::SSH::Perl::Packet 3 "2008-09-24" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
Net::SSH::Perl::Packet \- Packet layer of SSH protocol
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::SSH::Perl::Packet;
.Ve
.PP
.Vb 3
\&    # Send a packet to an ssh daemon.
\&    my $pack = Net::SSH::Perl::Packet->new($ssh, type => SSH_MSG_NONE);
\&    $pack->send;
.Ve
.PP
.Vb 2
\&    # Receive a packet.
\&    my $pack = Net::SSH::Perl::Packet->read($ssh);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINet::SSH::Perl::Packet\fR implements the packet-layer piece
of the \s-1SSH\s0 protocol. Messages between server and client
are sent as binary data packets, which are encrypted
(once the two sides have agreed on the encryption
cipher, that is).
.PP
Packets are made up primarily of a packet type, which
describes the type of message and data contained
therein, and the data itself. In addition, each packet:
indicates its length in a 32\-bit unsigned integer;
contains padding to pad the length of the packet to
a multiple of 8 bytes; and is verified by a 32\-bit crc
checksum.
.PP
Refer to the \s-1SSH\s0 \s-1RFC\s0 for more details on the packet
protocol and the \s-1SSH\s0 protocol in general.
.SH "USAGE"
.IX Header "USAGE"
.ie n .Sh "Net::SSH::Perl::Packet\->new($ssh, %params)"
.el .Sh "Net::SSH::Perl::Packet\->new($ssh, \f(CW%params\fP)"
.IX Subsection "Net::SSH::Perl::Packet->new($ssh, %params)"
Creates/starts a new packet in memory. \fI$ssh\fR is
a \fINet::SSH::Perl\fR object, which should already be connected
to an ssh daemon. \fI%params\fR can contain the following
keys:
.IP "* type" 4
.IX Item "type"
The message type of this packet. This should be one of
the values exported by \fINet::SSH::Perl::Constants\fR from the
\&\fImsg\fR tag; for example, \fI\s-1SSH_MSG_NONE\s0\fR.
.IP "* data" 4
.IX Item "data"
A \fINet::SSH::Perl::Buffer\fR object containing the data in this
packet. Realistically, there aren't many times you'll need
to supply this argument: when sending a packet, it will be
created automatically; and when receiving a packet, the
\&\fIread\fR method (see below) will create the buffer
automatically, as well.
.Sh "Net::SSH::Perl::Packet\->read($ssh)"
.IX Subsection "Net::SSH::Perl::Packet->read($ssh)"
Reads a packet from the ssh daemon and returns that packet.
.PP
This method will block until an entire packet has been read.
The socket itself is non\-blocking, but the method waits (using
\&\fIselect\fR) for data on the incoming socket, then processes
that data when it comes in. If the data makes up a complete
packet, the packet is returned to the caller. Otherwise \fIread\fR
continues to try to read more data.
.Sh "Net::SSH::Perl::Packet\->read_poll($ssh)"
.IX Subsection "Net::SSH::Perl::Packet->read_poll($ssh)"
Checks the data that's been read from the sshd to see if that
data comprises a complete packet. If so, that packet is
returned. If not, returns \f(CW\*(C`undef\*(C'\fR.
.PP
This method does not block.
.ie n .Sh "Net::SSH::Perl::Packet\->read_expect($ssh, $type)"
.el .Sh "Net::SSH::Perl::Packet\->read_expect($ssh, \f(CW$type\fP)"
.IX Subsection "Net::SSH::Perl::Packet->read_expect($ssh, $type)"
Reads the next packet from the daemon and dies if the
packet type does not match \fI$type\fR. Otherwise returns
the read packet.
.ie n .Sh "$packet\->send([ $data ])"
.el .Sh "$packet\->send([ \f(CW$data\fP ])"
.IX Subsection "$packet->send([ $data ])"
Sends a packet to the ssh daemon. \fI$data\fR is optional,
and if supplied specifies the buffer to be sent in
the packet (should be a \fINet::SSH::Perl::Buffer\fR object).
In addition, \fI$data\fR, if specified, \fImust\fR include
the packed message type.
.PP
If \fI$data\fR is not specified, \fIsend\fR sends the buffer
internal to the packet, which you've presumably filled
by calling the \fIput_*\fR methods (see below).
.Sh "$packet\->type"
.IX Subsection "$packet->type"
Returns the message type of the packet \fI$packet\fR.
.Sh "$packet\->data"
.IX Subsection "$packet->data"
Returns the message buffer from the packet \fI$packet\fR;
a \fINet::SSH::Perl::Buffer\fR object.
.Sh "Net::SSH::Perl::Buffer methods"
.IX Subsection "Net::SSH::Perl::Buffer methods"
Calling methods from the \fINet::SSH::Perl::Buffer\fR class on
your \fINet::SSH::Perl::Packet\fR object will automatically
invoke those methods on the buffer object internal
to your packet object (which is created when your
object is constructed). For example, if you executed
the following code:
.PP
.Vb 2
\&    my $packet = Net::SSH::Perl::Packet->new($ssh, type => SSH_CMSG_USER);
\&    $packet->put_str($user);
.Ve
.PP
this would construct a new packet object \fI$packet\fR,
then fill its internal buffer by calling the
\&\fIput_str\fR method on it.
.PP
Refer to the \fINet::SSH::Perl::Buffer\fR documentation
(the \fI\s-1GET\s0 \s-1AND\s0 \s-1PUT\s0 \s-1METHODS\s0\fR section) for more details
on those methods.
.SH "AUTHOR & COPYRIGHTS"
.IX Header "AUTHOR & COPYRIGHTS"
Please see the Net::SSH::Perl manpage for author, copyright,
and license information.