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

FreeBSD Manual Pages

  
 
  

home | help
Net::SSH::Perl::BufferUser Contributed Perl DocumentaNet::SSH::Perl::Buffer(3)

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

SYNOPSIS
	   use Net::SSH::Perl::Buffer (@args);
	   my $buffer =	Net::SSH::Perl::Buffer->new;

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

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

DESCRIPTION
       Net::SSH::Perl::Buffer implements the low-level binary buffer needed by
       the Net::SSH::Perl suite. Specifically, a Net::SSH::Perl::Buffer	object
       is what makes up	the data segment of a packet transferred between
       server and client (a Net::SSH::Perl::Packet object).

       Buffers contain integers, strings, characters, etc. Because of the use
       of GMP integers in SSH, buffers can also	contain	multiple-precision
       integers	(represented internally	by Math::GMP objects).

       Note: the method	documentation here is in what some might call a
       slightly	backwards order. The reason for	this is	that the get and put
       methods (listed first) are probably what	most users/developers of
       Net::SSH::Perl need to care about; they're high-level methods used to
       get/put data from the buffer. The other methods (LOW-LEVEL METHODS) are
       much more low-level, and	typically you won't need to use	them
       explicitly.

GET AND	PUT METHODS
       All of the get_*	and put_* methods respect the internal offset state in
       the buffer object. This means that, for example,	if you call get_int16
       twice in	a row, you can be ensured that you'll get the next two 16-bit
       integers	in the buffer. You don't need to worry about the number	of
       bytes a certain piece of	data takes up, for example.

   $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_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->get_mp_int
       Returns a bigint	object representing a multiple precision integer read
       from the	buffer.	Depending on the protocol, the object is either	of
       type Math::GMP (SSH1) or	a binary string	(SSH2).

       You determine which protocol will be in use when	you use	the module:
       specify SSH1 or SSH2 to load the	proper get and put routines for
       bigints:

	   use Net::SSH::Perl::Buffer qw( SSH1 );

   $buffer->put_mp_int($mp_int)
       Appends a multiple precision integer to the buffer.  Depending on the
       protocol	in use,	$mp_int	should be either a Math::GMP object (SSH1) or
       a binary	string (SSH2). The format in which the integer is stored in
       the buffer differs between the protocols, as well.

LOW-LEVEL METHODS
   Net::SSH::Perl::Buffer->new
       Creates a new buffer object and returns it. The buffer is empty.

       This method takes no arguments.

   $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->dump
       Returns a hex dump of the buffer.

   $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
       Please see the Net::SSH::Perl manpage for author, copyright, and
       license information.

perl v5.32.0			  2017-03-12	     Net::SSH::Perl::Buffer(3)

NAME | SYNOPSIS | DESCRIPTION | GET AND PUT METHODS | LOW-LEVEL METHODS | AUTHOR & COPYRIGHTS

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

home | help