[Tcl-bugs] [ tcl-Bugs-500930 ] Tcl_GetString* doc inconsistency

[<no...@so...>]

Bugs item #500930, was opened at 2002-01-08 09:51
You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=110894&aid=500930&group_id=10894

Category: 10. Objects
Group: 8.4a4
Status: Open
Resolution: None
Priority: 5
Submitted By: Don Porter (dgp)
Assigned to: miguel sofer (msofer)
Summary: Tcl_GetString* doc inconsistency

Initial Comment:

In doc/StringObj.3, the docs for Tcl_GetString
and Tcl_GetStringFromObj say:

 Tcl_GetStringFromObj and Tcl_GetString return an
 object's string representation. ... The storage
 referenced by the returned  byte pointer is owned
 by the object manager and should not be modified
 by the caller.  ...

If it is true that the caller should not modify the
storage referenced by the returned pointer, then
these routines should return a (CONST char *) so
that the return type enforces the documented
requirement.

However, there are many places within Tcl and
popular extensions such as Tk where the returned
value is stored in a (char *) variable, and some
places where the referenced storage is modified
directly, when it is known that it is safe to do
so within the rules of Tcl's copy-on-write rules
for Tcl_Obj's.

One choice or the other should be made.  It seems
likely that the documentation should be changed to
note the conditions where it is safe for the caller
to modify the internal storage of a Tcl_Obj referenced
by the returned pointer.

----------------------------------------------------------------------

You can respond by visiting: 
http://sourceforge.net/tracker/?func=detail&atid=110894&aid=500930&group_id=10894