Tcl_Eval(3)

_________________________________________________________________

NAME
       Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval - exe-
       cute Tcl commands

SYNOPSIS
       #include <<tcl.h>>

       int
       Tcl_Eval(interp, cmd)

       int
       Tcl_VarEval(interp, string, string, ... (char *) NULL)

       int
       Tcl_EvalFile(interp, fileName)

       int
       Tcl_GlobalEval(interp, cmd)

ARGUMENTS
       Tcl_Interp   *interp      (in)      Interpreter  in  which
                                           to  execute  the  com-
                                           mand.  A string result
                                           will   be   stored  in
                                           interp-&gt;result.

       char         *cmd         (in)      Command  (or  sequence
                                           of  commands)  to exe-
                                           cute.   Must   be   in
                                           writable        memory
                                           (Tcl_Eval makes tempo-
                                           rary  modifications to
                                           the command).

       char         *string      (in)      String forming part of
                                           Tcl command.

       char         *fileName    (in)      Name  of file contain-
                                           ing    Tcl     command
                                           string.
_________________________________________________________________

DESCRIPTION
       All   four  of  these  procedures  execute  Tcl  commands.
       Tcl_Eval is the core procedure and is used by all the oth-
       ers.   It  executes the commands in the script held by cmd
       until either an error occurs or it reaches the end of  the
       script.

       Note  that  Tcl_Eval  and Tcl_GlobalEval have been largely
       replaced by the object-based  procedures  Tcl_EvalObj  and

       Tcl_GlobalEvalObj.  Those object-based procedures evaluate
       a script held in a Tcl object instead of  a  string.   The
       object  argument  can retain the bytecode instructions for
       the script and so avoid reparsing the script each time  it
       is  executed.   Tcl_Eval  is implemented using Tcl_EvalObj
       but is slower because it must reparse the script each time
       since  there  is no object to retain the bytecode instruc-
       tions.

       The return value from Tcl_Eval is one of  the  Tcl  return
       codes   TCL_OK,   TCL_ERROR,   TCL_RETURN,  TCL_BREAK,  or
       TCL_CONTINUE, and interp-&gt;result will point  to  a  string
       with  additional information (a result value or error mes-
       sage).  If an error occurs during compilation, this return
       information  describes  the error.  Otherwise, this return
       information corresponds to the last command executed  from
       cmd.

       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-&gt;result in the usual fashion for Tcl commands.  The
       last argument to Tcl_VarEval must be NULL to indicate  the
       end of arguments.

       Tcl_EvalFile  reads  the file given by fileName and evalu-
       ates its contents as a Tcl command  by  calling  Tcl_Eval.
       It  returns a standard Tcl result that reflects the result
       of evaluating the file.  If the file couldn't be read then
       a  Tcl error is returned to describe why the file couldn't
       be read.

       During the processing of a Tcl command it is legal to make
       nested  calls to evaluate other commands (this is how pro-
       cedures and some control structures are implemented).   If
       a  code  other  than  TCL_OK  is  returned  from  a nested
       Tcl_Eval  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_Eval  keeps  track of how many nested Tcl_Eval invoca-
       tions  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_Eval invocation for  interp,
       it   converts  the  return  code  to  TCL_ERROR  and  sets
       interp-&gt;result to point to  an  error  message  indicating
       that the return, break, or continue command was invoked in
       an inappropriate place.  This means that top-level  appli-
       cations should never see a return code from Tcl_Eval other
       then TCL_OK or TCL_ERROR.

SEE ALSO
       Tcl_EvalObj, Tcl_GlobalEvalObj

KEYWORDS
       command, execute, file,  global,  object,  object  result,
       variable