146 lines
5.9 KiB
Groff
146 lines
5.9 KiB
Groff
'\"
|
|
'\" 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.
|
|
'\"
|
|
'\" SCCS: @(#) SetResult.3 1.18 96/03/25 20:06:54
|
|
'\"
|
|
.so man.macros
|
|
.TH Tcl_SetResult 3 7.0 Tcl "Tcl Library Procedures"
|
|
.BS
|
|
.SH NAME
|
|
Tcl_SetResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result string
|
|
.SH SYNOPSIS
|
|
.nf
|
|
\fB#include <tcl.h>\fR
|
|
.sp
|
|
\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
|
|
.sp
|
|
\fBTcl_AppendResult(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
|
|
.sp
|
|
.VS
|
|
\fBTcl_AppendElement\fR(\fIinterp, string\fR)
|
|
.VE
|
|
.sp
|
|
\fBTcl_ResetResult\fR(\fIinterp\fR)
|
|
.sp
|
|
\fBTcl_FreeResult\fR(\fIinterp\fR)
|
|
.SH ARGUMENTS
|
|
.AS Tcl_FreeProc freeProc
|
|
.AP Tcl_Interp *interp out
|
|
Interpreter whose result is to be modified.
|
|
.AP char *string in
|
|
String value to become result for \fIinterp\fR or to be
|
|
appended to existing result.
|
|
.AP Tcl_FreeProc *freeProc in
|
|
Address of procedure to call to release storage at
|
|
\fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
|
|
\fBTCL_VOLATILE\fR.
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The procedures described here are utilities for setting the
|
|
result/error string in a Tcl interpreter.
|
|
.PP
|
|
\fBTcl_SetResult\fR
|
|
arranges for \fIstring\fR to be the return string for the current Tcl
|
|
command in \fIinterp\fR, replacing any existing result.
|
|
If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
|
|
refers to an area of static storage that is guaranteed not to be
|
|
modified until at least the next call to \fBTcl_Eval\fR.
|
|
If \fIfreeProc\fR
|
|
is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
|
|
to \fBmalloc()\fR and is now the property of the Tcl system.
|
|
\fBTcl_SetResult\fR will arrange for the string's storage to be
|
|
released by calling \fBfree()\fR when it is no longer needed.
|
|
If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
|
|
points to an area of memory that is likely to be overwritten when
|
|
\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
|
|
In this case \fBTcl_SetResult\fR will make a copy of the string in
|
|
dynamically allocated storage and arrange for the copy to be the
|
|
return string for the current Tcl command.
|
|
.PP
|
|
If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
|
|
\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
|
|
of a procedure that Tcl should call to free the string.
|
|
This allows applications to use non-standard storage allocators.
|
|
When Tcl no longer needs the storage for the string, it will
|
|
call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
|
|
result that match the type \fBTcl_FreeProc\fR:
|
|
.CS
|
|
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
|
|
.CE
|
|
When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
|
|
the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
|
|
.PP
|
|
If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
|
|
and \fBTcl_SetResult\fR
|
|
re-initializes \fIinterp\fR's result to point to the pre-allocated result
|
|
area, with an empty string in the result area.
|
|
.PP
|
|
If \fBTcl_SetResult\fR is called at a time when \fIinterp\fR holds a
|
|
result, \fBTcl_SetResult\fR does whatever is necessary to dispose
|
|
of the old result (see the \fBTcl_Interp\fR manual entry for details
|
|
on this).
|
|
.PP
|
|
\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
|
|
It takes each of its \fIstring\fR arguments and appends them in order
|
|
to the current result associated with \fIinterp\fR.
|
|
If the result is in its initialized empty state (e.g. a command procedure
|
|
was just invoked or \fBTcl_ResetResult\fR was just called),
|
|
then \fBTcl_AppendResult\fR sets the result to the concatenation of
|
|
its \fIstring\fR arguments.
|
|
\fBTcl_AppendResult\fR may be called repeatedly as additional pieces
|
|
of the result are produced.
|
|
\fBTcl_AppendResult\fR takes care of all the
|
|
storage management issues associated with managing \fIinterp\fR's
|
|
result, such as allocating a larger result area if necessary.
|
|
Any number of \fIstring\fR arguments may be passed in a single
|
|
call; the last argument in the list must be a NULL pointer.
|
|
.PP
|
|
\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
|
|
that it allows results to be built up in pieces.
|
|
However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
|
|
argument and it appends that argument to the current result
|
|
as a proper Tcl list element.
|
|
\fBTcl_AppendElement\fR adds backslashes or braces if necessary
|
|
to ensure that \fIinterp\fR's result can be parsed as a list and that
|
|
\fIstring\fR will be extracted as a single element.
|
|
Under normal conditions, \fBTcl_AppendElement\fR will add a space
|
|
character to \fIinterp\fR's result just before adding the new
|
|
list element, so that the list elements in the result are properly
|
|
separated.
|
|
.VS
|
|
However if the new list element is the first in a list or sub-list
|
|
(i.e. \fIinterp\fR's current result is empty, or consists of the
|
|
single character ``{'', or ends in the characters `` {'') then no
|
|
space is added.
|
|
.VE
|
|
.PP
|
|
\fBTcl_ResetResult\fR clears the result for \fIinterp\fR,
|
|
freeing the memory associated with it if the current result was
|
|
dynamically allocated.
|
|
It leaves the result in its normal initialized state with
|
|
\fIinterp->result\fR pointing to a static buffer containing
|
|
\fBTCL_RESULT_SIZE\fR characters, of which the first character
|
|
is zero.
|
|
\fBTcl_ResetResult\fR also clears the error state managed by
|
|
\fBTcl_AddErrorInfo\fR and \fBTcl_SetErrorCode\fR.
|
|
.PP
|
|
\fBTcl_FreeResult\fR is a macro that performs part of the work
|
|
of \fBTcl_ResetResult\fR.
|
|
It frees up the memory associated with \fIinterp\fR's result
|
|
and sets \fIinterp->freeProc\fR to zero, but it doesn't
|
|
change \fIinterp->result\fR or clear error state.
|
|
\fBTcl_FreeResult\fR is most commonly used when a procedure
|
|
is about to replace one result value with another.
|
|
|
|
.SH "SEE ALSO"
|
|
Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_Interp
|
|
|
|
.SH KEYWORDS
|
|
append, command, element, list, result, return value, interpreter
|