Attachment "doc.diff.5" to
ticket [402725ffff]
added by
andreas_kupries
2001-09-11 04:45:35.
? doc/foo
? doc/StdChannels.3.dgp
? unix/mkLinks.xx
Index: ChangeLog
===================================================================
RCS file: /cvsroot/tcl/tcl/ChangeLog,v
retrieving revision 1.543
diff -u -r1.543 ChangeLog
--- ChangeLog 2001/08/27 02:14:08 1.543
+++ ChangeLog 2001/09/10 21:44:14
@@ -1,3 +1,16 @@
+2001-08-27 Andreas Kupries <[email protected]>
+
+ * doc/tclsh.1:
+ * doc/Tcl_Main.3:
+ * doc/CrtChannel.3:
+ * doc/OpenFileChnl.3:
+ * doc/GetStdChan.3: Enhanced the manpages with cross-references to
+ the new manpage and more explanations how these functions deal
+ with the standard channels in various situations.
+
+ * doc/StdChannels.3: New manpage describing handling of the
+ standard channels by the Tcl library [402725].
+
2001-08-26 Don Porter <[email protected]>
* library/auto.tcl (tcl_findLibrary):
Index: doc/CrtChannel.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/CrtChannel.3,v
retrieving revision 1.9
diff -u -r1.9 CrtChannel.3
--- doc/CrtChannel.3 2001/03/30 23:06:39 1.9
+++ doc/CrtChannel.3 2001/09/10 21:44:15
@@ -200,6 +200,15 @@
For a discussion of channel drivers, their operations and the
\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
.PP
+\fBTcl_CreateChannel\fR interacts with the code managing the standard
+channels. Once a standard channel was initialized either through a
+call to \fBTcl_GetStdChannel\fR or a call to \fBTcl_SetStdChannel\fR
+closing this standard channel will cause the next call to
+\fBTcl_CreateChannel\fR to make the new channel the new standard
+channel too. See \fBTcl_StandardChannel\fR for a general treatise
+about standard channels and the behaviour of the Tcl library with
+regard to them.
+.PP
\fBTcl_GetChannelInstanceData\fR returns the instance data associated with
the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
argument in the call to \fBTcl_CreateChannel\fR that created this channel.
@@ -813,7 +822,7 @@
implementation (in 8.2.0 to 8.3.1).
.SH "SEE ALSO"
-Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3)
+Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3), Tcl_StackChannel(3), Tcl_GetStdChannel(3)
.SH KEYWORDS
blocking, channel driver, channel registration, channel type, nonblocking
Index: doc/GetStdChan.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/GetStdChan.3,v
retrieving revision 1.2
diff -u -r1.2 GetStdChan.3
--- doc/GetStdChan.3 1998/09/14 18:39:48 1.2
+++ doc/GetStdChan.3 2001/09/10 21:44:15
@@ -59,15 +59,19 @@
\fBTcl_GetStdChannel\fR, then the default channel will not be created.
.PP
If one of the standard channels is set to NULL, either by calling
-\fBTcl_SetStdChannel\fR with a null \fIchannel\fR argument, or by calling
+\fBTcl_SetStdChannel\fR with a NULL \fIchannel\fR argument, or by calling
\fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR
will automatically set the standard channel with the newly created channel. If
more than one standard channel is NULL, then the standard channels will be
assigned starting with standard input, followed by standard output, with
standard error being last.
+.PP
+See \fBTcl_StandardChannel\fR for a general treatise about standard
+channels and the behaviour of the Tcl library with regard to them.
+.PP
.SH "SEE ALSO"
-Tcl_Close(3), Tcl_CreateChannel(3)
+Tcl_Close(3), Tcl_CreateChannel(3), Tcl_Main(3), tclsh(1)
.SH KEYWORDS
standard channel, standard input, standard output, standard error
Index: doc/OpenFileChnl.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/OpenFileChnl.3,v
retrieving revision 1.10
diff -u -r1.10 OpenFileChnl.3
--- doc/OpenFileChnl.3 2001/07/31 19:12:05 1.10
+++ doc/OpenFileChnl.3 2001/09/10 21:44:15
@@ -337,6 +337,13 @@
matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
This allows code executing outside of any interpreter to safely hold a
reference to a channel that is also registered in a Tcl interpreter.
+.PP
+This procedure interacts with the code managing the standard
+channels. If no standard channels were initialized before the first
+call to \fBTcl_RegisterChannel\fR they will get initialized by that
+call. See \fBTcl_StandardChannel\fR for a general treatise about
+standard channels and the behaviour of the Tcl library with regard to
+them.
.SH TCL_UNREGISTERCHANNEL
.PP
Index: doc/StdChannels.3
===================================================================
RCS file: StdChannels.3
diff -N StdChannels.3
--- /dev/null Thu May 24 22:33:05 2001
+++ StdChannels.3 Mon Sep 10 14:44:15 2001
@@ -0,0 +1,118 @@
+'\"
+'\" 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.
+'\"
+'\" RCS: @(#) $Id: GetStdChan.3,v 1.2 1998/09/14 18:39:48 stanton Exp $
+'\"
+.so man.macros
+.TH Standard channels 3 7.5 Tcl "Tcl Library Procedures"
+.BS
+'\" Note: do not modify the .SH NAME line immediately below!
+.SH NAME
+Tcl_StandardChannels \- How the Tcl library deals with the standard channels
+.SH SYNOPSIS
+.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.
+.SH APIs
+.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
+There are several ways for the Tcl standard channels to be
+initialized, described below. Each of these deals differently with the
+situation of having no platform-specific standard channels available.
+A channel is not "available" if it could not be successfully opened;
+for example, in a Tcl application run as a Windows NT service.
+.TP
+1)
+The application using the Tcl library explicitly specifies the Tcl
+channels to use as standard channels by calling
+\fBTcl_SetStdChannel\fR. Missing platform-specific standard channels
+do not matter here. This approach is not available at the script
+level.
+.TP
+2a)
+The application asks for one of the Tcl standard channels by calling
+\fBTcl_GetStdChannel\fR. This will initialize any of them which were
+not initialized before to their platform-dependent default values.
+.sp
+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.
+.TP
+2b)
+This is a special case of (2a). The initialization mentioned there
+will also happen whenever \fBTcl_GetChannel\fR is called with one of
+the standard names \fBstdin\fR, \fBstdout\fR and \fBstderr\fR as the
+name of the channel to retrieve. This happens whenever a command
+expecting a channel handle gets one of the standard names as its
+argument.
+.TP
+2c)
+Introspection of the list of open channels via \fBfile channels\fR (or
+\fBTcl_GetChannelNames\fR) will also initialize the Tcl standard
+channels to their platform-dependent default values.
+.TP
+3)
+If the application does neither of the above the Tcl library will
+setup and initialize the Tcl standard channels to their platform
+dependent default values during the creation of the first
+user-requested channel. This happens inside of
+\fBTcl_RegisterChannel\fR.
+.sp
+In case of missing 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.
+
+.PP
+.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 tclsh
+.PP
+The Tcl shell (or rather \fBTcl_Main\fR) uses method 2 to initialize
+the standard channels.
+
+.SH wish
+.PP
+The windowing shell (or rather \fBTk_MainEx\fR) 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
Index: doc/Tcl_Main.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Tcl_Main.3,v
retrieving revision 1.3
diff -u -r1.3 Tcl_Main.3
--- doc/Tcl_Main.3 2000/11/03 20:20:55 1.3
+++ doc/Tcl_Main.3 2001/09/10 21:44:15
@@ -77,5 +77,14 @@
.CE
.VE 8.4
+.PP
+\fBTcl_Main\fR and therefore all applications based upon it, like
+\fBtclsh\fR, use \fBTcl_GetStdChannel\fR to initialize the standard
+channels to their default values. See \fBTcl_StandardChannel\fR for
+more information.
+
+.SH "SEE ALSO"
+Tcl_GetStdChannel(3)
+
.SH KEYWORDS
application-specific initialization, command-line arguments, main program
Index: doc/tclsh.1
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/tclsh.1,v
retrieving revision 1.4
diff -u -r1.4 tclsh.1
--- doc/tclsh.1 2001/08/06 20:43:05 1.4
+++ doc/tclsh.1 2001/09/10 21:44:15
@@ -123,5 +123,12 @@
if \fBtcl_prompt2\fR isn't set then no prompt is output for
incomplete commands.
+.SH "STANDARD CHANNELS"
+.PP
+See \fBTcl_StandardChannel\fR for more explanations.
+
+.SH "SEE ALSO"
+fconfigure(1), tclvars(1)
+
.SH KEYWORDS
argument, interpreter, prompt, script file, shell
Index: unix/mkLinks
===================================================================
RCS file: /cvsroot/tcl/tcl/unix/mkLinks,v
retrieving revision 1.28
diff -u -r1.28 mkLinks
--- unix/mkLinks 2001/08/07 03:08:05 1.28
+++ unix/mkLinks 2001/09/10 21:44:15
@@ -476,6 +476,7 @@
rm -f Tcl_FSConvertToPathType.3
rm -f Tcl_FSGetInternalRep.3
rm -f Tcl_FSGetTranslatedPath.3
+ rm -f Tcl_FSGetTranslatedStringPath.3
rm -f Tcl_FSNewNativePath.3
rm -f Tcl_FSGetNativePath.3
rm -f Tcl_FSFileSystemInfo.3
@@ -512,6 +513,7 @@
ln FileSystem.3 Tcl_FSConvertToPathType.3
ln FileSystem.3 Tcl_FSGetInternalRep.3
ln FileSystem.3 Tcl_FSGetTranslatedPath.3
+ ln FileSystem.3 Tcl_FSGetTranslatedStringPath.3
ln FileSystem.3 Tcl_FSNewNativePath.3
ln FileSystem.3 Tcl_FSGetNativePath.3
ln FileSystem.3 Tcl_FSFileSystemInfo.3
@@ -965,6 +967,10 @@
if test -r StaticPkg.3; then
rm -f Tcl_StaticPackage.3
ln StaticPkg.3 Tcl_StaticPackage.3
+fi
+if test -r StdChannels.3; then
+ rm -f Tcl_StandardChannels.3
+ ln StdChannels.3 Tcl_StandardChannels.3
fi
if test -r StrMatch.3; then
rm -f Tcl_StringMatch.3
