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
28 The public API procedures dealing directly with standard channels are
29 Tcl_GetStdChannel and Tcl_SetStdChannel. Additional public APIs to con‐
30 sider are Tcl_RegisterChannel, Tcl_CreateChannel and Tcl_GetChannel.
31
33 Standard channels are initialized by the Tcl library in three cases:
34 when explicitly requested, when implicitly required before returning
35 channel information, or when implicitly required during registration of
36 a new channel.
37 These cases differ in how they handle unavailable platform- specific
39 standard channels. (A channel is not ``available'' if it could not be
40 successfully opened; for example, in a Tcl application run as a Windows
41 NT service.)
42 1) A single standard channel is initialized when it is explicitly
44 specified in a call to Tcl_SetStdChannel. The state of the
45 other standard channels are unaffected.
46 Missing platform-specific standard channels do not matter here.
48 This approach is not available at the script level.
49 2) All uninitialized standard channels are initialized to platform-
51 specific default values:
52 (a) when open channels are listed with Tcl_GetChannelNames
54 (or the file channels script command), or
55 (b) when information about any standard channel is requested
57 with a call to Tcl_GetStdChannel, or with a call to
58 Tcl_GetChannel which specifies one of the standard names
59 (stdin, stdout and stderr).
60 In case of missing platform-specific standard channels, the Tcl
62 standard channels are considered as initialized and then immedi‐
63 ately closed. This means that the first three Tcl channels then
64 opened by the application are designated as the Tcl standard
65 channels.
66 3) All uninitialized standard channels are initialized to platform-
68 specific default values when a user-requested channel is regis‐
69 tered with Tcl_RegisterChannel.
70 In case of unavailable platform-specific standard channels the
72 channel whose creation caused the initialization of the Tcl
73 standard channels is made a normal channel. The next three Tcl
74 channels opened by the application are designated as the Tcl
75 standard channels. In other words, of the first four Tcl chan‐
76 nels opened by the application the second to fourth are desig‐
77 nated as the Tcl standard channels.
78
80 Once a Tcl standard channel is initialized through one of the methods
81 above, closing this Tcl standard channel will cause the next call to
82 Tcl_CreateChannel to make the new channel the new standard channel,
83 too. If more than one Tcl standard channel was closed Tcl_CreateChannel
84 will fill the empty slots in the order stdin, stdout and stderr.
85 Tcl_CreateChannel will not try to reinitialize an empty slot if that
87 slot was not initialized before. It is this behavior which enables an
88 application to employ method 1 of initialization, i.e. to create and
89 designate their own Tcl standard channels.
90
93 The Tcl shell (or rather Tcl_Main) uses method 2 to initialize the
94 standard channels.
95
98 The windowing shell (or rather Tk_MainEx) uses method 1 to initialize
99 the standard channels (See Tk_InitConsoleChannels) on non-Unix plat‐
100 forms. On Unix platforms, Tk_MainEx implicitly uses method 2 to ini‐
101 tialize the standard channels.
102
105 Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetChannel(3),
106 Tcl_GetStdChannel(3), Tcl_SetStdChannel(3), Tk_InitConsoleChannels(3),
107 tclsh(1), wish(1), Tcl_Main(3), Tk_MainEx(3)
108
111 standard channels
112Tcl 7.5 Standard Channels(3)