NAME

       Tcl_Interp - client-visible fields of interpreter structures

SYNOPSIS

       #include <tcl.h>

       typedef struct {
            char *result;
            Tcl_FreeProc *freeProc;
            int errorLine;
       } Tcl_Interp;

       typedef void Tcl_FreeProc(char *blockPtr);
_________________________________________________________________

DESCRIPTION

       The  Tcl_CreateInterp procedure returns a pointer to a Tcl_Interp structure.  This pointer
       is then passed into other Tcl procedures  to  process  commands  in  the  interpreter  and
       perform  other  operations  on  the interpreter.  Interpreter structures contain many many
       fields that are used by Tcl, but only three that may  be  accessed  by  clients:   result,
       freeProc, and errorLine.

       The result and freeProc fields are used to return results or error messages from commands.
       This information is returned by command procedures back to Tcl_Eval, and by Tcl_Eval  back
       to its callers.  The result field points to the string that represents the result or error
       message, and the freeProc field tells how to dispose of the storage for the string when it
       isn't  needed  anymore.  The easiest way for command procedures to manipulate these fields
       is to call procedures like Tcl_SetResult or Tcl_AppendResult;   they  will  hide  all  the
       details  of  managing  the  fields.   The  description  below is for those procedures that
       manipulate the fields directly.

       Whenever a command procedure returns,  it  must  ensure  that  the  result  field  of  its
       interpreter  points  to  the  string being returned by the command.  The result field must
       always point  to  a  valid  string.   If  a  command  wishes  to  return  no  result  then
       interp->result  should  point  to  an  empty  string.  Normally, results are assumed to be
       statically allocated, which means that the contents will not change before the  next  time
       Tcl_Eval is called or some other command procedure is invoked.  In this case, the freeProc │
       field must be zero.  Alternatively, a  command  procedure  may  dynamically  allocate  its │
       return  value (e.g. using Tcl_Alloc) and store a pointer to it in interp->result.  In this │
       case, the command procedure must also set interp->freeProc to the address of  a  procedure │
       that can free the value, or TCL_DYNAMIC if the storage was allocated directly by Tcl or by │
       a call to Tcl_Alloc.  If interp->freeProc is non-zero, then Tcl will call freeProc to free
       the  space  pointed  to by interp->result before it invokes the next command.  If a client
       procedure  overwrites  interp->result  when  interp->freeProc  is  non-zero,  then  it  is
       responsible  for calling freeProc to free the old interp->result (the Tcl_FreeResult macro
       should be used for this purpose).

       FreeProc should have arguments and result that match the Tcl_FreeProc  declaration  above:
       it  receives  a  single  argument which is a pointer to the result value to free.  In most │
       applications TCL_DYNAMIC is the only non-zero value ever used for freeProc.   However,  an
       application  may  store  a  different  procedure  address  in  freeProc in order to use an
       alternate memory allocator or in order to do other  cleanup  when  the  result  memory  is
       freed.

       As   part   of   processing   each   command,   Tcl_Eval  initializes  interp->result  and
       interp->freeProc just before calling the command procedure for the command.  The  freeProc
       field  will  be  initialized  to  zero,  and interp->result will point to an empty string.
       Commands that do not return any value can simply leave the fields alone.  Furthermore, the
       empty  string  pointed  to  by  result  is  actually  part  of an array of TCL_RESULT_SIZE
       characters (approximately 200).  If a command wishes to return  a  short  string,  it  can
       simply  copy  it  to  the  area  pointed to by interp->result.  Or, it can use the sprintf
       procedure to generate a short result string at the location pointed to by interp->result.

       It is a general convention in Tcl-based applications that the result of an interpreter  is
       normally  in  the  initialized state described in the previous paragraph.  Procedures that
       manipulate an interpreter's result (e.g. by returning an error) will generally assume that
       the  result  has been initialized when the procedure is called.  If such a procedure is to
       be called after the result has been changed, then Tcl_ResetResult should be  called  first
       to  reset  the  result  to  its  initialized  state.   The direct use of interp->result is
       strongly deprecated (see Tcl_SetResult).

       The errorLine field is valid only after Tcl_Eval returns a TCL_ERROR return code.  In this
       situation  the  errorLine  field  identifies the line number of the command being executed
       when the error occurred.  The line numbers are relative to the command being executed:   1
       means  the  first  line of the command passed to Tcl_Eval, 2 means the second line, and so
       on.  The errorLine field is typically used in conjunction with Tcl_AddErrorInfo to  report
       information  about  where  an  error  occurred.  ErrorLine should not normally be modified
       except by Tcl_Eval.

KEYWORDS

       free, initialized, interpreter, malloc, result