Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  TEXT::NETSTRING (3)

.ds Aq ’


Text::Netstring - Perl module for manipulation of netstrings



 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);


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.


 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


The format of a netstring is described in


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)


James Raftery <>.
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.