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
       objects.   The  object-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 objects as arguments and those objects can retain an internal  representation  that
       can  be  manipulated more efficiently.  Also, Tcl's interpreter now uses objects 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 object before the call and create a new Tcl object to hold the
       string result returned by the string-based command procedure.   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  to
       point to a string value; 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

Tcl                                                                                      Tcl_CreateCommand(3tcl)