Tcl_Eval(3) Tcl Library Procedures Tcl_Eval(3)______________________________________________________________________________NAME
Tcl_EvalObjEx, Tcl_EvalFile, Tcl_EvalObjv, Tcl_Eval, Tcl_EvalEx,
Tcl_GlobalEval, Tcl_GlobalEvalObj, Tcl_VarEval, Tcl_VarEvalVA - execute
Tcl scripts
SYNOPSIS
#include <tcl.h>
int │
Tcl_EvalObjEx(interp, objPtr, flags) │
int │
Tcl_EvalFile(interp, fileName) │
int │
Tcl_EvalObjv(interp, objc, objv, flags) │
int │
Tcl_Eval(interp, script) │
int │
Tcl_EvalEx(interp, script, numBytes, flags) │
int │
Tcl_GlobalEval(interp, script) │
int │
Tcl_GlobalEvalObj(interp, objPtr, flags) │
int │
Tcl_VarEval(interp, string, string, ... (char *) NULL) │
int │
Tcl_VarEvalVA(interp, argList) │
ARGUMENTS │
Tcl_Interp *interp (in) │
Interpreter in which to execute the │
script. The interpreter's result │
is modified to hold the result or │
error message from the script. │
Tcl_Obj *objPtr (in) │
A Tcl object containing the script │
to execute. │
int flags (in) │
ORed combination of flag bits that │
specify additional options. │
TCL_EVAL_GLOBAL and TCL_EVAL_DIRECT │
are currently supported. │
char *fileName (in) │
Name of a file containing a Tcl │
script. │
int objc (in) │
The number of objects in the array │
pointed to by objPtr; this is also │
the number of words in the command. │
Tcl_Obj **objv (in) │
Points to an array of pointers to │
objects; each object holds the │
value of a single word in the com‐ │
mand to execute. │
int numBytes (in) │
The number of bytes in script, not │
including any null terminating │
character. If -1, then all charac‐ │
ters up to the first null byte are │
used. │
char *script (in) │
Points to first byte of script to │
execute (NULL terminated and │
UTF-8). This script must be in │
writable memory: temporary modifi‐ │
cations are made to it during pars‐ │
ing. │
char *string (in) │
String forming part of a Tcl │
script. │
va_list argList (in) │
An argument list which must have │
been initialised using │
TCL_VARARGS_START, and cleared │
using va_end. │
_________________________________________________________________ │
DESCRIPTION │
The procedures described here are invoked to execute Tcl scripts in │
various forms. Tcl_EvalObjEx is the core procedure and is used by many │
of the others. It executes the commands in the script stored in objPtr │
until either an error occurs or the end of the script is reached. If │
this is the first time objPtr has been executed, its commands are com‐ │
piled into bytecode instructions which are then executed. The byte‐ │
codes are saved in objPtr so that the compilation step can be skipped │
if the object is evaluated again in the future. │
The return value from Tcl_EvalObjEx (and all the other procedures │
described here) is a Tcl completion code with one of the values TCL_OK, │
TCL_ERROR, TCL_RETURN, TCL_BREAK, or TCL_CONTINUE. In addition, a │
result value or error message is left in interp's result; it can be │
retrieved using Tcl_GetObjResult. │
Tcl_EvalFile reads the file given by fileName and evaluates its con‐ │
tents as a Tcl script. It returns the same information as Tcl_EvalOb‐ │
jEx. If the file couldn't be read then a Tcl error is returned to │
describe why the file couldn't be read. │
Tcl_EvalObjv executes a single pre-parsed command instead of a script. │
The objc and objv arguments contain the values of the words for the Tcl │
command, one word in each object in objv. Tcl_EvalObjv evaluates the │
command and returns a completion code and result just like Tcl_EvalOb‐ │
jEx. │
Tcl_Eval is similar to Tcl_EvalObjEx except that the script to be exe‐ │
cuted is supplied as a string instead of an object and no compilation │
occurs. The string should be a proper UTF-8 string as converted by │
Tcl_ExternalToUtfDString or Tcl_ExternalToUtf when it is known to pos‐ │
sibly contain upper ascii characters who's possible combinations might │
be a UTF-8 special code. The string is parsed and executed directly │
(using Tcl_EvalObjv) instead of compiling it and executing the byte‐ │
codes. In situations where it is known that the script will never be │
executed again, Tcl_Eval may be faster than Tcl_EvalObjEx. Tcl_Eval │
returns a completion code and result just like Tcl_EvalObjEx. Note: │
for backward compatibility with versions before Tcl 8.0, Tcl_Eval │
copies the object result in interp to interp->result (use is depre‐ │
cated) where it can be accessed directly. This makes Tcl_Eval somewhat │
slower than Tcl_EvalEx, which doesn't do the copy. │
Tcl_EvalEx is an extended version of Tcl_Eval that takes additional │
arguments numBytes and flags. For the efficiency reason given above, │
Tcl_EvalEx is generally preferred over Tcl_Eval. │
Tcl_GlobalEval and Tcl_GlobalEvalObj are older procedures that are now │
deprecated. They are similar to Tcl_EvalEx and Tcl_EvalObjEx except │
that the script is evaluated in the global namespace and its variable │
context consists of global variables only (it ignores any Tcl proce‐ │
dures that are active). These functions are equivalent to using the │
TCL_EVAL_GLOBAL flag (see below). │
Tcl_VarEval takes any number of string arguments of any length, con‐ │
catenates them into a single string, then calls Tcl_Eval to execute │
that string as a Tcl command. It returns the result of the command and │
also modifies interp->result in the same way as Tcl_Eval. The last │
argument to Tcl_VarEval must be NULL to indicate the end of arguments. │
Tcl_VarEval is now deprecated. │
Tcl_VarEvalVA is the same as Tcl_VarEval except that instead of taking │
a variable number of arguments it takes an argument list. Like │
Tcl_VarEval, Tcl_VarEvalVA is deprecated. │
FLAG BITS │
Any ORed combination of the following values may be used for the flags │
argument to procedures such as Tcl_EvalObjEx: │
TCL_EVAL_DIRECT │
This flag is only used by Tcl_EvalObjEx; it is │
ignored by other procedures. If this flag bit │
is set, the script is not compiled to bytecodes; │
instead it is executed directly as is done by │
Tcl_EvalEx. The TCL_EVAL_DIRECT flag is useful │
in situations where the contents of an object │
are going to change immediately, so the byte‐ │
codes won't be reused in a future execution. In │
this case, it's faster to execute the script │
directly. │
TCL_EVAL_GLOBAL │
If this flag is set, the script is processed at │
global level. This means that it is evaluated │
in the global namespace and its variable context │
consists of global variables only (it ignores │
any Tcl procedures at are active). │
MISCELLANEOUS DETAILS │
During the processing of a Tcl command it is legal to make nested calls │
to evaluate other commands (this is how procedures and some control │
structures are implemented). If a code other than TCL_OK is returned │
from a nested Tcl_EvalObjEx invocation, then the caller should normally │
return immediately, passing that same return code back to its caller, │
and so on until the top-level application is reached. A few commands, │
like for, will check for certain return codes, like TCL_BREAK and │
TCL_CONTINUE, and process them specially without returning. │
Tcl_EvalObjEx keeps track of how many nested Tcl_EvalObjEx invocations │
are in progress for interp. If a code of TCL_RETURN, TCL_BREAK, or │
TCL_CONTINUE is about to be returned from the topmost Tcl_EvalObjEx │
invocation for interp, it converts the return code to TCL_ERROR and │
sets interp's result to an error message indicating that the return, │
break, or continue command was invoked in an inappropriate place. This │
means that top-level applications should never see a return code from │
Tcl_EvalObjEx other then TCL_OK or TCL_ERROR.
KEYWORDS
execute, file, global, object, result, script
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Availability │ SUNWTcl │
├────────────────────┼─────────────────┤
│Interface Stability │ External │
└────────────────────┴─────────────────┘
NOTES
Source for Tcl is available in the SUNWTclS package.
Tcl 8.1 Tcl_Eval(3)
