NAME

       Tcl_CreateCommand - implement new commands in C

SYNOPSIS

       #include <tcl.h>

       Tcl_Command
       Tcl_CreateCommand(interp, cmdName, proc, clientData, deleteProc)

ARGUMENTS

       Tcl_Interp *interp (in)                     Interpreter in which to create new command.

       const char *cmdName (in)                    Name of command.

       Tcl_CmdProc *proc (in)                      Implementation  of new command:  proc will be called whenever
                                                   cmdName is invoked as a command.

       ClientData clientData (in)                  Arbitrary one-word value to pass to proc and deleteProc.

       Tcl_CmdDeleteProc *deleteProc (in)          Procedure  to  call  before  cmdName  is  deleted  from   the
                                                   interpreter;  allows  for command-specific cleanup.  If NULL,
                                                   then no procedure is called before the command is deleted.
________________________________________________________________________________________________________________

DESCRIPTION

       Tcl_CreateCommand defines a new command in interp  and  associates  it  with  procedure  proc  such  that
       whenever  cmdName is invoked as a Tcl command (via a call to Tcl_Eval) the Tcl interpreter will call proc
       to process the command.  It differs from Tcl_CreateObjCommand in  that  a  new  string-based  command  is
       defined;  that  is,  a  command  procedure  is defined that takes an array of argument strings instead of
       values.  The value-based command procedures registered by Tcl_CreateObjCommand can execute  significantly
       faster  than the string-based command procedures defined by Tcl_CreateCommand.  This is because they take
       Tcl values as arguments and those values can retain an internal representation that  can  be  manipulated
       more efficiently.  Also, Tcl's interpreter now uses values internally.  In order to invoke a string-based
       command procedure registered by Tcl_CreateCommand, it must generate and  fetch  a  string  representation
       from each argument value before the call.  New commands should be defined using Tcl_CreateObjCommand.  We
       support Tcl_CreateCommand for backwards compatibility.

       The procedures Tcl_DeleteCommand, Tcl_GetCommandInfo, and Tcl_SetCommandInfo are used in conjunction with
       Tcl_CreateCommand.

       Tcl_CreateCommand  will  delete  an  existing  command  cmdName,  if  one  is already associated with the
       interpreter.  It returns a token that may be used  to  refer  to  the  command  in  subsequent  calls  to
       Tcl_GetCommandName.   If  cmdName  contains any :: namespace qualifiers, then the command is added to the
       specified namespace; otherwise the command is added to the global  namespace.   If  Tcl_CreateCommand  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.  Proc should have arguments and result that match the type Tcl_CmdProc:

              typedef int Tcl_CmdProc(
                      ClientData clientData,
                      Tcl_Interp *interp,
                      int argc,
                      const char *argv[]);

       When proc is invoked the clientData and interp parameters will be copies of  the  clientData  and  interp
       arguments  given  to  Tcl_CreateCommand.   Typically,  clientData  points to an application-specific data
       structure that describes what to do when the command procedure is invoked.  Argc and  argv  describe  the
       arguments  to  the  command,  argc  giving  the number of arguments (including the command name) and argv
       giving the values of the arguments as strings.  The argv array will contain argc+1 values; the first argc
       values  point to the argument strings, and the last value is NULL.  Note that the argument strings should
       not be modified as they may point to  constant  strings  or  may  be  shared  with  other  parts  of  the
       interpreter.

       Note that the argument strings are encoded in normalized UTF-8 since version 8.1 of Tcl.

       Proc  must return an integer code that is expected to be one of TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK,
       or TCL_CONTINUE.  See the Tcl overview man page for details  on  what  these  codes  mean.   Most  normal
       commands will only return TCL_OK or TCL_ERROR.  In addition, proc must set the interpreter result; in the
       case of a TCL_OK return code this gives the result of the command, and in the case of TCL_ERROR it  gives
       an  error  message.  The Tcl_SetResult procedure provides an easy interface for setting the return value;
       for complete details on how the interpreter result field is managed, see the Tcl_Interp man page.  Before
       invoking a command procedure, Tcl_Eval sets the interpreter result to point to an empty string, so simple
       commands can return an empty result by doing nothing at all.

       The contents of the argv array belong to Tcl and are not guaranteed to persist once proc  returns:   proc
       should  not  modify  them,  nor  should  it  set the interpreter result to point anywhere within the argv
       values.  Call Tcl_SetResult with status TCL_VOLATILE if you want to return something from the argv array.

       DeleteProc  will  be  invoked  when  (if)  cmdName  is  deleted.  This  can  occur  through  a  call   to
       Tcl_DeleteCommand  or  Tcl_DeleteInterp,  or  by  replacing cmdName in another call to Tcl_CreateCommand.
       DeleteProc is invoked before the command is deleted, and gives the application an opportunity to  release
       any  structures  associated with the command.  DeleteProc should have arguments and result that match the
       type Tcl_CmdDeleteProc:

              typedef void Tcl_CmdDeleteProc(
                      ClientData clientData);

       The clientData argument will be the same as the clientData argument passed to Tcl_CreateCommand.

SEE ALSO

       Tcl_CreateObjCommand,  Tcl_DeleteCommand,  Tcl_GetCommandInfo,  Tcl_SetCommandInfo,   Tcl_GetCommandName,
       Tcl_SetObjResult

KEYWORDS

       bind, command, create, delete, interpreter, namespace