Scroll to navigation

irc(3tcl) Low Level Tcl IRC Interface irc(3tcl)


irc - Create IRC connection and interface.


package require Tcl

package require irc ?0.6.2?

::irc::config ?key? ?value?



net registerevent event script

net getevent event script

net eventexists event script

net connect hostname ?port?

net config ?key? ?value?

net log level message

net logname

net connected

net sockname

net peername

net socket

net user username localhostname localdomainname userinfo

net nick nick

net ping target

net serverping

net join channel ?key?

net part channel ?message?

net quit ?message?

net privmsg target message

net notice target message

net ctcp target message

net kick channel target ?message?

net mode target args

net topic channel message

net invite channel target

net send text

net destroy

who ?address?







This package provides low-level commands to deal with the IRC protocol (Internet Relay Chat) for immediate and interactive multi-cast communication.

::irc::config ?key? ?value?
Sets configuration ?key? to ?value?. The configuration keys currently defined are the boolean flags logger and debug. logger makes irc use the logger package for printing error. debug requires logger and prints extra debug output. If no ?key? or ?value? is given the current values are returned.
The command creates a new object to deal with an IRC connection. Creating this IRC object does not automatically create the network connection. It returns a new irc namespace command which can be used to interact with the new IRC connection. NOTE: the old form of the connection command, which took a hostname and port as arguments, is deprecated. Use connect instead to specify this information.
Returns a list of all the current connections that were created with connection


In the following list of available connection methods net represents a connection command as returned by ::irc::connection.

Registers a callback handler for the specific event. Events available are those described in RFC 1459 In addition, there are several other events defined. defaultcmd adds a command that is called if no other callback is present. EOF is called if the connection signals an End of File condition. The events defaultcmd, defaultnumeric, defaultevent, and EOF are required. script is executed in the connection namespace, which can take advantage of several commands (see Callback Commands below) to aid in the parsing of data.
Returns the current handler for the event if one exists. Otherwise an empty string is returned.
Returns a boolean value indicating the existence of the event handler.
This causes the socket to be established. ::irc::connection created the namespace and the commands to be used, but did not actually open the socket. This is done here. NOTE: the older form of ´connect' did not require the user to specify a hostname and port, which were specified with 'connection'. That form is deprecated.
The same as ::irc::config but sets and gets options for the net connection only.
If logger is turned on by config this will write a log message at level.
Returns the name of the logger instance if logger is turned on.
Returns a boolean value indicating if this connection is connected to a server.
Returns a 3 element list consisting of the ip address, the hostname, and the port of the local end of the connection, if currently connected.
Returns a 3 element list consisting of the ip address, the hostname, and the port of the remote end of the connection, if currently connected.
Return the Tcl channel for the socket used by the connection.
Sends USER command to server. username is the username you want to appear. localhostname is the host portion of your hostname, localdomainname is your domain name, and userinfo is a short description of who you are. The 2nd and 3rd arguments are normally ignored by the IRC server.
NICK command. nick is the nickname you wish to use for the particular connection.
Send a CTCP PING to target.
PING the server.
channel is the IRC channel to join. IRC channels typically begin with a hashmark ("#") or ampersand ("&").
Makes the client leave channel. Some networks may support the optional argument message
Instructs the IRC server to close the current connection. The package will use a generic default if no message was specified.
Sends message to target, which can be either a channel, or another user, in which case their nick is used.
Sends a notice with message message to target, which can be either a channel, or another user, in which case their nick is used.
Sends a CTCP of type message to target
Kicks the user target from the channel channel with a message. The latter can be left out.
Sets the mode args on the target target. target may be a channel, a channel user, or yourself.
Sets the topic on channel to message specifying an empty string will remove the topic.
Invites target to join the channel channel
Sends text to the IRC server.
Deletes the connection and its associated namespace and information.


These commands can be used within callbacks

Returns the nick of the user who performed a command. The optional keyword address causes the command to return the user in the format "username@address".
Returns the action performed, such as KICK, PRIVMSG, MODE, etc... Normally not useful, as callbacks are bound to a particular event.
Returns the target of a particular command, such as the channel or user to whom a PRIVMSG is sent.
Returns a list of any additional arguments after the target.
Returns the entire event header (everything up to the :) as a proper list.
Returns the message portion of the command (the part after the :).


This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category irc of the Tcllib Trackers []. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.


rfc 1459


chat, irc



0.6.2 tcllib