Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Buffer(3)	      User Contributed Perl Documentation	     Buffer(3)

NAME
       Data::Buffer - Read/write buffer	class

SYNOPSIS
	   use Data::Buffer;
	   my $buffer =	Data::Buffer->new;

	   ## Add a 32-bit integer.
	   $buffer->put_int32(10932930);

	   ## Get it back.
	   my $int = $buffer->get_int32;

DESCRIPTION
       Data::Buffer implements a low-level binary buffer in which you can get
       and put integers, strings, and other data.  Internally the
       implementation is based on "pack" and "unpack", such that Data::Buffer
       is really a layer on top	of those built-in functions.

       All of the get_*	and put_* methods respect the internal offset state in
       the buffer object. This means that you should read data out of the
       buffer in the same order	that you put it	in. For	example:

	   $buf->put_int16(24);
	   $buf->put_int32(1233455);
	   $buf->put_int16(99);

	   $buf->get_int16;   #	24
	   $buf->get_int32;   #	1233455
	   $buf->get_int16;   #	99

       Of course, this assumes that you	know the order of the data items in
       the buffer. If your setup is such that your sending and receiving
       processes won't necessarily know	what's inside the buffers they
       receive,	take a look at the TEMPLATE USAGE section.

USAGE
   Data::Buffer->new
       Creates a new buffer object and returns it. The buffer is initially
       empty.

       This method takes no arguments.

   Data::Buffer->new_with_init(@strs)
       Creates a new buffer object and appends to it each of the octet strings
       in @strs.

       Returns the new buffer object.

   $buffer->get_int8
       Returns the next	8-bit integer from the buffer (which is	really just
       the ASCII code for the next character/byte in the buffer).

   $buffer->put_int8
       Appends an 8-bit	integer	to the buffer (which is	really just the
       character corresponding to that integer,	in ASCII).

   $buffer->get_int16
       Returns the next	16-bit integer from the	buffer.

   $buffer->put_int16($integer)
       Appends a 16-bit	integer	to the buffer.

   $buffer->get_int32
       Returns the next	32-bit integer from the	buffer.

   $buffer->put_int32($integer)
       Appends a 32-bit	integer	to the buffer.

   $buffer->get_char
       More appropriately called get_byte, perhaps, this returns the next byte
       from the	buffer.

   $buffer->put_char($bytes)
       Appends a byte (or a sequence of	bytes) to the buffer.  There is	no
       restriction on the length of the	byte string $bytes; if it makes	you
       uncomfortable to	call put_char to put multiple bytes, you can instead
       call this method	as put_chars. It's the same thing.

   $buffer->get_bytes($n)
       Grabs $n	bytes from the buffer, where $n	is a positive integer.
       Increments the internal offset state by $n.

   $buffer->put_bytes($bytes [,	$n ])
       Appends a sequence of bytes to the buffer; if $n	is unspecified,
       appends the entire length of $bytes.  Otherwise appends only the	first
       $n bytes	of $bytes.

   $buffer->get_str
       Returns the next	"string" from the buffer. A string here	is represented
       as the length of	the string (a 32-bit integer) followed by the string
       itself.

   $buffer->put_str($string)
       Appends a string	(32-bit	integer	length and the string itself) to the
       buffer.

   $buffer->extract($n)
       Extracts	the next $n bytes from the buffer $buffer, increments the
       offset state in $buffer,	and returns a new buffer object	containing the
       extracted bytes.

TEMPLATE USAGE
       Generally when you use Data::Buffer it's	to communicate with another
       process (perhaps	a C program) that bundles up its data into binary
       buffers.	In those cases,	it's very likely that the data will be in some
       well-known order	in the buffer: in other	words, it might	be documented
       that a certain C	program	creates	a buffer containing:

       o   an int8

       o   a string

       o   an int32

       In this case, you would presumably know about the order of the data in
       the buffer, and you could extract it accordingly:

	   $buffer->get_int8;
	   $buffer->get_str;
	   $buffer->get_int32;

       In other	cases, however,	there may not be a well-defined	order of data
       items in	the buffer. This might be the case if you're inventing your
       own protocol, and you want your binary buffers to "know"	about their
       contents. In this case, you'll want to use the templating features of
       Data::Buffer.

       When you	use the	put_ methods to	place data in a	buffer,	Data::Buffer
       keeps track of the types	of data	that you're inserting in a template
       description of the buffer. This template	contains all of	the
       information necessary for a process to receive a	buffer and extract the
       data in the buffer without knowledge of the order of the	items.

       To use this feature, simply use the insert_template method after	you've
       filled your buffer to completion. For example:

	   my $buffer =	Data::Buffer->new;
	   $buffer->put_str("foo");
	   $buffer->put_int32(9999);
	   $buffer->insert_template;

	   ## Ship off the buffer to another process.

       The receiving process should then invoke	the get_all method on the
       buffer to extract all of	the data:

	   my $buffer =	Data::Buffer->new;
	   $buffer->append( $received_buffer_data );
	   my @data = $buffer->get_all;

       @data will now contain two elements: "foo" and 9999.

LOW-LEVEL METHODS
   $buffer->append($bytes)
       Appends raw data	$bytes to the end of the in-memory buffer. Generally
       you don't need to use this method unless	you're initializing an empty
       buffer, because when you	need to	add data to a buffer you should
       generally use one of the	put_* methods.

   $buffer->empty
       Empties out the buffer object.

   $buffer->bytes([ $offset [, $length [, $replacement ]]])
       Behaves exactly like the	substr built-in	function, except on the	buffer
       $buffer.	Given no arguments, bytes returns the entire buffer; given one
       argument	$offset, returns everything from that position to the end of
       the string; given $offset and $length, returns the segment of the
       buffer starting at $offset and consisting of $length bytes; and given
       all three arguments, replaces that segment with $replacement.

       This is a very low-level	method,	and you	generally won't	need to	use
       it.

       Also be warned that you should not intermix use of this method with use
       of the get_* and	put_* methods; the latter classes of methods maintain
       internal	state of the buffer offset where arguments will	be gotten from
       and put,	respectively. The bytes	method gives no	thought	to this
       internal	offset state.

   $buffer->length
       Returns the length of the buffer	object.

   $buffer->offset
       Returns the internal offset state.

       If you insist on	intermixing calls to bytes with	calls to the get_* and
       put_* methods, you'll probably want to use this method to get some
       status on that internal offset.

   $buffer->set_offset($offset)
       Sets the	internal offset	state to $offset.

   $buffer->reset_offset
       Sets the	internal offset	state to 0.

   $buffer->dump(@args)
       Returns a hex dump of the buffer. The dump is of	the entire buffer
       $buffer;	in other words,	dump doesn't respect the internal offset
       pointer.

       @args is	passed directly	through	to the bytes method, which means that
       you can supply arguments	to emulate support of the internal offset:

	   my $dump = $buffer->dump($buffer->offset);

   $buffer->insert_padding
       A helper	method:	pads out the buffer so that the	length of the
       transferred packet will be evenly divisible by 8, which is a
       requirement of the SSH protocol.

AUTHOR & COPYRIGHTS
       Benjamin	Trott, ben@rhumba.pair.com

       Except where otherwise noted, Data::Buffer is Copyright 2001 Benjamin
       Trott. All rights reserved. Data::Buffer	is free	software; you may
       redistribute it and/or modify it	under the same terms as	Perl itself.

perl v5.32.0			  2001-07-28			     Buffer(3)

NAME | SYNOPSIS | DESCRIPTION | USAGE | TEMPLATE USAGE | LOW-LEVEL METHODS | AUTHOR & COPYRIGHTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Data::Buffer&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help