1 | '\" |
---|
2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. |
---|
3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
4 | '\" |
---|
5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
7 | '\" |
---|
8 | '\" RCS: @(#) $Id: Interp.3,v 1.13 2007/12/13 15:22:31 dgp Exp $ |
---|
9 | '\" |
---|
10 | .so man.macros |
---|
11 | .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures" |
---|
12 | .BS |
---|
13 | .SH NAME |
---|
14 | Tcl_Interp \- client-visible fields of interpreter structures |
---|
15 | .SH SYNOPSIS |
---|
16 | .nf |
---|
17 | \fB#include <tcl.h>\fR |
---|
18 | .sp |
---|
19 | typedef struct { |
---|
20 | char *\fIresult\fR; |
---|
21 | Tcl_FreeProc *\fIfreeProc\fR; |
---|
22 | int \fIerrorLine\fR; |
---|
23 | } Tcl_Interp; |
---|
24 | |
---|
25 | typedef void Tcl_FreeProc(char *\fIblockPtr\fR); |
---|
26 | .BE |
---|
27 | |
---|
28 | .SH DESCRIPTION |
---|
29 | .PP |
---|
30 | The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp |
---|
31 | structure. This pointer is then passed into other Tcl procedures |
---|
32 | to process commands in the interpreter and perform other operations |
---|
33 | on the interpreter. Interpreter structures contain many fields |
---|
34 | that are used by Tcl, but only three that may be accessed by |
---|
35 | clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR. |
---|
36 | .PP |
---|
37 | .VS 8.5 |
---|
38 | \fBNote that access to all three fields, \fIresult\fB, \fIfreeProc\fB and |
---|
39 | \fIerrorLine\fB is deprecated.\fR Use \fBTcl_SetResult\fR, |
---|
40 | \fBTcl_GetResult\fR, and \fBTcl_GetReturnOptions\fR instead. |
---|
41 | .VE 8.5 |
---|
42 | .PP |
---|
43 | The \fIresult\fR and \fIfreeProc\fR fields are used to return |
---|
44 | results or error messages from commands. |
---|
45 | This information is returned by command procedures back to \fBTcl_Eval\fR, |
---|
46 | and by \fBTcl_Eval\fR back to its callers. |
---|
47 | The \fIresult\fR field points to the string that represents the |
---|
48 | result or error message, and the \fIfreeProc\fR field tells how |
---|
49 | to dispose of the storage for the string when it is not needed anymore. |
---|
50 | The easiest way for command procedures to manipulate these |
---|
51 | fields is to call procedures like \fBTcl_SetResult\fR |
---|
52 | or \fBTcl_AppendResult\fR; they |
---|
53 | will hide all the details of managing the fields. |
---|
54 | The description below is for those procedures that manipulate the |
---|
55 | fields directly. |
---|
56 | .PP |
---|
57 | Whenever a command procedure returns, it must ensure |
---|
58 | that the \fIresult\fR field of its interpreter points to the string |
---|
59 | being returned by the command. |
---|
60 | The \fIresult\fR field must always point to a valid string. |
---|
61 | If a command wishes to return no result then \fIinterp->result\fR |
---|
62 | should point to an empty string. |
---|
63 | Normally, results are assumed to be statically allocated, |
---|
64 | which means that the contents will not change before the next time |
---|
65 | \fBTcl_Eval\fR is called or some other command procedure is invoked. |
---|
66 | In this case, the \fIfreeProc\fR field must be zero. |
---|
67 | Alternatively, a command procedure may dynamically |
---|
68 | allocate its return value (e.g. using \fBTcl_Alloc\fR) |
---|
69 | and store a pointer to it in \fIinterp->result\fR. |
---|
70 | In this case, the command procedure must also set \fIinterp->freeProc\fR |
---|
71 | to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR |
---|
72 | if the storage was allocated directly by Tcl or by a call to |
---|
73 | \fBTcl_Alloc\fR. |
---|
74 | If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR |
---|
75 | to free the space pointed to by \fIinterp->result\fR before it |
---|
76 | invokes the next command. |
---|
77 | If a client procedure overwrites \fIinterp->result\fR when |
---|
78 | \fIinterp->freeProc\fR is non-zero, then it is responsible for calling |
---|
79 | \fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR |
---|
80 | macro should be used for this purpose). |
---|
81 | .PP |
---|
82 | \fIFreeProc\fR should have arguments and result that match the |
---|
83 | \fBTcl_FreeProc\fR declaration above: it receives a single |
---|
84 | argument which is a pointer to the result value to free. |
---|
85 | In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever |
---|
86 | used for \fIfreeProc\fR. |
---|
87 | However, an application may store a different procedure address |
---|
88 | in \fIfreeProc\fR in order to use an alternate memory allocator |
---|
89 | or in order to do other cleanup when the result memory is freed. |
---|
90 | .PP |
---|
91 | As part of processing each command, \fBTcl_Eval\fR initializes |
---|
92 | \fIinterp->result\fR |
---|
93 | and \fIinterp->freeProc\fR just before calling the command procedure for |
---|
94 | the command. The \fIfreeProc\fR field will be initialized to zero, |
---|
95 | and \fIinterp->result\fR will point to an empty string. Commands that |
---|
96 | do not return any value can simply leave the fields alone. |
---|
97 | Furthermore, the empty string pointed to by \fIresult\fR is actually |
---|
98 | part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200). |
---|
99 | If a command wishes to return a short string, it can simply copy |
---|
100 | it to the area pointed to by \fIinterp->result\fR. Or, it can use |
---|
101 | the sprintf procedure to generate a short result string at the location |
---|
102 | pointed to by \fIinterp->result\fR. |
---|
103 | .PP |
---|
104 | It is a general convention in Tcl-based applications that the result |
---|
105 | of an interpreter is normally in the initialized state described |
---|
106 | in the previous paragraph. |
---|
107 | Procedures that manipulate an interpreter's result (e.g. by |
---|
108 | returning an error) will generally assume that the result |
---|
109 | has been initialized when the procedure is called. |
---|
110 | If such a procedure is to be called after the result has been |
---|
111 | changed, then \fBTcl_ResetResult\fR should be called first to |
---|
112 | reset the result to its initialized state. The direct use of |
---|
113 | \fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR). |
---|
114 | .PP |
---|
115 | The \fIerrorLine\fR |
---|
116 | field is valid only after \fBTcl_Eval\fR returns |
---|
117 | a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR |
---|
118 | field identifies the line number of the command being executed when |
---|
119 | the error occurred. The line numbers are relative to the command |
---|
120 | being executed: 1 means the first line of the command passed to |
---|
121 | \fBTcl_Eval\fR, 2 means the second line, and so on. |
---|
122 | The \fIerrorLine\fR field is typically used in conjunction with |
---|
123 | \fBTcl_AddErrorInfo\fR to report information about where an error |
---|
124 | occurred. |
---|
125 | \fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR. |
---|
126 | |
---|
127 | .SH KEYWORDS |
---|
128 | free, initialized, interpreter, malloc, result |
---|