1Buffer(3)             User Contributed Perl Documentation            Buffer(3)
2
3
4

NAME

6       Data::Buffer - Read/write buffer class
7

SYNOPSIS

9           use Data::Buffer;
10           my $buffer = Data::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       Data::Buffer implements a low-level binary buffer in which you can get
20       and put integers, strings, and other data.  Internally the
21       implementation is based on "pack" and "unpack", such that Data::Buffer
22       is really a layer on top of those built-in functions.
23
24       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
26       buffer in the same order that you put it in. For example:
27
28           $buf->put_int16(24);
29           $buf->put_int32(1233455);
30           $buf->put_int16(99);
31
32           $buf->get_int16;   # 24
33           $buf->get_int32;   # 1233455
34           $buf->get_int16;   # 99
35
36       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
38       processes won't necessarily know what's inside the buffers they
39       receive, take a look at the TEMPLATE USAGE section.
40

USAGE

42   Data::Buffer->new
43       Creates a new buffer object and returns it. The buffer is initially
44       empty.
45
46       This method takes no arguments.
47
48   Data::Buffer->new_with_init(@strs)
49       Creates a new buffer object and appends to it each of the octet strings
50       in @strs.
51
52       Returns the new buffer object.
53
54   $buffer->get_int8
55       Returns the next 8-bit integer from the buffer (which is really just
56       the ASCII code for the next character/byte in the buffer).
57
58   $buffer->put_int8
59       Appends an 8-bit integer to the buffer (which is really just the
60       character corresponding to that integer, in ASCII).
61
62   $buffer->get_int16
63       Returns the next 16-bit integer from the buffer.
64
65   $buffer->put_int16($integer)
66       Appends a 16-bit integer to the buffer.
67
68   $buffer->get_int32
69       Returns the next 32-bit integer from the buffer.
70
71   $buffer->put_int32($integer)
72       Appends a 32-bit integer to the buffer.
73
74   $buffer->get_char
75       More appropriately called get_byte, perhaps, this returns the next byte
76       from the buffer.
77
78   $buffer->put_char($bytes)
79       Appends a byte (or a sequence of bytes) to the buffer.  There is no
80       restriction on the length of the byte string $bytes; if it makes you
81       uncomfortable to call put_char to put multiple bytes, you can instead
82       call this method as put_chars. It's the same thing.
83
84   $buffer->get_bytes($n)
85       Grabs $n bytes from the buffer, where $n is a positive integer.
86       Increments the internal offset state by $n.
87
88   $buffer->put_bytes($bytes [, $n ])
89       Appends a sequence of bytes to the buffer; if $n is unspecified,
90       appends the entire length of $bytes.  Otherwise appends only the first
91       $n bytes of $bytes.
92
93   $buffer->get_str
94       Returns the next "string" from the buffer. A string here is represented
95       as the length of the string (a 32-bit integer) followed by the string
96       itself.
97
98   $buffer->put_str($string)
99       Appends a string (32-bit integer length and the string itself) to the
100       buffer.
101
102   $buffer->extract($n)
103       Extracts the next $n bytes from the buffer $buffer, increments the
104       offset state in $buffer, and returns a new buffer object containing the
105       extracted bytes.
106

TEMPLATE USAGE

108       Generally when you use Data::Buffer it's to communicate with another
109       process (perhaps a C program) that bundles up its data into binary
110       buffers. In those cases, it's very likely that the data will be in some
111       well-known order in the buffer: in other words, it might be documented
112       that a certain C program creates a buffer containing:
113
114       ·   an int8
115
116       ·   a string
117
118       ·   an int32
119
120       In this case, you would presumably know about the order of the data in
121       the buffer, and you could extract it accordingly:
122
123           $buffer->get_int8;
124           $buffer->get_str;
125           $buffer->get_int32;
126
127       In other cases, however, there may not be a well-defined order of data
128       items in the buffer. This might be the case if you're inventing your
129       own protocol, and you want your binary buffers to "know" about their
130       contents. In this case, you'll want to use the templating features of
131       Data::Buffer.
132
133       When you use the put_ methods to place data in a buffer, Data::Buffer
134       keeps track of the types of data that you're inserting in a template
135       description of the buffer. This template contains all of the
136       information necessary for a process to receive a buffer and extract the
137       data in the buffer without knowledge of the order of the items.
138
139       To use this feature, simply use the insert_template method after you've
140       filled your buffer to completion. For example:
141
142           my $buffer = Data::Buffer->new;
143           $buffer->put_str("foo");
144           $buffer->put_int32(9999);
145           $buffer->insert_template;
146
147           ## Ship off the buffer to another process.
148
149       The receiving process should then invoke the get_all method on the
150       buffer to extract all of the data:
151
152           my $buffer = Data::Buffer->new;
153           $buffer->append( $received_buffer_data );
154           my @data = $buffer->get_all;
155
156       @data will now contain two elements: "foo" and 9999.
157

LOW-LEVEL METHODS

159   $buffer->append($bytes)
160       Appends raw data $bytes to the end of the in-memory buffer. Generally
161       you don't need to use this method unless you're initializing an empty
162       buffer, because when you need to add data to a buffer you should
163       generally use one of the put_* methods.
164
165   $buffer->empty
166       Empties out the buffer object.
167
168   $buffer->bytes([ $offset [, $length [, $replacement ]]])
169       Behaves exactly like the substr built-in function, except on the buffer
170       $buffer. Given no arguments, bytes returns the entire buffer; given one
171       argument $offset, returns everything from that position to the end of
172       the string; given $offset and $length, returns the segment of the
173       buffer starting at $offset and consisting of $length bytes; and given
174       all three arguments, replaces that segment with $replacement.
175
176       This is a very low-level method, and you generally won't need to use
177       it.
178
179       Also be warned that you should not intermix use of this method with use
180       of the get_* and put_* methods; the latter classes of methods maintain
181       internal state of the buffer offset where arguments will be gotten from
182       and put, respectively. The bytes method gives no thought to this
183       internal offset state.
184
185   $buffer->length
186       Returns the length of the buffer object.
187
188   $buffer->offset
189       Returns the internal offset state.
190
191       If you insist on intermixing calls to bytes with calls to the get_* and
192       put_* methods, you'll probably want to use this method to get some
193       status on that internal offset.
194
195   $buffer->set_offset($offset)
196       Sets the internal offset state to $offset.
197
198   $buffer->reset_offset
199       Sets the internal offset state to 0.
200
201   $buffer->dump(@args)
202       Returns a hex dump of the buffer. The dump is of the entire buffer
203       $buffer; in other words, dump doesn't respect the internal offset
204       pointer.
205
206       @args is passed directly through to the bytes method, which means that
207       you can supply arguments to emulate support of the internal offset:
208
209           my $dump = $buffer->dump($buffer->offset);
210
211   $buffer->insert_padding
212       A helper method: pads out the buffer so that the length of the
213       transferred packet will be evenly divisible by 8, which is a
214       requirement of the SSH protocol.
215

AUTHOR & COPYRIGHTS

217       Benjamin Trott, ben@rhumba.pair.com
218
219       Except where otherwise noted, Data::Buffer is Copyright 2001 Benjamin
220       Trott. All rights reserved. Data::Buffer is free software; you may
221       redistribute it and/or modify it under the same terms as Perl itself.
222
223
224
225perl v5.32.0                      2020-07-28                         Buffer(3)
Impressum