Provided by: tcl9.0-doc_9.0.1+dfsg-1_all 
NAME
Tcl_CreateObjCommand, Tcl_CreateObjCommand2, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken,
Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken,
Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj - implement new commands in C
SYNOPSIS
#include <tcl.h>
Tcl_Command
Tcl_CreateObjCommand(interp, cmdName, proc, clientData, deleteProc)
Tcl_Command
Tcl_CreateObjCommand2(interp, cmdName, proc2, clientData, deleteProc)
int
Tcl_DeleteCommand(interp, cmdName)
int
Tcl_DeleteCommandFromToken(interp, token)
int
Tcl_GetCommandInfo(interp, cmdName, infoPtr)
int
Tcl_SetCommandInfo(interp, cmdName, infoPtr)
int
Tcl_GetCommandInfoFromToken(token, infoPtr)
int
Tcl_SetCommandInfoFromToken(token, infoPtr)
const char *
Tcl_GetCommandName(interp, token)
Tcl_GetCommandFullName(interp, token, objPtr)
Tcl_Command
Tcl_GetCommandFromObj(interp, objPtr)
ARGUMENTS
Tcl_Interp *interp (in) Interpreter in which to create a new command or that contains
a command.
const char *cmdName (in) Name of command.
Tcl_ObjCmdProc *proc (in) Implementation of the new command: proc will be called
whenever cmdName is invoked as a command.
Tcl_ObjCmdProc2 *proc2 (in) Implementation of the new command: proc2 will be called
whenever cmdName is invoked as a command.
void *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.
Tcl_Command token (in) Token for command, returned by previous call to
Tcl_CreateObjCommand. The command must not have been
deleted.
Tcl_CmdInfo *infoPtr (in/out) Pointer to structure containing various information about a
Tcl command.
Tcl_Obj *objPtr (in) Value containing the name of a Tcl command.
const char *typeName (in) Indicates the name of the type of command implementation
associated with a particular proc, or NULL to break the
association.
________________________________________________________________________________________________________________
DESCRIPTION
Tcl_CreateObjCommand defines a new command in interp and associates it with procedure proc such that
whenever name is invoked as a Tcl command (e.g., via a call to Tcl_EvalObjEx) the Tcl interpreter will
call proc to process the command.
Tcl_CreateObjCommand deletes any existing command name already associated with the interpreter (however
see below for an exception where the existing command is not deleted). It returns a token that may be
used to refer to the command in subsequent calls to Tcl_GetCommandName. If name contains any ::
namespace qualifiers, then the command is added to the specified namespace; otherwise the command is
added to the global namespace. If Tcl_CreateObjCommand 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_ObjCmdProc:
typedef int Tcl_ObjCmdProc(
void *clientData,
Tcl_Interp *interp,
int objc,
Tcl_Obj *const objv[]);
When proc is invoked, the clientData and interp parameters will be copies of the clientData and interp
arguments given to Tcl_CreateObjCommand. Typically, clientData points to an application-specific data
structure that describes what to do when the command procedure is invoked. Objc and objv describe the
arguments to the command, objc giving the number of argument values (including the command name) and objv
giving the values of the arguments. The objv array will contain objc values, pointing to the argument
values. Unlike argv[argv] used in a string-based command procedure, objv[objc] will not contain NULL.
Additionally, when proc is invoked, it must not modify the contents of the objv array by assigning new
pointer values to any element of the array (for example, objv[2] = NULL) because this will cause memory
to be lost and the runtime stack to be corrupted. The const in the declaration of objv will cause ANSI-
compliant compilers to report any such attempted assignment as an error. However, it is acceptable to
modify the internal representation of any individual value argument. For instance, the user may call
Tcl_GetIntFromObj on objv[2] to obtain the integer representation of that value; that call may change the
type of the value that objv[2] points at, but will not change where objv[2] points.
proc must return an integer code that is either TCL_OK, TCL_ERROR, TCL_RETURN, TCL_BREAK, or
TCL_CONTINUE. See the return man page for details on what these codes mean and the use of extended
values for an extension's private use. Most normal commands will only return TCL_OK or TCL_ERROR.
In addition, if proc needs to return a non-empty result, it can call Tcl_SetObjResult to set the
interpreter's result. In the case of a TCL_OK return code this gives the result of the command, and in
the case of TCL_ERROR this gives an error message. Before invoking a command procedure, Tcl_EvalObjEx
sets interpreter's result to point to a value representing an empty string, so simple commands can return
an empty result by doing nothing at all.
The contents of the objv array belong to Tcl and are not guaranteed to persist once proc returns: proc
should not modify them. Call Tcl_SetObjResult if you want to return something from the objv array.
Ordinarily, Tcl_CreateObjCommand deletes any existing command name already associated with the
interpreter. However, if the existing command was created by a previous call to Tcl_CreateCommand,
Tcl_CreateObjCommand does not delete the command but instead arranges for the Tcl interpreter to call the
Tcl_ObjCmdProc proc in the future. The old string-based Tcl_CmdProc associated with the command is
retained and its address can be obtained by subsequent Tcl_GetCommandInfo calls. This is done for
backwards compatibility.
DeleteProc will be invoked when (if) name is deleted. This can occur through a call to
Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, or Tcl_DeleteInterp, or by replacing name in another call
to Tcl_CreateObjCommand. 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(
void *clientData);
The clientData argument will be the same as the clientData argument passed to Tcl_CreateObjCommand.
Tcl_CreateObjCommand2 does the same as Tcl_CreateObjCommand, except its proc2 argument is of type
Tcl_ObjCmdProc2.
typedef int Tcl_ObjCmdProc2(
void *clientData,
Tcl_Interp *interp,
Tcl_Size objc,
Tcl_Obj *const objv[]);
Tcl_DeleteCommand deletes a command from a command interpreter. Once the call completes, attempts to
invoke cmdName in interp will result in errors. If cmdName is not bound as a command in interp then
Tcl_DeleteCommand does nothing and returns -1; otherwise it returns 0. There are no restrictions on
cmdName: it may refer to a built-in command, an application-specific command, or a Tcl procedure. If
name contains any :: namespace qualifiers, the command is deleted from the specified namespace.
Given a token returned by Tcl_CreateObjCommand, Tcl_DeleteCommandFromToken deletes the command from a
command interpreter. It will delete a command even if that command has been renamed. Once the call
completes, attempts to invoke the command in interp will result in errors. If the command corresponding
to token has already been deleted from interp then Tcl_DeleteCommand does nothing and returns -1;
otherwise it returns 0.
Tcl_GetCommandInfo checks to see whether its cmdName argument exists as a command in interp. cmdName may
include :: namespace qualifiers to identify a command in a particular namespace. If the command is not
found, then it returns 0. Otherwise it places information about the command in the Tcl_CmdInfo structure
pointed to by infoPtr and returns 1. A Tcl_CmdInfo structure has the following fields:
typedef struct {
int isNativeObjectProc;
Tcl_ObjCmdProc *objProc;
void *objClientData;
Tcl_CmdProc *proc;
void *clientData;
Tcl_CmdDeleteProc *deleteProc;
void *deleteData;
Tcl_Namespace *namespacePtr;
Tcl_ObjCmdProc2 *objProc2;
void *objClientData2;
} Tcl_CmdInfo;
The isNativeObjectProc field has the value 2 if Tcl_CreateObjCommand2 was called to register the command;
it has the value 1 if Tcl_CreateObjCommand was called to register the command; it is 0 if only
Tcl_CreateCommand was called. It allows a program to determine whether it is faster to call objProc2,
objProc or proc: objProc2/objProc is normally faster if isNativeObjectProc has the value 2;
objProc/objProc is normally faster if isNativeObjectProc has the value 1. The fields objProc and
objClientData have the same meaning as the proc and clientData arguments to Tcl_CreateObjCommand; they
hold information about the value-based command procedure that the Tcl interpreter calls to implement the
command. The fields proc and clientData hold information about the string-based command procedure that
implements the command. If Tcl_CreateCommand was called for this command, this is the procedure passed
to it; otherwise, this is a compatibility procedure registered by Tcl_CreateObjCommand that simply calls
the command's value-based procedure after converting its string arguments to Tcl values. The field
deleteData is the clientData value to pass to deleteProc; it is normally the same as clientData but may
be set independently using the Tcl_SetCommandInfo procedure. The field namespacePtr holds a pointer to
the Tcl_Namespace that contains the command.
Tcl_GetCommandInfoFromToken is identical to Tcl_GetCommandInfo except that it uses a command token
returned from Tcl_CreateObjCommand in place of the command name. If the token parameter is NULL, it
returns 0; otherwise, it returns 1 and fills in the structure designated by infoPtr.
Tcl_SetCommandInfo is used to modify the procedures and clientData values associated with a command. Its
cmdName argument is the name of a command in interp. cmdName may include :: namespace qualifiers to
identify a command in a particular namespace. If this command does not exist then Tcl_SetCommandInfo
returns 0. Otherwise, it copies the information from *infoPtr to Tcl's internal structure for the
command and returns 1.
Tcl_SetCommandInfoFromToken is identical to Tcl_SetCommandInfo except that it takes a command token as
returned by Tcl_CreateObjCommand instead of the command name. If the token parameter is NULL, it returns
0. Otherwise, it copies the information from *infoPtr to Tcl's internal structure for the command and
returns 1.
Note that Tcl_SetCommandInfo and Tcl_SetCommandInfoFromToken both allow the clientData for a command's
deletion procedure to be given a different value than the clientData for its command procedure. Note
also that neither Tcl_SetCommandInfo nor Tcl_SetCommandInfoFromToken will change a command's namespace.
Use Tcl_Eval to call the rename command to do that.
Tcl_GetCommandName provides a mechanism for tracking commands that have been renamed. Given a token
returned by Tcl_CreateObjCommand when the command was created, Tcl_GetCommandName returns the string name
of the command. If the command has been renamed since it was created, then Tcl_GetCommandName returns
the current name. This name does not include any :: namespace qualifiers. The command corresponding to
token must not have been deleted. The string returned by Tcl_GetCommandName is in dynamic memory owned
by Tcl and is only guaranteed to retain its value as long as the command is not deleted or renamed;
callers should copy the string if they need to keep it for a long time.
Tcl_GetCommandFullName produces the fully qualified name of a command from a command token. The name,
including all namespace prefixes, is appended to the value specified by objPtr.
Tcl_GetCommandFromObj returns a token for the command specified by the name in a Tcl_Obj. The command
name is resolved relative to the current namespace. Returns NULL if the command is not found.
REFERENCE COUNT MANAGEMENT
When the proc passed to Tcl_CreateObjCommand is called, the values in its objv argument will have a
reference count of at least 1, with that guaranteed reference being from the Tcl evaluation stack. You
should not call Tcl_DecrRefCount on any of those values unless you call Tcl_IncrRefCount on them first.
Also, when the proc is called, the interpreter result is guaranteed to be an empty string value with a
reference count of 1.
Tcl_GetCommandFullName does not modify the reference count of its objPtr argument, but does require that
the object be unshared.
Tcl_GetCommandFromObj does not modify the reference count of its objPtr argument; it only reads.
SEE ALSO
Tcl_CreateCommand(3tcl), Tcl_ResetResult(3tcl), Tcl_SetObjResult(3tcl)
KEYWORDS
bind, command, create, delete, namespace, value
Tcl 8.0 Tcl_CreateObjCommand(3tcl)