Provided by: tcl8.5-doc_8.5.15-2ubuntu1_all bug

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 fields
       that are used by Tcl, but only three that may be accessed by clients:   result,  freeProc,
       and errorLine.

       Note  that  access to all three fields, result, freeProc and errorLine is deprecated.  Use │
       Tcl_SetResult, Tcl_GetResult, and Tcl_GetReturnOptions instead.

       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