* doc/GetStdChan.3: Added recommendation that each call to

        Tcl_SetStdChannel() be accompanied by a call to Tcl_RegisterChannel().

2 files changed, 16 insertions, 1 deletions

diff --git a/ChangeLog b/ChangeLog
index 9c89faa..571c505 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-06-06  Don Porter  <dgp@users.sourceforge.net>
+
+	* doc/GetStdChan.3:	Added recommendation that each call to
+	Tcl_SetStdChannel() be accompanied by a call to Tcl_RegisterChannel().
+
 2006-06-05  Donal K. Fellows  <donal.k.fellows@manchester.ac.uk>
 
 	* doc/Alloc.3: Added documentation of promise that Tcl_Realloc(NULL,x)
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index cf17650..ed6adde 100644
--- a/doc/GetStdChan.3
+++ b/doc/GetStdChan.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: GetStdChan.3,v 1.5 2004/10/07 14:44:32 dkf Exp $
+'\" RCS: @(#) $Id: GetStdChan.3,v 1.6 2006/06/06 20:06:57 dgp Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
@@ -53,6 +53,16 @@ by calling \fBTcl_SetStdChannel\fR with a new channel or NULL in the
 \fBTcl_Close\fR, then the corresponding standard channel will automatically be
 set to NULL.
 .PP
+If a non-NULL value for \fIchannel\fR is passed to \fBTcl_SetStdChannel\fR,
+then that same value should be passed to \fBTcl_RegisterChannel\fR, like so:
+.CS
+Tcl_RegisterChannel(NULL, channel);
+.CE
+This is a workaround for a misfeature in \fBTcl_SetStdChannel\fR that it
+fails to do some reference counting housekeeping.  This misfeature cannot
+be corrected without contradicting the assumptions of some existing
+code that calls \fBTcl_SetStdChannel\fR.
+.PP
 If \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will
 construct a new channel to wrap the appropriate platform-specific standard 
 file handle.  If \fBTcl_SetStdChannel\fR is called before