* doc/tclsh.1:

	* doc/Tcl_Main.3:
	* doc/CrtChannel.3:
	* doc/OpenFileChnl.3:
	* doc/GetStdChan.3: Enhanced the manpages with cross-references to
	  the new manpage and more explanations how these functions deal
	  with the standard channels in various situations.

	* doc/StdChannels.3: New manpage describing handling of the
	  standard channels by the Tcl library [402725].

6 files changed, 162 insertions, 8 deletions

diff --git a/doc/CrtChannel.3 b/doc/CrtChannel.3
index 9cab385..f9e79be 100644
--- a/doc/CrtChannel.3
+++ b/doc/CrtChannel.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: CrtChannel.3,v 1.9 2001/03/30 23:06:39 andreas_kupries Exp $
+'\" RCS: @(#) $Id: CrtChannel.3,v 1.10 2001/09/10 21:49:37 andreas_kupries Exp $
 .so man.macros
 .TH Tcl_CreateChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
@@ -200,6 +200,15 @@ mode indicated by \fImask\fR.
 For a discussion of channel drivers, their operations and the
 \fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
 .PP
+\fBTcl_CreateChannel\fR interacts with the code managing the standard
+channels. Once a standard channel was initialized either through a
+call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR
+closing this standard channel will cause the next call to
+\fBTcl_CreateChannel\fR to make the new channel the new standard
+channel too. See \fBTcl_StandardChannel\fR for a general treatise
+about standard channels and the behaviour of the Tcl library with
+regard to them.
+.PP
 \fBTcl_GetChannelInstanceData\fR returns the instance data associated with
 the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
 argument in the call to \fBTcl_CreateChannel\fR that created this channel.
@@ -813,7 +822,7 @@ channel driver, due to problems with the earlier stacked channel
 implementation (in 8.2.0 to 8.3.1).
 
 .SH "SEE ALSO"
-Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3)
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
 
 .SH KEYWORDS
 blocking, channel driver, channel registration, channel type, nonblocking
diff --git a/doc/GetStdChan.3 b/doc/GetStdChan.3
index 565eaa7..c78bc96 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.2 1998/09/14 18:39:48 stanton Exp $
+'\" RCS: @(#) $Id: GetStdChan.3,v 1.3 2001/09/10 21:49:37 andreas_kupries Exp $
 '\" 
 .so man.macros
 .TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
@@ -59,15 +59,19 @@ file handle.  If \fBTcl_SetStdChannel\fR is called before
 \fBTcl_GetStdChannel\fR, then the default channel will not be created.
 .PP
 If one of the standard channels is set to NULL, either by calling
-\fBTcl_SetStdChannel\fR with a null \fIchannel\fR argument, or by calling
+\fBTcl_SetStdChannel\fR with a NULL \fIchannel\fR argument, or by calling
 \fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR
 will automatically set the standard channel with the newly created channel.  If
 more than one standard channel is NULL, then the standard channels will be
 assigned starting with standard input, followed by standard output, with
 standard error being last.
+.PP
+See \fBTcl_StandardChannel\fR for a general treatise about standard
+channels and the behaviour of the Tcl library with regard to them.
+.PP
 
 .SH "SEE ALSO"
-Tcl_Close(3), Tcl_CreateChannel(3)
+Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
 
 .SH KEYWORDS
 standard channel, standard input, standard output, standard error
diff --git a/doc/OpenFileChnl.3 b/doc/OpenFileChnl.3
index eeafd08..9237fb2 100644
--- a/doc/OpenFileChnl.3
+++ b/doc/OpenFileChnl.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: OpenFileChnl.3,v 1.10 2001/07/31 19:12:05 vincentdarley Exp $
+'\" RCS: @(#) $Id: OpenFileChnl.3,v 1.11 2001/09/10 21:49:37 andreas_kupries Exp $
 .so man.macros
 .TH Tcl_OpenFileChannel 3 8.3 Tcl "Tcl Library Procedures"
 .BS
@@ -337,6 +337,13 @@ be registered in a Tcl interpreter and it will only be closed when the
 matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
 This allows code executing outside of any interpreter to safely hold a
 reference to a channel that is also registered in a Tcl interpreter.
+.PP
+This procedure interacts with the code managing the standard
+channels. If no standard channels were initialized before the first
+call to \fBTcl_RegisterChannel\fR they will get initialized by that
+call. See \fBTcl_StandardChannel\fR for a general treatise about
+standard channels and the behaviour of the Tcl library with regard to
+them.
 
 .SH TCL_UNREGISTERCHANNEL
 .PP
diff --git a/doc/StdChannels.3 b/doc/StdChannels.3
new file mode 100644
index 0000000..0945368
--- /dev/null
+++ b/doc/StdChannels.3
@@ -0,0 +1,118 @@
+'\"
+'\" Copyright (c) 2001 by ActiveState Corporation
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: StdChannels.3,v 1.1 2001/09/10 21:49:37 andreas_kupries Exp $
+'\" 
+.so man.macros
+.TH Standard channels 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_StandardChannels \- How the Tcl library deals with the standard channels
+.SH SYNOPSIS
+.PP
+This page explains the initialization and use of standard channels in
+the Tcl library.
+.PP
+The term \fIstandard channels\fR comes out of the Unix world and
+refers to the three channels automatically opened by the OS for
+each new application. They are \fBstdin\fR, \fBstdout\fR and
+\fBstderr\fR. The first is the standard input an application can read
+from, the other two refer to writable channels, one for regular
+output and the other for error messages.
+.PP
+Tcl generalizes this concept in a cross-platform way and
+exposes standard channels to the script level.
+.SH APIs
+.PP
+The public API procedures dealing directly with standard channels are
+\fBTcl_GetStdChannel\fR and \fBTcl_SetStdChannel\fR. Additional public
+APIs to consider are \fBTcl_RegisterChannel\fR,
+\fBTcl_CreateChannel\fR and \fBTcl_GetChannel\fR.
+.SH Initialization of Tcl standard channels
+.PP
+There are several ways for the Tcl standard channels to be
+initialized, described below. Each of these deals differently with the
+situation of having no platform-specific standard channels available.
+A channel is not "available" if it could not be successfully opened;
+for example, in a Tcl application run as a Windows NT service.
+.TP
+1)
+The application using the Tcl library explicitly specifies the Tcl
+channels to use as standard channels by calling
+\fBTcl_SetStdChannel\fR.  Missing platform-specific standard channels
+do not matter here. This approach is not available at the script
+level.
+.TP
+2a)
+The application asks for one of the Tcl standard channels by calling
+\fBTcl_GetStdChannel\fR. This will initialize any of them which were
+not initialized before to their platform-dependent default values.
+.sp
+In case of missing platform-specific standard channels, the Tcl
+standard channels are considered as initialized and then immediately
+closed. This means that the first three Tcl channels then opened by
+the application are designated as the Tcl standard channels.
+.TP
+2b)
+This is a special case of (2a). The initialization mentioned there
+will also happen whenever \fBTcl_GetChannel\fR is called with one of
+the standard names \fBstdin\fR, \fBstdout\fR and \fBstderr\fR as the
+name of the channel to retrieve. This happens whenever a command
+expecting a channel handle gets one of the standard names as its
+argument.
+.TP
+2c)
+Introspection of the list of open channels via \fBfile channels\fR (or
+\fBTcl_GetChannelNames\fR) will also initialize the Tcl standard
+channels to their platform-dependent default values.
+.TP
+3)
+If the application does neither of the above the Tcl library will
+setup and initialize the Tcl standard channels to their platform
+dependent default values during the creation of the first
+user-requested channel. This happens inside of
+\fBTcl_RegisterChannel\fR.
+.sp
+In case of missing platform-specific standard channels the channel
+whose creation caused the initialization of the Tcl standard channels
+is made a normal channel. The next three Tcl channels opened by the
+application are designated as the Tcl standard channels. In other
+words, of the first four Tcl channels opened by the application the
+second to fourth are designated as the Tcl standard channels.
+
+.PP
+.SH Re-initialization of Tcl standard channels
+.PP
+Once a Tcl standard channel is initialized through one of the methods
+above, closing this Tcl standard channel will cause the next call to
+\fBTcl_CreateChannel\fR to make the new channel the new standard
+channel, too. If more than one Tcl standard channel was closed
+\fBTcl_CreateChannel\fR will fill the empty slots in the order
+\fBstdin\fR, \fBstdout\fR and \fBstderr\fR.
+.PP
+\fBTcl_CreateChannel\fR will not try to reinitialize an empty slot if
+that slot was not initialized before. It is this behavior which
+enables an application to employ method 1 of initialization, i.e. to
+create and designate their own Tcl standard channels.
+
+.SH tclsh
+.PP
+The Tcl shell (or rather \fBTcl_Main\fR) uses method 2 to initialize
+the standard channels.
+
+.SH wish
+.PP
+The windowing shell (or rather \fBTk_MainEx\fR) uses method 1 to
+initialize the standard channels (See \fBTk_InitConsoleChannels\fR)
+on non-Unix platforms.  On Unix platforms, \fBTk_MainEx\fR implicitly
+uses method 2 to initialize the standard channels.
+
+.SH "SEE ALSO"
+Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetChannel(3), Tcl_GetStdChannel(3), Tcl_SetStdChannel(3), Tk_InitConsoleChannels(3), tclsh(1), wish(1), Tcl_Main(3), Tk_MainEx(3)
+
+.SH KEYWORDS
+standard channels
diff --git a/doc/Tcl_Main.3 b/doc/Tcl_Main.3
index fb266d9..388c70f 100644
--- a/doc/Tcl_Main.3
+++ b/doc/Tcl_Main.3
@@ -6,7 +6,7 @@
 '\" See the file "license.terms" for information on usage and redistribution
 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 '\" 
-'\" RCS: @(#) $Id: Tcl_Main.3,v 1.3 2000/11/03 20:20:55 hobbs Exp $
+'\" RCS: @(#) $Id: Tcl_Main.3,v 1.4 2001/09/10 21:49:37 andreas_kupries Exp $
 '\" 
 .so man.macros
 .TH Tcl_Main 3 8.4 Tcl "Tcl Library Procedures"
@@ -77,5 +77,14 @@ typedef void Tcl_MainLoopProc(void);
 .CE
 .VE 8.4
 
+.PP
+\fBTcl_Main\fR and therefore all applications based upon it, like
+\fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard
+channels to their default values. See \fBTcl_StandardChannel\fR for
+more information.
+
+.SH "SEE ALSO"
+Tcl_GetStdChannel(3)
+
 .SH KEYWORDS
 application-specific initialization, command-line arguments, main program
diff --git a/doc/tclsh.1 b/doc/tclsh.1
index e849fac..ebaba05 100644
--- a/doc/tclsh.1
+++ b/doc/tclsh.1
@@ -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: tclsh.1,v 1.4 2001/08/06 20:43:05 dgp Exp $
+'\" RCS: @(#) $Id: tclsh.1,v 1.5 2001/09/10 21:49:37 andreas_kupries Exp $
 '\" 
 .so man.macros
 .TH tclsh 1 "" Tcl "Tcl Applications"
@@ -123,5 +123,12 @@ a newline is typed but the current command isn't yet complete;
 if \fBtcl_prompt2\fR isn't set then no prompt is output for
 incomplete commands.
 
+.SH "STANDARD CHANNELS"
+.PP
+See \fBTcl_StandardChannel\fR for more explanations.
+
+.SH "SEE ALSO"
+fconfigure(1), tclvars(1)
+
 .SH KEYWORDS
 argument, interpreter, prompt, script file, shell