133 lines
6.1 KiB
Groff
133 lines
6.1 KiB
Groff
'\"
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
|
'\" All rights reserved.
|
|
'\"
|
|
'\" Permission is hereby granted, without written agreement and without
|
|
'\" license or royalty fees, to use, copy, modify, and distribute this
|
|
'\" documentation for any purpose, provided that the above copyright
|
|
'\" notice and the following two paragraphs appear in all copies.
|
|
'\"
|
|
'\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
|
|
'\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
|
'\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
|
|
'\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
'\"
|
|
'\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
|
|
'\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
|
|
'\" AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED HEREUNDER IS
|
|
'\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
|
|
'\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
|
|
'\"
|
|
'\" $Header: /user6/ouster/tcl/man/RCS/Interp.3,v 1.10 93/04/01 09:25:32 ouster Exp $ SPRITE (Berkeley)
|
|
'\"
|
|
.so man.macros
|
|
.HS Tcl_Interp tclc
|
|
.BS
|
|
.SH NAME
|
|
Tcl_Interp \- client-visible fields of interpreter structures
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
typedef struct {
|
|
char *\fIresult\fR;
|
|
Tcl_FreeProc *\fIfreeProc\fR;
|
|
int \fIerrorLine\fR;
|
|
} Tcl_Interp;
|
|
|
|
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \fBTcl_CreateInterp\fR 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: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
|
|
.PP
|
|
The \fIresult\fR and \fIfreeProc\fR fields are used to return
|
|
results or error messages from commands.
|
|
This information is returned by command procedures back to \fBTcl_Eval\fR,
|
|
and by \fBTcl_Eval\fR back to its callers.
|
|
The \fIresult\fR field points to the string that represents the
|
|
result or error message, and the \fIfreeProc\fR 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 \fBTcl_SetResult\fR
|
|
or \fBTcl_AppendResult\fR; they
|
|
will hide all the details of managing the fields.
|
|
The description below is for those procedures that manipulate the
|
|
fields directly.
|
|
.PP
|
|
Whenever a command procedure returns, it must ensure
|
|
that the \fIresult\fR field of its interpreter points to the string
|
|
being returned by the command.
|
|
The \fIresult\fR field must always point to a valid string.
|
|
If a command wishes to return no result then \fIinterp->result\fR
|
|
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
|
|
\fBTcl_Eval\fR is called or some other command procedure is invoked.
|
|
In this case, the \fIfreeProc\fR field must be zero.
|
|
Alternatively, a command procedure may dynamically
|
|
allocate its return value (e.g. using \fBmalloc\fR)
|
|
and store a pointer to it in \fIinterp->result\fR.
|
|
In this case, the command procedure must also set \fIinterp->freeProc\fR
|
|
to the address of a procedure that can free the value (usually \fBfree\fR).
|
|
If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
|
|
to free the space pointed to by \fIinterp->result\fR before it
|
|
invokes the next command.
|
|
If a client procedure overwrites \fIinterp->result\fR when
|
|
\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
|
|
\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
|
|
macro should be used for this purpose).
|
|
.PP
|
|
\fIFreeProc\fR should have arguments and result that match the
|
|
\fBTcl_FreeProc\fR declaration above: it receives a single
|
|
argument which is a pointer to the result value to free.
|
|
In most applications \fBfree\fR is the only non-zero value ever
|
|
used for \fIfreeProc\fR.
|
|
However, an application may store a different procedure address
|
|
in \fIfreeProc\fR in order to use an alternate memory allocator
|
|
or in order to do other cleanup when the result memory is freed.
|
|
.PP
|
|
As part of processing each command, \fBTcl_Eval\fR initializes
|
|
\fIinterp->result\fR
|
|
and \fIinterp->freeProc\fR just before calling the command procedure for
|
|
the command. The \fIfreeProc\fR field will be initialized to zero,
|
|
and \fIinterp->result\fR 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 \fIresult\fR is actually
|
|
part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
|
|
If a command wishes to return a short string, it can simply copy
|
|
it to the area pointed to by \fIinterp->result\fR. Or, it can use
|
|
the sprintf procedure to generate a short result string at the location
|
|
pointed to by \fIinterp->result\fR.
|
|
.PP
|
|
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 \fBTcl_ResetResult\fR should be called first to
|
|
reset the result to its initialized state.
|
|
.PP
|
|
The \fIerrorLine\fR
|
|
field is valid only after \fBTcl_Eval\fR returns
|
|
a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR
|
|
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
|
|
\fBTcl_Eval\fR, 2 means the second line, and so on.
|
|
The \fIerrorLine\fR field is typically used in conjunction with
|
|
\fBTcl_AddErrorInfo\fR to report information about where an error
|
|
occurred.
|
|
\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
|
|
|
|
.SH KEYWORDS
|
|
free, initialized, interpreter, malloc, result
|