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

FreeBSD Manual Pages

  
 
  

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

NAME
       Text::Netstring - Perl module for manipulation of netstrings

SYNOPSIS
	use Text::Netstring qw(netstring_encode	netstring_decode
	       netstring_verify	netstring_read);

	$ns = netstring_encode($text);
	@ns = netstring_encode(@text);
	$ns = netstring_encode(@text);

	$text =	netstring_decode($ns);
	@text =	netstring_decode(@ns);
	$text =	netstring_decode(@ns);

	$valid = netstring_verify($string);
	@valid = netstring_verify(@string);
	$valid = netstring_verify(@string);

	$ns = netstring_read($socket);

DESCRIPTION
       This module is a	collection of functions	to make	use of netstrings in
       your perl programs. A netstring is a string encoding used by, at	least,
       the QMTP	and QMQP email protocols.

       netstring_encode()
	   Encode the argument string, list of strings,	or referenced list of
	   strings as a	netstring.

	   Supplying a scalar argument in a scalar context, or a list or list
	   reference argument in list context, does what you'd expect;
	   encoding the	scalar or each element of the list as appropriate.
	   Supplying a list or list reference argument in a scalar context,
	   however, returns a single scalar which is the concatenation of each
	   element of the list encoded as a netstring.

       netstring_decode()
	   Decode the argument netstring, list of netstrings, or referenced
	   list	of netstrings returning	the interpretation of each. You	should
	   use "netstring_verify()" over any data before you try to decode it.
	   An invalid netstring	will be	returned as an empty string.

	   The same scalar/list	context	handling as for	netstring_encode()
	   applies.

       netstring_verify()
	   Check the validity of the supplied netstring, list of netstrings or
	   referenced list of netstrings. Returns a "TRUE" or "FALSE" value,
	   or list of same, as appropriate. Supplying a	list argument in a
	   scalar context will return a	single boolean value which is "TRUE"
	   if and only if each element of the argument list was	successfully
	   verified, otherwise it's "FALSE".

       netstring_read()
	   Read	the next netstring from	a socket reference supplied as an
	   argument.  The function returns a scalar which is the netstring
	   read	from the socket. You will need to use netstring_decode() on
	   the return value to obtain the string interpretation. Returns undef
	   in case of an error,	or an empty string ("")	if a premature EOF was
	   encountered.

	   This	function will regard a netstring claiming to be	larger than
	   200,000,000 characters as an	error, yielding	undef.

EXAMPLES
	use Text::Netstring qw(netstring_encode	netstring_decode);

	@s = ("foo", "bar");
	$t = netstring_encode( scalar netstring_encode(@s) );

       "12:3:foo,3:bar,," is the value of $t

	$s = ["5:whizz," , "4:bang,"];
	$t = netstring_decode($s);

       "whizzbang" is the value	of $t

NOTES
       The format of a netstring is described in
       http://cr.yp.to/proto/qmtp.txt

LICENSE
       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself. (Being a speaker of	British
       english,	I'd call it a "licence"	though)

AUTHOR
       James Raftery <james@now.ie>.

perl v5.32.1			  2006-11-20			  Netstring(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | NOTES | LICENSE | AUTHOR

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

home | help