1Net::SSH::Perl::Buffer(U3s)er Contributed Perl DocumentatNieotn::SSH::Perl::Buffer(3)
2
3
4

NAME

6       Net::SSH::Perl::Buffer - Low-level read/write buffer class
7

SYNOPSIS

9           use Net::SSH::Perl::Buffer (@args);
10           my $buffer = Net::SSH::Perl::Buffer->new;
11
12           ## Add a 32-bit integer.
13           $buffer->put_int32(10932930);
14
15           ## Get it back.
16           my $int = $buffer->get_int32;
17

DESCRIPTION

19       Net::SSH::Perl::Buffer implements the low-level binary buffer needed by
20       the Net::SSH::Perl suite. Specifically, a Net::SSH::Perl::Buffer object
21       is what makes up the data segment of a packet transferred between
22       server and client (a Net::SSH::Perl::Packet object).
23
24       Buffers contain integers, strings, characters, etc. Because of the use
25       of GMP integers in SSH, buffers can also contain multiple-precision
26       integers (represented internally by Math::GMP objects).
27
28       Note: the method documentation here is in what some might call a
29       slightly backwards order. The reason for this is that the get and put
30       methods (listed first) are probably what most users/developers of
31       Net::SSH::Perl need to care about; they're high-level methods used to
32       get/put data from the buffer. The other methods (LOW-LEVEL METHODS) are
33       much more low-level, and typically you won't need to use them
34       explicitly.
35

GET AND PUT METHODS

37       All of the get_* and put_* methods respect the internal offset state in
38       the buffer object. This means that, for example, if you call get_int16
39       twice in a row, you can be ensured that you'll get the next two 16-bit
40       integers in the buffer. You don't need to worry about the number of
41       bytes a certain piece of data takes up, for example.
42
43   $buffer->get_int8
44       Returns the next 8-bit integer from the buffer (which is really just
45       the ASCII code for the next character/byte in the buffer).
46
47   $buffer->put_int8
48       Appends an 8-bit integer to the buffer (which is really just the
49       character corresponding to that integer, in ASCII).
50
51   $buffer->get_int16
52       Returns the next 16-bit integer from the buffer.
53
54   $buffer->put_int16($integer)
55       Appends a 16-bit integer to the buffer.
56
57   $buffer->get_int32
58       Returns the next 32-bit integer from the buffer.
59
60   $buffer->put_int32($integer)
61       Appends a 32-bit integer to the buffer.
62
63   $buffer->get_char
64       More appropriately called get_byte, perhaps, this returns the next byte
65       from the buffer.
66
67   $buffer->put_char($bytes)
68       Appends a byte (or a sequence of bytes) to the buffer.  There is no
69       restriction on the length of the byte string $bytes; if it makes you
70       uncomfortable to call put_char to put multiple bytes, you can instead
71       call this method as put_chars. It's the same thing.
72
73   $buffer->get_str
74       Returns the next "string" from the buffer. A string here is represented
75       as the length of the string (a 32-bit integer) followed by the string
76       itself.
77
78   $buffer->put_str($string)
79       Appends a string (32-bit integer length and the string itself) to the
80       buffer.
81
82   $buffer->get_mp_int
83       Returns a bigint object representing a multiple precision integer read
84       from the buffer. Depending on the protocol, the object is either of
85       type Math::GMP (SSH1) or Math::Pari (SSH2).
86
87       You determine which protocol will be in use when you use the module:
88       specify SSH1 or SSH2 to load the proper get and put routines for
89       bigints:
90
91           use Net::SSH::Perl::Buffer qw( SSH1 );
92
93   $buffer->put_mp_int($mp_int)
94       Appends a multiple precision integer to the buffer.  Depending on the
95       protocol in use, $mp_int should be either a Math::GMP object (SSH1) or
96       a Math::Pari object (SSH2). The format in which the integer is stored
97       in the buffer differs between the protocols, as well.
98

LOW-LEVEL METHODS

100   Net::SSH::Perl::Buffer->new
101       Creates a new buffer object and returns it. The buffer is empty.
102
103       This method takes no arguments.
104
105   $buffer->append($bytes)
106       Appends raw data $bytes to the end of the in-memory buffer. Generally
107       you don't need to use this method unless you're initializing an empty
108       buffer, because when you need to add data to a buffer you should
109       generally use one of the put_* methods.
110
111   $buffer->empty
112       Empties out the buffer object.
113
114   $buffer->bytes([ $offset [, $length [, $replacement ]]])
115       Behaves exactly like the substr built-in function, except on the buffer
116       $buffer. Given no arguments, bytes returns the entire buffer; given one
117       argument $offset, returns everything from that position to the end of
118       the string; given $offset and $length, returns the segment of the
119       buffer starting at $offset and consisting of $length bytes; and given
120       all three arguments, replaces that segment with $replacement.
121
122       This is a very low-level method, and you generally won't need to use
123       it.
124
125       Also be warned that you should not intermix use of this method with use
126       of the get_* and put_* methods; the latter classes of methods maintain
127       internal state of the buffer offset where arguments will be gotten from
128       and put, respectively. The bytes method gives no thought to this
129       internal offset state.
130
131   $buffer->length
132       Returns the length of the buffer object.
133
134   $buffer->offset
135       Returns the internal offset state.
136
137       If you insist on intermixing calls to bytes with calls to the get_* and
138       put_* methods, you'll probably want to use this method to get some
139       status on that internal offset.
140
141   $buffer->dump
142       Returns a hex dump of the buffer.
143
144   $buffer->insert_padding
145       A helper method: pads out the buffer so that the length of the
146       transferred packet will be evenly divisible by 8, which is a
147       requirement of the SSH protocol.
148

AUTHOR & COPYRIGHTS

150       Please see the Net::SSH::Perl manpage for author, copyright, and
151       license information.
152
153
154
155perl v5.12.2                      2008-10-02         Net::SSH::Perl::Buffer(3)
Impressum