Tcl_Interp(3tcl)

Tcl_Interp(3)        Tcl Library Procedures         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  structure.   This  pointer  is  then passed into
     other Tcl procedures to process commands in the  interpreter
     and  perform  other  operations  on the interpreter.  Inter-
     preter 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.

Tcl                     Last change: 7.5                        1

Tcl_Interp(3)        Tcl Library Procedures         Tcl_Interp(3)

     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 pro-
     cedure 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 argu-
     ment 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 com-
     mand 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  ini-
     tialized  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  exe-
     cuted  when  the error occurred.  The line numbers are rela-
     tive to the command being executed:  1 means the first  line

Tcl                     Last change: 7.5                        2

Tcl_Interp(3)        Tcl Library Procedures         Tcl_Interp(3)

     of  the command passed to Tcl_Eval, 2 means the second line,
     and so on.  The errorLine field is typically  used  in  con-
     junction  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                     Last change: 7.5                        3