clarifications in doc/CrtInterp.3 and doc/StringObj.3

3 files changed, 21 insertions, 6 deletions

diff --git a/ChangeLog b/ChangeLog
index b9be86c..a426773 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2002-06-26  Miguel Sofer  <msofer@users.sourceforge.net>
+
+	* doc/CrtInterp.3:
+	* doc/StringObj.3: clarifications by Don Porter, bugs #493995 and
+	#500930. 
+	
 2002-06-24  Don Porter  <dgp@users.sourceforge.net>
 
 	* library/tcltest/tcltest.tcl:	Corrected suppression of -verbose skip
diff --git a/doc/CrtInterp.3 b/doc/CrtInterp.3
index 4e8572d..b0dfc50 100644
--- a/doc/CrtInterp.3
+++ b/doc/CrtInterp.3
@@ -5,7 +5,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: CrtInterp.3,v 1.6 2001/12/14 20:31:22 msofer Exp $
+'\" RCS: @(#) $Id: CrtInterp.3,v 1.7 2002/06/26 11:50:52 msofer Exp $
 '\" 
 .so man.macros
 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
@@ -103,8 +103,6 @@ has been called. To ensure that the interpreter is properly deleted when
 it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
 code already called \fBTcl_DeleteInterp\fR; if not, call
 \fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
-Do not call \fBTcl_DeleteInterp\fR on an interpreter for which
-\fBTcl_InterpDeleted\fR returns nonzero.
 .TP
 Retrieving An Interpreter From A Data Structure
 When an interpreter is retrieved from a data structure (e.g. the client
diff --git a/doc/StringObj.3 b/doc/StringObj.3
index 632590c..df2eafc 100644
--- a/doc/StringObj.3
+++ b/doc/StringObj.3
@@ -4,7 +4,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: StringObj.3,v 1.11 2002/04/24 09:44:36 dkf Exp $
+'\" RCS: @(#) $Id: StringObj.3,v 1.12 2002/06/26 11:50:52 msofer Exp $
 '\" 
 .so man.macros
 .TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
@@ -154,8 +154,19 @@ string representation.  This is given by the returned byte pointer and
 representation is invalid (its byte pointer is NULL), the string
 representation is regenerated from the object's internal
 representation.  The storage referenced by the returned byte pointer
-is owned by the object manager and should not be modified by the
-caller.  The procedure \fBTcl_GetString\fR is used in the common case
+is owned by the object manager.  It is passed back as a writable
+pointer so that extension author creating their own \fBTcl_ObjType\fR
+will be able to modify the string representation within the
+\fBTcl_UpdateStringProc\fR of their \fBTcl_ObjType\fR.  Except for that
+limited purpose, the pointer returned by \fBTcl_GetStringFromObj\fR
+or \fBTcl_GetString\fR should be treated as read-only.  It is
+recommended that this pointer be assigned to a (CONST char *) variable.
+Even in the limited situations where writing to this pointer is
+acceptable, one should take care to respect the copy-on-write
+semantics required by \fBTcl_Obj\fR's, with appropriate calls
+to \fBTcl_IsShared\fR and \fBTcl_DuplicateObj\fR prior to any
+in-place modification of the string representation.
+The procedure \fBTcl_GetString\fR is used in the common case
 where the caller does not need the length of the string
 representation.
 .PP