Tcl_EvalEx man page on Peanut

Man page or keyword search:  
man Server   7435 pages
apropos Keyword Search (all sections)
Output format
Peanut logo
[printable version]

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)

       int
       Tcl_VarEval(interp, part, part, ... (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 command.

       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 char‐
					  acter.  If -1, then  all  characters
					  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 *part (in)			  String forming part of a Tcl script.

       va_list argList (in)		  An argument  list  which  must  have
					  been initialized using va_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, 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  con‐
       tents  as a Tcl script.	It returns the same information as Tcl_EvalOb‐
       jEx.  If the file could not be read then a Tcl  error  is  returned  to
       describe	 why  the  file	 could	not 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 “\032” or “\u001a”, which will be safely sub‐
       stituted 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_EvalOb‐
       jEx.  The caller of Tcl_EvalObjv has to manage the reference  count  of
       the  elements  of  objv,	 insuring  that	 the  objects  are valid until
       Tcl_EvalObjv returns.

       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 whose 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 does not 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 will not be reused in a future  execution.
			      In this case, it is 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

Tcl				      8.1			   Tcl_Eval(3)
[top]

List of man pages available for Peanut

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net