1 files changed, 181 insertions, 0 deletions
diff --git a/contrib/tcl/doc/CrtCommand.3 b/contrib/tcl/doc/CrtCommand.3
new file mode 100644
index 0000000..8c27e2f
--- /dev/null
+++ b/contrib/tcl/doc/CrtCommand.3
@@ -0,0 +1,181 @@
+'\"
+'\" Copyright (c) 1989-1993 The Regents of the University of California.
+'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" SCCS: @(#) CrtCommand.3 1.22 96/03/25 19:58:44
+'\" 
+.so man.macros
+.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
+.BS
+.SH NAME
+Tcl_CreateCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo \- implement new commands in C
+.SH SYNOPSIS
+.nf
+\fB#include <tcl.h>\fR
+.sp
+.VS
+.VE
+Tcl_Command
+\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
+.sp
+int
+\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
+.sp
+.VS
+int
+\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
+.sp
+int
+\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
+.sp
+.VS
+char *
+\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
+.VE
+.VE
+.SH ARGUMENTS
+.AS Tcl_CmdDeleteProc **deleteProcPtr
+.AP Tcl_Interp *interp in
+Interpreter in which to create new command.
+.AP char *cmdName in
+Name of command.
+.AP Tcl_CmdProc *proc in
+Implementation of new command:  \fIproc\fR will be called whenever
+\fIcmdName\fR is invoked as a command.
+.AP ClientData clientData in
+Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
+.AP Tcl_CmdDeleteProc *deleteProc in
+Procedure to call before \fIcmdName\fR is deleted from the interpreter;
+allows for command-specific cleanup.  If NULL, then no procedure is
+called before the command is deleted.
+.AP Tcl_CmdInfo *infoPtr in/out
+.VS
+Pointer to structure containing various information about a
+Tcl command.
+.AP Tcl_Command token in
+Token for command, returned by previous call to \fBTcl_CreateCommand\fR.
+The command must not have been deleted.
+.VE
+.BE
+
+.SH DESCRIPTION
+.PP
+\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
+it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
+invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
+will call \fIproc\fR
+to process the command.  If there is already a command \fIcmdName\fR
+associated with the interpreter, it is deleted.
+.VS
+\fBTcl_CreateCommand\fR returns a token that may be used to refer
+to the command in subsequent calls to \fBTcl_GetCommandName\fR.
+If \fBTcl_CreateCommand\fR is called for an interpreter that is in
+the process of being deleted, then it does not create a new command
+and it returns NULL.
+.VE
+\fIProc\fR should have arguments and result that match the type
+\fBTcl_CmdProc\fR:
+.CS
+typedef int Tcl_CmdProc(
+	ClientData \fIclientData\fR,
+	Tcl_Interp *\fIinterp\fR,
+	int \fIargc\fR,
+	char *\fIargv\fR[]);
+.CE
+When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
+parameters will be copies of the \fIclientData\fR and \fIinterp\fR
+arguments given to \fBTcl_CreateCommand\fR.
+Typically, \fIclientData\fR points to an application-specific
+data structure that describes what to do when the command procedure
+is invoked.  \fIArgc\fR and \fIargv\fR describe the arguments to
+the command, \fIargc\fR giving the number of arguments (including
+the command name) and \fIargv\fR giving the values of the arguments
+as strings.  The \fIargv\fR array will contain \fIargc\fR+1 values;
+the first \fIargc\fR values point to the argument strings, and the
+last value is NULL.
+.PP
+\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
+\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.  See the Tcl overview man page
+for details on what these codes mean.  Most normal commands will only
+return \fBTCL_OK\fR or \fBTCL_ERROR\fR.  In addition, \fIproc\fR must set
+\fIinterp->result\fR to point to a string value;
+in the case of a \fBTCL_OK\fR return code this gives the result
+of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
+The \fBTcl_SetResult\fR procedure provides an easy interface for setting
+the return value;  for complete details on how the \fIinterp->result\fR
+field is managed, see the \fBTcl_Interp\fR man page.
+Before invoking a command procedure,
+\fBTcl_Eval\fR sets \fIinterp->result\fR to point to an empty string, so simple
+commands can return an empty result by doing nothing at all.
+.PP
+.VS
+The contents of the \fIargv\fR array belong to Tcl and are not
+guaranteed to persist once \fIproc\fR returns:  \fIproc\fR should
+not modify them, nor should it set \fIinterp->result\fR to point
+anywhere within the \fIargv\fR values.
+Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
+to return something from the \fIargv\fR array.
+.VE
+.PP
+\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
+This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
+or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
+\fIDeleteProc\fR is invoked before the command is deleted, and gives the
+application an opportunity to release any structures associated
+with the command.  \fIDeleteProc\fR should have arguments and
+result that match the type \fBTcl_CmdDeleteProc\fR:
+.CS
+typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
+.CE
+The \fIclientData\fR argument will be the same as the \fIclientData\fR
+argument passed to \fBTcl_CreateCommand\fR.
+.PP
+\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
+Once the call completes, attempts to invoke \fIcmdName\fR in
+\fIinterp\fR will result in errors.
+If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
+\fBTcl_DeleteCommand\fR does nothing and returns -1;  otherwise
+it returns 0.
+There are no restrictions on \fIcmdName\fR:  it may refer to
+a built-in command, an application-specific command, or a Tcl procedure.
+.PP
+.VS
+\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
+exists as a command in \fIinterp\fR.  If not then it returns 0.
+Otherwise it places information about the command in the structure
+pointed to by \fIinfoPtr\fR and returns 1.
+Tcl_CmdInfo structures have fields named \fIproc\fR, \fIclientData\fR,
+and \fIdeleteProc\fR, which have the same meaning as the corresponding
+arguments to \fBTcl_CreateCommand\fR.
+There is also a field \fIdeleteData\fR, which is the ClientData value
+to pass to \fIdeleteProc\fR;  it is normally the same as
+\fIclientData\fR but may be set independently using the
+\fBTcl_SetCommandInfo\fR procedure.
+.PP
+\fBTcl_SetCommandInfo\fR is used to modify the procedures and
+ClientData values associated with a command.
+Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
+If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
+Otherwise, it copies the information from \fI*infoPtr\fR to
+Tcl's internal structure for the command and returns 1.
+Note that this procedure allows the ClientData for a command's
+deletion procedure to be given a different value than the ClientData
+for its command procedure.
+.PP
+\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
+that have been renamed.  Given a token returned by \fBTcl_CreateCommand\fR
+when the command was created, \fBTcl_GetCommandName\fR returns the
+string name of the command.  If the command has been renamed since it
+was created, then \fBTcl_GetCommandName\fR returns the current name.
+The command corresponding to \fItoken\fR must not have been deleted.
+The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
+owned by Tcl and is only guaranteed to retain its value as long as the
+command isn't deleted or renamed;  callers should copy the string if
+they need to keep it for a long time.
+.VE
+
+.SH KEYWORDS
+bind, command, create, delete, interpreter