Arne Gödeke
        foreach (keys %$v) {
            $m .= make_header(':', $_, $v->{$_});
        foreach (keys %$v) {
            $m .= make_header(':', $_, $v->{$_});


Net::PSYC - Implementation of the Protocol for SYnchronous Conferencing.


PSYC is a flexible text-based protocol for delivery of data to a flexible amount of recipients by unicast or multicast TCP or UDP. It is primarily used for chat conferencing, multicasting presence, friendcasting, newscasting, event notifications and plain instant messaging, but not limited to that.

Existing systems can easily use PSYC, since PSYC hides its complexity from them. For example if an application wants to send data to one person or a group of people, it just needs to drop a few lines of text into a TCP connection (or UDP packet) to a static address. In other words: trivial.

The PSYC network resembles more the Web rather than IRC, which it once was inspired by. Each administrator of a machine on the Internet can install a PSYC server which has equal rights in the world wide network. No hierarchies, no boundaries. The administrator then has the right to decide which rooms or people to host, without interfering with other PSYC servers. Should an administrator behave incorrectly towards her users, they will simply move on to a different server. Thus, administrators must behave to be a popular PSYC host for their friends and social network.

This implementation is pretty stable and has been doing a good job in production environments for several years.

See for protocol specs and other info on PSYC.


Small example on how to send one single message:

    use Net::PSYC;
    sendmsg('psyc://', '_notice_whatever', 
            'Whatever happened to the 80\'s...');

Receiving messages:

    use Net::PSYC qw(:event bind_uniform); 
    register_uniform(); # get all messages
    bind_uniform(); # start listening on :4404 tcp and udp.

    start_loop(); # start the Event loop

    sub msg {
        my ($source, $mc, $data, $vars) = @_;
        print "A message ($mc) from $source reads: '$data'\n";


bind_uniform( $localpsycUNI )

starts listening on a local hostname and TCP and/or UDP port according to the PSYC UNI specification. When omitted, a random port will be chosen for both service types.

sendmsg( $target, $mc, $data, $vars )

sends a PSYC packet defined by mc, data and vars to the given target. data and vars may be left out. bind_uniform() is not necessary to send PSYC packets.

castmsg( $context, $mc, $data, $vars )

is NOT available yet. Net::PSYC does not implement neither context masters nor multicasting. if you need to distribute content to several recipients please allocate a context on a psycMUVE and sendmsg to it.

send_mmp( $target, $data, $vars )

sends an MMP packet to the given $target. $data may be a reference to an array of fragmented data.

psyctext( $format, $vars )

renders the strings in $vars into the $format and returns the resulting text conformant to the text/psyc content type specification. compatible to psycMUVEs psyctext.

make_uniform( $user, $host, $port, $type, $object )

Renders a PSYC uniform specified by the given elements. It basically produces: "psyc://$user@$host:$port$type/$object"


returns the current complete source uniform. UNL stands for Uniform Network Location.

setDEBUG( $level )

Sets $level of debug:

0 - no debug, only critical errors are reported

1 - some

2 - a lot (even incoming/outgoing packets)


returns the current level of debug.

W$level( $formal, @vars )

W() is used internally to print out debug-messages depending on the level of debug. You may want to overwrite this function to redirect output since the default is STDERR which can be really fancy-shmancy.

dns_lookup( $host )

Tries to resolve $host and returns the ip if successful. else 0.

Take care, dns_lookup is blocking. Maybe I will try to switch to nonblocking dns in the future.

same_host( $host1, $host2 )

Returns 1 if the two hosts are considered identical. 0 else. Use this function instead of your own dns_lookup magic since hostnames are cached internally.

register_host( $ip, $host )

Make $host point to $ip internally.

register_route( $target, $connection )

From now on all packets for $target are send via $connection (Net::PSYC::Circuit or Net::PSYC::Datagram). $target may be a full URL or of format host[:port].


Apart from the shortcuts below every single function may be exported seperately. You can switch on Eventing by using

    use Net::PSYC qw(Event=IO::Select); 
    # or
    use Net::PSYC qw(Event=Gtk2);
    # or
    use Net::PSYC qw(Event=Event); #
use Net::PSYC qw(:encrypt);

Try to use ssl for tcp connections. You need to have IO::Socket::SSL installed. Right now only tls client functionality works. Works with psycMUVE.

use Net::PSYC qw(:compress);

Use Compress::Zlib to compress data sent via tcp. Works fine with Net::PSYC and psycMUVE.

use Net::PSYC qw(:event);

:event activates eventing (by default IO::Select which should work on every system) and exports some functions (watch, forget, register_uniform, unregister_uniform, add, remove, start_loop, stop_loop) which are useful in that context. Have a look at Net::PSYC::Event for further documentation.

use Net::PSYC qw(:base);

exports bind_uniform, psyctext, make_uniform, UNL, sendmsg, dirty_add, dirty_remove, dirty_wait, parse_uniform and dirty_getmsg.

use Net::PSYC qw(:all);

exports makeMSG, parse_uniform, PSYC_PORT, PSYCS_PORT, UNL, W, AUTOWATCH, sendmsg, make_uniform, psyctext, BASE, SRC, DEBUG, setBASE, setSRC, setDEBUG, register_uniform, make_mmp, make_psyc, parse_mmp, parse_psyc, send_mmp, get_connection, register_route, register_host, same_host, dns_resolve, start_loop, stop_loop and psyctext.


See Net::PSYC::Event for more.

For further details.. Use The Source, Luke!


Net::PSYC::Event, Net::PSYC::Client, for more information about the PSYC protocol, for a rather mature PSYC server implementation (also offering IRC, Jabber and a Telnet interface) , for a bunch of applications using Net::PSYC.


Carlo v. Loesch


Arne Gödeke



Copyright (c) 1998-2005 Carlo v. Loesch and Arne Gödeke. All rights reserved.

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself. Derivatives may not carry the title "Official PSYC API Implementation" or equivalents.

6 POD Errors

The following errors were encountered while parsing the POD:

Around line 735:

Unknown directive: =state

Around line 802:

Unknown directive: =state

Around line 870:

Unknown directive: =state

Around line 875:

Unknown directive: =state

Around line 910:

Unknown directive: =state

Around line 916:

Unknown directive: =state