man/man3/Interp.3 - toolchains/skids - Git at Google

 '\"
 '\" Copyright (c) 1989-1993 The Regents of the University of California.
 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
 '\"
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\"
 '\" RCS: @(#) $Id: Interp.3,v 1.3 2000/04/14 23:01:51 hobbs Exp $
 '\"
 '\" The definitions below are for supplemental macros used in Tcl/Tk
 '\" manual entries.
 '\"
 '\" .AP type name in/out ?indent?
 '\"	Start paragraph describing an argument to a library procedure.
 '\"	type is type of argument (int, etc.), in/out is either "in", "out",
 '\"	or "in/out" to describe whether procedure reads or modifies arg,
 '\"	and indent is equivalent to second arg of .IP (shouldn't ever be
 '\"	needed;  use .AS below instead)
 '\"
 '\" .AS ?type? ?name?
 '\"	Give maximum sizes of arguments for setting tab stops.  Type and
 '\"	name are examples of largest possible arguments that will be passed
 '\"	to .AP later.  If args are omitted, default tab stops are used.
 '\"
 '\" .BS
 '\"	Start box enclosure.  From here until next .BE, everything will be
 '\"	enclosed in one large box.
 '\"
 '\" .BE
 '\"	End of box enclosure.
 '\"
 '\" .CS
 '\"	Begin code excerpt.
 '\"
 '\" .CE
 '\"	End code excerpt.
 '\"
 '\" .VS ?version? ?br?
 '\"	Begin vertical sidebar, for use in marking newly-changed parts
 '\"	of man pages.  The first argument is ignored and used for recording
 '\"	the version when the .VS was added, so that the sidebars can be
 '\"	found and removed when they reach a certain age.  If another argument
 '\"	is present, then a line break is forced before starting the sidebar.
 '\"
 '\" .VE
 '\"	End of vertical sidebar.
 '\"
 '\" .DS
 '\"	Begin an indented unfilled display.
 '\"
 '\" .DE
 '\"	End of indented unfilled display.
 '\"
 '\" .SO
 '\"	Start of list of standard options for a Tk widget.  The
 '\"	options follow on successive lines, in four columns separated
 '\"	by tabs.
 '\"
 '\" .SE
 '\"	End of list of standard options for a Tk widget.
 '\"
 '\" .OP cmdName dbName dbClass
 '\"	Start of description of a specific option.  cmdName gives the
 '\"	option's name as specified in the class command, dbName gives
 '\"	the option's name in the option database, and dbClass gives
 '\"	the option's class in the option database.
 '\"
 '\" .UL arg1 arg2
 '\"	Print arg1 underlined, then print arg2 normally.
 '\"
 '\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
 '\"
 '\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
 .if t .wh -1.3i ^B
 .nr ^l \n(.l
 .ad b
 '\"	# Start an argument description
 .de AP
 .ie !"\\$4"" .TP \\$4
 .el \{\
 .   ie !"\\$2"" .TP \\n()Cu
 .   el          .TP 15
 .\}
 .ta \\n()Au \\n()Bu
 .ie !"\\$3"" \{\
 \&\\$1	\\fI\\$2\\fP	(\\$3)
 .\".b
 .\}
 .el \{\
 .br
 .ie !"\\$2"" \{\
 \&\\$1	\\fI\\$2\\fP
 .\}
 .el \{\
 \&\\fI\\$1\\fP
 .\}
 .\}
 ..
 '\"	# define tabbing values for .AP
 .de AS
 .nr )A 10n
 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 .nr )B \\n()Au+15n
 .\"
 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 ..
 .AS Tcl_Interp Tcl_CreateInterp in/out
 '\"	# BS - start boxed text
 '\"	# ^y = starting y location
 '\"	# ^b = 1
 .de BS
 .br
 .mk ^y
 .nr ^b 1u
 .if n .nf
 .if n .ti 0
 .if n \l'\\n(.lu\(ul'
 .if n .fi
 ..
 '\"	# BE - end boxed text (draw box now)
 .de BE
 .nf
 .ti 0
 .mk ^t
 .ie n \l'\\n(^lu\(ul'
 .el \{\
 .\"	Draw four-sided box normally, but don't draw top of
 .\"	box if the box started on an earlier page.
 .ie !\\n(^b-1 \{\
 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .el \}\
 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 .\}
 .\}
 .fi
 .br
 .nr ^b 0
 ..
 '\"	# VS - start vertical sidebar
 '\"	# ^Y = starting y location
 '\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
 .de VS
 .if !"\\$2"" .br
 .mk ^Y
 .ie n 'mc \s12\(br\s0
 .el .nr ^v 1u
 ..
 '\"	# VE - end of vertical sidebar
 .de VE
 .ie n 'mc
 .el \{\
 .ev 2
 .nf
 .ti 0
 .mk ^t
 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 .sp -1
 .fi
 .ev
 .\}
 .nr ^v 0
 ..
 '\"	# Special macro to handle page bottom:  finish off current
 '\"	# box/sidebar if in box/sidebar mode, then invoked standard
 '\"	# page bottom macro.
 .de ^B
 .ev 2
 'ti 0
 'nf
 .mk ^t
 .if \\n(^b \{\
 .\"	Draw three-sided box if this is the box's first page,
 .\"	draw two sides but no top otherwise.
 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 .\}
 .if \\n(^v \{\
 .nr ^x \\n(^tu+1v-\\n(^Yu
 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 .\}
 .bp
 'fi
 .ev
 .if \\n(^b \{\
 .mk ^y
 .nr ^b 2
 .\}
 .if \\n(^v \{\
 .mk ^Y
 .\}
 ..
 '\"	# DS - begin display
 .de DS
 .RS
 .nf
 .sp
 ..
 '\"	# DE - end display
 .de DE
 .fi
 .RE
 .sp
 ..
 '\"	# SO - start of list of standard options
 .de SO
 .SH "STANDARD OPTIONS"
 .LP
 .nf
 .ta 5.5c 11c
 .ft B
 ..
 '\"	# SE - end of list of standard options
 .de SE
 .fi
 .ft R
 .LP
 See the \\fBoptions\\fR manual entry for details on the standard options.
 ..
 '\"	# OP - start of full description for a single option
 .de OP
 .LP
 .nf
 .ta 4c
 Command-Line Name:	\\fB\\$1\\fR
 Database Name:	\\fB\\$2\\fR
 Database Class:	\\fB\\$3\\fR
 .fi
 .IP
 ..
 '\"	# CS - begin code excerpt
 .de CS
 .RS
 .nf
 .ta .25i .5i .75i 1i
 ..
 '\"	# CE - end code excerpt
 .de CE
 .fi
 .RE
 ..
 .de UL
 \\$1\l'|0\(ul'\\$2
 ..
 .TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
 .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.
 .VS
 In this case, the \fIfreeProc\fR field must be zero.
 Alternatively, a command procedure may dynamically
 allocate its return value (e.g. using \fBTcl_Alloc\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, or \fBTCL_DYNAMIC\fR
 if the storage was allocated directly by Tcl or by a call to
 \fBTcl_Alloc\fR.
 .VE
 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.
 .VS
 In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
 used for \fIfreeProc\fR.
 .VE
 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.  The direct use of
 \fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
 .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
	'\"
	'\" Copyright (c) 1989-1993 The Regents of the University of California.
	'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
	'\"
	'\" See the file "license.terms" for information on usage and redistribution
	'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
	'\"
	'\" RCS: @(#) $Id: Interp.3,v 1.3 2000/04/14 23:01:51 hobbs Exp $
	'\"
	'\" The definitions below are for supplemental macros used in Tcl/Tk
	'\" manual entries.
	'\"
	'\" .AP type name in/out ?indent?
	'\" Start paragraph describing an argument to a library procedure.
	'\" type is type of argument (int, etc.), in/out is either "in", "out",
	'\" or "in/out" to describe whether procedure reads or modifies arg,
	'\" and indent is equivalent to second arg of .IP (shouldn't ever be
	'\" needed; use .AS below instead)
	'\"
	'\" .AS ?type? ?name?
	'\" Give maximum sizes of arguments for setting tab stops. Type and
	'\" name are examples of largest possible arguments that will be passed
	'\" to .AP later. If args are omitted, default tab stops are used.
	'\"
	'\" .BS
	'\" Start box enclosure. From here until next .BE, everything will be
	'\" enclosed in one large box.
	'\"
	'\" .BE
	'\" End of box enclosure.
	'\"
	'\" .CS
	'\" Begin code excerpt.
	'\"
	'\" .CE
	'\" End code excerpt.
	'\"
	'\" .VS ?version? ?br?
	'\" Begin vertical sidebar, for use in marking newly-changed parts
	'\" of man pages. The first argument is ignored and used for recording
	'\" the version when the .VS was added, so that the sidebars can be
	'\" found and removed when they reach a certain age. If another argument
	'\" is present, then a line break is forced before starting the sidebar.
	'\"
	'\" .VE
	'\" End of vertical sidebar.
	'\"
	'\" .DS
	'\" Begin an indented unfilled display.
	'\"
	'\" .DE
	'\" End of indented unfilled display.
	'\"
	'\" .SO
	'\" Start of list of standard options for a Tk widget. The
	'\" options follow on successive lines, in four columns separated
	'\" by tabs.
	'\"
	'\" .SE
	'\" End of list of standard options for a Tk widget.
	'\"
	'\" .OP cmdName dbName dbClass
	'\" Start of description of a specific option. cmdName gives the
	'\" option's name as specified in the class command, dbName gives
	'\" the option's name in the option database, and dbClass gives
	'\" the option's class in the option database.
	'\"
	'\" .UL arg1 arg2
	'\" Print arg1 underlined, then print arg2 normally.
	'\"
	'\" RCS: @(#) $Id: man.macros,v 1.4 2000/08/25 06:18:32 ericm Exp $
	'\"
	'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
	.if t .wh -1.3i ^B
	.nr ^l \n(.l
	.ad b
	'\" # Start an argument description
	.de AP
	.ie !"\\$4"" .TP \\$4
	.el \{\
	. ie !"\\$2"" .TP \\n()Cu
	. el .TP 15
	.\}
	.ta \\n()Au \\n()Bu
	.ie !"\\$3"" \{\
	\&\\$1 \\fI\\$2\\fP (\\$3)
	.\".b
	.\}
	.el \{\
	.br
	.ie !"\\$2"" \{\
	\&\\$1 \\fI\\$2\\fP
	.\}
	.el \{\
	\&\\fI\\$1\\fP
	.\}
	.\}
	..
	'\" # define tabbing values for .AP
	.de AS
	.nr )A 10n
	.if !"\\$1"" .nr )A \\w'\\$1'u+3n
	.nr )B \\n()Au+15n
	.\"
	.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
	.nr )C \\n()Bu+\\w'(in/out)'u+2n
	..
	.AS Tcl_Interp Tcl_CreateInterp in/out
	'\" # BS - start boxed text
	'\" # ^y = starting y location
	'\" # ^b = 1
	.de BS
	.br
	.mk ^y
	.nr ^b 1u
	.if n .nf
	.if n .ti 0
	.if n \l'\\n(.lu\(ul'
	.if n .fi
	..
	'\" # BE - end boxed text (draw box now)
	.de BE
	.nf
	.ti 0
	.mk ^t
	.ie n \l'\\n(^lu\(ul'
	.el \{\
	.\" Draw four-sided box normally, but don't draw top of
	.\" box if the box started on an earlier page.
	.ie !\\n(^b-1 \{\
	\h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.el \}\
	\h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'\|0u-1.5n\(ul'
	.\}
	.\}
	.fi
	.br
	.nr ^b 0
	..
	'\" # VS - start vertical sidebar
	'\" # ^Y = starting y location
	'\" # ^v = 1 (for troff; for nroff this doesn't matter)
	.de VS
	.if !"\\$2"" .br
	.mk ^Y
	.ie n 'mc \s12\(br\s0
	.el .nr ^v 1u
	..
	'\" # VE - end of vertical sidebar
	.de VE
	.ie n 'mc
	.el \{\
	.ev 2
	.nf
	.ti 0
	.mk ^t
	\h'\|\\n(^lu+3n'\L'\|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-\|\\n(^lu+3n'
	.sp -1
	.fi
	.ev
	.\}
	.nr ^v 0
	..
	'\" # Special macro to handle page bottom: finish off current
	'\" # box/sidebar if in box/sidebar mode, then invoked standard
	'\" # page bottom macro.
	.de ^B
	.ev 2
	'ti 0
	'nf
	.mk ^t
	.if \\n(^b \{\
	.\" Draw three-sided box if this is the box's first page,
	.\" draw two sides but no top otherwise.
	.ie !\\n(^b-1 \h'-1.5n'\L'\|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.el \h'-1.5n'\L'\|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'\|0u'\c
	.\}
	.if \\n(^v \{\
	.nr ^x \\n(^tu+1v-\\n(^Yu
	\kx\h'-\\nxu'\h'\|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'\|0u'\c
	.\}
	.bp
	'fi
	.ev
	.if \\n(^b \{\
	.mk ^y
	.nr ^b 2
	.\}
	.if \\n(^v \{\
	.mk ^Y
	.\}
	..
	'\" # DS - begin display
	.de DS
	.RS
	.nf
	.sp
	..
	'\" # DE - end display
	.de DE
	.fi
	.RE
	.sp
	..
	'\" # SO - start of list of standard options
	.de SO
	.SH "STANDARD OPTIONS"
	.LP
	.nf
	.ta 5.5c 11c
	.ft B
	..
	'\" # SE - end of list of standard options
	.de SE
	.fi
	.ft R
	.LP
	See the \\fBoptions\\fR manual entry for details on the standard options.
	..
	'\" # OP - start of full description for a single option
	.de OP
	.LP
	.nf
	.ta 4c
	Command-Line Name: \\fB\\$1\\fR
	Database Name: \\fB\\$2\\fR
	Database Class: \\fB\\$3\\fR
	.fi
	.IP
	..
	'\" # CS - begin code excerpt
	.de CS
	.RS
	.nf
	.ta .25i .5i .75i 1i
	..
	'\" # CE - end code excerpt
	.de CE
	.fi
	.RE
	..
	.de UL
	\\$1\l'\|0\(ul'\\$2
	..
	.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
	.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.
	.VS
	In this case, the \fIfreeProc\fR field must be zero.
	Alternatively, a command procedure may dynamically
	allocate its return value (e.g. using \fBTcl_Alloc\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, or \fBTCL_DYNAMIC\fR
	if the storage was allocated directly by Tcl or by a call to
	\fBTcl_Alloc\fR.
	.VE
	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.
	.VS
	In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
	used for \fIfreeProc\fR.
	.VE
	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. The direct use of
	\fIinterp->result\fR is strongly deprecated (see \fBTcl_SetResult\fR).
	.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