GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  TEXT::NETSTRING (3)

.ds Aq ’

NAME

Text::Netstring - Perl module for manipulation of netstrings

CONTENTS

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>.
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 NETSTRING (3) 2006-11-20

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.