Manual Pages for UNIX Operating System command usage for man Tcl_StandardChannels

Tcl Library Procedures                    Standard Channels(3TCL)



_________________________________________________________________

NAME
     Tcl_StandardChannels - How the Tcl library  deals  with  the
     standard channels
_________________________________________________________________


DESCRIPTION
     This page explains the initialization and  use  of  standard
     channels in the Tcl library.

     The term standard channels comes out of the Unix  world  and
     refers  to the three channels automatically opened by the OS
     for each new application. They are stdin, stdout and stderr.
     The  first  is  the  standard  input an application can read
     from, the other two refer to writable channels, one for reg-
     ular output and the other for error messages.

     Tcl generalizes this concept in  a  cross-platform  way  and
     exposes standard channels to the script level.


APIs
     The public API procedures  dealing  directly  with  standard
     channels  are Tcl_GetStdChannel and Tcl_SetStdChannel. Addi-
     tional public  APIs  to  consider  are  Tcl_RegisterChannel,
     Tcl_CreateChannel and Tcl_GetChannel.

INITIALIZATION OF TCL STANDARD CHANNELS
     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.

     These cases differ in how they handle unavailable  platform-
     specific standard channels.  (A channel is not ``available''
     if it could not be successfully opened; for  example,  in  a
     Tcl application run as a Windows NT service.)

     1)   A single standard channel is  initialized  when  it  is
          explicitly  specified  in  a call to Tcl_SetStdChannel.
          The state of the  other  standard  channels  are  unaf-
          fected.

          Missing  platform-specific  standard  channels  do  not
          matter  here.  This  approach  is  not available at the
          script level.

     2)   All uninitialized standard channels are initialized  to
          platform-specific default values:




Tcl                     Last change: 7.5                        1






Tcl Library Procedures                    Standard Channels(3TCL)



          (a)  when    open    channels    are    listed     with
               Tcl_GetChannelNames  (or  the file channels script
               command), or

          (b)  when information about  any  standard  channel  is
               requested  with  a  call  to Tcl_GetStdChannel, or
               with a call to Tcl_GetChannel which specifies  one
               of the standard names (stdin, stdout and stderr).

          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.

     3)   All uninitialized standard channels are initialized  to
          platform-specific  default values when a user-requested
          channel is registered with Tcl_RegisterChannel.

          In case of unavailable platform-specific standard chan-
          nels  the channel whose creation caused the initializa-
          tion 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  chan-
          nels.   In  other words, of the first four Tcl channels
          opened by the application  the  second  to  fourth  are
          designated as the Tcl standard channels.

RE-INITIALIZATION OF TCL STANDARD CHANNELS
     Once a Tcl standard channel is initialized  through  one  of
     the  methods  above,  closing this Tcl standard channel will
     cause the next call to Tcl_CreateChannel  to  make  the  new
     channel  the new standard channel, too. If more than one Tcl
     standard channel was closed Tcl_CreateChannel will fill  the
     empty slots in the order stdin, stdout and stderr.

     Tcl_CreateChannel 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 initiali-
     zation,  i.e. to create and designate their own Tcl standard
     channels.


tclsh
     The Tcl shell (or rather Tcl_Main) uses method 2 to initial-
     ize the standard channels.


wish
     The windowing shell (or rather Tk_MainEx) uses method  1  to
     initialize       the       standard       channels      (See
     Tk_InitConsoleChannels)  on  non-Unix  platforms.   On  Unix



Tcl                     Last change: 7.5                        2






Tcl Library Procedures                    Standard Channels(3TCL)



     platforms,  Tk_MainEx implicitly uses method 2 to initialize
     the standard channels.


SEE ALSO
     Tcl_CreateChannel(3TCL),          Tcl_RegisterChannel(3TCL),
     Tcl_GetChannel(3TCL),               Tcl_GetStdChannel(3TCL),
     Tcl_SetStdChannel(3TCL),       Tk_InitConsoleChannels(3TCL),
     tclsh(1), wish(1), Tcl_Main(3TCL), Tk_MainEx(3TCL)


KEYWORDS
     standard channels

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.



























Tcl                     Last change: 7.5                        3