diff options
Diffstat (limited to 'tcl8.6/doc/StdChannels.3')
| -rw-r--r-- | tcl8.6/doc/StdChannels.3 | 120 |
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 |