173 lines
7.1 KiB
Groff
173 lines
7.1 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/tcl/man/RCS/CrtCommand.3,v 1.12 93/10/29 15:52:29 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tcl_CreateCommand tclc
|
|
.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
|
|
\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)
|
|
.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.
|
|
.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. \fIProc\fP should
|
|
have arguments and result that match the type \fBTcl_CmdProc\fR:
|
|
.nf
|
|
.RS
|
|
typedef int Tcl_CmdProc(
|
|
.RS
|
|
ClientData \fIclientData\fR,
|
|
Tcl_Interp *\fIinterp\fR,
|
|
int \fIargc\fR,
|
|
char *\fIargv\fR[]);
|
|
.RE
|
|
.RE
|
|
.fi
|
|
When \fIproc\fR is invoked the \fIclientData\fP and \fIinterp\fR
|
|
parameters will be copies of the \fIclientData\fP 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:
|
|
.nf
|
|
.RS
|
|
.sp
|
|
typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
|
|
.sp
|
|
.RE
|
|
.fi
|
|
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 exists 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.
|
|
.VE
|
|
|
|
.SH KEYWORDS
|
|
bind, command, create, delete, interpreter
|