1Net::SSH::Perl::Buffer(U3s)er Contributed Perl DocumentatNieotn::SSH::Perl::Buffer(3)
2
6 Net::SSH::Perl::Buffer - Low-level read/write buffer class
7
9 use Net::SSH::Perl::Buffer (@args);
10 my $buffer = Net::SSH::Perl::Buffer->new;
11 ## Add a 32-bit integer.
13 $buffer->put_int32(10932930);
14 ## Get it back.
16 my $int = $buffer->get_int32;
17
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 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 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 explic‐
34 itly.
35
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 $buffer->get_int8
44 Returns the next 8-bit integer from the buffer (which is really just
46 the ASCII code for the next character/byte in the buffer).
47 $buffer->put_int8
49 Appends an 8-bit integer to the buffer (which is really just the char‐
51 acter corresponding to that integer, in ASCII).
52 $buffer->get_int16
54 Returns the next 16-bit integer from the buffer.
56 $buffer->put_int16($integer)
58 Appends a 16-bit integer to the buffer.
60 $buffer->get_int32
62 Returns the next 32-bit integer from the buffer.
64 $buffer->put_int32($integer)
66 Appends a 32-bit integer to the buffer.
68 $buffer->get_char
70 More appropriately called get_byte, perhaps, this returns the next byte
72 from the buffer.
73 $buffer->put_char($bytes)
75 Appends a byte (or a sequence of bytes) to the buffer. There is no
77 restriction on the length of the byte string $bytes; if it makes you
78 uncomfortable to call put_char to put multiple bytes, you can instead
79 call this method as put_chars. It's the same thing.
80 $buffer->get_str
82 Returns the next "string" from the buffer. A string here is represented
84 as the length of the string (a 32-bit integer) followed by the string
85 itself.
86 $buffer->put_str($string)
88 Appends a string (32-bit integer length and the string itself) to the
90 buffer.
91 $buffer->get_mp_int
93 Returns a bigint object representing a multiple precision integer read
95 from the buffer. Depending on the protocol, the object is either of
96 type Math::GMP (SSH1) or Math::Pari (SSH2).
97 You determine which protocol will be in use when you use the module:
99 specify SSH1 or SSH2 to load the proper get and put routines for big‐
100 ints:
101 use Net::SSH::Perl::Buffer qw( SSH1 );
103 $buffer->put_mp_int($mp_int)
105 Appends a multiple precision integer to the buffer. Depending on the
107 protocol in use, $mp_int should be either a Math::GMP object (SSH1) or
108 a Math::Pari object (SSH2). The format in which the integer is stored
109 in the buffer differs between the protocols, as well.
110
112 Net::SSH::Perl::Buffer->new
113 Creates a new buffer object and returns it. The buffer is empty.
115 This method takes no arguments.
117 $buffer->append($bytes)
119 Appends raw data $bytes to the end of the in-memory buffer. Generally
121 you don't need to use this method unless you're initializing an empty
122 buffer, because when you need to add data to a buffer you should gener‐
123 ally use one of the put_* methods.
124 $buffer->empty
126 Empties out the buffer object.
128 $buffer->bytes([ $offset [, $length [, $replacement ]]])
130 Behaves exactly like the substr built-in function, except on the buffer
132 $buffer. Given no arguments, bytes returns the entire buffer; given one
133 argument $offset, returns everything from that position to the end of
134 the string; given $offset and $length, returns the segment of the buf‐
135 fer starting at $offset and consisting of $length bytes; and given all
136 three arguments, replaces that segment with $replacement.
137 This is a very low-level method, and you generally won't need to use
139 it.
140 Also be warned that you should not intermix use of this method with use
142 of the get_* and put_* methods; the latter classes of methods maintain
143 internal state of the buffer offset where arguments will be gotten from
144 and put, respectively. The bytes method gives no thought to this inter‐
145 nal offset state.
146 $buffer->length
148 Returns the length of the buffer object.
150 $buffer->offset
152 Returns the internal offset state.
154 If you insist on intermixing calls to bytes with calls to the get_* and
156 put_* methods, you'll probably want to use this method to get some sta‐
157 tus on that internal offset.
158 $buffer->dump
160 Returns a hex dump of the buffer.
162 $buffer->insert_padding
164 A helper method: pads out the buffer so that the length of the trans‐
166 ferred packet will be evenly divisible by 8, which is a requirement of
167 the SSH protocol.
168
170 Please see the Net::SSH::Perl manpage for author, copyright, and
171 license information.
172perl v5.8.8 2003-12-03 Net::SSH::Perl::Buffer(3)