diff options
Diffstat (limited to 'contrib/tcl/doc/SetResult.3')
-rw-r--r-- | contrib/tcl/doc/SetResult.3 | 145 |
1 files changed, 145 insertions, 0 deletions
diff --git a/contrib/tcl/doc/SetResult.3 b/contrib/tcl/doc/SetResult.3 new file mode 100644 index 0000000..af2d323 --- /dev/null +++ b/contrib/tcl/doc/SetResult.3 @@ -0,0 +1,145 @@ +'\" +'\" 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 |