Merge commit 'c8bc058c566bbcbcd23e732197d64fecc739008f' as 'tcl8.6'

1 files changed, 120 insertions, 0 deletions

diff --git a/tcl8.6/doc/StdChannels.3 b/tcl8.6/doc/StdChannels.3
new file mode 100644
index 0000000..651ad7d
--- /dev/null
+++ b/tcl8.6/doc/StdChannels.3
@@ -0,0 +1,120 @@
+'\"
+'\" 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.
+'\" 
+.TH "Standard Channels" 3 7.5 Tcl "Tcl Library Procedures"
+.so man.macros
+.BS
+'\" Note:  do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_StandardChannels \- How the Tcl library deals with the standard channels
+.BE
+
+.SH DESCRIPTION
+.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.
+.SS "APPLICATION PROGRAMMING INTERFACES"
+.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
+Standard channels are initialized by the Tcl library in three cases:
+when explicitly requested, when implicitly required before returning
+channel information, or when implicitly required during registration
+of a new channel.
+.PP
+These cases differ in how they handle unavailable platform- specific
+standard channels.  (A channel is not
+.QW available
+if it could not be
+successfully opened; for example, in a Tcl application run as a
+Windows NT service.)
+.TP
+1)
+A single standard channel is initialized when it is explicitly
+specified in a call to \fBTcl_SetStdChannel\fR.  The states of the
+other standard channels are unaffected.
+.RS
+.PP
+Missing platform-specific standard channels do not matter here. This
+approach is not available at the script level.
+.RE
+.TP
+2)
+All uninitialized standard channels are initialized to
+platform-specific default values:
+.RS
+.TP
+(a)
+when open channels are listed with \fBTcl_GetChannelNames\fR (or the
+\fBfile channels\fR script command), or
+.TP
+(b)
+when information about any standard channel is requested with a call
+to \fBTcl_GetStdChannel\fR, or with a call to \fBTcl_GetChannel\fR
+which specifies one of the standard names (\fBstdin\fR, \fBstdout\fR
+and \fBstderr\fR).
+.PP
+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.
+.RE
+.TP
+3)
+All uninitialized standard channels are initialized to
+platform-specific default values when a user-requested channel is
+registered with \fBTcl_RegisterChannel\fR.
+.PP
+In case of unavailable 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.
+.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 "SHELL-SPECIFIC DETAILS"
+.SS tclsh
+.PP
+The Tcl shell (or rather the function \fBTcl_Main\fR, which forms the
+core of the shell's implementation) uses method 2 to initialize
+the standard channels.
+.SS wish
+.PP
+The windowing shell (or rather the function \fBTk_MainEx\fR, which
+forms the core of the shell's implementation) 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