Linux and UNIX Man Pages

Linux & Unix Commands - Search Man Pages

tcl_evalfile(3tcl) [opensolaris man page]

Tcl_Eval(3TCL)						      Tcl Library Procedures						    Tcl_Eval(3TCL)

__________________________________________________________________________________________________________________________________________________

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) | 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. | CONST 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 com- | mand. | Tcl_Obj **objv (in) | Points to an array of pointers to objects; each object holds the value of a single word in the command | 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. | CONST char *script (in) | Points to first byte of script to execute (null-terminated and UTF-8). | 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 compiled into bytecode instructions which are then executed. The | bytecodes 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, or possibly some other integer value originating in an extension. 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 contents 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. The eofchar for files is '32' | (^Z) for all platforms. If you require a ``^Z'' in code for string comparison, you can use ``32'' or ``u001a'', which will be safely | substituted by the Tcl interpreter into ``^Z''. 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_EvalObjEx. Tcl_Eval is similar to Tcl_EvalObjEx except that the script to be executed 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 bytecodes. 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 deprecated) 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, concatenates 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 bytecodes 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 names- pace 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 nor- mally 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 | Uncommitted | +--------------------+-----------------+ NOTES
Source for Tcl is available on http://opensolaris.org. Tcl 8.1 Tcl_Eval(3TCL)
Man Page