diff options
| -rw-r--r-- | doc/SetResult.3 | 239 |
1 files changed, 67 insertions, 172 deletions
diff --git a/doc/SetResult.3 b/doc/SetResult.3 index 42e3ce0..94990d7 100644 --- a/doc/SetResult.3 +++ b/doc/SetResult.3 @@ -34,213 +34,108 @@ const char * .SH ARGUMENTS .AS Tcl_FreeProc sourceInterp out .AP Tcl_Interp *interp out -Interpreter whose result is to be modified or read. +The interpreter get or set the result for. .AP Tcl_Obj *objPtr in -Tcl value to become result for \fIinterp\fR. +A value to set the result to. .AP char *result in -String value to become result for \fIinterp\fR or to be -appended to the existing result. +The string value set the result to, or to append to the existing result. .AP "const char" *element in -String value to append as a list element +The string value to append as a list element to the existing result of \fIinterp\fR. .AP Tcl_FreeProc *freeProc in -Address of procedure to call to release storage at -\fIresult\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or -\fBTCL_VOLATILE\fR. +Pointer to a procedure to call to release storage at +\fIresult\fR. .AP va_list argList in An argument list which must have been initialized using \fBva_start\fR, and cleared using \fBva_end\fR. .AP Tcl_Interp *sourceInterp in -Interpreter that the result and return options should be transferred from. +The interpreter to transfer the result and return options from. .AP Tcl_Interp *targetInterp in -Interpreter that the result and return options should be transferred to. +The interpreter to transfer the result and return options to. .AP int code in Return code value that controls transfer of return options. .BE .SH DESCRIPTION .PP -The procedures described here are utilities for manipulating the -result value in a Tcl interpreter. -The interpreter result may be either a Tcl value or a string. -For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR -set the interpreter result to, respectively, a value and a string. -Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR -return the interpreter result as a value and as a string. -The procedures always keep the string and value forms -of the interpreter result consistent. -For example, if \fBTcl_SetObjResult\fR is called to set -the result to a value, -then \fBTcl_GetStringResult\fR is called, -it will return the value's string representation. +These procedures manipulate the result of an interpreter. Some procedures +provide a Tcl_Obj interface while others provide a string interface. For +example, \fBTcl_SetObjResult\fR accepts a Tcl_Obj and \fBTcl_SetResult\fR +accepts a char *. Similarly, \fBTcl_GetObjResult\fR produces a Tcl_Obj * and +\fBTcl_GetStringResult\fR produces a char *. The procedures can be mixed and +matched. For example, if \fBTcl_SetObjResult\fR is called to set the result to +a Tcl_Obj value, and then \fBTcl_GetStringResult\fR is called, it returns a +char * (but see caveats below). .PP -\fBTcl_SetObjResult\fR -arranges for \fIobjPtr\fR to be the result for \fIinterp\fR, +\fBTcl_SetObjResult\fR sets \fIobjPtr\fR as the result for \fIinterp\fR, replacing any existing result. -The result is left pointing to the value -referenced by \fIobjPtr\fR. -\fIobjPtr\fR's reference count is incremented -since there is now a new reference to it from \fIinterp\fR. -The reference count for any old result value -is decremented and the old result value is freed if no -references to it remain. .PP -\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as a value. -The value's reference count is not incremented; -if the caller needs to retain a long-term pointer to the value -they should use \fBTcl_IncrRefCount\fR to increment its reference count -in order to keep it from being freed too early or accidentally changed. -.PP -\fBTcl_SetResult\fR -arranges for \fIresult\fR to be the result for the current Tcl -command in \fIinterp\fR, replacing any existing result. -The \fIfreeProc\fR argument specifies how to manage the storage -for the \fIresult\fR argument; -it is discussed in the section -\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below. -If \fIresult\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored -and \fBTcl_SetResult\fR -re-initializes \fIinterp\fR's result to point to an empty string. -.PP -\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string. -If the result was set to a value by a \fBTcl_SetObjResult\fR call, -the value form will be converted to a string and returned. -If the value's string representation contains null bytes, -this conversion will lose information. -For this reason, programmers are encouraged to -write their code to use the new value API procedures -and to call \fBTcl_GetObjResult\fR instead. -.PP -\fBTcl_ResetResult\fR clears the result for \fIinterp\fR -and leaves the result in its normal empty initialized state. -If the result is a value, -its reference count is decremented and the result is left -pointing to an unshared value representing an empty string. -If the result is a dynamically allocated string, its memory is free*d -and the result is left as a empty string. -\fBTcl_ResetResult\fR also clears the error state managed by -\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR, -and \fBTcl_SetErrorCode\fR. -.PP -\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces. -It takes each of its \fIresult\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 \fIresult\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. -It also manages conversion to and from the \fIresult\fR field of the -\fIinterp\fR so as to handle backward-compatibility with old-style -extensions. -Any number of \fIresult\fR arguments may be passed in a single -call; the last argument in the list must be a NULL pointer. -.PP -\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR -to \fItargetInterp\fR. The two interpreters must have been created in the -same thread. If \fIsourceInterp\fR and \fItargetInterp\fR are the same, -nothing is done. Otherwise, \fBTcl_TransferResult\fR moves the result -from \fIsourceInterp\fR to \fItargetInterp\fR, and resets the result -in \fIsourceInterp\fR. It also moves the return options dictionary as -controlled by the return code value \fIcode\fR in the same manner +\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR, without +incrementing its reference count. +.PP +\fBTcl_SetResult\fR sets \fIresult\fR as the result for \fIinterp\fR, replacing +any existing result, and calls \fIfreeProc\fR to free \fIresult\fR. See \fBTHE +TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below. If \fIresult\fR is +\fBNULL\fR, ignores \fIfreeProc\fR and sets the result for \fIinterp\fR to +point to the empty string. +.PP +\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as a string, i.e. +the bytes of the Tcl_Obj for the result, which can be decoded using +\fBTcl_UtfToExternal\fR. This value is freed when its corresponding Tcl_Obj is +freed.Programmers are encouraged to use the newer Tcl_Obj API procedures, e.g. +to call \fBTcl_GetObjResult\fR instead. +.PP +\fBTcl_ResetResult\fR sets the empty string as the result for \fIinterp\fR and +clears the error state managed by \fBTcl_AddErrorInfo\fR, +\fBTcl_AddObjErrorInfo\fR, and \fBTcl_SetErrorCode\fR. +.PP +\fBTcl_AppendResult\fR builds up a result from smaller pieces, appending each +\fIresult\fR in order to the current result for \fIinterp\fR. It may be called +repeatedly as additional pieces of the result are produced, and manages the +storage for the \fIinterp\fR's result, allocating a larger result area if +necessary. It also manages conversion to and from the \fIresult\fR field of +the \fIinterp\fR to handle backward-compatibility with old-style extensions. +Any number of \fIresult\fR arguments may be passed in a single call; the last +argument in the list must be a NULL pointer. +.PP +\fBTcl_TransferResult\fR transfers interpreter state from \fIsourceInterp\fR to +\fItargetInterp\fR, both of which must have been created in the same thread, +resets the result in \fIsourceInterp\fR, and moves the return options +dictionary as controlled by the return code value \fIcode\fR in the same manner as \fBTcl_GetReturnOptions\fR. +.PP +If \fIsourceInterp\fR and \fItargetInterp\fR are the same, nothing is done. .SH "DEPRECATED INTERFACES" .SS "OLD STRING PROCEDURES" .PP -Use of the following procedures is deprecated -since they manipulate the Tcl result as a string. -Procedures such as \fBTcl_SetObjResult\fR -that manipulate the result as a value -can be significantly more efficient. -.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 \fIelement\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 -\fIelement\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. -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 +The following procedures are deprecated since they manipulate the Tcl result as +a string. Procedures such as \fBTcl_SetObjResult\fR can be significantly more +efficient. +.PP +\fBTcl_AppendElement\fR is like \fBTcl_AppendResult\fR, but it appends only one +piece, and also appends that piece as a list item. +\fBTcl_AppendElement\fR adds backslashes or braces as necessary to ensure that +f\Ielement\fR is properly formatted as a list item. Under normal conditions, +\fBTcl_AppendElement\fR adds 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. However if the new list element is the first item in the +list or sublist (i.e. \fIinterp\fR's current result is empty, or consists of +the single character .QW { , or ends in the characters .QW " {" ) then no space is added. .SH "THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT" .PP -\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how -the Tcl system is to manage the storage for the \fIresult\fR argument. -If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called -at a time when \fIinterp\fR holds a string result, -they do whatever is necessary to dispose of the old string result -(see the \fBTcl_Interp\fR manual entry for details on this). -.PP -If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIresult\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 \fIresult\fR was allocated with a call -to \fBTcl_Alloc\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 \fBTcl_Free\fR when it is no longer needed. -If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIresult\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 -result for the current Tcl command. -.PP -If \fIfreeProc\fR is not 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: +\fIFreeProc\fR has the following type: .PP .CS typedef void \fBTcl_FreeProc\fR( char *\fIblockPtr\fR); .CE .PP -When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to -the value of \fIresult\fR passed to \fBTcl_SetResult\fR. +When \fIfreeProc\fR is called, \fIblockPtr\fR is the \fIresult\fR value passed +to \fBTcl_SetResult\fR. -.SH "REFERENCE COUNT MANAGEMENT" -.PP -The interpreter result is one of the main places that owns references to -values, along with the bytecode execution stack, argument lists, variables, -and the list and dictionary collection values. -.PP -\fBTcl_SetObjResult\fR takes a value with an arbitrary reference count -\fI(specifically including zero)\fR and guarantees to increment the reference -count. If code wishes to continue using the value after setting it as the -result, it should add its own reference to it with \fBTcl_IncrRefCount\fR. -.PP -\fBTcl_GetObjResult\fR returns the current interpreter result value. This will -have a reference count of at least 1. If the caller wishes to keep the -interpreter result value, it should increment its reference count. -.PP -\fBTcl_GetStringResult\fR does not manipulate reference counts, but the string -it returns is owned by (and has a lifetime controlled by) the current -interpreter result value; it should be copied instead of being relied upon to -persist after the next Tcl API call, as most Tcl operations can modify the -interpreter result. -.PP -\fBTcl_SetResult\fR, \fBTcl_AppendResult\fR, \fBTcl_AppendResultVA\fR, -\fBTcl_AppendElement\fR, and \fBTcl_ResetResult\fR all modify the interpreter -result. They may cause the old interpreter result to have its reference count -decremented and a new interpreter result to be allocated. After they have been -called, the reference count of the interpreter result is guaranteed to be 1. .SH "SEE ALSO" Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp, Tcl_GetReturnOptions |