![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to Tcl_Interp.man CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10no / cmd / worm / scsi / tcl|
Return to Tcl_Interp.man CVS log | Up to [Research Unix] / researchv10no / cmd / worm / scsi / tcl |
1.1 root 1: '\" Copyright 1989 Regents of the University of California
2: '\" Permission to use, copy, modify, and distribute this
3: '\" documentation for any purpose and without fee is hereby
4: '\" granted, provided that this notice appears in all copies.
5: '\" The University of California makes no representations about
6: '\" the suitability of this material for any purpose. It is
7: '\" provided "as is" without express or implied warranty.
8: '\"
9: '\" $Header: /sprite/src/lib/tcl/RCS/Tcl_Interp.man,v 1.3 90/01/15 14:58:40 ouster Exp $ SPRITE (Berkeley)
10: '\"
11: .so \*(]ltmac.sprite
12: .HS Tcl_Interp tcl
13: .BS
14: .SH NAME
15: Tcl_Interp \- client-visible fields of interpreter structures
16: .SH SYNOPSIS
17: .nf
18: \fB#include <tcl.h>\fR
19: .sp
20: typedef struct {
21: char *\fIresult\fR;
22: int \fIdynamic\fR;
23: int \fIerrorLine\fR;
24: } Tcl_Interp;
25: .BE
26:
27: .SH DESCRIPTION
28: .PP
29: The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
30: structure. This pointer is then passed into other Tcl procedures
31: to process commands in the interpreter and perform other operations
32: on the interpreter. Interpreter structures contain many many fields
33: that are used by Tcl, but only three that may be accessed by
34: clients: \fIresult\fR and \fIdynamic\fR. These fields are used by
35: Tcl command procedures to return strings that form part of the result
36: of each command. When Tcl_Eval returns, the string pointed to be
37: the \fIresult\fR field will be used by Tcl_Eval's caller
38: as a return value or error message.
39: .PP
40: The easiest way for command procedures to manipulate the \fIresult\fR
41: and \fIdynamic\fR fields is to call Tcl_Return; Tcl_Return
42: will hide all the details of managing these fields.
43: The description below is for those procedures that manipulate the
44: fields directly.
45: .PP
46: Whenever a command procedure returns, it must ensure
47: that the \fIresult\fR field of its interpreter points to the string
48: being returned by the command. Normally, these strings are assumed
49: to be statically allocated; in this case, the \fIdynamic\fR field
50: must be zero. As an alternative, a command procedure may dynamically
51: allocate its return value and store a pointer to it in \fIinterp->result\fR.
52: In this case, the command procedure must also set \fIinterp->dynamic\fR
53: to non-zero. If \fIinterp->dynamic\fR is non-zero, then Tcl will free
54: the space pointed to by \fIinterp->result\fR before it invokes the next command.
55: If a client procedure overwrites \fIinterp->result\fR field when
56: \fIinterp->dynamic\fR is non-zero, then it is responsible for freeing the
57: old \fIinterp->result\fR. Once again, if clients use the
58: \fBTcl_Result\fR procedure to manage these fields, they need not worry
59: about these issues.
60: .PP
61: As part of processing each command, \fBTcl_Eval\fR initializes
62: \fIinterp->result\fR
63: and \fIinterp->dynamic\fR just before calling the command procedure for
64: the command. The \fIdynamic\fR field will be initialized to zero,
65: and \fIinterp->result\fR will point to an empty string. Commands that
66: do not return any value can simply leave the fields alone.
67: Furthermore, the empty string pointed to by \fIresult\fR is actually
68: part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
69: If a command wishes to return a short string, it can simply copy
70: it to the area pointed to by \fIinterp->result\fR. Or, it can use
71: the sprintf procedure to generate a short result string at the location
72: pointed to by \fIinterp->result\fR.
73: .PP
74: If a command procedure calls a lower-level procedure that sets
75: \fIinterp->result\fR and \fIinterp->dynamic\fR (such as a recursive
76: instance of \fBTcl_Eval\fR), then the command procedure must reset
77: \fIinterp->result\fR if it wishes to return a value different
78: than that returned by the lower-level procedure. As part of
79: resetting \fIinterp->result\fR, it must free the space if
80: \fIinterp->dynamic\fR is set. Once again, the easiest way to
81: make sure this gets done right is to call \fBTcl_Result\fR.
82: .PP
83: The \fIerrorLine\fR
84: .VS
85: field is valid only after \fBTcl_Eval\fR returns
86: a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR
87: field identifies the line number of the command being executed when
88: the error occurred. The line numbers are relative to the command
89: being executed: 1 means the first line of the command passed to
90: \fBTcl_Eval\fR, 2 means the second line, and so on. \fIErrorLine\fR
91: should not normally be modified except by \fBTcl_Eval\fR.
92: .VE
93:
94: .SH KEYWORDS
95: dynamic, interpreter, result
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.