Attachment "doc.diff.2" to
ticket [402725ffff]
added by
andreas_kupries
2001-08-28 02:12:17.
? doc/foo
? 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/08/27 19:09:34
@@ -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/08/27 19:09:34
@@ -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/08/27 19:09:34
@@ -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/08/27 19:09:34
@@ -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 Aug 27 12:09:34 2001
@@ -0,0 +1,111 @@
+'\"
+'\" 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 how the tcl library deals with standard channels,
+i.e. their initialization and usage.
+.PP
+The term "standard channels" comes out of the Unix world and refers
+there 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 writeable channels, one for regular output and the other for error
+messages.
+.PP
+Tcl transfers this into its own world in a cross-platform way and
+lifts the standard channels coming from the OS into 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 and
+\fBTcl_CreateChannel\fR.
+.SH Initialization of standard channels
+.PP
+There are several ways for the standard channels to be initialized.
+.TP
+1)
+The application using the Tcl library explicitly specifies the
+channels to use as standard channels explicitly by calling
+\fBTcl_SetStdChannel\fR.
+.TP
+2)
+The application asks for one of the standard channels by calling
+\fBTcl_GetStdChannel\fR. This will initialize any of them which were
+not initialized before to their platform-dependent default values.
+.TP
+3)
+If the application does neither of the above the Tcl library will
+setup and initialize the standard channels to their platform dependent
+default values during the creation of the first user-requested
+channel. This happens inside of \fBTcl_RegisterChannel\fR.
+.PP
+.SH Reusage after closing
+.PP
+Once a standard channel was initialized through one of the methods
+above closing this standard channel will cause the next call to
+\fBTcl_CreateChannel\fR to make the new channel the new standard
+channel too. If more than standard channel was closed
+\fBTcl_CreateChannel\fR will fill the empty slots in the order
+"stdin", "stdout" and "stderr".
+.PP
+Note that the above happens only if the slot was initialized at
+all. This is necessary to allow applications to employ the method 1 of
+initialization, i.e. to create and designate their own standard
+channels.
+.PP
+.SH Behaviour in a situation without standard channels
+.PP
+In some situations the tcl library simply has no standard channels
+available it could lift into the script level. This happens for
+example if a tcl application is run as an Windows NT service.
+.PP
+In such sitations the standard channels are considered as initialized
+and then immediately closed, if initialized through either method 2 or
+3 described in the first section.
+.PP
+Given the strategy of filling the empty slots as explained in the last
+section this means that some of the next channels opened by the
+application will be automatically designated as the standard
+channels.
+.PP
+Which of the opened channels are designated as such depends on the
+exact method which was used to initialize them.
+.TP
+1)
+There is nothing special here. The application itself designated which
+channels to use.
+.TP
+2)
+The first three channels opened by the application are designated as
+the standard channels.
+.TP
+3)
+The channel whose creation caused the initialization of the standard
+channels is made a normal channel. The next three channels opened by
+the application are made into the standard channels. In other words,
+of the first four channel opened by the application the second to
+fourth are designated as the standard channels.
+
+.SH Tclsh
+.PP
+The Tcl shell (or rather \fBTcl_Main\fR) uses method 2 to initialize
+the standard channels.
+
+.SH "SEE ALSO"
+Tcl_CreateChannel(3), Tcl_RegisterChannel(3), Tcl_GetStdChannel(3), Tcl_SetStdChannel(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/08/27 19:09:34
@@ -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/08/27 19:09:34
@@ -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/08/27 19:09:34
@@ -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
