1Standard Channels(3) Tcl Library Procedures Standard Channels(3)
2______________________________________________________________________________
6
8 Tcl_StandardChannels - How the Tcl library deals with the standard
9 channels
10______________________________________________________________________________
11
14 This page explains the initialization and use of standard channels in
15 the Tcl library.
16 The term standard channels comes out of the Unix world and refers to
18 the three channels automatically opened by the OS for each new applica‐
19 tion. They are stdin, stdout and stderr. The first is the standard
20 input an application can read from, the other two refer to writable
21 channels, one for regular output and the other for error messages.
22 Tcl generalizes this concept in a cross-platform way and exposes stan‐
24 dard channels to the script level.
25 APPLICATION PROGRAMMING INTERFACES
27 The public API procedures dealing directly with standard channels are
28 Tcl_GetStdChannel and Tcl_SetStdChannel. Additional public APIs to con‐
29 sider are Tcl_RegisterChannel, Tcl_CreateChannel and Tcl_GetChannel.
30
32 Standard channels are initialized by the Tcl library in three cases:
33 when explicitly requested, when implicitly required before returning
34 channel information, or when implicitly required during registration of
35 a new channel.
36 These cases differ in how they handle unavailable platform- specific
38 standard channels. (A channel is not “available” if it could not be
39 successfully opened; for example, in a Tcl application run as a Windows
40 NT service.)
41 1) A single standard channel is initialized when it is explicitly
43 specified in a call to Tcl_SetStdChannel. The states of the
44 other standard channels are unaffected.
45 Missing platform-specific standard channels do not matter here.
47 This approach is not available at the script level.
48 2) All uninitialized standard channels are initialized to platform-
50 specific default values:
51 (a) when open channels are listed with Tcl_GetChannelNames
53 (or the file channels script command), or
54 (b) when information about any standard channel is requested
56 with a call to Tcl_GetStdChannel, or with a call to
57 Tcl_GetChannel which specifies one of the standard names
58 (stdin, stdout and stderr).
59 In case of missing platform-specific standard channels, the Tcl
61 standard channels are considered as initialized and then immedi‐
62 ately closed. This means that the first three Tcl channels then
63 opened by the application are designated as the Tcl standard
64 channels.
65 3) All uninitialized standard channels are initialized to platform-
67 specific default values when a user-requested channel is regis‐
68 tered with Tcl_RegisterChannel.
69 In case of unavailable platform-specific standard channels the channel
71 whose creation caused the initialization of the Tcl standard channels
72 is made a normal channel. The next three Tcl channels opened by the
73 application are designated as the Tcl standard channels. In other
74 words, of the first four Tcl channels opened by the application the
75 second to fourth are designated as the Tcl standard channels.
76
78 Once a Tcl standard channel is initialized through one of the methods
79 above, closing this Tcl standard channel will cause the next call to
80 Tcl_CreateChannel to make the new channel the new standard channel,
81 too. If more than one Tcl standard channel was closed Tcl_CreateChannel
82 will fill the empty slots in the order stdin, stdout and stderr.
83 Tcl_CreateChannel will not try to reinitialize an empty slot if that
85 slot was not initialized before. It is this behavior which enables an
86 application to employ method 1 of initialization, i.e. to create and
87 designate their own Tcl standard channels.
88
90 tclsh
91 The Tcl shell (or rather the function Tcl_Main, which forms the core of
92 the shell's implementation) uses method 2 to initialize the standard
93 channels.
94 wish
96 The windowing shell (or rather the function Tk_MainEx, which forms the
97 core of the shell's implementation) uses method 1 to initialize the
98 standard channels (See Tk_InitConsoleChannels) on non-Unix platforms.
99 On Unix platforms, Tk_MainEx implicitly uses method 2 to initialize the
100 standard channels.
101
103 Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetChannel(3),
104 Tcl_GetStdChannel(3), Tcl_SetStdChannel(3), Tk_InitConsoleChannels(3),
105 tclsh(1), wish(1), Tcl_Main(3), Tk_MainEx(3)
106
108 standard channels
109Tcl 7.5 Standard Channels(3)