1Buffer(3) User Contributed Perl Documentation Buffer(3)
2
6 Data::Buffer - Read/write buffer class
7
9 use Data::Buffer;
10 my $buffer = Data::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 Data::Buffer implements a low-level binary buffer in which you can get
20 and put integers, strings, and other data. Internally the implementa‐
21 tion is based on "pack" and "unpack", such that Data::Buffer is really
22 a layer on top of those built-in functions.
23 All of the get_* and put_* methods respect the internal offset state in
25 the buffer object. This means that you should read data out of the buf‐
26 fer in the same order that you put it in. For example:
27 $buf->put_int16(24);
29 $buf->put_int32(1233455);
30 $buf->put_int16(99);
31 $buf->get_int16; # 24
33 $buf->get_int32; # 1233455
34 $buf->get_int16; # 99
35 Of course, this assumes that you know the order of the data items in
37 the buffer. If your setup is such that your sending and receiving pro‐
38 cesses won't necessarily know what's inside the buffers they receive,
39 take a look at the TEMPLATE USAGE section.
40
42 Data::Buffer->new
43 Creates a new buffer object and returns it. The buffer is initially
45 empty.
46 This method takes no arguments.
48 Data::Buffer->new_with_init(@strs)
50 Creates a new buffer object and appends to it each of the octet strings
52 in @strs.
53 Returns the new buffer object.
55 $buffer->get_int8
57 Returns the next 8-bit integer from the buffer (which is really just
59 the ASCII code for the next character/byte in the buffer).
60 $buffer->put_int8
62 Appends an 8-bit integer to the buffer (which is really just the char‐
64 acter corresponding to that integer, in ASCII).
65 $buffer->get_int16
67 Returns the next 16-bit integer from the buffer.
69 $buffer->put_int16($integer)
71 Appends a 16-bit integer to the buffer.
73 $buffer->get_int32
75 Returns the next 32-bit integer from the buffer.
77 $buffer->put_int32($integer)
79 Appends a 32-bit integer to the buffer.
81 $buffer->get_char
83 More appropriately called get_byte, perhaps, this returns the next byte
85 from the buffer.
86 $buffer->put_char($bytes)
88 Appends a byte (or a sequence of bytes) to the buffer. There is no
90 restriction on the length of the byte string $bytes; if it makes you
91 uncomfortable to call put_char to put multiple bytes, you can instead
92 call this method as put_chars. It's the same thing.
93 $buffer->get_bytes($n)
95 Grabs $n bytes from the buffer, where $n is a positive integer. Incre‐
97 ments the internal offset state by $n.
98 $buffer->put_bytes($bytes [, $n ])
100 Appends a sequence of bytes to the buffer; if $n is unspecified,
102 appends the entire length of $bytes. Otherwise appends only the first
103 $n bytes of $bytes.
104 $buffer->get_str
106 Returns the next "string" from the buffer. A string here is represented
108 as the length of the string (a 32-bit integer) followed by the string
109 itself.
110 $buffer->put_str($string)
112 Appends a string (32-bit integer length and the string itself) to the
114 buffer.
115 $buffer->extract($n)
117 Extracts the next $n bytes from the buffer $buffer, increments the off‐
119 set state in $buffer, and returns a new buffer object containing the
120 extracted bytes.
121
123 Generally when you use Data::Buffer it's to communicate with another
124 process (perhaps a C program) that bundles up its data into binary buf‐
125 fers. In those cases, it's very likely that the data will be in some
126 well-known order in the buffer: in other words, it might be documented
127 that a certain C program creates a buffer containing:
128 * an int8
130 * a string
131 * an int32
132 In this case, you would presumably know about the order of the data in
134 the buffer, and you could extract it accordingly:
135 $buffer->get_int8;
137 $buffer->get_str;
138 $buffer->get_int32;
139 In other cases, however, there may not be a well-defined order of data
141 items in the buffer. This might be the case if you're inventing your
142 own protocol, and you want your binary buffers to "know" about their
143 contents. In this case, you'll want to use the templating features of
144 Data::Buffer.
145 When you use the put_ methods to place data in a buffer, Data::Buffer
147 keeps track of the types of data that you're inserting in a template
148 description of the buffer. This template contains all of the informa‐
149 tion necessary for a process to receive a buffer and extract the data
150 in the buffer without knowledge of the order of the items.
151 To use this feature, simply use the insert_template method after you've
153 filled your buffer to completion. For example:
154 my $buffer = Data::Buffer->new;
156 $buffer->put_str("foo");
157 $buffer->put_int32(9999);
158 $buffer->insert_template;
159 ## Ship off the buffer to another process.
161 The receiving process should then invoke the get_all method on the buf‐
163 fer to extract all of the data:
164 my $buffer = Data::Buffer->new;
166 $buffer->append( $received_buffer_data );
167 my @data = $buffer->get_all;
168 @data will now contain two elements: "foo" and 9999.
170
172 $buffer->append($bytes)
173 Appends raw data $bytes to the end of the in-memory buffer. Generally
175 you don't need to use this method unless you're initializing an empty
176 buffer, because when you need to add data to a buffer you should gener‐
177 ally use one of the put_* methods.
178 $buffer->empty
180 Empties out the buffer object.
182 $buffer->bytes([ $offset [, $length [, $replacement ]]])
184 Behaves exactly like the substr built-in function, except on the buffer
186 $buffer. Given no arguments, bytes returns the entire buffer; given one
187 argument $offset, returns everything from that position to the end of
188 the string; given $offset and $length, returns the segment of the buf‐
189 fer starting at $offset and consisting of $length bytes; and given all
190 three arguments, replaces that segment with $replacement.
191 This is a very low-level method, and you generally won't need to use
193 it.
194 Also be warned that you should not intermix use of this method with use
196 of the get_* and put_* methods; the latter classes of methods maintain
197 internal state of the buffer offset where arguments will be gotten from
198 and put, respectively. The bytes method gives no thought to this inter‐
199 nal offset state.
200 $buffer->length
202 Returns the length of the buffer object.
204 $buffer->offset
206 Returns the internal offset state.
208 If you insist on intermixing calls to bytes with calls to the get_* and
210 put_* methods, you'll probably want to use this method to get some sta‐
211 tus on that internal offset.
212 $buffer->set_offset($offset)
214 Sets the internal offset state to $offset.
216 $buffer->reset_offset
218 Sets the internal offset state to 0.
220 $buffer->dump(@args)
222 Returns a hex dump of the buffer. The dump is of the entire buffer
224 $buffer; in other words, dump doesn't respect the internal offset
225 pointer.
226 @args is passed directly through to the bytes method, which means that
228 you can supply arguments to emulate support of the internal offset:
229 my $dump = $buffer->dump($buffer->offset);
231 $buffer->insert_padding
233 A helper method: pads out the buffer so that the length of the trans‐
235 ferred packet will be evenly divisible by 8, which is a requirement of
236 the SSH protocol.
237
239 Benjamin Trott, ben@rhumba.pair.com
240 Except where otherwise noted, Data::Buffer is Copyright 2001 Benjamin
242 Trott. All rights reserved. Data::Buffer is free software; you may
243 redistribute it and/or modify it under the same terms as Perl itself.
244perl v5.8.8 2001-07-28 Buffer(3)