121 lines
4.7 KiB
Groff
121 lines
4.7 KiB
Groff
'\"
|
|
'\" Copyright (c) 2001 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
|