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.  Callers of
       Tcl_CreateInterp should use this pointer as an opaque token, suitable  for  nothing  other
       than  passing  back  to  other  routines  in the Tcl interface.  Accessing fields directly
       through the pointer as described below is  no  longer  supported.   The  supported  public
       routines  Tcl_SetResult,  Tcl_GetResult,  Tcl_SetErrorLine,  Tcl_GetErrorLine must be used
       instead.

       For legacy programs and extensions no longer being maintained, compiles  against  the  Tcl
       8.6 header files are only possible with the compiler directives
              #define USE_INTERP_RESULT
       and/or
              #define USE_INTERP_ERRORLINE
       depending  on which fields of the Tcl_Interp struct are accessed.  These directives may be
       embedded in code or supplied via compiler options.

       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
       is not 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