Tcl_Interp(3)

______________________________________________________________________________

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 struc-
       ture.  This pointer is then passed into other Tcl procedures to process
       commands  in the interpreter and perform other operations on the inter-
       preter.  Interpreter structures contain many many fields that are  used
       by Tcl, but only three that may be accessed by clients:  result, freeP-
       roc, and errorLine.

       The result and freeProc fields are used to return results or error mes-
       sages  from  commands.   This information is returned by command proce-
       dures 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 allo-
       cated, 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->freeP-
       roc 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  pur-
       pose).

       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_SetRe-
       sult).

       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

Tcl                                   7.5                        Tcl_Interp(3)