Implement TIP#307.

1 files changed, 31 insertions, 7 deletions

diff --git a/doc/SetResult.3 b/doc/SetResult.3
index da3b3f9..2a17dac 100644
--- a/doc/SetResult.3
+++ b/doc/SetResult.3
@@ -5,13 +5,13 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: SetResult.3,v 1.20 2008/10/15 10:43:37 dkf Exp $
+'\" RCS: @(#) $Id: SetResult.3,v 1.21 2008/12/05 14:27:36 dkf Exp $
 '\" 
 .so man.macros
 .TH Tcl_SetResult 3 8.0 Tcl "Tcl Library Procedures"
 .BS
 .SH NAME
-Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_FreeResult \- manipulate Tcl result
+Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendResultVA, Tcl_AppendElement, Tcl_ResetResult, Tcl_TransferResult, Tcl_FreeResult \- manipulate Tcl result
 .SH SYNOPSIS
 .nf
 \fB#include <tcl.h>\fR
@@ -30,13 +30,17 @@ const char *
 .sp
 \fBTcl_AppendResultVA\fR(\fIinterp, argList\fR)
 .sp
-\fBTcl_AppendElement\fR(\fIinterp, element\fR)
-.sp
 \fBTcl_ResetResult\fR(\fIinterp\fR)
 .sp
+.VS 8.6
+\fBTcl_TransferResult\fR(\fIsourceInterp, result, targetInterp\fR)
+.VE 8.6
+.sp
+\fBTcl_AppendElement\fR(\fIinterp, element\fR)
+.sp
 \fBTcl_FreeResult\fR(\fIinterp\fR)
 .SH ARGUMENTS
-.AS Tcl_FreeProc freeProc out
+.AS Tcl_FreeProc sourceInterp out
 .AP Tcl_Interp *interp out
 Interpreter whose result is to be modified or read.
 .AP Tcl_Obj *objPtr in
@@ -54,6 +58,19 @@ Address of procedure to call to release storage at
 .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
+.VS 8.6
+Interpreter that the result and error information should be copied from.
+.VE 8.6
+.AP Tcl_Interp *targetInterp in
+.VS 8.6
+Interpreter that the result and error information should be copied to.
+.VE 8.6
+.AP int result in
+.VS 8.6
+If \fBTCL_OK\fR, only copy the result. If \fBTCL_ERROR\fR, copy the error
+information as well.
+.VE 8.6
 .BE
 .SH DESCRIPTION
 .PP
@@ -139,7 +156,14 @@ call; the last argument in the list must be a NULL pointer.
 .PP
 \fBTcl_AppendResultVA\fR is the same as \fBTcl_AppendResult\fR except that
 instead of taking a variable number of arguments it takes an argument list.
-.SH "OLD STRING PROCEDURES"
+.PP
+.VS 8.6
+\fBTcl_TransferResult\fR moves a result from one interpreter to another,
+optionally (dependent on the \fIresult\fR parameter) including the error
+information as well. The interpreters must be in the same thread.
+.VE 8.6
+.SH "DEPRECATED INTERFACES"
+.SS "OLD STRING PROCEDURES"
 .PP
 Use of the following procedures (is deprecated
 since they manipulate the Tcl result as a string.
@@ -174,7 +198,7 @@ It also sets \fIinterp->freeProc\fR to zero, but does not
 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 "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED"
+.SS "DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED"
 .PP
 It used to be legal for programs to
 directly read and write \fIinterp->result\fR