TclServer -- Embeddable Tcl Server script object


package require TclServer

set server [TclServer %AUTO% ?options?]

$server methodname ?params?


TclServer provides a pure Tcl Tcl server that can be embedded into a script. A script using TclServer must be based on the Tcl event loop as that is used to dispatch connection and input events.

In insecure environments you should probably embed the TclServer in a secure slave interpreter. Users can implement authentication protocols via the -onconnect script. Error handling can also be customized via the -onerror script.

The sever can be in two states. In the inactive state the server is not listening for new connections. Prior connections could still be executing. In the active state, the server is listening for connections on the port configured via the -port option.


Several options control the way the server works:

-port port-num

Determines which TCP/IP port the server will listen on for client connections. This can only be configured when the server is in the inactive state. See the start and stop methods in the METHODS section below for more information.

-onconnect script

Specifies a script to be called when a connection request is received. The script must take three parameters which are in order;

  1. The socket fd on which data are transferred

  2. The IP address of the client

  3. The port assigned the client

If the script returns false, the connection will be immediately closed by the server. If true, the server will set up to handle commands from the client. This option therefore allows users of the TclServer object to implement authentication protocols.

-onerror script

Specifies a script that will be called whenever a remotely requested script has thrown an error. The script is called with three parameters that are in order:

  1. The channel on which the script was received.

  2. The command that caused the error.

  3. The error message produced by the command.

If the script returns false the client connection is closed by the server. If the script returns true the client connection remains open.


The following methods control the server.


Starts the server. This puts the server into the active mode. Configuring the -port option when active results in an error. If the server is already active an error is also thrown.

If the -port configuration option is not a legal positive integer an error will be thrown. If a privileged port is chosen but the application does not have privilege the socket -server command will throw an error.


Stops the server. This puts the server into the inactive state. Note that this only stops listening for new connections. Existing connections are retained unless or until the close method is invoked.

It is an error to stop the server when it is inactive.


Closes all active client connections. This can be performed in any server state. It is not an error to close if there are no active connections.