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

1 files changed, 14 insertions, 3 deletions

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